@colixsystems/widget-sdk 0.210.0 → 0.212.0

package/README.md

@@ -83,8 +83,59 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.210.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+`v0.212.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
 
+### What's new in 0.212.0 (contract 1.171.0)
+
+**Standard form controls: `Checkbox`, `Switch`, `Select` and `SearchField`.** Only text entry had a themed component, so every widget drew its own tick boxes, toggles, dropdowns and search boxes. Four controls now sit beside `TextField`, each one view bound to both hosts, and all five share one frame: `label` draws the control's label and names it for a screen reader (pressing a field's label focuses it), `helper` a hint below, `error` a message in the hint's place that also marks the control (`true` marks it without a message), and `disabled` stops input.
+
+```jsx
+<SearchField value={query} onChangeText={setQuery} placeholder="Search orders" />
+<Select
+  label="Status"
+  value={status}
+  onValueChange={setStatus}
+  options={[{ value: "open", label: "Open" }, { value: "done", label: "Done" }]}
+/>
+<Checkbox label="Urgent only" value={urgent} onValueChange={setUrgent} />
+<Switch label="Notify me" value={notify} onValueChange={setNotify} />
+```
+
+**What existing widgets will look different.** `Switch` was already exported, as React Native's switch with the platform's default colours. It is now themed, so every existing `<Switch>` that passes no colours is repainted when this ships, in published and generated widgets alike:
+
+| | Before | Now |
+| --- | --- | --- |
+| Web, off track | `#939393` | the theme's border colour |
+| Web, on track | `#A3D3CF` | the theme's primary colour |
+| Web, on thumb | teal `#009688` | white |
+| Web, off thumb | `#FAFAFA` | unchanged |
+| Web, disabled | the host's grey track and thumb | the themed colours at half opacity |
+| iOS and Android, tracks | the platform's defaults | the theme's border (off) and primary (on) |
+| iOS and Android, thumb | the platform's default | unchanged |
+| iOS and Android, disabled | the platform's greyed switch | unchanged |
+
+Three smaller changes reach switches that do pass something:
+
+- **Web, `thumbColor` without `activeThumbColor`:** the "on" thumb was the host's teal and is now the `thumbColor` you passed.
+- **Web, a partial `trackColor`** (`{ true: "#0a0" }`, a string, or `activeTrackColor` alone): the state you did not name was the host's default and is now the theme's.
+- **iOS and Android, a truthy non-boolean `value`** (`value={1}`): it was off, because React Native's switch is on only for `true`, and is now on, as it already was on the web.
+
+A switch that passes its own colours keeps them, disabled or not: a `trackColor` overrides the theme for the states it names (`{ true: "#0a0" }` still gets the themed off track), the web's `activeTrackColor` and string `trackColor` are still read, and iOS's off colour follows `trackColor.false` unless `ios_backgroundColor` is passed. A disabled switch that brings its own colours is drawn exactly as before on the web, at full strength; only one that left its colours to the theme is dimmed there. Layout does not change: a switch with no `label`, `helper` or `error` renders the bare control. Nothing else that existed before changes appearance; a `TextField` with none of the new props renders exactly what it did.
+
+- **`Checkbox`**: `value` / `onValueChange(next)`. One 44px row with the checkbox role and checked state on both hosts; Space toggles it on the web. The box is the input surface and fills with the primary colour when checked. `style` is the row, `containerStyle` the box around a row that shows a helper or error; other props and the ref land on the row.
+- **`Switch`**: the platform's own switch (React Native's `Switch`), so each host keeps its role, state and keys. A device greys a disabled switch itself; on the web a disabled switch is drawn at half strength unless it brings its own colours. With a `label`, `helper` or `error` it draws a row whose label toggles it too.
+- **`Select`**: `options` (`[{ value, label, disabled?, testID? }]`), `value`, `onValueChange(value, option)`, `placeholder`, `title`, `emptyText`. The trigger is the input field, exposed as a button that opens a dialog (`aria-haspopup`, `aria-expanded`). Its options open through `Overlay`, at screen level, each with the option role and a selected state on both hosts (the list around them is a `listbox` on the web only; React Native has no such role), so a card or scroll container cannot clip them, and a long list scrolls inside the sheet. 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. Other props and the ref land on the trigger.
+- **`SearchField`**: a `TextField` with a search glyph, the search key on the on-screen keyboard (`enterKeyHint="search"`, overridable) and a clear control that appears once there is text. Clearing calls `onChangeText("")`, then `onClear`, and keeps focus in the field. `style` styles the input and `containerStyle` the box around it.
+- **`TextField`** gains `label`, `helper`, `error`, `disabled` and `containerStyle`. An invalid field keeps its danger border while focused.
+- **`spaceActivates(onPress)`**: the `onKeyDown` handler the controls use to answer Space on the web, for a control you build yourself whose role is not a button. It fires once per key press and is ignored on native.
+
+**Theming.** No new scope. All five read **Design > Components > Muted** for the field (background, text colour, border, corner radius, height) and show focus in the primary colour, as `TextField` always has: a field and a Select trigger in their own border, a checkbox and a labelled switch as a 2px ring around the control whose width is always reserved, so focusing moves nothing. A bare switch keeps the host's own focus indication. The Select's option sheet reads **Popover** (background, text colour, border). In the contract, `muted` and `popover` now list these components under `sdkComponents` next to the form widgets they already targeted. The `ring` scope is the Button widget's emphasis border and is not read by these controls.
+
+**Known limits.** On a device a long option list does not scroll to the current choice when it opens (the web does, through focus). A helper or error is linked to its control with `aria-describedby` on the web, for all five controls; a device's screen reader reads it in place, and Android announces an error when it appears.
+
+The built-in Data List, Files and User Management widgets and the form widgets' user and group pickers now draw their search boxes with `SearchField`.
+
+- **`CONTRACT.version` → `1.171.0`** (`Checkbox`, `Select`, `SearchField`, `spaceActivates`; the `TextField` frame props; `sdkComponents` on `muted` and `popover`; and the visible change to `Switch` described above).
 ### What's new in 0.210.0 (contract 1.169.0)
 
 **New component `<Modal>` — the standard dialog.** Widgets that opened a dialog each built their own header, close button and action row inside a bare `<Overlay>`, so no two dialogs in an app matched and none could be restyled from the theme. `<Modal>` is that dialog, built once on `<Overlay>`:
