@colixsystems/widget-sdk 0.210.0 → 0.213.0

package/dist/contract.cjs

@@ -618,6 +618,8 @@ const THEME_COMPONENTS = Object.freeze({
   // `text` scope already owns.
   muted: Object.freeze({
     label: "Muted",
+    // The SDK's form controls read this scope directly, in every widget.
+    sdkComponents: Object.freeze(["TextField", "Checkbox", "Switch", "Select", "SearchField"]),
     tokens: Object.freeze({
       background: Object.freeze({ type: "color", uiDefault: "colors.surfaceMuted" }),
       textColor: Object.freeze({ type: "color", uiDefault: "colors.onSurfaceMuted" }),
@@ -635,6 +637,7 @@ const THEME_COMPONENTS = Object.freeze({
   // list is the closest thing the built-in catalog has to a popover panel.
   popover: Object.freeze({
     label: "Popover",
+    sdkComponents: Object.freeze(["Select"]),
     tokens: Object.freeze({
       background: Object.freeze({ type: "color", uiDefault: "colors.surface" }),
       textColor: Object.freeze({ type: "color", uiDefault: "colors.onSurface" }),
@@ -2811,7 +2814,7 @@ const PRIMITIVES = [
   {
     name: "Switch",
     description:
-      "Toggle. Controlled — `value` + `onValueChange`. See https://reactnative.dev/docs/switch.",
+      'Themed on/off toggle. `<Switch label="Email me updates" value={on} onValueChange={setOn} />` — THE way to draw a setting that takes effect at once. It is the platform\'s own switch, so each host gives it its switch role, state and keys; its "on" track is the app\'s primary colour and its "off" track the input border (Design > Components > Muted). `label` draws the text beside it and makes the text tappable too, `helper` a hint below, `error` a message in its place (or `true` to mark it without one), `disabled` stops it (a device greys it; on the web it is drawn at half strength unless you passed your own colours). Always pass `label`, or `accessibilityLabel` when a visible label already sits next to it. Controlled — `value` + `onValueChange(next)`. Every React Native `Switch` prop still works: a `trackColor` you pass overrides the theme for the states it names, and `thumbColor` colours the thumb. Never hand-roll a toggle from `Pressable` + a sliding `View`.',
     rnComponent: "Switch",
     docsUrl: "https://reactnative.dev/docs/switch",
   },
@@ -2917,6 +2920,13 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  {
+    name: "ConfirmDialog",
+    description:
+      'Standard confirmation prompt, a preset of `<Modal>`. `<ConfirmDialog visible={!!pending} tone="destructive" title="Delete this order?" message="This cannot be undone." confirmLabel={t("delete", "Delete")} onCancel={() => setPending(null)} onConfirm={async () => { await remove(pending.id); setPending(null); }} />`. THE way to ask "are you sure?" before a delete or any other action that cannot be undone, so every confirmation in the app has the same wording slots, button order and colours. Never hand-build one from a `<Modal>` or an `<Overlay>` with your own two buttons, never arm a button to be pressed twice, and never use `Alert.alert` or `window.confirm`. Props: `visible` (boolean), `title` (string, the question), `message` (what confirming does; text or a node), `confirmLabel` and `cancelLabel` (default the app\'s translated "Confirm" and "Cancel" — name the action: "Delete", "Remove", "Send"), `tone` ("default" | "destructive"; destructive draws the confirm button from the theme\'s Destructive colours and opens with focus on Cancel), `busy` (boolean; disables both buttons, shows a `<Spinner>` and keeps the dialog open), `onConfirm` (return the promise of the action and the dialog stays busy until it settles, with a second press ignored; a rejection is NOT caught, so catch a failure yourself and report it), `onCancel` (fired by the Cancel button, the close button, the backdrop press, the Escape key on web and the Android back button — cancelling is always the safe default), `closeAccessibilityLabel` and `testID`. The dialog never closes itself: set `visible` false from `onCancel` and after the action. Its panel follows the theme (Design > Components > Dialogs) and its buttons the Buttons and Destructive settings — do not re-style it.',
+    rnComponent: null,
+    docsUrl: null,
+  },
   // sc-8104 — the in-app emoji picker. Typed emoji always worked; what this
   // replaces is being forced out to the OS keyboard to find one.
   {
@@ -3053,7 +3063,35 @@ const PRIMITIVES = [
   {
     name: "TextField",
     description:
-      'Themed text-entry field. `<TextField value={name} onChangeText={setName} placeholder="Your name" accessibilityLabel="Name" />` — every `TextInput` prop works, and its background, text colour, border, corner radius and height come from the app\'s input look (Theme Settings > Muted), so a widget\'s fields match the built-in forms. `multiline` grows the field to a ceiling and then scrolls inside it. Override one field with `background`, `textColor`, `borderColor`, `radius` or `height`; `style` is merged last. Use it instead of styling a bare `TextInput`.',
+      'Themed text-entry field. `<TextField value={name} onChangeText={setName} placeholder="Your name" accessibilityLabel="Name" />` — every `TextInput` prop works, and its background, text colour, border, corner radius and height come from the app\'s input look (Theme Settings > Muted), so a widget\'s fields match the built-in forms. `multiline` grows the field to a ceiling and then scrolls inside it. Override one field with `background`, `textColor`, `borderColor`, `radius` or `height`; `style` is merged last. `label` draws a label above the field and names it for a screen reader, `helper` a hint below, `error` a message in the helper\'s place with a danger border (`true` marks it without a message), `disabled` makes it read-only and dimmed; `containerStyle` styles the box around a labelled field. Use it instead of styling a bare `TextInput`.',
+    rnComponent: null,
+    docsUrl: null,
+  },
+  {
+    name: "Checkbox",
+    description:
+      'Themed tick box. `<Checkbox label="Remember me" value={checked} onValueChange={setChecked} />` — THE way to draw a yes/no choice that is submitted with a form, or one row of a multi-select list. The box is the app\'s input surface (Design > Components > Muted) and fills with the primary colour when checked; focus draws a ring in the primary colour around it. The whole row is one 44px target with the checkbox role and checked state on both hosts, and Space toggles it on the web. Props: `value` (boolean), `onValueChange(next)`, `label` (text, or an element), `helper`, `error` (a message, or `true`), `disabled`, `accessibilityLabel` (required when there is no text `label`), `style` (the row), `containerStyle` (the box around a row that shows a helper or error), `testID`; any other prop lands on the row. Never hand-roll a tick box from `Pressable` + a bordered `View` + a "✓".',
+    rnComponent: null,
+    docsUrl: null,
+  },
+  {
+    name: "Select",
+    description:
+      'Themed single-choice picker. `<Select label="Status" value={status} onValueChange={setStatus} options={[{ value: "open", label: "Open" }, { value: "done", label: "Done" }]} placeholder="Choose a status" />` — THE way to let the user pick ONE of a known list. The trigger is the app\'s input field (Design > Components > Muted) showing the chosen label; pressing it opens the options at SCREEN level, in a sheet painted from Design > Components > Popover, so no card or scroll container can clip them, and a long list scrolls inside the sheet. The trigger is a button that opens a dialog (expanded state included) and each option carries the option role and its selected state on both hosts; the list around them is a listbox on the web only. On the web Enter, Space or an arrow key opens it, the arrow keys, Home and End move between options, Enter or Space chooses, Escape closes, and focus returns to the trigger; on Android the back button closes it. Props: `options` (`[{ value, label, disabled?, testID? }]`, `value` a string or number, unique), `value`, `onValueChange(value, option)`, `placeholder` (default "Select"), `title` (the sheet\'s heading; defaults to a text `label`), `emptyText` (default "No options"), `label`, `helper`, `error`, `disabled`, `accessibilityLabel`, `closeAccessibilityLabel`, `background` / `textColor` / `borderColor` / `radius` / `height` to override one field, `style` (the trigger), `containerStyle`, `testID`; any other prop lands on the trigger. Never hand-roll a dropdown from `Pressable` + an absolutely positioned list: it is clipped by the widget\'s container on both hosts.',
+    rnComponent: null,
+    docsUrl: null,
+  },
+  {
+    name: "SearchField",
+    description:
+      'Themed search box. `<SearchField value={query} onChangeText={setQuery} placeholder="Search orders" />` — THE way to draw a field that filters or searches. It IS a `TextField` (same look, same props, same `label` / `helper` / `error` / `disabled`) with a search glyph, the search key on the on-screen keyboard and a clear control that appears once there is text; clearing calls `onChangeText("")`, then `onClear` if you passed one, and keeps focus in the field. `placeholder` defaults to "Search" and `clearAccessibilityLabel` to "Clear search" — pass translated ones. `style` styles the input and `containerStyle` the box around it (use it for `flex: 1` in a toolbar). Debounce the query yourself before you fetch. Never hand-roll a search box from a `TextInput` + an icon.',
+    rnComponent: null,
+    docsUrl: null,
+  },
+  {
+    name: "spaceActivates",
+    description:
+      'Space-key activation for a control whose role is not a button. `<Pressable accessibilityRole="radio" aria-checked={on} onPress={pick} onKeyDown={spaceActivates(pick)} />`. On the web a `Pressable` answers Enter for every role but Space only for a button, and Space is the key a checkbox, radio, switch or option is operated with; this restores it, once per key press. Native ignores `onKeyDown`, so it is safe on both hosts. `<Checkbox>` and `<Select>` already use it — reach for it only for a control you build yourself.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -5589,7 +5627,20 @@ const CONTRACT = deepFreeze({
   //    `initialFocusRef`, `backdropAccessible` and `testID`. A scope may now
   //    name `sdkComponents` and bind no widget field; a colour token may be
   //    `translucent` (always painted see-through) and carry a `note`.
-  version: "1.169.0",
+  // 1.171.0: (sc-10929) — the form controls `Checkbox`, `Select` and
+  //    `SearchField`, and the `spaceActivates` helper. `TextField` gains
+  //    `label`, `helper`, `error`, `disabled` and `containerStyle`. The `muted`
+  //    and `popover` scopes name the `sdkComponents` that read them directly.
+  //    VISIBLE CHANGE, not additive: `Switch` is now the themed platform
+  //    switch, so an existing `<Switch>` with no colour props is repainted:
+  //    its tracks follow the theme on both hosts and its "on" thumb is white
+  //    on the web. A caller's `trackColor` / `thumbColor` still win.
+  // 1.172.0: additive (sc-10925) — the `ConfirmDialog` primitive: the standard
+  //    confirmation, a preset of `Modal` and `Button` (title, message, confirm
+  //    and cancel labels, `tone` "default" | "destructive", `busy`). No new
+  //    theme scope: the panel reads `modal`, the actions `button` and
+  //    `destructive`. `Button` forwards a ref to its pressable.
+  version: "1.172.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -618,6 +618,8 @@ const THEME_COMPONENTS = Object.freeze({
   // `text` scope already owns.
   muted: Object.freeze({
     label: "Muted",
+    // The SDK's form controls read this scope directly, in every widget.
+    sdkComponents: Object.freeze(["TextField", "Checkbox", "Switch", "Select", "SearchField"]),
     tokens: Object.freeze({
       background: Object.freeze({ type: "color", uiDefault: "colors.surfaceMuted" }),
       textColor: Object.freeze({ type: "color", uiDefault: "colors.onSurfaceMuted" }),
@@ -635,6 +637,7 @@ const THEME_COMPONENTS = Object.freeze({
   // list is the closest thing the built-in catalog has to a popover panel.
   popover: Object.freeze({
     label: "Popover",
+    sdkComponents: Object.freeze(["Select"]),
     tokens: Object.freeze({
       background: Object.freeze({ type: "color", uiDefault: "colors.surface" }),
       textColor: Object.freeze({ type: "color", uiDefault: "colors.onSurface" }),
@@ -2811,7 +2814,7 @@ const PRIMITIVES = [
   {
     name: "Switch",
     description:
-      "Toggle. Controlled — `value` + `onValueChange`. See https://reactnative.dev/docs/switch.",
+      'Themed on/off toggle. `<Switch label="Email me updates" value={on} onValueChange={setOn} />` — THE way to draw a setting that takes effect at once. It is the platform\'s own switch, so each host gives it its switch role, state and keys; its "on" track is the app\'s primary colour and its "off" track the input border (Design > Components > Muted). `label` draws the text beside it and makes the text tappable too, `helper` a hint below, `error` a message in its place (or `true` to mark it without one), `disabled` stops it (a device greys it; on the web it is drawn at half strength unless you passed your own colours). Always pass `label`, or `accessibilityLabel` when a visible label already sits next to it. Controlled — `value` + `onValueChange(next)`. Every React Native `Switch` prop still works: a `trackColor` you pass overrides the theme for the states it names, and `thumbColor` colours the thumb. Never hand-roll a toggle from `Pressable` + a sliding `View`.',
     rnComponent: "Switch",
     docsUrl: "https://reactnative.dev/docs/switch",
   },
@@ -2917,6 +2920,13 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  {
+    name: "ConfirmDialog",
+    description:
+      'Standard confirmation prompt, a preset of `<Modal>`. `<ConfirmDialog visible={!!pending} tone="destructive" title="Delete this order?" message="This cannot be undone." confirmLabel={t("delete", "Delete")} onCancel={() => setPending(null)} onConfirm={async () => { await remove(pending.id); setPending(null); }} />`. THE way to ask "are you sure?" before a delete or any other action that cannot be undone, so every confirmation in the app has the same wording slots, button order and colours. Never hand-build one from a `<Modal>` or an `<Overlay>` with your own two buttons, never arm a button to be pressed twice, and never use `Alert.alert` or `window.confirm`. Props: `visible` (boolean), `title` (string, the question), `message` (what confirming does; text or a node), `confirmLabel` and `cancelLabel` (default the app\'s translated "Confirm" and "Cancel" — name the action: "Delete", "Remove", "Send"), `tone` ("default" | "destructive"; destructive draws the confirm button from the theme\'s Destructive colours and opens with focus on Cancel), `busy` (boolean; disables both buttons, shows a `<Spinner>` and keeps the dialog open), `onConfirm` (return the promise of the action and the dialog stays busy until it settles, with a second press ignored; a rejection is NOT caught, so catch a failure yourself and report it), `onCancel` (fired by the Cancel button, the close button, the backdrop press, the Escape key on web and the Android back button — cancelling is always the safe default), `closeAccessibilityLabel` and `testID`. The dialog never closes itself: set `visible` false from `onCancel` and after the action. Its panel follows the theme (Design > Components > Dialogs) and its buttons the Buttons and Destructive settings — do not re-style it.',
+    rnComponent: null,
+    docsUrl: null,
+  },
   // sc-8104 — the in-app emoji picker. Typed emoji always worked; what this
   // replaces is being forced out to the OS keyboard to find one.
   {
@@ -3053,7 +3063,35 @@ const PRIMITIVES = [
   {
     name: "TextField",
     description:
-      'Themed text-entry field. `<TextField value={name} onChangeText={setName} placeholder="Your name" accessibilityLabel="Name" />` — every `TextInput` prop works, and its background, text colour, border, corner radius and height come from the app\'s input look (Theme Settings > Muted), so a widget\'s fields match the built-in forms. `multiline` grows the field to a ceiling and then scrolls inside it. Override one field with `background`, `textColor`, `borderColor`, `radius` or `height`; `style` is merged last. Use it instead of styling a bare `TextInput`.',
+      'Themed text-entry field. `<TextField value={name} onChangeText={setName} placeholder="Your name" accessibilityLabel="Name" />` — every `TextInput` prop works, and its background, text colour, border, corner radius and height come from the app\'s input look (Theme Settings > Muted), so a widget\'s fields match the built-in forms. `multiline` grows the field to a ceiling and then scrolls inside it. Override one field with `background`, `textColor`, `borderColor`, `radius` or `height`; `style` is merged last. `label` draws a label above the field and names it for a screen reader, `helper` a hint below, `error` a message in the helper\'s place with a danger border (`true` marks it without a message), `disabled` makes it read-only and dimmed; `containerStyle` styles the box around a labelled field. Use it instead of styling a bare `TextInput`.',
+    rnComponent: null,
+    docsUrl: null,
+  },
+  {
+    name: "Checkbox",
+    description:
+      'Themed tick box. `<Checkbox label="Remember me" value={checked} onValueChange={setChecked} />` — THE way to draw a yes/no choice that is submitted with a form, or one row of a multi-select list. The box is the app\'s input surface (Design > Components > Muted) and fills with the primary colour when checked; focus draws a ring in the primary colour around it. The whole row is one 44px target with the checkbox role and checked state on both hosts, and Space toggles it on the web. Props: `value` (boolean), `onValueChange(next)`, `label` (text, or an element), `helper`, `error` (a message, or `true`), `disabled`, `accessibilityLabel` (required when there is no text `label`), `style` (the row), `containerStyle` (the box around a row that shows a helper or error), `testID`; any other prop lands on the row. Never hand-roll a tick box from `Pressable` + a bordered `View` + a "✓".',
+    rnComponent: null,
+    docsUrl: null,
+  },
+  {
+    name: "Select",
+    description:
+      'Themed single-choice picker. `<Select label="Status" value={status} onValueChange={setStatus} options={[{ value: "open", label: "Open" }, { value: "done", label: "Done" }]} placeholder="Choose a status" />` — THE way to let the user pick ONE of a known list. The trigger is the app\'s input field (Design > Components > Muted) showing the chosen label; pressing it opens the options at SCREEN level, in a sheet painted from Design > Components > Popover, so no card or scroll container can clip them, and a long list scrolls inside the sheet. The trigger is a button that opens a dialog (expanded state included) and each option carries the option role and its selected state on both hosts; the list around them is a listbox on the web only. On the web Enter, Space or an arrow key opens it, the arrow keys, Home and End move between options, Enter or Space chooses, Escape closes, and focus returns to the trigger; on Android the back button closes it. Props: `options` (`[{ value, label, disabled?, testID? }]`, `value` a string or number, unique), `value`, `onValueChange(value, option)`, `placeholder` (default "Select"), `title` (the sheet\'s heading; defaults to a text `label`), `emptyText` (default "No options"), `label`, `helper`, `error`, `disabled`, `accessibilityLabel`, `closeAccessibilityLabel`, `background` / `textColor` / `borderColor` / `radius` / `height` to override one field, `style` (the trigger), `containerStyle`, `testID`; any other prop lands on the trigger. Never hand-roll a dropdown from `Pressable` + an absolutely positioned list: it is clipped by the widget\'s container on both hosts.',
+    rnComponent: null,
+    docsUrl: null,
+  },
+  {
+    name: "SearchField",
+    description:
+      'Themed search box. `<SearchField value={query} onChangeText={setQuery} placeholder="Search orders" />` — THE way to draw a field that filters or searches. It IS a `TextField` (same look, same props, same `label` / `helper` / `error` / `disabled`) with a search glyph, the search key on the on-screen keyboard and a clear control that appears once there is text; clearing calls `onChangeText("")`, then `onClear` if you passed one, and keeps focus in the field. `placeholder` defaults to "Search" and `clearAccessibilityLabel` to "Clear search" — pass translated ones. `style` styles the input and `containerStyle` the box around it (use it for `flex: 1` in a toolbar). Debounce the query yourself before you fetch. Never hand-roll a search box from a `TextInput` + an icon.',
+    rnComponent: null,
+    docsUrl: null,
+  },
+  {
+    name: "spaceActivates",
+    description:
+      'Space-key activation for a control whose role is not a button. `<Pressable accessibilityRole="radio" aria-checked={on} onPress={pick} onKeyDown={spaceActivates(pick)} />`. On the web a `Pressable` answers Enter for every role but Space only for a button, and Space is the key a checkbox, radio, switch or option is operated with; this restores it, once per key press. Native ignores `onKeyDown`, so it is safe on both hosts. `<Checkbox>` and `<Select>` already use it — reach for it only for a control you build yourself.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -5585,7 +5623,20 @@ const CONTRACT = deepFreeze({
   //    `initialFocusRef`, `backdropAccessible` and `testID`. A scope may now
   //    name `sdkComponents` and bind no widget field; a colour token may be
   //    `translucent` (always painted see-through) and carry a `note`.
-  version: "1.169.0",
+  // 1.171.0: (sc-10929) — the form controls `Checkbox`, `Select` and
+  //    `SearchField`, and the `spaceActivates` helper. `TextField` gains
+  //    `label`, `helper`, `error`, `disabled` and `containerStyle`. The `muted`
+  //    and `popover` scopes name the `sdkComponents` that read them directly.
+  //    VISIBLE CHANGE, not additive: `Switch` is now the themed platform
+  //    switch, so an existing `<Switch>` with no colour props is repainted:
+  //    its tracks follow the theme on both hosts and its "on" thumb is white
+  //    on the web. A caller's `trackColor` / `thumbColor` still win.
+  // 1.172.0: additive (sc-10925) — the `ConfirmDialog` primitive: the standard
+  //    confirmation, a preset of `Modal` and `Button` (title, message, confirm
+  //    and cancel labels, `tone` "default" | "destructive", `busy`). No new
+  //    theme scope: the panel reads `modal`, the actions `button` and
+  //    `destructive`. `Button` forwards a ref to its pressable.
+  version: "1.172.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/form-control-logic.js

@@ -0,0 +1,55 @@
+// The form controls' pure rules: what counts as shown, how a control is
+// named, when the frame is needed, and the keys a non-button role answers.
+// No renderer here, so the node suite can test them and both hosts share them.
+
+export function isShown(value) {
+  return value !== undefined && value !== null && value !== false && value !== "";
+}
+
+export function isText(value) {
+  return typeof value === "string" || typeof value === "number";
+}
+
+/** The spoken name of a control: its own label, else its visible one. */
+export function spokenLabel(accessibilityLabel, label) {
+  if (isShown(accessibilityLabel)) return accessibilityLabel;
+  return isText(label) ? String(label) : undefined;
+}
+
+/** An `error` that carries a message (`true` only marks the control). */
+export function errorMessage(error) {
+  return isShown(error) && error !== true ? error : null;
+}
+
+/** Whether the frame draws a helper or an error line under the control. */
+export function hasNote({ helper, error }) {
+  return errorMessage(error) !== null || isShown(helper);
+}
+
+/** Whether a control needs the frame at all, or renders bare. */
+export function needsFrame({ label, helper, error }) {
+  return isShown(label) || hasNote({ helper, error });
+}
+
+/** Hand one node to both a forwarded ref and the control's own. */
+export function shareRef(forwarded, own) {
+  return (node) => {
+    own.current = node;
+    if (typeof forwarded === "function") forwarded(node);
+    else if (forwarded) forwarded.current = node;
+  };
+}
+
+// The web host presses a non-button role on Enter only; Space is the key a
+// checkbox, a radio and an option are operated with. Native ignores onKeyDown.
+export function spaceActivates(onPress) {
+  return (event) => {
+    if (event.key !== " " && event.key !== "Spacebar") return;
+    // A shortcut, or a space typed into a field nested in the control.
+    if (event.shiftKey || event.ctrlKey || event.altKey || event.metaKey) return;
+    if (event.target && event.currentTarget && event.target !== event.currentTarget) return;
+    event.preventDefault();
+    // A held key must not also act on whatever its first press focused.
+    if (!event.repeat) onPress();
+  };
+}

package/dist/form-control-tokens.js

@@ -0,0 +1,121 @@
+// The values the form controls (`<Checkbox>`, `<Switch>`, `<Select>`,
+// `<SearchField>`) paint with. The field itself is `<TextField>`'s own
+// resolution, so all five follow the theme's `muted` scope as one and show
+// focus in the accent; the Select's option list adds the `popover` scope.
+// Platform-free.
+
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import { resolveTextFieldTokens } from "./text-field-tokens.js";
+
+// The smallest target a finger can hit reliably, as the field's own floor.
+export const CONTROL_MIN_TARGET = 44;
+export const CHECKBOX_SIZE = 22;
+export const CHECKBOX_MAX_RADIUS = 6;
+export const HALO_WIDTH = 2;
+export const HALO_GAP = 2;
+export const DISABLED_OPACITY = 0.5;
+
+function isSet(value) {
+  return value !== undefined && value !== null && value !== "";
+}
+
+/**
+ * Resolve one form control from the workspace theme.
+ *
+ * @param {object} theme — the resolved workspace theme (`useTheme()` shape).
+ * @param {object} [overrides] — per-control values keyed by TEXT_FIELD_TOKEN_NAMES.
+ */
+export function resolveFormControlTokens(theme, overrides) {
+  const base = theme && typeof theme === "object" ? theme : DEFAULT_THEME_TOKENS;
+  const colors = base.colors || DEFAULT_THEME_TOKENS.colors;
+  const spacing = base.spacing || DEFAULT_THEME_TOKENS.spacing;
+  const typography = base.typography || DEFAULT_THEME_TOKENS.typography;
+  const popover = (base.components && base.components.popover) || {};
+  const field = resolveTextFieldTokens(base, overrides);
+  return {
+    ...field,
+    // The checked and on states are the accent, as a primary button is.
+    accent: colors.primary,
+    onAccent: colors.onPrimary,
+    labelColor: colors.onSurface,
+    helperColor: colors.onSurfaceMuted,
+    labelSize: typography.sizes.sm,
+    helperSize: typography.sizes.xs,
+    gap: spacing.xs,
+    rowGap: spacing.sm,
+    disabledOpacity: DISABLED_OPACITY,
+    errorColor: colors.danger,
+    popover: {
+      background: isSet(popover.background) ? popover.background : colors.surface,
+      textColor: isSet(popover.textColor) ? popover.textColor : colors.onSurface,
+      borderColor: isSet(popover.borderColor) ? popover.borderColor : colors.border,
+    },
+  };
+}
+
+/**
+ * The ring drawn AROUND a filled control (a checkbox, a switch), whose own
+ * border cannot show focus once it is the accent. Its width is always
+ * reserved, so focusing never moves the control.
+ *
+ * @param {object} t — resolved form-control tokens.
+ * @param {boolean} focused
+ * @param {number} radius — the control's own corner radius.
+ */
+export function focusHaloStyle(t, focused, radius) {
+  return {
+    padding: HALO_GAP,
+    borderWidth: HALO_WIDTH,
+    borderRadius: radius + HALO_GAP + HALO_WIDTH,
+    borderColor: focused ? t.focusColor : "transparent",
+  };
+}
+
+/**
+ * The colours a switch hands the platform control. A caller's `trackColor`
+ * overrides the theme per state, and iOS, which paints the off track from
+ * `ios_backgroundColor`, follows the off colour unless told otherwise.
+ *
+ * @param {object} t — resolved form-control tokens.
+ * @param {{trackColor?: object, iosBackgroundColor?: string, invalid?: boolean}} own
+ */
+export function resolveSwitchColors(t, own) {
+  const { trackColor, iosBackgroundColor, invalid } = own || {};
+  const offTrack = invalid ? t.errorColor : t.borderColor;
+  const track = {
+    false: offTrack,
+    true: t.accent,
+    ...(trackColor && typeof trackColor === "object" ? trackColor : null),
+  };
+  return { trackColor: track, iosBackgroundColor: iosBackgroundColor ?? track.false };
+}
+
+/** The option whose `value` is the selected one, or `undefined`. */
+export function selectedOption(options, value) {
+  if (!Array.isArray(options)) return undefined;
+  return options.find((option) => option && option.value === value);
+}
+
+/**
+ * The index focus moves to for a navigation key, skipping disabled options
+ * and stopping at either end. Returns `from` when the key moves nothing.
+ *
+ * @param {Array<{disabled?: boolean}>} options
+ * @param {number} from — the focused option's index.
+ * @param {string} key — a KeyboardEvent `key`.
+ */
+export function nextOptionIndex(options, from, key) {
+  const list = Array.isArray(options) ? options : [];
+  const enabled = (i) => list[i] && !list[i].disabled;
+  const scan = (start, step) => {
+    for (let i = start; i >= 0 && i < list.length; i += step) {
+      if (enabled(i)) return i;
+    }
+    return from;
+  };
+  if (key === "ArrowDown") return scan(from + 1, 1);
+  if (key === "ArrowUp") return scan(from - 1, -1);
+  if (key === "Home") return scan(0, 1);
+  if (key === "End") return scan(list.length - 1, -1);
+  return from;
+}

package/dist/form-control-view.js

@@ -0,0 +1,98 @@
+// What every form control shares on screen: the label above it and the helper
+// or error below it. One frame, so `<TextField>`, `<Checkbox>`, `<Switch>`,
+// `<Select>` and `<SearchField>` cannot drift apart. Its rules, which need no
+// renderer, live in ./form-control-logic.js.
+
+import React from "react";
+import { errorMessage, isShown, isText } from "./form-control-logic.js";
+
+const h = React.createElement;
+
+/**
+ * Bind the shared frame to one platform's primitives.
+ *
+ * @param {{View: any, Text: any, Pressable: any}} rn
+ */
+export function makeFieldFrame(rn) {
+  const { View, Text, Pressable } = rn;
+
+  /**
+   * @param {object} props
+   * @param {object} props.t — resolved form-control tokens.
+   * @param {any} [props.label] — text, or an element rendered as given.
+   * @param {any} [props.helper]
+   * @param {any} [props.error] — a message replaces the helper; `true` shows none.
+   * @param {string} [props.noteId] — the id the control's `aria-describedby` names.
+   * @param {() => void} [props.onLabelPress] — a text label then acts for the control.
+   * @param {boolean} [props.noteDisabled] — dim the note alone, when the
+   *   control dims itself and `disabled` would dim it twice.
+   */
+  function FieldFrame({
+    t,
+    label,
+    helper,
+    error,
+    disabled,
+    noteId,
+    onLabelPress,
+    noteDisabled,
+    style,
+    children,
+  }) {
+    const message = errorMessage(error);
+    const note = message || (isShown(helper) ? helper : null);
+    const labelText = isText(label)
+      ? h(
+          Text,
+          {
+            style: {
+              color: t.labelColor,
+              fontFamily: t.fontFamily,
+              fontSize: t.labelSize,
+              fontWeight: "500",
+            },
+          },
+          label,
+        )
+      : null;
+    return h(
+      View,
+      { style: [{ gap: t.gap }, disabled ? { opacity: t.disabledOpacity } : null, style] },
+      labelText && typeof onLabelPress === "function"
+        ? h(
+            Pressable,
+            {
+              onPress: onLabelPress,
+              disabled,
+              // The control is the one stop for a keyboard and a reader.
+              tabIndex: -1,
+              accessible: false,
+              style: { alignSelf: "flex-start" },
+            },
+            labelText,
+          )
+        : labelText || (isShown(label) ? label : null),
+      children,
+      isText(note)
+        ? h(
+            Text,
+            {
+              nativeID: noteId,
+              // Announced where the host can: the web and Android.
+              ...(message ? { accessibilityLiveRegion: "polite" } : null),
+              style: {
+                color: message ? t.errorColor : t.helperColor,
+                fontFamily: t.fontFamily,
+                fontSize: t.helperSize,
+                ...(noteDisabled ? { opacity: t.disabledOpacity } : null),
+              },
+            },
+            note,
+          )
+        : note,
+    );
+  }
+
+  FieldFrame.displayName = "FieldFrame";
+  return FieldFrame;
+}