Interface-control SDK and manifest reference (SDK 1.1.3)
This is the reference for building a browser interface control. It covers:
- the
interfaceControlssection ofplugin.json; - the
@inflowai/control-sdklifecycle ABI; - the
@inflowai/control-test-kitmocked host; - the versions, limits, refusal codes, licensing and trust rules that apply to them.
Most of this page is generated by inflow-control-sdk/scripts/reference.mjs. It reads the manifest schema, the reviewed public API baselines, the host's Java contract constants and the enforced limits directly, so the reference cannot drift from what ships.
Two commands keep it honest, both part of npm run verify in inflow-control-sdk:
npm run reference:checkfails when this page is stale.npm run reference:examplespacks the SDK and test kit and installs them into a clean project. It then compiles every example below and validates the example manifest with the packaging tool.
Guides for first-time developers (IDE setup, recipes, testing, packaging, troubleshooting) are listed in the documentation index.
Versions and compatibility
| Artifact | Version | Contract facts |
|---|---|---|
@inflowai/control-sdk |
1.1.3 | lifecycle ABI 1; targets control contract 1; Node >=22.22.0 for building |
@inflowai/control-test-kit |
1.0.2 | requires @inflowai/control-sdk ^1.1.0; a mocked host, never platform acceptance |
@inflowai/control-tools |
1.0.2 | packages and validates exactly as the host admits |
| Inflow host (plugin platform) | 0.1.0 | accepts control contract 1; accepts SDK major 1 in interfaceControls.sdk; a manifest whose requires is newer than 0.1.0 is refused |
A module built with SDK 1.1.3 reports ABI 1; the host refuses a module whose ABI differs. Declare "contractVersion": 1 and "sdk": "^1.1.3" (or a lower 1.x caret) in interfaceControls.
Compatibility rules:
- Control contract (
interfaceControls.contractVersion): the meaning of the declaration and of the host services. A host refuses a contract version it does not implement. It never silently drops the section. - SDK range (
interfaceControls.sdk): the caret range of the browser SDK your bundle was built with. A host accepts only the SDK majors it provides. Minor versions add API, so a module built with an older minor still loads. - Lifecycle ABI: checked when the module loads. The module's default export must be the frozen value returned by
defineControl, carrying the ABI this host implements. requires: the minimum Inflow plugin platform version. A newer value is refused before anything loads.
Lifecycle
A control is an ES module whose default export is defineControl({ controlKey, mount }).
- Load. The
entrymust be one self-contained ES module with no imports: bundle your code, the SDK and every dependency into it. The host loads it from ablob:URL, where imports cannot resolve. The host lazily loads the declaredentryasset of an active (uploaded and enabled) package and checks the module withcheckControlModule. If the check fails, or the module'scontrolKeydiffers from the declaration, the host shows the shared unavailable state. - Mount.
mount(element, context)runs once per placed instance and returns the instance.contextcarries:- the resolved, typed
propertiesand theirpropertyStates; options,themetokens,direction,locale,modeandsize;- the admitted
providersand their browser-publicconfiguration; - the
hostservices.
- the resolved, typed
- Update.
update(change)delivers changed properties, states, options, theme, direction or locale. Re-render in place, and never emit fromupdate. - Resize.
resize(size)is optional. It delivers the host element's new size. - Dispose.
dispose()must be safe to call more than once. It releases every listener, timer, observer and provider object. Passcontext.host.signalto anything that accepts anAbortSignal: it aborts on dispose. A change of providers or configuration remounts the control.
A control proposes edits with host.setOutput(key, value) and reports genuine user interactions with host.emit(key, payload). Both return a HostResult; the control must not assume success. host.reportError shows the shared error state.
The other host services are listed in the API below: setBusy, announce, searchOptions, adoptStyles and onDispose.
A complete control
The declaration is the control's reviewed plugin.json entry. It is kept in TypeScript as const, so the property, output and event types are derived from it.
import type { ControlDeclaration } from '@inflowai/control-sdk';
export const declaration = {
controlKey: 'region-picker',
displayName: 'Region picker',
entry: 'control.js',
properties: [
{ key: 'region', label: 'Region', valueType: { kind: 'ENUM', enumValues: ['north', 'south'], nullable: true },
sourceModes: ['LITERAL', 'EXPRESSION', 'BINDING'] },
{ key: 'heading', label: 'Heading', valueType: { kind: 'TEXT', maxLength: 80 }, sourceModes: ['LITERAL', 'EXPRESSION'],
restrictionReason: 'A heading is presentation text, never form data.' },
],
outputs: [
{ key: 'region', label: 'Chosen region', valueType: { kind: 'ENUM', enumValues: ['north', 'south'], nullable: true },
property: 'region' },
],
events: [
{ key: 'confirmed', label: 'Region confirmed',
payload: [{ name: 'region', valueType: { kind: 'ENUM', enumValues: ['north', 'south'] } }] },
],
} as const satisfies ControlDeclaration;
import { defineControl, type EventsOf, type OutputsOf, type PropertiesOf } from '@inflowai/control-sdk';
import { declaration } from './declaration.js';
type Props = PropertiesOf<typeof declaration>;
// The control's own copy of the current values, which it updates as changes arrive.
type Current = { -readonly [K in keyof Props]?: Props[K] };
export default defineControl<Props, OutputsOf<typeof declaration>, EventsOf<typeof declaration>>({
controlKey: declaration.controlKey,
mount(element, context) {
const doc = element.ownerDocument;
// Theme tokens are CSS custom-property references (for example `var(--ink)`): build the styles from them.
const { spaceSmall = '8px', text = 'inherit' } = context.theme;
context.host.adoptStyles(`.picker { display: flex; gap: ${spaceSmall}; color: ${text}; }`);
const group = element.appendChild(doc.createElement('div'));
group.className = 'picker';
group.setAttribute('role', 'group');
const heading = group.appendChild(doc.createElement('span'));
// The current values and states. A key the host sends as `undefined` is withdrawn: its content is cleared, never kept.
const values: Current = { ...context.properties };
const states = { ...context.propertyStates };
const buttons = (['north', 'south'] as const).map((region) => {
const button = group.appendChild(doc.createElement('button'));
button.type = 'button';
button.textContent = region === 'north' ? 'North' : 'South';
button.addEventListener('click', () => {
const edit = context.host.setOutput('region', region);
// A refused edit changed nothing: say so, and confirm nothing.
if (!edit.accepted && edit.reason !== 'unchanged') {
context.host.announce('The region could not be changed.');
return;
}
const sent = context.host.emit('confirmed', { region });
if (!sent.accepted) context.host.announce('The region was not confirmed.');
}, { signal: context.host.signal });
return { region, button };
});
const status = (key: keyof Props) => states[key]?.status ?? 'ready';
const render = () => {
// Only a ready property shows its value; any other state shows none.
heading.textContent = status('heading') === 'ready' ? values.heading ?? '' : '';
for (const { region, button } of buttons) {
// Choosing stays possible in every state but loading: the host accepts a first or corrective choice for an
// unset, empty or no-longer-offered value, and its HostResult says when it does not.
button.disabled = status('region') === 'loading';
button.setAttribute('aria-pressed', String(status('region') === 'ready' && values.region === region));
}
group.setAttribute('aria-label', heading.textContent || 'Region');
};
render();
return {
update(change) {
// Own keys only: an omitted key is unchanged, a key present as `undefined` is withdrawn.
for (const key of Object.keys(change.properties ?? {}) as (keyof Props)[]) values[key] = change.properties![key] as never;
Object.assign(states, change.propertyStates ?? {});
render();
},
dispose() { element.replaceChildren(); },
};
},
});
The manifest
This is the package's source plugin.json. The source never lists assets: the packaging tool (inflow-control package) computes them, with each asset's hash and size, from the build output.
{
"id": "region-controls",
"version": "1.0.0",
"provider": "Example Org",
"description": "A region picker for service forms.",
"requires": "0.1.0",
"dependencies": [],
"capabilities": [],
"interfaceControls": {
"contractVersion": 1,
"sdk": "^1.1.0",
"controls": [
{
"controlKey": "region-picker",
"displayName": "Region picker",
"entry": "control.js",
"properties": [
{ "key": "region", "label": "Region", "valueType": { "kind": "ENUM", "enumValues": ["north", "south"], "nullable": true },
"sourceModes": ["LITERAL", "EXPRESSION", "BINDING"] },
{ "key": "heading", "label": "Heading", "valueType": { "kind": "TEXT", "maxLength": 80 }, "sourceModes": ["LITERAL", "EXPRESSION"],
"restrictionReason": "A heading is presentation text, never form data." }
],
"outputs": [
{ "key": "region", "label": "Chosen region", "valueType": { "kind": "ENUM", "enumValues": ["north", "south"], "nullable": true },
"property": "region" }
],
"events": [
{ "key": "confirmed", "label": "Region confirmed",
"payload": [{ "name": "region", "valueType": { "kind": "ENUM", "enumValues": ["north", "south"] } }] }
]
}
]
}
}
Testing with the kit
The test kit is a mocked host. It is useful for development and CI, but passing it never shows that a control works on the platform. Only platform acceptance on a real server shows that.
import { MOCKED_BOUNDARY, mountForTest, runConformance } from '@inflowai/control-test-kit';
import control from './control.js';
import { declaration } from './declaration.js';
export async function check(): Promise<string[]> {
const problems: string[] = [];
const harness = await mountForTest(control, { declaration, properties: { region: 'north', heading: 'Region' } });
const pressed = () => [...harness.element.querySelectorAll('button')].filter((b) => b.getAttribute('aria-pressed') === 'true').length;
// Withdrawn values disappear, and come back on recovery.
harness.update({ properties: { heading: undefined, region: undefined }, propertyStates: { heading: { status: 'error', reason: 'Unavailable.' }, region: { status: 'unavailable' } } });
if (harness.element.textContent?.includes('Region') || pressed() > 0) problems.push('withdrawn values are still shown');
harness.update({ properties: { heading: 'Region', region: 'south' }, propertyStates: { heading: { status: 'ready' }, region: { status: 'ready' } } });
if (pressed() !== 1) problems.push('recovered values are not shown');
harness.dispose();
// A first or corrective choice is possible where the host accepts it: an unset binding and a no-longer-offered choice.
for (const state of [{ status: 'unavailable' }, { status: 'invalid', reason: 'This choice is no longer offered.' }] as const) {
const writable = await mountForTest(control, { declaration, properties: { heading: 'Region' }, propertyStates: { region: state } });
const choice = [...writable.element.querySelectorAll('button')].find((b) => b.textContent === 'South')!;
writable.interact(choice);
choice.click();
if (!writable.calls.some((call) => call.service === 'setOutput' && call.result?.accepted)) problems.push(`no choice could be made while ${state.status}`);
writable.dispose();
}
// A refused edit confirms nothing: while the region is loading, the host refuses the edit.
const loading = await mountForTest(control, { declaration, properties: { region: 'north', heading: 'Region' }, propertyStates: { region: { status: 'loading' } } });
const south = [...loading.element.querySelectorAll('button')].find((b) => b.textContent === 'South')!;
south.disabled = false; // as if a stale state let the click through
loading.interact(south);
south.click();
if (loading.calls.some((call) => call.service === 'emit')) problems.push('a refused edit still emitted an event');
loading.dispose();
const report = await runConformance(control, declaration);
problems.push(...report.checks.filter((c) => !c.passed).map((c) => `${c.id}: ${c.problems.join('; ')}`));
return report.boundary === MOCKED_BOUNDARY ? problems : ['unexpected boundary'];
}
Limits
| Limit | Value | Enforced by |
|---|---|---|
| Package archive (compressed) | 5 MiB | host admission (PluginArchiveValidator) and inflow-control package |
| Package expanded size | 50 MiB | host admission (PluginArchiveValidator) and inflow-control package |
| One archive entry | 10 MiB | host admission (PluginArchiveValidator) and inflow-control package |
plugin.json |
64 KiB | host admission (PluginArchiveValidator) and inflow-control package |
| Archive entries | 2048 | host admission (PluginArchiveValidator) and inflow-control package |
| Compression ratio | 100:1 | host admission (PluginArchiveValidator) and inflow-control package |
| Event payload (serialized JSON) | 16 KiB | the host refuses a larger emit with invalid-value |
Interaction window for emit |
5000 ms after a real pointer or key input inside the control | the host refuses an emit without one with suppressed |
| Record option page | 50 items (hasMore signals more) |
host option reads |
| Option search debounce | 250 ms | host.searchOptions |
| Option read timeout | 10000 ms, then an error option state |
host option reads |
Declaration bounds (controls per package, properties per control, string lengths, list sizes) are in the manifest reference of docs/plugins/interface-controls/sdk-reference.md.
Refusal codes
| Code | When the host refuses |
|---|---|
PLUGIN_HOST_VERSION_UNSUPPORTED |
The manifest's requires names a plugin platform version newer than this host. |
PLUGIN_UI_ONLY_NOT_JVM |
A UI-only package was offered to an entry point that only understands Java plugins. |
PLUGIN_UI_ONLY_NOT_RUNNABLE |
The plugin runner was asked to describe or load a UI-only package. |
PLUGIN_CONTROL_CONTRACT_UNSUPPORTED |
The manifest names a control-contract version this host does not implement. |
PLUGIN_CONTROL_SDK_UNSUPPORTED |
The manifest requires a browser SDK major version this host does not provide. |
PLUGIN_CONTROLS_INVALID |
The section is schema-valid but internally inconsistent (duplicates, dangling references, conflicts). |
PLUGIN_MANIFEST_INVALID |
plugin.json does not match the schema (an unknown field, a bound or a pattern). |
PLUGIN_CONTROL_DEFAULT_INVALID |
A property's default does not fit its declared value type exactly as a literal: its canonical shape (INTEGER a JSON whole number; LONG and DECIMAL digits written as text), its declared facets or its nullability. Studio places the default as the property's literal source, so the package and the upload refuse it rather than every publication. |
Value kinds a control may not declare: AUTO_NUMBER, BINARY. Canonical value kinds a control may not declare, each for a stated reason. AUTO_NUMBER is generated by the platform only, never authored by a control. BINARY has no bounded browser transport in contract version 1.
Reserved keys (never a property, output or event payload field, ignoring case): id, pluginId, pluginClass, provider, controlKey, version, digest, sha256, entry, assets, capabilities, permissions, contractVersion, sdk.
Licensing
| Artifact | License | Notices |
|---|---|---|
@inflowai/control-sdk |
UNLICENSED |
LICENSE and NOTICE ship inside the package |
@inflowai/control-test-kit |
UNLICENSED |
LICENSE and NOTICE ship inside the package |
@inflowai/control-tools |
UNLICENSED |
LICENSE and NOTICE ship inside the package |
Each package also lists its third-party notices in NOTICE.
For a package you build, inflow-control package requires a package-lock.json (lockfile version 2 or 3). Every dependency that ships must:
- resolve from the public registry;
- declare a license;
- be listed in your
THIRD-PARTY-NOTICES.md.
Your LICENSE, NOTICE, THIRD-PARTY-NOTICES.md and README.md are packaged when present.
Trust
Trust: controls are trusted browser code that a plugin administrator verified and uploaded (an upload is live at once; there is no approval step). They run with the browser privileges of the page that hosts them. This typed API is a contract, not a sandbox. It deliberately offers no network, credential, session or storage capability: everything a control may do to the platform goes through HostServices, and the host re-checks current authority for every effect.
This typed contract is not a sandbox. The host keeps adopted styles visually contained and re-authorizes every effect at its service boundary. It cannot undo third-party requests or browser actions that trusted code has already made. Untrusted code and a public marketplace are out of scope for this release.
Manifest reference
Generated from tools/interface-control-plugins/schema/plugin-manifest.schema.json. The host, the packaging tool and Studio all validate against this schema, so these bounds are exactly what admission enforces.
Schema fingerprint (SHA-256 of its text without insignificant whitespace): 81689defbd99a0684edc3bc3749d959b88c8eccc1daaf563fda87460d3d4b2b3. Any change to the schema changes it, so the reference must be regenerated with the schema.
plugin.json (fields used by control packages)
| Field | Type | Required | Bounds | Meaning |
|---|---|---|---|---|
id |
string | yes | max length 100; pattern ^[a-z0-9\-]+$ |
A stable lowercase alphanumeric slug with hyphens. |
version |
string | yes | max length 64; pattern ^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$ |
Semantic versioning representation. |
provider |
string | yes | min length 1; max length 200 | |
description |
string | no | max length 2000 | |
requires |
string | yes | pattern ^[0-9]+\.[0-9]+\.[0-9]+$ |
Minimum platform/SDK version required by the plugin. |
pluginClass |
string | no | pattern ^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)*$ |
Fully qualified class name of the plugin wrapper. |
dependencies |
array of string | yes | max items 100; unique items; each: min length 1; max length 200 | |
capabilities |
array of string | yes | max items 100; unique items; each: pattern ^[a-z][a-z0-9._-]{0,99}$ |
|
interfaceControls |
interfaceControls | no |
A package must declare at least one of pluginClass or interfaceControls.
When pluginClass is absent, processNode and hostFunctions must be absent. SCRUM-4847: a package without a Java plugin class (UI-only) cannot declare server-side sections.
The manifest also accepts hostFunctions and processNode: server-side sections of a package with a Java plugin, not part of an interface-control declaration, so they are not listed above.
No other fields are accepted.
interfaceControls
SCRUM-4846: browser interface controls this package contributes (contract version 1). With no pluginClass the package is UI-only and carries no Java; with one it is mixed. Every declaration here is reviewed by an administrator and requests nothing: controls, events and providers grant no permission. First release admits reviewed trusted browser code only; this typed contract is not a sandbox.
| Field | Type | Required | Bounds | Meaning |
|---|---|---|---|---|
contractVersion |
integer | yes | minimum 1; maximum 1000 | Control-contract version. The host refuses versions it does not implement. |
sdk |
string | yes | pattern ^\^(0|[1-9][0-9]{0,3})\.(0|[1-9][0-9]{0,3})\.(0|[1-9][0-9]{0,3})$ |
Caret range of the browser companion SDK the controls were built against, e.g. ^1.0.0. |
controls |
array of interfaceControl | yes | min items 1; max items 50 | |
assets |
array of controlAsset | yes | min items 1; max items 2048 | |
providers |
array of controlProvider | no | max items 20 |
No other fields are accepted.
interfaceControl
| Field | Type | Required | Bounds | Meaning |
|---|---|---|---|---|
controlKey |
string | yes | pattern ^[a-z][a-z0-9-]{0,63}$ |
Stable machine key, unique within the package. Never derived from an expression. |
displayName |
string | yes | min length 1; max length 120 | |
description |
string | no | max length 1000 | |
icon |
controlRelativePath | no | ||
category |
string | no | min length 1; max length 80 | |
entry |
controlRelativePath | yes | Relative path of the declared JavaScript module asset the host loads. Never derived from an expression. | |
properties |
array of controlProperty | no | max items 100 | |
outputs |
array of controlOutput | no | max items 50 | |
events |
array of controlEvent | no | max items 50 |
No other fields are accepted.
controlProperty
| Field | Type | Required | Bounds | Meaning |
|---|---|---|---|---|
key |
string | yes | pattern ^[a-z][A-Za-z0-9]{0,63}$; reserved: id, pluginId, pluginClass, provider, controlKey, version, digest, sha256, entry, assets, capabilities, permissions, contractVersion, sdk |
Stable property key. Package identity and authority facts are reserved and can never be properties. |
label |
string | yes | min length 1; max length 120 | |
description |
string | no | max length 1000 | |
group |
string | no | min length 1; max length 80 | |
valueType |
controlValueType | yes | ||
sourceModes |
array of LITERAL · EXPRESSION · BINDING |
yes | min items 1; max items 3; unique items; each: one of LITERAL · EXPRESSION · BINDING |
|
restrictionReason |
string | no | min length 1; max length 300; pattern \S |
Why fewer than all source modes are allowed. Required whenever the property is restricted. |
default |
any JSON value | no | Literal default, placed as the property's literal source when the control is added. It must fit valueType exactly as a literal: canonical shape (INTEGER a JSON whole number; LONG and DECIMAL digits written as text), declared facets and nullability. Packaging and upload refuse a default that does not fit with PLUGIN_CONTROL_DEFAULT_INVALID (SCRUM-5076). | |
readOnly |
boolean | no | A computed input the control displays but never writes. | |
dynamicOptions |
array of EXPRESSION · DATA_SOURCE |
no | min items 1; max items 2; unique items; each: one of EXPRESSION · DATA_SOURCE |
Where the option list of a choice property may come from besides its declared enumValues. |
labels |
controlLocalizedText | no | Localized labels by BCP-47 tag (SCRUM-4858). | |
memberLabels |
object | no | max properties 500; keys: min length 1; max length 200; values: string; min length 1; max length 200 | Display labels of an ENUM property's members, by member value (SCRUM-4861). The member stays the stored and delivered value; a label never replaces one. Keys must be declared enumValues. |
memberLabelsByLocale |
object | no | max properties 40; keys: controlLocaleTag; values: object; max properties 500; keys: min length 1; max length 200; values: string; min length 1; max length 200 | Localized member labels by BCP-47 tag, then member value (SCRUM-4861). |
descriptions |
controlLocalizedDescription | no | Localized descriptions by BCP-47 tag (SCRUM-4858). | |
visibleWhen |
object | no | Declarative designer condition (SCRUM-4858): show this property only while another declared property's literal value is one of in. Never an expression. |
|
visibleWhen.property |
string | yes | pattern ^[a-z][A-Za-z0-9]{0,63}$ |
|
visibleWhen.in |
array of string or number or boolean | yes | min items 1; max items 50 | |
visibleWhen.… |
— | — | no other fields |
When sourceModes has max items 2 (and sourceModes is present), restrictionReason is required.
No other fields are accepted.
controlOutput
| Field | Type | Required | Bounds | Meaning |
|---|---|---|---|---|
key |
string | yes | pattern ^[a-z][A-Za-z0-9]{0,63}$ |
|
label |
string | yes | min length 1; max length 120 | |
valueType |
controlValueType | yes | ||
property |
string | yes | pattern ^[a-z][A-Za-z0-9]{0,63}$ |
The editable property this output writes back to. |
No other fields are accepted.
controlEvent
| Field | Type | Required | Bounds | Meaning |
|---|---|---|---|---|
key |
string | yes | pattern ^[a-z][A-Za-z0-9]{0,63}$ |
|
label |
string | yes | min length 1; max length 120 | |
description |
string | no | max length 1000 | |
payload |
array of object | no | max items 30 | |
payload[].name |
string | yes | pattern ^[a-z][A-Za-z0-9]{0,63}$ |
|
payload[].valueType |
controlValueType | yes | ||
payload[].… |
— | — | no other fields |
No other fields are accepted.
controlLocalizedText
Type: object; max properties 40; keys: pattern ^(([A-Za-z]{2,3}(-[A-Za-z]{3}){0,3}|[A-Za-z]{4,8})(-[A-Za-z]{4})?(-([A-Za-z]{2}|[0-9]{3}))?(-([A-Za-z0-9]{5,8}|[0-9][A-Za-z0-9]{3}))*(-[0-9A-WY-Za-wy-z](-[A-Za-z0-9]{2,8})+)*(-[Xx](-[A-Za-z0-9]{1,8})+)?|[Xx](-[A-Za-z0-9]{1,8})+|[Cc][Ee][Ll]\-[Gg][Aa][Uu][Ll][Ii][Ss][Hh]|[Ii]\-[Ee][Nn][Oo][Cc][Hh][Ii][Aa][Nn]|[Aa][Rr][Tt]\-[Ll][Oo][Jj][Bb][Aa][Nn]|[Zz][Hh]\-[Mm][Ii][Nn]\-[Nn][Aa][Nn]|[Ee][Nn]\-[Gg][Bb]\-[Oo][Ee][Dd]|[Ii]\-[Dd][Ee][Ff][Aa][Uu][Ll][Tt]|[Ii]\-[Kk][Ll][Ii][Nn][Gg][Oo][Nn]|[Ss][Gg][Nn]\-[Bb][Ee]\-[Ff][Rr]|[Ss][Gg][Nn]\-[Bb][Ee]\-[Nn][Ll]|[Ss][Gg][Nn]\-[Cc][Hh]\-[Dd][Ee]|[Ii]\-[Nn][Aa][Vv][Aa][Jj][Oo]|[Zz][Hh]\-[Gg][Uu][Oo][Yy][Uu]|[Zz][Hh]\-[Hh][Aa][Kk][Kk][Aa]|[Zz][Hh]\-[Xx][Ii][Aa][Nn][Gg]|[Ii]\-[Mm][Ii][Nn][Gg][Oo]|[Nn][Oo]\-[Bb][Oo][Kk]|[Nn][Oo]\-[Nn][Yy][Nn]|[Zz][Hh]\-[Mm][Ii][Nn]|[Ii]\-[Aa][Mm][Ii]|[Ii]\-[Bb][Nn][Nn]|[Ii]\-[Hh][Aa][Kk]|[Ii]\-[Ll][Uu][Xx]|[Ii]\-[Pp][Ww][Nn]|[Ii]\-[Tt][Aa][Oo]|[Ii]\-[Tt][Aa][Yy]|[Ii]\-[Tt][Ss][Uu])$; values: string; min length 1; max length 120.
Keys: pattern ^(([A-Za-z]{2,3}(-[A-Za-z]{3}){0,3}|[A-Za-z]{4,8})(-[A-Za-z]{4})?(-([A-Za-z]{2}|[0-9]{3}))?(-([A-Za-z0-9]{5,8}|[0-9][A-Za-z0-9]{3}))*(-[0-9A-WY-Za-wy-z](-[A-Za-z0-9]{2,8})+)*(-[Xx](-[A-Za-z0-9]{1,8})+)?|[Xx](-[A-Za-z0-9]{1,8})+|[Cc][Ee][Ll]\-[Gg][Aa][Uu][Ll][Ii][Ss][Hh]|[Ii]\-[Ee][Nn][Oo][Cc][Hh][Ii][Aa][Nn]|[Aa][Rr][Tt]\-[Ll][Oo][Jj][Bb][Aa][Nn]|[Zz][Hh]\-[Mm][Ii][Nn]\-[Nn][Aa][Nn]|[Ee][Nn]\-[Gg][Bb]\-[Oo][Ee][Dd]|[Ii]\-[Dd][Ee][Ff][Aa][Uu][Ll][Tt]|[Ii]\-[Kk][Ll][Ii][Nn][Gg][Oo][Nn]|[Ss][Gg][Nn]\-[Bb][Ee]\-[Ff][Rr]|[Ss][Gg][Nn]\-[Bb][Ee]\-[Nn][Ll]|[Ss][Gg][Nn]\-[Cc][Hh]\-[Dd][Ee]|[Ii]\-[Nn][Aa][Vv][Aa][Jj][Oo]|[Zz][Hh]\-[Gg][Uu][Oo][Yy][Uu]|[Zz][Hh]\-[Hh][Aa][Kk][Kk][Aa]|[Zz][Hh]\-[Xx][Ii][Aa][Nn][Gg]|[Ii]\-[Mm][Ii][Nn][Gg][Oo]|[Nn][Oo]\-[Bb][Oo][Kk]|[Nn][Oo]\-[Nn][Yy][Nn]|[Zz][Hh]\-[Mm][Ii][Nn]|[Ii]\-[Aa][Mm][Ii]|[Ii]\-[Bb][Nn][Nn]|[Ii]\-[Hh][Aa][Kk]|[Ii]\-[Ll][Uu][Xx]|[Ii]\-[Pp][Ww][Nn]|[Ii]\-[Tt][Aa][Oo]|[Ii]\-[Tt][Aa][Yy]|[Ii]\-[Tt][Ss][Uu])$.
Values: string; min length 1; max length 120.
controlLocalizedDescription
Type: object; max properties 40; keys: pattern ^(([A-Za-z]{2,3}(-[A-Za-z]{3}){0,3}|[A-Za-z]{4,8})(-[A-Za-z]{4})?(-([A-Za-z]{2}|[0-9]{3}))?(-([A-Za-z0-9]{5,8}|[0-9][A-Za-z0-9]{3}))*(-[0-9A-WY-Za-wy-z](-[A-Za-z0-9]{2,8})+)*(-[Xx](-[A-Za-z0-9]{1,8})+)?|[Xx](-[A-Za-z0-9]{1,8})+|[Cc][Ee][Ll]\-[Gg][Aa][Uu][Ll][Ii][Ss][Hh]|[Ii]\-[Ee][Nn][Oo][Cc][Hh][Ii][Aa][Nn]|[Aa][Rr][Tt]\-[Ll][Oo][Jj][Bb][Aa][Nn]|[Zz][Hh]\-[Mm][Ii][Nn]\-[Nn][Aa][Nn]|[Ee][Nn]\-[Gg][Bb]\-[Oo][Ee][Dd]|[Ii]\-[Dd][Ee][Ff][Aa][Uu][Ll][Tt]|[Ii]\-[Kk][Ll][Ii][Nn][Gg][Oo][Nn]|[Ss][Gg][Nn]\-[Bb][Ee]\-[Ff][Rr]|[Ss][Gg][Nn]\-[Bb][Ee]\-[Nn][Ll]|[Ss][Gg][Nn]\-[Cc][Hh]\-[Dd][Ee]|[Ii]\-[Nn][Aa][Vv][Aa][Jj][Oo]|[Zz][Hh]\-[Gg][Uu][Oo][Yy][Uu]|[Zz][Hh]\-[Hh][Aa][Kk][Kk][Aa]|[Zz][Hh]\-[Xx][Ii][Aa][Nn][Gg]|[Ii]\-[Mm][Ii][Nn][Gg][Oo]|[Nn][Oo]\-[Bb][Oo][Kk]|[Nn][Oo]\-[Nn][Yy][Nn]|[Zz][Hh]\-[Mm][Ii][Nn]|[Ii]\-[Aa][Mm][Ii]|[Ii]\-[Bb][Nn][Nn]|[Ii]\-[Hh][Aa][Kk]|[Ii]\-[Ll][Uu][Xx]|[Ii]\-[Pp][Ww][Nn]|[Ii]\-[Tt][Aa][Oo]|[Ii]\-[Tt][Aa][Yy]|[Ii]\-[Tt][Ss][Uu])$; values: string; min length 1; max length 1000.
Keys: pattern ^(([A-Za-z]{2,3}(-[A-Za-z]{3}){0,3}|[A-Za-z]{4,8})(-[A-Za-z]{4})?(-([A-Za-z]{2}|[0-9]{3}))?(-([A-Za-z0-9]{5,8}|[0-9][A-Za-z0-9]{3}))*(-[0-9A-WY-Za-wy-z](-[A-Za-z0-9]{2,8})+)*(-[Xx](-[A-Za-z0-9]{1,8})+)?|[Xx](-[A-Za-z0-9]{1,8})+|[Cc][Ee][Ll]\-[Gg][Aa][Uu][Ll][Ii][Ss][Hh]|[Ii]\-[Ee][Nn][Oo][Cc][Hh][Ii][Aa][Nn]|[Aa][Rr][Tt]\-[Ll][Oo][Jj][Bb][Aa][Nn]|[Zz][Hh]\-[Mm][Ii][Nn]\-[Nn][Aa][Nn]|[Ee][Nn]\-[Gg][Bb]\-[Oo][Ee][Dd]|[Ii]\-[Dd][Ee][Ff][Aa][Uu][Ll][Tt]|[Ii]\-[Kk][Ll][Ii][Nn][Gg][Oo][Nn]|[Ss][Gg][Nn]\-[Bb][Ee]\-[Ff][Rr]|[Ss][Gg][Nn]\-[Bb][Ee]\-[Nn][Ll]|[Ss][Gg][Nn]\-[Cc][Hh]\-[Dd][Ee]|[Ii]\-[Nn][Aa][Vv][Aa][Jj][Oo]|[Zz][Hh]\-[Gg][Uu][Oo][Yy][Uu]|[Zz][Hh]\-[Hh][Aa][Kk][Kk][Aa]|[Zz][Hh]\-[Xx][Ii][Aa][Nn][Gg]|[Ii]\-[Mm][Ii][Nn][Gg][Oo]|[Nn][Oo]\-[Bb][Oo][Kk]|[Nn][Oo]\-[Nn][Yy][Nn]|[Zz][Hh]\-[Mm][Ii][Nn]|[Ii]\-[Aa][Mm][Ii]|[Ii]\-[Bb][Nn][Nn]|[Ii]\-[Hh][Aa][Kk]|[Ii]\-[Ll][Uu][Xx]|[Ii]\-[Pp][Ww][Nn]|[Ii]\-[Tt][Aa][Oo]|[Ii]\-[Tt][Aa][Yy]|[Ii]\-[Tt][Ss][Uu])$.
Values: string; min length 1; max length 1000.
controlLocaleTag
A well-formed BCP-47 (RFC 5646) language tag; repeated variants and singletons are refused by the validator.
Type: any JSON value; pattern ^(([A-Za-z]{2,3}(-[A-Za-z]{3}){0,3}|[A-Za-z]{4,8})(-[A-Za-z]{4})?(-([A-Za-z]{2}|[0-9]{3}))?(-([A-Za-z0-9]{5,8}|[0-9][A-Za-z0-9]{3}))*(-[0-9A-WY-Za-wy-z](-[A-Za-z0-9]{2,8})+)*(-[Xx](-[A-Za-z0-9]{1,8})+)?|[Xx](-[A-Za-z0-9]{1,8})+|[Cc][Ee][Ll]\-[Gg][Aa][Uu][Ll][Ii][Ss][Hh]|[Ii]\-[Ee][Nn][Oo][Cc][Hh][Ii][Aa][Nn]|[Aa][Rr][Tt]\-[Ll][Oo][Jj][Bb][Aa][Nn]|[Zz][Hh]\-[Mm][Ii][Nn]\-[Nn][Aa][Nn]|[Ee][Nn]\-[Gg][Bb]\-[Oo][Ee][Dd]|[Ii]\-[Dd][Ee][Ff][Aa][Uu][Ll][Tt]|[Ii]\-[Kk][Ll][Ii][Nn][Gg][Oo][Nn]|[Ss][Gg][Nn]\-[Bb][Ee]\-[Ff][Rr]|[Ss][Gg][Nn]\-[Bb][Ee]\-[Nn][Ll]|[Ss][Gg][Nn]\-[Cc][Hh]\-[Dd][Ee]|[Ii]\-[Nn][Aa][Vv][Aa][Jj][Oo]|[Zz][Hh]\-[Gg][Uu][Oo][Yy][Uu]|[Zz][Hh]\-[Hh][Aa][Kk][Kk][Aa]|[Zz][Hh]\-[Xx][Ii][Aa][Nn][Gg]|[Ii]\-[Mm][Ii][Nn][Gg][Oo]|[Nn][Oo]\-[Bb][Oo][Kk]|[Nn][Oo]\-[Nn][Yy][Nn]|[Zz][Hh]\-[Mm][Ii][Nn]|[Ii]\-[Aa][Mm][Ii]|[Ii]\-[Bb][Nn][Nn]|[Ii]\-[Hh][Aa][Kk]|[Ii]\-[Ll][Uu][Xx]|[Ii]\-[Pp][Ww][Nn]|[Ii]\-[Tt][Aa][Oo]|[Ii]\-[Tt][Aa][Yy]|[Ii]\-[Tt][Ss][Uu])$.
controlValueType
The canonical platform value-type descriptor (spec 489 contracts/value-types.md). AUTO_NUMBER and BINARY are excluded for controls (InterfaceControlContract.EXCLUDED_VALUE_KINDS).
| Field | Type | Required | Bounds | Meaning |
|---|---|---|---|---|
kind |
TEXT · INTEGER · LONG · DECIMAL · BOOLEAN · DATE · TIME · LOCAL_DATETIME · INSTANT · UUID · JSON · ENUM · DOCUMENT · USER · GROUP · FOLDER · CABINET · LIFECYCLE_REF · FUNCTION_REF · RECORD · RECORD_REF |
yes | ||
cardinality |
ONE · MANY |
no | ||
nullable |
boolean | no | ||
itemNullable |
boolean | no | ||
schemaRef |
string | no | min length 1; max length 512 | |
enumValues |
array of string | no | max items 500; unique items; each: min length 1; max length 200 | |
minLength |
integer | no | minimum 0 | |
maxLength |
integer | no | minimum 0 | |
minItems |
integer | no | minimum 0 | |
maxItems |
integer | no | minimum 0 | |
minInclusive |
string | no | max length 64 | |
maxInclusive |
string | no | max length 64 | |
precision |
integer | no | minimum 1; maximum 1000 | |
scale |
integer | no | minimum 0; maximum 1000 | |
referenceMode |
PRESERVE · CURRENT · PINNED |
no |
When kind is RECORD or RECORD_REF (and kind is present), schemaRef is required.
No other fields are accepted.
controlAsset
| Field | Type | Required | Bounds | Meaning |
|---|---|---|---|---|
path |
controlRelativePath | yes | ||
contentType |
text/javascript · text/css · application/json · application/source-map · image/png · image/svg+xml · font/woff2 |
yes | ||
sha256 |
string | yes | pattern ^[0-9a-f]{64}$ |
|
size |
integer | yes | minimum 0; maximum 10485760 |
No other fields are accepted.
controlProvider
An external service the controls call from the browser. Declared for review and environment configuration; it grants nothing.
| Field | Type | Required | Bounds | Meaning |
|---|---|---|---|---|
key |
string | yes | pattern ^[a-z][a-z0-9-]{0,63}$ |
|
purpose |
string | yes | min length 1; max length 300 | |
origins |
array of string | yes | min items 1; max items 20; unique items; each: pattern ^https://([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]([a-z0-9-]{0,61}[a-z0-9])?(:([1-9][0-9]{0,3}|[1-5][0-9]{4}|6[0-4][0-9]{3}|65[0-4][0-9]{2}|655[0-2][0-9]|6553[0-5]))?$ |
|
dataCategories |
array of none · location · address · personal-name · contact · record-identifier · free-text · usage |
no | max items 8; unique items; each: one of none · location · address · personal-name · contact · record-identifier · free-text · usage |
What the provider receives from the browser, disclosed at review (SCRUM-4871). |
configuration |
array of providerConfiguration | no | max items 10 | Environment configuration the provider needs. browserPublic values are intentionally visible in the browser (a restricted key, a map id); serverSecret values are stored only as vault references and never reach the browser (SCRUM-4871). |
No other fields are accepted.
providerConfiguration
| Field | Type | Required | Bounds | Meaning |
|---|---|---|---|---|
key |
string | yes | pattern ^[a-z][a-zA-Z0-9]{0,63}$ |
|
classification |
browserPublic · serverSecret |
yes | ||
label |
string | yes | min length 1; max length 120 | |
required |
boolean | no |
No other fields are accepted.
controlRelativePath
A relative archive path: no leading slash, no scheme, no backslash and no '.' or '..' segment.
Type: string; pattern ^[A-Za-z0-9_-][A-Za-z0-9._-]{0,127}(/[A-Za-z0-9_-][A-Za-z0-9._-]{0,127}){0,15}$.
SDK API: @inflowai/control-sdk
Generated from inflow-control-sdk/api/control-sdk.api.d.ts, the reviewed public API of @inflowai/control-sdk. Every export is listed.
| Export | Kind | Module |
|---|---|---|
CONTROL_ABI_VERSION |
const | abi |
CONTROL_CONTRACT_VERSION |
const | abi |
ControlMode |
type | abi |
TextDirection |
type | abi |
PropertyState |
type | abi |
ThemeTokens |
interface | abi |
Size |
interface | abi |
HostResult |
type | abi |
HostRefusal |
type | abi |
ControlError |
interface | abi |
HostServices |
interface | abi |
ControlContext |
interface | abi |
ControlUpdate |
interface | abi |
ControlInstance |
interface | abi |
ControlModule |
interface | abi |
ControlDefinition |
interface | abi |
defineControl |
function | abi |
ControlModuleProblem |
type | abi |
checkControlModule |
function | abi |
VALUE_KINDS |
const | declaration |
ValueKind |
type | declaration |
SOURCE_MODES |
const | declaration |
SourceMode |
type | declaration |
ValueTypeDeclaration |
interface | declaration |
PropertyDeclaration |
interface | declaration |
OutputDeclaration |
interface | declaration |
EventFieldDeclaration |
interface | declaration |
EventDeclaration |
interface | declaration |
ControlDeclaration |
interface | declaration |
JsonValue |
type | declaration |
DocumentReference |
interface | declaration |
UserReference |
interface | declaration |
GroupReference |
interface | declaration |
FolderReference |
interface | declaration |
CabinetReference |
interface | declaration |
LifecycleReference |
interface | declaration |
FunctionReference |
interface | declaration |
RecordReference |
interface | declaration |
RecordValue |
type | declaration |
ScalarValueOf |
type | declaration |
ValueOf |
type | declaration |
PropertiesOf |
type | declaration |
OutputsOf |
type | declaration |
PayloadOf |
type | declaration |
EventsOf |
type | declaration |
CONTROL_ABI_VERSION
The lifecycle ABI version this SDK implements. A host refuses modules built for a different ABI.
export declare const CONTROL_ABI_VERSION: 1;
CONTROL_CONTRACT_VERSION
The control-contract version (interfaceControls.contractVersion in plugin.json) this SDK targets.
export declare const CONTROL_CONTRACT_VERSION: 1;
ControlMode
Where the control is running. Design and preview supply synthetic data and suppress business effects.
export type ControlMode = 'design' | 'preview' | 'runtime';
TextDirection
Layout direction of the surrounding interface. Controls must mirror horizontally for rtl.
export type TextDirection = 'ltr' | 'rtl';
PropertyState
Resolution state of one property. invalid and error carry a reason a person can act on. The control renders
the shared unavailable state rather than guessing a value.
export type PropertyState = {
readonly status: 'ready';
} | {
readonly status: 'loading';
} | {
readonly status: 'empty';
} | {
readonly status: 'invalid';
readonly reason: string;
} | {
readonly status: 'error';
readonly reason: string;
} | {
readonly status: 'unavailable';
};
ThemeTokens
Design tokens the control should use instead of raw colours, so it follows the interface theme. The keys are the
platform's public token vocabulary (surface, surfaceRaised, text, textMuted, border, accent, danger,
warning, radius, spaceSmall, ...); the values are CSS custom-property references (for example var(--surface)),
never literal colours. Light and dark deliver the same references: the page redefines the variables.
export interface ThemeTokens {
readonly [token: string]: string;
}
Size
A pixel size of the host element.
export interface Size {
readonly width: number;
readonly height: number;
}
HostResult
Outcome of a request the host may refuse. The control must not assume success.
export type HostResult = {
readonly accepted: true;
} | {
readonly accepted: false;
readonly reason: HostRefusal;
};
HostRefusal
Why the host refused. not-ready: the instance is loading, hidden, frozen or disposed. not-declared: the key is
not in the reviewed declaration. invalid-value: the value does not match the declared type. suppressed:
design/preview mode never performs business effects. unchanged: an output equal to the current value is not an
edit (echo guard).
export type HostRefusal = 'not-ready' | 'not-declared' | 'invalid-value' | 'suppressed' | 'unchanged';
ControlError
A failure the control reports so the host can show the shared error state. Never include secrets or payloads.
export interface ControlError {
readonly code: string;
readonly message: string;
}
HostServices
What the host lets a control do. Every effect is validated by the host against the reviewed declaration and the instance's current lifetime, and every business effect is re-authorized by the platform at its service boundary.
export interface HostServices<Outputs = Record<string, unknown>, Events = Record<string, unknown>> {
/**
* Proposes a user edit of a declared editable output. The host validates it and places it in the interface's
* existing draft (dirty/validation/save/cancel). It never persists anything by itself. Call only for genuine user
* interaction, never to mirror a value the host just pushed.
*/
setOutput<K extends keyof Outputs & string>(key: K, value: Outputs[K]): HostResult;
/**
* Emits a declared event from a genuine user interaction. The host routes it to the actions the interface author
* configured. Mounting, rendering and refreshing must never emit events.
*/
emit<K extends keyof Events & string>(event: K, payload: Events[K]): HostResult;
/** Reports a failure; the host shows the shared error state and keeps the authored configuration. */
reportError(error: ControlError): void;
/** Marks the control busy (for example while a provider library loads) so the host can show a loading state. */
setBusy(busy: boolean): void;
/** Announces a short message to assistive technology through the host's live region. */
announce(message: string): void;
/**
* Asks for the choices of a property whose options the server searches (SCRUM-4862), narrowed by `text` (at most 160
* characters; empty text asks for the first page). The host debounces, bounds and authorizes the read and delivers
* the result through {@link ControlInstance.update} as that property's `options`. `not-declared` when that
* property's choices are not searched on the server; `invalid-value` when `text` is not short text.
*/
searchOptions(key: string, text: string): HostResult;
/**
* Adopts the control's own CSS (T020). The host scopes it to this instance's root element with `@scope`, so it styles
* nothing else on the page, and removes it when the instance is disposed. A new call replaces the previous sheet. At
* most 64 KiB; anything else is `invalid-value`. Use theme tokens (`context.theme`) rather than literal colours. This is
* visual containment for trusted code, not a security sandbox: never inject global styles yourself.
*/
adoptStyles(css: string): HostResult;
/** Registers a cleanup run exactly once at dispose, in reverse registration order. */
onDispose(cleanup: () => void): void;
/** Aborted when the instance is disposed or replaced. Pass it to every timer, listener and request. */
readonly signal: AbortSignal;
}
ControlContext
Everything the host gives an instance at mount.
export interface ControlContext<Properties = Record<string, unknown>, Outputs = Record<string, unknown>, Events = Record<string, unknown>> {
/** Stable for the instance's lifetime; distinct for every placed instance, even of the same control. */
readonly instanceId: string;
/** Resolved, typed property values. Never expression source text. */
readonly properties: Readonly<Properties>;
/** Per-property resolution state. */
readonly propertyStates: Readonly<Record<keyof Properties & string, PropertyState>>;
readonly mode: ControlMode;
readonly locale: string;
readonly direction: TextDirection;
readonly theme: ThemeTokens;
/** Browser-public environment configuration an administrator saved for this package's providers (never secrets). */
readonly configuration: Readonly<Record<string, string>>;
/**
* The keys of the reviewed providers an administrator admitted for real loading in this environment (SCRUM-4871). A
* control loads a provider only when its key is listed here, whether or not it has configuration values; empty in
* design and preview, and whenever loading is not admitted (the control shows its offline alternative).
*/
readonly providers?: readonly string[];
/** Dynamic option lists by property key, for properties that declare `dynamicOptions` and are configured with one. */
readonly options?: Readonly<Record<string, PropertyOptions>>;
readonly size: Size;
readonly host: HostServices<Outputs, Events>;
}
ControlUpdate
A change the host pushes to a mounted instance. Only changed parts are present.
export interface ControlUpdate<Properties = Record<string, unknown>> {
readonly properties?: Readonly<Partial<Properties>>;
readonly propertyStates?: Readonly<Partial<Record<keyof Properties & string, PropertyState>>>;
readonly options?: Readonly<Record<string, PropertyOptions>>;
readonly direction?: TextDirection;
readonly locale?: string;
readonly theme?: ThemeTokens;
}
ControlInstance
A mounted control instance.
export interface ControlInstance<Properties = Record<string, unknown>> {
/** Applies pushed changes. Must not emit events or outputs as a result. */
update(update: ControlUpdate<Properties>): void;
/** Reacts to a size change of the host element. */
resize?(size: Size): void;
/**
* Releases everything: listeners, timers, provider objects, DOM. Must be idempotent. After dispose the host ignores
* every call the instance makes.
*/
dispose(): void;
}
ControlModule
What a control module exports. Build it with defineControl.
export interface ControlModule<Properties = Record<string, unknown>, Outputs = Record<string, unknown>, Events = Record<string, unknown>> {
readonly abi: typeof CONTROL_ABI_VERSION;
/** Must equal the `controlKey` of the control's reviewed declaration in plugin.json. */
readonly controlKey: string;
mount(element: HTMLElement, context: ControlContext<Properties, Outputs, Events>): ControlInstance<Properties> | Promise<ControlInstance<Properties>>;
}
ControlDefinition
The definition passed to defineControl.
export interface ControlDefinition<Properties, Outputs, Events> {
readonly controlKey: string;
mount(element: HTMLElement, context: ControlContext<Properties, Outputs, Events>): ControlInstance<Properties> | Promise<ControlInstance<Properties>>;
}
defineControl
Defines a control module. Use it as the module's default export:
export default defineControl<Props, Outputs, Events>({ controlKey: 'service-visits-map', mount(element, ctx) { ... } });
export declare function defineControl<Properties = Record<string, unknown>, Outputs = Record<string, unknown>, Events = Record<string, unknown>>(definition: ControlDefinition<Properties, Outputs, Events>): ControlModule<Properties, Outputs, Events>;
ControlModuleProblem
Why a value is not a usable control module for this ABI.
export type ControlModuleProblem = 'not-an-object' | 'abi-mismatch' | 'bad-control-key' | 'no-mount' | 'key-mismatch';
checkControlModule
Checks a loaded module's default export against this ABI without calling it. Hosts and tools use it before mount.
@param expectedControlKey the reviewed declaration's control key, when known
export declare function checkControlModule(candidate: unknown, expectedControlKey?: string): {
readonly ok: true;
readonly module: ControlModule;
} | {
readonly ok: false;
readonly problem: ControlModuleProblem;
};
VALUE_KINDS
The canonical platform value kinds a control may declare (AUTO_NUMBER and BINARY are excluded for controls). The package's tests pin this list to the host schema.
export declare const VALUE_KINDS: readonly ["TEXT", "INTEGER", "LONG", "DECIMAL", "BOOLEAN", "DATE", "TIME", "LOCAL_DATETIME", "INSTANT", "UUID", "JSON", "ENUM", "DOCUMENT", "USER", "GROUP", "FOLDER", "CABINET", "LIFECYCLE_REF", "FUNCTION_REF", "RECORD", "RECORD_REF"];
ValueKind
One of VALUE_KINDS: the valueType.kind of a declared property, output or event field.
export type ValueKind = (typeof VALUE_KINDS)[number];
SOURCE_MODES
Where a property value may come from.
export declare const SOURCE_MODES: readonly ["LITERAL", "EXPRESSION", "BINDING"];
SourceMode
One of SOURCE_MODES: a typed literal, an expression the host evaluates, or a binding to form data.
export type SourceMode = (typeof SOURCE_MODES)[number];
ValueTypeDeclaration
The canonical platform value type of a property, output or event field (valueType in plugin.json). Facets
(lengths, item counts, inclusive bounds, precision and scale) are enforced by the host before a value reaches the
control and when the control proposes one. schemaRef is required for RECORD and RECORD_REF.
export interface ValueTypeDeclaration {
readonly kind: ValueKind;
readonly cardinality?: 'ONE' | 'MANY';
readonly nullable?: boolean;
readonly itemNullable?: boolean;
readonly schemaRef?: string;
readonly enumValues?: readonly string[];
readonly minLength?: number;
readonly maxLength?: number;
readonly minItems?: number;
readonly maxItems?: number;
readonly minInclusive?: string;
readonly maxInclusive?: string;
readonly precision?: number;
readonly scale?: number;
readonly referenceMode?: 'PRESERVE' | 'CURRENT' | 'PINNED';
}
PropertyDeclaration
One designer property of a control. The interface author supplies its value as a literal, an expression or a
binding (only the declared sourceModes; restricting them requires a restrictionReason). The control receives
the resolved, typed value in context.properties[key], never expression text.
export interface PropertyDeclaration {
readonly key: string;
readonly label: string;
readonly description?: string;
readonly group?: string;
readonly valueType: ValueTypeDeclaration;
readonly sourceModes: readonly SourceMode[];
readonly restrictionReason?: string;
readonly default?: unknown;
readonly readOnly?: boolean;
readonly dynamicOptions?: readonly ('EXPRESSION' | 'DATA_SOURCE')[];
/** Localized labels and descriptions by BCP-47 tag (for example `ar`, `en-GB`). */
readonly labels?: Readonly<Record<string, string>>;
/** Display labels of an ENUM property's members, by member value. The member, never its label, is what a control receives. */
readonly memberLabels?: Readonly<Record<string, string>>;
/** Localized member labels by BCP-47 tag, then member value. */
readonly memberLabelsByLocale?: Readonly<Record<string, Readonly<Record<string, string>>>>;
readonly descriptions?: Readonly<Record<string, string>>;
/** Show this property in the designer only while another declared property's literal value is one of `in`. */
readonly visibleWhen?: {
readonly property: string;
readonly in: readonly (string | number | boolean)[];
};
}
OutputDeclaration
An editable value the control may propose with host.setOutput(key, value). It writes back to the declared
property only when that property is bound to form data; the edit lands in the interface's draft, never saved
by the control.
export interface OutputDeclaration {
readonly key: string;
readonly label: string;
readonly valueType: ValueTypeDeclaration;
/** The editable property this output writes back to. */
readonly property: string;
}
EventFieldDeclaration
One typed field of an event payload. Payload field names may not use reserved keys.
export interface EventFieldDeclaration {
readonly name: string;
readonly valueType: ValueTypeDeclaration;
}
EventDeclaration
A user interaction the control may report with host.emit(key, payload). The interface author decides which
actions run for it; they run with the current user's authority.
export interface EventDeclaration {
readonly key: string;
readonly label: string;
readonly description?: string;
readonly payload?: readonly EventFieldDeclaration[];
}
ControlDeclaration
One control of a package (an entry of interfaceControls.controls). controlKey is the stable machine key and
entry the declared JavaScript module asset the host loads. Declare it as const to derive typed properties,
outputs and events.
export interface ControlDeclaration {
readonly controlKey: string;
readonly displayName: string;
readonly description?: string;
readonly icon?: string;
readonly category?: string;
readonly entry: string;
readonly properties?: readonly PropertyDeclaration[];
readonly outputs?: readonly OutputDeclaration[];
readonly events?: readonly EventDeclaration[];
}
JsonValue
Any JSON value (the JSON kind is explicitly untyped and never a reference authority).
export type JsonValue = string | number | boolean | null | readonly JsonValue[] | {
readonly [key: string]: JsonValue;
};
DocumentReference
A reference to a document, optionally a version (DOCUMENT values). References match the platform's reference JSON objects.
export interface DocumentReference {
readonly kind: 'document';
readonly documentId: string;
readonly versionNumber?: number;
readonly name?: string;
readonly mimeType?: string;
readonly sizeBytes?: number;
}
UserReference
A reference to a platform user (USER values).
export interface UserReference {
readonly kind: 'user';
readonly userId: string;
}
GroupReference
A reference to a platform group (GROUP values).
export interface GroupReference {
readonly kind: 'group';
readonly groupId: string;
}
FolderReference
A reference to a folder (FOLDER values).
export interface FolderReference {
readonly kind: 'folder';
readonly folderId: string;
}
CabinetReference
A reference to a cabinet (CABINET values).
export interface CabinetReference {
readonly kind: 'cabinet';
readonly cabinetId: string;
}
LifecycleReference
A reference to a lifecycle definition, optionally pinned to a version (LIFECYCLE_REF values).
export interface LifecycleReference {
readonly kind: 'lifecycle';
readonly key: string;
readonly version?: number;
}
FunctionReference
A reference to a platform function, optionally pinned to a version (FUNCTION_REF values).
export interface FunctionReference {
readonly kind: 'function';
readonly key: string;
readonly version?: number;
}
RecordReference
A reference to a record of the declared schemaRef (RECORD_REF values).
export interface RecordReference {
readonly kind: 'record';
readonly schemaRef: string;
readonly recordId: string;
}
RecordValue
A record value: an object validated by the host against the declared schemaRef.
export type RecordValue = {
readonly [field: string]: JsonValue | RecordValue | readonly RecordValue[];
};
ScalarValueOf
The single (ONE) value type of a declared kind. LONG and DECIMAL arrive as canonical text, never as JS numbers, so no precision is lost; temporal kinds arrive as ISO text.
export type ScalarValueOf<T extends ValueTypeDeclaration> = T['kind'] extends 'TEXT' | 'LONG' | 'DECIMAL' | 'DATE' | 'TIME' | 'LOCAL_DATETIME' | 'INSTANT' | 'UUID' ? string : T['kind'] extends 'INTEGER' ? number : T['kind'] extends 'BOOLEAN' ? boolean : T['kind'] extends 'JSON' ? JsonValue : T['kind'] extends 'ENUM' ? (T['enumValues'] extends readonly (infer Member)[] ? Member : string) : T['kind'] extends 'DOCUMENT' ? DocumentReference : T['kind'] extends 'USER' ? UserReference : T['kind'] extends 'GROUP' ? GroupReference : T['kind'] extends 'FOLDER' ? FolderReference : T['kind'] extends 'CABINET' ? CabinetReference : T['kind'] extends 'LIFECYCLE_REF' ? LifecycleReference : T['kind'] extends 'FUNCTION_REF' ? FunctionReference : T['kind'] extends 'RECORD' ? RecordValue : T['kind'] extends 'RECORD_REF' ? RecordReference : never;
ValueOf
The full value type: cardinality, item nullability and nullability applied.
export type ValueOf<T extends ValueTypeDeclaration> = (T['cardinality'] extends 'MANY' ? ReadonlyArray<ScalarValueOf<T> | (T['itemNullable'] extends true ? null : never)> : ScalarValueOf<T>) | (T['nullable'] extends true ? null : never);
type Entries<T> = T extends readonly (infer E)[] ? E : never;
PropertiesOf
The resolved property values of a declared control.
export type PropertiesOf<C extends ControlDeclaration> = {
readonly [P in Entries<NonNullable<C['properties']>> as P['key']]: ValueOf<P['valueType']>;
};
OutputsOf
The editable outputs of a declared control, keyed by output key.
export type OutputsOf<C extends ControlDeclaration> = {
readonly [O in Entries<NonNullable<C['outputs']>> as O['key']]: ValueOf<O['valueType']>;
};
PayloadOf
The payload object of a declared event.
export type PayloadOf<E extends EventDeclaration> = {
readonly [F in Entries<NonNullable<E['payload']>> as F['name']]: ValueOf<F['valueType']>;
};
EventsOf
The events of a declared control, keyed by event key, with their payloads.
export type EventsOf<C extends ControlDeclaration> = {
readonly [E in Entries<NonNullable<C['events']>> as E['key']]: PayloadOf<E>;
};
export {};
Test-kit API: @inflowai/control-test-kit
Generated from inflow-control-test-kit/api/control-test-kit.api.d.ts, the reviewed public API of @inflowai/control-test-kit. Every export is listed.
| Export | Kind | Module |
|---|---|---|
PropertyOptions |
type | host |
MOCKED_BOUNDARY |
const | host |
RecordedCall |
interface | host |
MountOptions |
interface | host |
TestHarness |
interface | host |
mountForTest |
function | host |
OFFLINE_CONTENT_SECURITY_POLICY |
const | conformance |
ConformanceCheck |
interface | conformance |
ConformanceReport |
interface | conformance |
ConformanceOptions |
interface | conformance |
runConformance |
function | conformance |
valueMatches |
function | values |
valueProblem |
function | values |
PropertySource |
interface | outputs |
routeOutput |
function | outputs |
SAMPLE_VALUES |
const | fixtures |
INVALID_VALUES |
const | fixtures |
typeFixtures |
function | fixtures |
PROPERTY_STATES |
const | fixtures |
OPTIONS |
const | fixtures |
optionsRace |
function | fixtures |
BINDING_SEQUENCE |
const | fixtures |
THEME_TOKENS |
const | fixtures |
THEMES |
const | fixtures |
PALETTES |
const | fixtures |
RTL |
const | fixtures |
PROVIDERS |
const | fixtures |
accessibleAlternativeProblems |
function | accessibility |
keyboardReachProblems |
function | accessibility |
incompatibleModules |
function | compatibility |
incompatibleDeclarations |
function | compatibility |
PropertyOptions
One property's dynamic option list, as the host delivers it in context.options.
export type PropertyOptions = NonNullable<ControlContext['options']>[string];
MOCKED_BOUNDARY
The label every harness carries. The test kit simulates the Inflow host so a control can be developed and checked in isolation; it is a mocked boundary. Passing its checks is never evidence that a control works on the platform, with a real provider, or for real users: that is shown only by the platform's own acceptance on a real server.
export declare const MOCKED_BOUNDARY: 'MOCKED HOST: simulated Inflow host services, not platform or provider acceptance';
RecordedCall
One call a control made to its host, in order, with the lifecycle phase it happened in.
export interface RecordedCall {
readonly service: 'setOutput' | 'emit' | 'reportError' | 'setBusy' | 'announce' | 'searchOptions' | 'adoptStyles';
readonly phase: 'mount' | 'update' | 'resize' | 'idle' | 'retired';
readonly args: readonly unknown[];
readonly result?: HostResult;
/** Whether a simulated interaction (`interact` or `press`) on this harness came before the call (review r76). */
readonly afterInteraction: boolean;
}
MountOptions
How mountForTest mounts a control: its reviewed declaration plus the mode, property values and states,
property sources, options, theme and palette, direction, locale, provider configuration, size and document the
simulated host supplies.
export interface MountOptions {
/** The control's reviewed declaration (its plugin.json entry). Outputs, events and value types are checked against it. */
readonly declaration: ControlDeclaration;
readonly mode?: ControlMode;
readonly properties?: Readonly<Record<string, unknown>>;
readonly propertyStates?: Readonly<Record<string, PropertyState>>;
/**
* Where each property's value comes from on the placed node. An output writes only a property bound to form data
* (`BINDING`). By default every property an output targets is bound (`locals:<key>`) and the others are literals.
*/
readonly sources?: Readonly<Record<string, PropertySource>>;
readonly options?: Readonly<Record<string, PropertyOptions>>;
/** The theme tokens (default: Studio's own vocabulary, `THEME_TOKENS`). */
readonly theme?: ThemeTokens;
/** The page palette the tokens resolve to (default `light`): the variables the page defines, see `PALETTES`. */
readonly palette?: 'light' | 'dark';
readonly direction?: TextDirection;
readonly locale?: string;
/** Browser-public provider configuration, as an administrator would admit it (SDK 1.1). Empty by default. */
readonly configuration?: Readonly<Record<string, string>>;
/** Providers admitted for real loading (SDK 1.1). Empty by default: the control must stay offline. */
readonly providers?: readonly string[];
readonly size?: Size;
/** The document to mount into (jsdom, happy-dom or a real browser). Defaults to the global `document`. */
/** How long an asynchronous mount may take before it fails and is retired (default 10000 ms) (review r139). */
readonly mountTimeoutMs?: number;
readonly document?: Document;
}
TestHarness
A mounted control under the simulated host.
export interface TestHarness {
readonly boundary: typeof MOCKED_BOUNDARY;
/** The element the host owns and the control renders into (removed when the instance retires). */
readonly element: HTMLElement;
readonly context: ControlContext;
/** The control's own instance, as `mount` returned it (so a test can call `dispose` a second time, for example). */
readonly instance: ControlInstance;
/** Every host call, in order. */
readonly calls: readonly RecordedCall[];
/** The CSS the control last adopted, as accepted (null when none). */
readonly styles: string | null;
/** Whether the instance has retired (disposed, or after `reportError`). */
readonly disposed: boolean;
/** Whether the host shows the shared unavailable state (the control reported an error). */
readonly unavailable: boolean;
/** Failures the control's own `dispose` or cleanups threw; the host contains them. */
readonly teardownErrors: readonly unknown[];
/**
* Failures the control's `update` or `resize` threw, or an invalid instance `mount` returned. The host contains them
* and retires the instance with the unavailable state, as the platform does (review r75).
*/
readonly failures: readonly unknown[];
/** Pushes a change, as the host does when bindings, options, theme or direction change. */
update(change: ControlUpdate): void;
resize(size: Size): void;
/** Switches the page palette, as the page does on a theme change (the tokens stay the same, as on the platform). */
setPalette(palette: 'light' | 'dark'): void;
/**
* Simulates a person's interaction inside `target` (default: the control's element): it dispatches `pointerdown` and
* `mousedown` there, for the control's own handlers, and records the interaction as the page's latest. The record is
* explicit because a synthetic event is not trusted input in a real browser (review r75). As on the platform, the
* latest interaction anywhere on the page decides: one in another control, or outside every control, takes the
* licence away from this one.
*/
interact(target?: Element): void;
/**
* Simulates a person pressing `key` on `target` (default: the focused element, else the control's element): the
* interaction is recorded first, then `keydown` and `keyup` are dispatched there (review r76).
*/
press(key: string, target?: Element): void;
/** Retires the instance as the host does: abort the signal, run cleanups newest first, dispose once, remove the root. */
dispose(): void;
}
mountForTest
Mounts a control module under the simulated host (awaiting an asynchronous mount). The host services follow the
platform host (Studio's PluginControlHost), using Studio's own vendored rules for values, events, styles and
interaction provenance:
- nothing has an effect before the instance is ready or after it retires (
not-ready); - an undeclared output or event is
not-declared; design and preview suppress them (suppressed); - an output writes only a bound, writable, ready property, with a value of its exact declared type; an echo of the
delivered value is
unchanged; - an event needs a person's latest interaction on the page inside this control and never runs while the host is
calling into it (
suppressed); its payload is plain data of the declared fields, at most 16 KiB; reportErrorretires the instance and shows the unavailable state;- adopted styles are at most 64 KiB (UTF-8) and are rebuilt by the scoped-stylesheet validator, or refused.
export declare function mountForTest(module: unknown, options: MountOptions): Promise<TestHarness>;
OFFLINE_CONTENT_SECURITY_POLICY
The content security policy for running conformance in a real browser (review r84). The kit's offline check
intercepts and records the page's network paths, which makes a control's network use visible and fails the check;
in a browser, prevention is the policy's job: serve the test page with this header (or the equivalent meta tag) so
that nothing a control does reaches any server but the test server itself (connect-src 'self', which browser test
runners need). Inline scripts and styles stay allowed for test runners.
export declare const OFFLINE_CONTENT_SECURITY_POLICY: "default-src 'none'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; style-src 'self' 'unsafe-inline'; img-src data: blob:; font-src data:; connect-src 'self'; frame-src 'none'; worker-src 'none'; object-src 'none'; base-uri 'none'; form-action 'none'";
ConformanceCheck
One conformance check and what it found.
export interface ConformanceCheck {
readonly id: string;
readonly title: string;
readonly passed: boolean;
readonly problems: readonly string[];
}
ConformanceReport
The result of runConformance. Always labelled as a mocked boundary.
export interface ConformanceReport {
readonly boundary: typeof MOCKED_BOUNDARY;
readonly controlKey: string;
readonly passed: boolean;
readonly checks: readonly ConformanceCheck[];
}
ConformanceOptions
How runConformance exercises the control: the property values to mount with, the list alternative and
rendered choices to expect, property changes to apply, how long to let effects settle, and the document to use.
export interface ConformanceOptions {
/** Properties to mount with (default: a declaration-valid sample of each declared property's type). */
readonly properties?: Readonly<Record<string, unknown>>;
/** When the primary view is not accessible: the list alternative expected for `properties` (FR-024). */
readonly listAlternative?: {
readonly items: readonly string[];
readonly selected?: string | null;
};
/**
* How the control shows the choices it was given, for the options-race check. By default the check reads the
* element's text (the latest labels must appear and stale-only labels must not); a control that draws its choices
* (a canvas, a map) supplies this.
*/
readonly renderedChoices?: (element: HTMLElement) => readonly string[];
/**
* Values to change each property to, in order, for the binding-change scenario (default: generated from the
* declaration). A property whose domain admits another value must receive at least one real change (review r78).
*/
readonly changes?: Readonly<Record<string, readonly unknown[]>>;
/** How long to let deferred work (timers, microtasks) run before evaluating effects, in milliseconds (default 30). */
readonly settleMs?: number;
/** How long each asynchronous mount may take before it fails (default 10000 ms) (review r139). */
readonly mountTimeoutMs?: number;
readonly document?: Document;
}
runConformance
Runs the interface-control conformance checks against a module under the simulated host (SCRUM-4872): the ABI, declaration-valid inputs, every mode, no effects without a person's interaction (including deferred ones), clean and idempotent disposal in the host's order, every property state, an options race, theme and right-to-left, focus kept on update, offline without provider admission (the network intercepted for the whole run, deferred requests and those after disposal included), automation labels and (when given) the accessible list alternative. Runs are serialized. A mocked boundary: passing is not platform or provider acceptance.
export declare function runConformance(module: unknown, declaration: ControlDeclaration, options?: ConformanceOptions): Promise<ConformanceReport>;
valueMatches
Whether a value fits a declared value type, exactly as the platform's typed boundary decides: this is Studio's own
validator (resolvedValueProblem, vendored and kept identical by npm run verify), covering facets, ranges, calendar
dates, exact numbers, references, nullability and size limits.
export declare function valueMatches(type: ValueTypeDeclaration | undefined, value: unknown): boolean;
valueProblem
Why a value does not fit a declared value type (null when it fits), in the platform's words.
export declare function valueProblem(type: ValueTypeDeclaration, value: unknown): string | null;
PropertySource
Where a placed property's value comes from: a literal, an expression, or a binding to form data.
export interface PropertySource {
readonly mode: 'LITERAL' | 'EXPRESSION' | 'BINDING';
readonly bind?: string;
}
routeOutput
The simulated host's output routing. It follows Studio's routePluginOutput
(screens/plugin-controls/pluginOutputs.ts) step by step. Studio's parity test runs both over one matrix and requires
the same verdicts:
- undeclared →
not-declared; - a read-only property, or one not bound to form data →
suppressed; - a binding loading →
not-ready, and refused or computed states →suppressed; - a type that differs from the property's, or a value that does not fit it (Studio's vendored validator)
→
invalid-value; - an echo of the delivered value →
unchanged. The platform's destination check is simulated by kind (only TEXT, UUID, ENUM, INTEGER, BOOLEAN, DATE and TIME are ever written); whether the bound path itself is a declared, performer-owned value of that kind needs a real form, so a bound path is taken to be one.
export declare function routeOutput(input: {
readonly key: unknown;
readonly value: unknown;
readonly outputs: readonly {
readonly key: string;
readonly property?: unknown;
readonly valueType?: unknown;
}[];
readonly properties: readonly {
readonly key: string;
readonly readOnly?: unknown;
readonly valueType?: unknown;
}[];
readonly sources: Readonly<Record<string, PropertySource>>;
readonly states: Readonly<Record<string, PropertyState>>;
readonly delivered: Readonly<Record<string, unknown>>;
}): HostResult;
SAMPLE_VALUES
A valid sample of each declared kind, as the host delivers it (LONG and DECIMAL as exact text, temporal as ISO text).
export declare const SAMPLE_VALUES: Readonly<Record<ValueKind, unknown>>;
INVALID_VALUES
A value of the wrong shape for each kind, which the host refuses (invalid-value).
export declare const INVALID_VALUES: Readonly<Record<ValueKind, unknown>>;
typeFixtures
One property declaration per kind, for table-driven type tests.
export declare function typeFixtures(): readonly {
readonly kind: ValueKind;
readonly valueType: ValueTypeDeclaration;
readonly valid: unknown;
readonly invalid: unknown;
}[];
PROPERTY_STATES
Every property state a control must render (FR-013).
export declare const PROPERTY_STATES: Readonly<Record<PropertyState['status'], PropertyState>>;
OPTIONS
Option lists in each status, the value never the label (FR-016).
export declare const OPTIONS: Readonly<Record<'ready' | 'loading' | 'empty' | 'error' | 'more' | 'unavailable', PropertyOptions>>;
optionsRace
An options race: two searches answer out of order. The host delivers only the latest search's answer
(latest), never the stale one; a control must show latest and must not keep stale items.
export declare function optionsRace(): {
readonly stale: PropertyOptions;
readonly latest: PropertyOptions;
};
BINDING_SEQUENCE
A binding round trip: the host pushes successive values of a bound property, as the form changes.
export declare const BINDING_SEQUENCE: readonly string[];
THEME_TOKENS
The theme a control receives: Studio's own public token vocabulary (CONTROL_THEME_TOKENS, vendored), whose values are
CSS custom-property references such as var(--surface), never literal colours (review r79). Light and dark deliver
the same tokens: the page switches theme by redefining the variables (see PALETTES), so a control that styles
itself with the tokens follows every theme without an update.
export declare const THEME_TOKENS: ThemeTokens;
THEMES
The token vocabulary in light and in dark: identical by design, as on the platform.
export declare const THEMES: Readonly<Record<'light' | 'dark', ThemeTokens>>;
PALETTES
Representative values of the page variables the tokens reference, in Studio's light and dark themes. The simulated
host defines them on the control's root (MountOptions.palette, harness.setPalette), as the page does. They are
fixtures: the page owns the real values, and a control must read the tokens, never these colours.
export declare const PALETTES: Readonly<Record<'light' | 'dark', Readonly<Record<string, string>>>>;
RTL
Right-to-left locales a control must mirror for.
export declare const RTL: Readonly<{
direction: 'rtl';
locale: "ar";
label: "الرياض";
}>;
PROVIDERS
Provider admission as an administrator would set it (SDK 1.1). offline is the default everywhere and in design
and preview. admitted is simulated configuration for a mocked host only; a real provider is qualified on the
platform with real environment configuration, never with these values.
export declare const PROVIDERS: Readonly<{
offline: {
providers: readonly string[];
configuration: Readonly<Record<string, string>>;
};
admitted: {
providers: readonly string[];
configuration: Readonly<Record<string, string>>;
};
}>;
accessibleAlternativeProblems
Checks the shape of a control's accessible list alternative under root: exactly one rendered, named list (a
listbox, a list, ul or ol, found through shadow roots and slots), one entry per expected item in order,
each named as items[i], and only the selected item (if any) marked aria-selected="true". Returns the problems
found; an empty array means the shape is right. Pair it with keyboardReachProblems for operability.
export declare function accessibleAlternativeProblems(root: Element, expected: {
readonly items: readonly string[];
readonly selected?: string | null;
}): string[];
keyboardReachProblems
The list must be operable, not only shaped right. From its single tab stop, ArrowUp reaches the first item (clamping
or wrapping) and ArrowDown then visits every item in order, moving focus. Focus is read right after each key, so a
control that moves focus later needs runConformance, which waits after each key. Returns the problems found.
export declare function keyboardReachProblems(root: Element, items: readonly string[], pressKey?: (key: string, target: Element) => void): string[];
incompatibleModules
Deliberately incompatible modules (SCRUM-4872). Each must be refused by the host's ABI check before mount; a test kit
or host change that starts accepting one is a compatibility regression. problem is the expected refusal.
export declare function incompatibleModules(controlKey: string): readonly {
readonly name: string;
readonly module: unknown;
readonly problem: 'not-an-object' | 'abi-mismatch' | 'bad-control-key' | 'no-mount' | 'key-mismatch';
}[];
incompatibleDeclarations
Declarations a host refuses to mount against, for negative tests of tooling built on the kit.
export declare function incompatibleDeclarations(base: ControlDeclaration): readonly {
readonly name: string;
readonly declaration: ControlDeclaration;
}[];