@@ -2510,6 +2561,7 @@ import { defineWidget, validateManifest, useDatastoreQuery, Text, View } from "@
 - `Banner` — the themed inline message. `<Banner tone message>` shows an error, warning, success or notice in place, styled by the theme's `alert` scope; `action` adds one button and `onDismiss` a close control. Use `useToast()` for a brief confirmation instead. Never hand-roll a tinted error box.
 - `Accordion`, `AccordionItem` — themed collapsible sections. `<Accordion><AccordionItem title subtitle trailing>…</AccordionItem></Accordion>` draws its surface from the theme's `card` scope and its headers and dividers from the `list` scope; one section open at a time, or `multiple`. Never hand-roll a collapsible from `Pressable` + a chevron.
 - `Spinner`, `Skeleton` — the themed loading states. `<Spinner size label>` for a pending action; `<Skeleton shape="text" | "block" | "circle" | "listRow">` (or a group of bones) for content whose layout you know. The spinner wears `colors.loader`, the skeleton follows the theme's `loading` scope; both stop under reduced motion and mark one busy region. Never use `ActivityIndicator` or hand-build placeholder bars.
+- `Checkbox`, `Switch`, `Select`, `SearchField` — the themed tick box, on/off toggle, single-choice picker and search box. Like `TextField` they follow the theme's `muted` scope (and `popover` for the Select's option sheet) and take `label`, `helper`, `error` and `disabled`. `Select` opens its options at screen level. Never hand-roll one from `Pressable` and `View`.
 - `Tabs` — the themed tab strip. `<Tabs items value onChange>` draws a segmented control, pills or an underline as the theme's `tabs` scope says; render the selected panel yourself. Never hand-roll tabs from `Pressable` chips.
 - `textRoleStyle(role, typography, colors)`, `TEXT_ROLES` — the style of a semantic text tier, shared with the built-in widgets.
 - `WidgetContextProvider` — React context provider that the host (Studio, Player, exported app) wraps widgets with.
@@ -2541,7 +2593,7 @@ A widget that works but looks unfinished is only half done. `useTheme()` is the
 - **Spend one gradient.** `<Gradient colors={[theme.colors.primary, theme.colors.primaryStrong]} angle={160} style={…}>` is a `View` that paints a gradient behind its children, so it replaces the `View` you'd otherwise give a flat `backgroundColor`. `angle` is CSS degrees (0 = to top, 90 = to right, default 180); text on it uses `colors.onPrimary`. Exactly **one** per widget — on the focal element — and never behind body text. Both hosts render it identically (web paints CSS, native uses `expo-linear-gradient`), so there is no per-platform branching to write; don't import `expo-linear-gradient` yourself and don't write a `backgroundImage` string.
 - **Answer the touch.** Every tappable card, row and list entry lifts while the pointer is over it (web) or it is pressed (touch). One declaration does both: give the Pressable a style FUNCTION and spread `pressableLift` — `<Pressable onPress={open} style={(state) => [styles.card, ...pressableLift(state)]}>`. The lift is a -2px nudge plus one elevation step from `theme.interaction`, with the web transition built in. Never hand-write hover logic or your own pressed shadows, and never fake feedback with `opacity` — a dimmed surface reads as disabling itself.
 - **Size to your container — measure it, don't stretch into it.** The same widget sits in a full-width desktop section (~1400px), a half-width grid cell (~700px) and a phone (~360px), so layout built only from `flex: 1` stretches to fill whatever it is handed — a month calendar ends up with 200px day cells and swallows the page. Measure your own width with `const [width, onLayout] = useContainerWidth();`, spreading `onLayout` on an unpadded root `View` (a React Native callback, so it behaves identically on both hosts). A width of `0` means "not yet measured" and the SDK helpers answer it with the wide form, so do not special-case it — except a count or size computed from the width (a calendar day, a chart, a card grid's cards per line), which renders nothing size-dependent until the width arrives: a widget gets no declared breakpoint prop, but it can always measure. **Every form, list, table and filter bar lays out in three tiers** (sc-8508): `const [width, onLayout] = useContainerWidth();` then branch on `widthTier(width)` — a form is one column narrow, paired short fields at medium, a 2–3 column grid capped near 1000px wide; a list is stacked cards, one-line cards, then real columns under a header; a filter bar is one toolbar row (search, a dropdown per facet, sort) with the active filters as removable chips beneath, and a single "Filters" button opening a panel when narrow. **Cap a repeating cell** rather than giving a grid `flex: 1` — `const cell = Math.max(32, Math.min(Math.floor((usable - gap * (columns - 1)) / columns), 64));`, with a calendar day cell topping out at 56–72px on `aspectRatio: 1`, and the grid given its exact computed width plus `alignSelf: 'center'` when the cap leaves slack. **Split two co-equal surfaces in the wide tier** (`flexDirection: widthTier(width) === 'wide' ? 'row' : 'column'`, each half `{ flex: 1, minWidth: 0 }`) — a picker beside the form it feeds on a wide canvas, stacked in reading order below it. Never hardcode a width, never put `flex: 1` / `height: '100%'` on a content widget's root, and don't read the screen with `Dimensions` — the screen is not the widget. **Whatever you narrow, you centre** — a block that caps its own measure carries all three of `{ width: '100%', maxWidth: FORM_MAX, alignSelf: 'center' }`, because `alignSelf` alone stops the block stretching and sizes it to its content instead, and `maxWidth` alone leaves the widget flush left with dead space beside it; a capped wrap row lays its cells out along the MAIN axis, so it centres with `justifyContent: 'center'` on the row instead — but a card grid or a tile row is never capped. **A card grid fills its lines, it never wraps freely** — a free `flexWrap` strands the remainder (six cards that fit five render 5 + 1). Count the cards that fit the measured width (`const max = Math.max(1, Math.floor((width + gap) / (CARD_MIN + gap)));`), take `const lines = Math.ceil(count / max); const cols = Math.ceil(count / lines);`, and render each slice of `cols` cards as a row of `{ flex: 1, minWidth: 0 }` cells, padding the last line with empty `{ flex: 1 }` spacers so its cards keep the width of the cards above (six that fit five are 3 + 3, ten that fit four are 4 + 4 + 2). **A short value never breaks across lines** — a time, date, price, count, percentage or code takes `numberOfLines={1}` and `flexShrink: 0`, never a fixed width narrower than it, and a narrow slot re-arranges or steps the font down instead. **A metric / stat-tile row FILLS ITS ROW** — when you know the count, balance the lines (`const lines = Math.ceil(count / max); const base = Math.floor(count / lines); const extra = count % lines; const rows = Array.from({ length: lines }, (_, i) => tiles.slice(i * base + Math.min(i, extra), (i + 1) * base + Math.min(i + 1, extra)));`, with `max` 4 / 3 / 2 by tier, each tile `{ flex: 1, minWidth: 0 }`), and when the count comes from data wrap it (`{ flexDirection: 'row', flexWrap: 'wrap', gap: theme.spacing.md }`, each tile `{ flexGrow: 1, flexBasis: TILE_MIN }`, never a `maxWidth` — capped tiles cluster to one side), because a bare `flexDirection: 'row'` has no way to break and a React Native flex child defaults to `flexShrink: 0` (unlike CSS), so the tiles cannot give ground either: the row runs past its container, spilling out of the card natively and cut off by the scrolling page column on web, with nothing thrown and nothing logged, once there are enough of them (four fit where five do not). The basis is also the per-line ceiling — `Math.floor((usable + gap) / (TILE_MIN + gap))` tiles fit a line, so 240 tops out at five across a full-width ~1400px section and 320 at four; past four or five a line the tiles stop reading as cards.
-- **Compose forms — pair fields into rows, don't stack one per row.** Lay the form out in three tiers and cap it near 1000px, centred with the three declarations above — never a 560–720px column alone in a wide box, which leaves a form that IS the page as a narrow strip in empty space. Put short, related fields side by side (first + last name, city + postal code, expiry + CVC): a row of `{ flexDirection: 'row', flexWrap: 'wrap', gap: theme.spacing.md }` with each field cell `{ flexGrow: 1, flexBasis: 160 }` splits the width on a wide card and wraps to stacked on a narrow phone — the right recipe for field pairs because it needs no measurement (a fixed-width column overflows a phone; when a layout needs a real column count instead of wrapping, measure your width as above). Keep wide fields (email, address, notes) full-width with `width: '100%'` — NEVER `flexBasis: '100%'`, which sizes the main axis and therefore claims the parent's whole HEIGHT in a column (sc-7274) — cap it at two–three per row, group a long form into labelled sections, and label every input above it (not placeholder-only). Give a `multiline` field BOTH a floor and a ceiling (`{ minHeight: 150, maxHeight: 260 }`) so a long value scrolls inside the box instead of growing past its card, and keep the Save / Cancel row in normal flow below the fields, never positioned over them. When a field carries an icon beside it (a search glyph, a clear button), the border belongs on the WRAPPER row and the `TextInput` inside it goes borderless and transparent with `flex: 1, minWidth: 0` (the `minWidth: 0` stops a long value pushing the border past its container) — React Native has no `:focus-within`, so drive the wrapper's `borderColor` between `colors.border` and `colors.primary` from the input's own `onFocus` / `onBlur`. A border left on the input rings only its own `<input>` box on web, leaving the icon outside the ring; never absolutely-position the icon over the field to work around it.
+- **Compose forms — pair fields into rows, don't stack one per row.** Lay the form out in three tiers and cap it near 1000px, centred with the three declarations above — never a 560–720px column alone in a wide box, which leaves a form that IS the page as a narrow strip in empty space. Put short, related fields side by side (first + last name, city + postal code, expiry + CVC): a row of `{ flexDirection: 'row', flexWrap: 'wrap', gap: theme.spacing.md }` with each field cell `{ flexGrow: 1, flexBasis: 160 }` splits the width on a wide card and wraps to stacked on a narrow phone — the right recipe for field pairs because it needs no measurement (a fixed-width column overflows a phone; when a layout needs a real column count instead of wrapping, measure your width as above). Keep wide fields (email, address, notes) full-width with `width: '100%'` — NEVER `flexBasis: '100%'`, which sizes the main axis and therefore claims the parent's whole HEIGHT in a column (sc-7274) — cap it at two–three per row, group a long form into labelled sections, and label every input above it (not placeholder-only). Give a `multiline` field BOTH a floor and a ceiling (`{ minHeight: 150, maxHeight: 260 }`) so a long value scrolls inside the box instead of growing past its card, and keep the Save / Cancel row in normal flow below the fields, never positioned over them. A search box is `<SearchField>`, which already carries its glyph and clear control. Put any other icon or unit beside the field as a sibling in a row (`flex: 1, minWidth: 0` on the field, so a long value shrinks instead of pushing the row past its container) rather than rebuilding the field to hold it: a hand-built bordered wrapper around a bare `TextInput` loses the app's input look and its label, focus and error handling.
 - **Respond to touch.** Give every `Pressable` the lift via the function-style `style={(state) => [base, ...pressableLift(state)]}` — see "Answer the touch" above. Never dim with `opacity`, which reads as the surface disabling itself.
 - **Drag and drop — show what is being dragged.** A drag where the item stays put reads as broken. Three things change the moment a drag starts: the **drag proxy** (the item lifts and follows the finger — `...theme.elevation.lg`, `{ scale: 1.03 }`, `opacity: 0.9`; for a tall or full-width item drag a compact `primarySoft` pill with its icon + one line of label instead), the **source placeholder** (the vacated slot keeps its height as a quiet `colors.surfaceMuted` block so the list doesn't collapse), and the **drop target** (one slot at a time highlighted with `primarySoft` or a 2px `colors.primary` border). Always animate the release — settle into the new slot, or `Animated.spring(pan, { toValue: { x: 0, y: 0 }, useNativeDriver: false })` back to the origin on cancel. Build it with `Animated` + `PanResponder` from `react-native` (the only mechanism that behaves identically on both hosts) — never HTML5 drag events (`draggable` / `onDragStart` / `dataTransfer` are web-only, and `document` / `window` are banned) — and start the drag from a `GripVertical` grip handle whenever the row is also tappable or sits in a `ScrollView`. **A board (kanban, pipeline) drops onto ANOTHER column**, which needs four more things: the board's root renders the one proxy (a column clips whatever leaves it); you hit-test the drop yourself — `measureInWindow` every column and the board when the drag starts and compare the gesture's window `moveX` (never `onLayout` frames, which are relative to a padded or scrolled parent) — highlighting exactly one target; the drop WRITES (`update(id, { [statusField]: value })` through `useDatastoreMutation`, optimistic until `refetch()`, a toast and a spring-back on failure); and three or more columns go in a `horizontal` `ScrollView` when `widthTier(width) === "narrow"`, with the grip claiming the gesture (`onStartShouldSetPanResponder`, `onPanResponderTerminationRequest: () => false`) and carrying `touchAction: 'none'` on web so a finger drag moves the card instead of scrolling the page. And because `useRef(PanResponder.create(...))` runs ONCE, everything its callbacks read — the `useCanWrite` flag included, which starts `false` — goes through a ref refreshed every render (`latest.current.canDrag`); the publish gate `widget.staleResponder` rejects a value read directly.
 - **Use icons for clarity.** Pair a `lucide-react-native` icon with its label at a consistent size, coloured from the theme. The label never repeats the icon as a character — with a `Plus` icon the button says "Add item", never "+ Add item" (that renders a doubled plus).

package/dist/checkbox-view.js

@@ -0,0 +1,150 @@
+// The ONE implementation behind the `<Checkbox>` SDK primitive. The platform
+// bindings (`checkbox.js` / `checkbox.native.js`) differ only in where the
+// primitives come from, so the hosts cannot drift.
+//
+// Widgets each drew their own tick box, so one control looked different per
+// widget. This one follows the theme's `muted` scope.
+
+import React from "react";
+import { useHostTheme } from "./hooks.js";
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import { Icon } from "./icon.js";
+import {
+  CHECKBOX_MAX_RADIUS,
+  CHECKBOX_SIZE,
+  CONTROL_MIN_TARGET,
+  focusHaloStyle,
+  resolveFormControlTokens,
+} from "./form-control-tokens.js";
+import {
+  errorMessage,
+  hasNote,
+  isShown,
+  isText,
+  spaceActivates,
+  spokenLabel,
+} from "./form-control-logic.js";
+import { makeFieldFrame } from "./form-control-view.js";
+
+const h = React.createElement;
+
+/**
+ * Bind the shared checkbox to one platform's primitives.
+ *
+ * @param {{View: any, Text: any, Pressable: any}} rn
+ */
+export function makeCheckbox(rn) {
+  const { View, Text, Pressable } = rn;
+  const FieldFrame = makeFieldFrame(rn);
+
+  const Checkbox = React.forwardRef(function Checkbox(props, ref) {
+    const {
+      value = false,
+      onValueChange,
+      label,
+      helper,
+      error,
+      disabled = false,
+      accessibilityLabel,
+      style,
+      containerStyle,
+      onFocus,
+      onBlur,
+      ...rest
+    } = props;
+    const theme = useHostTheme() || DEFAULT_THEME_TOKENS;
+    const t = resolveFormControlTokens(theme);
+    const [focused, setFocused] = React.useState(false);
+    const noteId = React.useId();
+    const checked = Boolean(value);
+    const invalid = isShown(error);
+    const noted = hasNote({ helper, error });
+    const radius = Math.min(t.radius, CHECKBOX_MAX_RADIUS);
+    const toggle = () => {
+      if (!disabled && typeof onValueChange === "function") onValueChange(!checked);
+    };
+
+    const row = h(
+      Pressable,
+      {
+        ...rest,
+        ref,
+        onPress: toggle,
+        onKeyDown: spaceActivates(toggle),
+        onFocus: (event) => {
+          setFocused(true);
+          if (typeof onFocus === "function") onFocus(event);
+        },
+        onBlur: (event) => {
+          setFocused(false);
+          if (typeof onBlur === "function") onBlur(event);
+        },
+        disabled,
+        // accessibilityRole + aria-*: the pair that announces on both hosts.
+        accessibilityRole: "checkbox",
+        "aria-checked": checked,
+        "aria-disabled": disabled,
+        ...(invalid ? { "aria-invalid": true } : null),
+        ...(noted ? { "aria-describedby": noteId } : null),
+        accessibilityLabel: spokenLabel(accessibilityLabel, label),
+        style: [
+          {
+            flexDirection: "row",
+            alignItems: "center",
+            gap: t.rowGap,
+            minHeight: CONTROL_MIN_TARGET,
+            minWidth: CONTROL_MIN_TARGET,
+          },
+          // The frame dims a noted checkbox as a whole.
+          disabled && !noted ? { opacity: t.disabledOpacity } : null,
+          style,
+        ],
+      },
+      h(
+        View,
+        { style: focusHaloStyle(t, focused, radius) },
+        h(
+          View,
+          {
+            style: {
+              width: CHECKBOX_SIZE,
+              height: CHECKBOX_SIZE,
+              alignItems: "center",
+              justifyContent: "center",
+              borderWidth: 1,
+              borderRadius: radius,
+              borderColor: checked ? t.accent : invalid ? t.errorColor : t.borderColor,
+              backgroundColor: checked ? t.accent : t.background,
+            },
+          },
+          checked ? h(Icon, { name: "check", size: 16, color: t.onAccent }) : null,
+        ),
+      ),
+      isText(label)
+        ? h(
+            Text,
+            {
+              style: {
+                flexShrink: 1,
+                color: t.labelColor,
+                fontFamily: t.fontFamily,
+                fontSize: t.fontSize,
+              },
+            },
+            label,
+          )
+        : isShown(label)
+          ? label
+          : null,
+    );
+    if (!noted) return row;
+    return h(
+      FieldFrame,
+      { t, helper, error: errorMessage(error), disabled, noteId, style: containerStyle },
+      row,
+    );
+  });
+
+  Checkbox.displayName = "Checkbox";
+  return Checkbox;
+}

package/dist/checkbox.js

@@ -0,0 +1,11 @@
+// `<Checkbox>` (web). Binds ./checkbox-view.js to react-native-web; see
+// ./primitives.js for why not the bare specifier.
+
+import * as ReactNative from "react-native-web";
+import { makeCheckbox } from "./checkbox-view.js";
+
+export const Checkbox = makeCheckbox({
+  View: ReactNative.View,
+  Text: ReactNative.Text,
+  Pressable: ReactNative.Pressable,
+});

package/dist/checkbox.native.js

@@ -0,0 +1,7 @@
+// `<Checkbox>` (native). Binds ./checkbox-view.js to React Native's own
+// primitives; only the import differs from ./checkbox.js.
+
+import { View, Text, Pressable } from "react-native";
+import { makeCheckbox } from "./checkbox-view.js";
+
+export const Checkbox = makeCheckbox({ View, Text, Pressable });

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",
   },
@@ -3053,7 +3056,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 +5620,15 @@ 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.
+  version: "1.171.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",
   },
@@ -3053,7 +3056,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 +5616,15 @@ 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.
+  version: "1.171.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;
+}