@colixsystems/widget-sdk 0.207.0 → 0.212.0

package/dist/switch-view.js

@@ -0,0 +1,149 @@
+// The ONE implementation behind the `<Switch>` SDK primitive. The platform
+// bindings (`switch.js` / `switch.native.js`) differ only in where the
+// primitives come from, so the hosts cannot drift.
+//
+// It is the platform's own switch, so it keeps the role, state, keys and
+// disabled look each host gives it; this view adds the theme's track colours,
+// a label, a helper and an error.
+
+import React from "react";
+import { useHostTheme } from "./hooks.js";
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import {
+  CONTROL_MIN_TARGET,
+  focusHaloStyle,
+  resolveFormControlTokens,
+  resolveSwitchColors,
+} from "./form-control-tokens.js";
+import {
+  errorMessage,
+  hasNote,
+  isShown,
+  isText,
+  needsFrame,
+  spokenLabel,
+} from "./form-control-logic.js";
+import { makeFieldFrame } from "./form-control-view.js";
+
+const h = React.createElement;
+const TRACK_RADIUS = 16;
+
+/**
+ * Bind the shared switch to one platform's primitives.
+ *
+ * @param {{View: any, Text: any, Pressable: any, Switch: any}} rn
+ */
+export function makeSwitch(rn) {
+  const { View, Text, Pressable, Switch: PlatformSwitch } = rn;
+  const FieldFrame = makeFieldFrame(rn);
+
+  const Switch = React.forwardRef(function Switch(props, ref) {
+    const {
+      value = false,
+      onValueChange,
+      label,
+      helper,
+      error,
+      disabled = false,
+      accessibilityLabel,
+      trackColor,
+      ios_backgroundColor: iosBackgroundColor,
+      containerStyle,
+      ...rest
+    } = props;
+    const theme = useHostTheme() || DEFAULT_THEME_TOKENS;
+    const t = resolveFormControlTokens(theme);
+    const [focused, setFocused] = React.useState(false);
+    const noteId = React.useId();
+    const on = Boolean(value);
+    const invalid = isShown(error);
+    const noted = hasNote({ helper, error });
+    const colors = resolveSwitchColors(t, { trackColor, iosBackgroundColor, invalid });
+
+    // The thumb is left to the platform unless the caller colours it.
+    const control = h(PlatformSwitch, {
+      ...rest,
+      ref,
+      value: on,
+      onValueChange,
+      disabled,
+      trackColor: colors.trackColor,
+      ios_backgroundColor: colors.iosBackgroundColor,
+      accessibilityLabel: spokenLabel(accessibilityLabel, label),
+      ...(invalid ? { "aria-invalid": true } : null),
+      ...(noted ? { "aria-describedby": noteId } : null),
+    });
+    if (!needsFrame({ label, helper, error })) return control;
+
+    const toggle = () => {
+      if (!disabled && typeof onValueChange === "function") onValueChange(!on);
+    };
+    const row = h(
+      View,
+      {
+        style: {
+          flexDirection: "row",
+          alignItems: "center",
+          justifyContent: "space-between",
+          gap: t.rowGap,
+          minHeight: CONTROL_MIN_TARGET,
+        },
+      },
+      isShown(label)
+        ? h(
+            Pressable,
+            {
+              onPress: toggle,
+              disabled,
+              // The switch itself is the one stop for a keyboard and a reader.
+              tabIndex: -1,
+              accessible: false,
+              style: [
+                { flexShrink: 1, minHeight: CONTROL_MIN_TARGET, justifyContent: "center" },
+                // The control dims itself on each host; only the label is ours.
+                disabled ? { opacity: t.disabledOpacity } : null,
+              ],
+            },
+            isText(label)
+              ? h(
+                  Text,
+                  {
+                    style: {
+                      color: t.labelColor,
+                      fontFamily: t.fontFamily,
+                      fontSize: t.fontSize,
+                    },
+                  },
+                  label,
+                )
+              : label,
+          )
+        : null,
+      h(
+        View,
+        {
+          // Focus events bubble from the control on the web host.
+          onFocus: () => setFocused(true),
+          onBlur: () => setFocused(false),
+          style: focusHaloStyle(t, focused, TRACK_RADIUS),
+        },
+        control,
+      ),
+    );
+    return h(
+      FieldFrame,
+      {
+        t,
+        helper,
+        error: errorMessage(error),
+        noteId,
+        noteDisabled: disabled,
+        style: containerStyle,
+      },
+      row,
+    );
+  });
+
+  Switch.displayName = "Switch";
+  return Switch;
+}

package/dist/switch.js

@@ -0,0 +1,80 @@
+// `<Switch>` (web). Binds ./switch-view.js to react-native-web; see
+// ./primitives.js for why not the bare specifier.
+//
+// This host's switch differs from a device's in ways the shared view cannot
+// see, so they are bridged here and nowhere else:
+//  - it takes `activeTrackColor` and a STRING `trackColor` (the off colour),
+//    and ignores both once it is handed the `{ false, true }` object;
+//  - it colours an "on" thumb from `activeThumbColor`, not `thumbColor`;
+//  - it stops greying a disabled switch once it is given any track colour;
+//  - it forwards only a label to its `<input>`, dropping the other ARIA props.
+
+import React from "react";
+import * as ReactNative from "react-native-web";
+import { makeSwitch } from "./switch-view.js";
+import { DISABLED_OPACITY } from "./form-control-tokens.js";
+import { shareRef } from "./form-control-logic.js";
+
+const ON_THUMB_COLOR = "#ffffff";
+// A caller's own `style.opacity` comes later in the list and wins.
+const DIMMED = { opacity: DISABLED_OPACITY };
+
+function isSet(value) {
+  return value !== undefined && value !== null;
+}
+
+/** The caller's colours in the object form the shared view merges. */
+export function webTrackColor(trackColor, activeTrackColor) {
+  if (trackColor && typeof trackColor === "object") return trackColor;
+  const own = {};
+  if (typeof trackColor === "string") own.false = trackColor;
+  if (isSet(activeTrackColor)) own.true = activeTrackColor;
+  return Object.keys(own).length > 0 ? own : undefined;
+}
+
+const INPUT_ARIA = ["aria-describedby", "aria-invalid"];
+
+const PlatformSwitch = React.forwardRef(function PlatformSwitch(props, ref) {
+  const { "aria-describedby": describedBy, "aria-invalid": invalid, ...rest } = props;
+  const inputRef = React.useRef(null);
+  const setRef = React.useMemo(() => shareRef(ref, inputRef), [ref]);
+  React.useEffect(() => {
+    const input = inputRef.current;
+    if (!input || typeof input.setAttribute !== "function") return;
+    const values = { "aria-describedby": describedBy, "aria-invalid": invalid ? "true" : null };
+    for (const name of INPUT_ARIA) {
+      if (isSet(values[name])) input.setAttribute(name, values[name]);
+      else input.removeAttribute(name);
+    }
+  }, [describedBy, invalid]);
+  return React.createElement(ReactNative.Switch, {
+    activeThumbColor: rest.thumbColor ?? ON_THUMB_COLOR,
+    ...rest,
+    ref: setRef,
+  });
+});
+
+const ThemedSwitch = makeSwitch({
+  View: ReactNative.View,
+  Text: ReactNative.Text,
+  Pressable: ReactNative.Pressable,
+  Switch: PlatformSwitch,
+});
+
+export const Switch = React.forwardRef(function Switch(props, ref) {
+  const { trackColor, activeTrackColor, style, ...rest } = props;
+  const ownColours =
+    isSet(trackColor) ||
+    isSet(activeTrackColor) ||
+    isSet(rest.thumbColor) ||
+    isSet(rest.activeThumbColor);
+  return React.createElement(ThemedSwitch, {
+    ...rest,
+    ref,
+    trackColor: webTrackColor(trackColor, activeTrackColor),
+    // Only a switch that left its colours to us lost the host's grey look.
+    style: rest.disabled && !ownColours ? [DIMMED, style] : style,
+  });
+});
+
+Switch.displayName = "Switch";

package/dist/switch.native.js

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

package/dist/text-field-view.js

@@ -1,14 +1,21 @@
 // The ONE text-entry field, behind the `<TextField>` SDK primitive and the
-// built-in form fields. The bindings differ only in where `TextInput` comes
+// built-in form fields. The bindings differ only in where the primitives come
 // from, so the hosts cannot drift.
 
 import React from "react";
 import { useHostTheme } from "./hooks.js";
 import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import { TEXT_FIELD_TOKEN_NAMES } from "./text-field-tokens.js";
+import { resolveFormControlTokens } from "./form-control-tokens.js";
 import {
-  resolveTextFieldTokens,
-  TEXT_FIELD_TOKEN_NAMES,
-} from "./text-field-tokens.js";
+  errorMessage,
+  hasNote,
+  isShown,
+  needsFrame,
+  shareRef,
+  spokenLabel,
+} from "./form-control-logic.js";
+import { makeFieldFrame } from "./form-control-view.js";
 
 // A paragraph field grows to a ceiling, then scrolls inside itself.
 const MULTILINE = { minHeight: 88, maxHeight: 220, textAlignVertical: "top" };
@@ -16,10 +23,11 @@ const MULTILINE = { minHeight: 88, maxHeight: 220, textAlignVertical: "top" };
 /**
  * Bind the shared field to one platform's primitives.
  *
- * @param {{TextInput: any}} rn
+ * @param {{TextInput: any, View: any, Text: any, Pressable: any}} rn
  */
 export function makeTextField(rn) {
   const { TextInput } = rn;
+  const FieldFrame = makeFieldFrame(rn);
 
   const TextField = React.forwardRef(function TextField(props, ref) {
     const {
@@ -28,6 +36,12 @@ export function makeTextField(rn) {
       placeholderTextColor,
       onFocus,
       onBlur,
+      label,
+      helper,
+      error,
+      disabled = false,
+      containerStyle,
+      accessibilityLabel,
       ...others
     } = props;
     const theme = useHostTheme() || DEFAULT_THEME_TOKENS;
@@ -39,11 +53,21 @@ export function makeTextField(rn) {
       if (TEXT_FIELD_TOKEN_NAMES.includes(key)) overrides[key] = value;
       else rest[key] = value;
     }
-    const t = resolveTextFieldTokens(theme, overrides);
-    return React.createElement(TextInput, {
-      ref,
+    const t = resolveFormControlTokens(theme, overrides);
+    const invalid = isShown(error);
+    const framed = needsFrame({ label, helper, error });
+    const inputRef = React.useRef(null);
+    // Stable, so the host does not detach and re-attach the node every render.
+    const setRef = React.useMemo(() => shareRef(ref, inputRef), [ref]);
+    const noteId = React.useId();
+    const input = React.createElement(TextInput, {
+      ref: setRef,
       multiline,
       placeholderTextColor: placeholderTextColor || t.placeholderColor,
+      accessibilityLabel: spokenLabel(accessibilityLabel, label),
+      ...(disabled ? { editable: false, "aria-disabled": true } : null),
+      ...(invalid ? { "aria-invalid": true } : null),
+      ...(hasNote({ helper, error }) ? { "aria-describedby": noteId } : null),
       style: [
         {
           borderWidth: 1,
@@ -58,6 +82,10 @@ export function makeTextField(rn) {
           fontSize: t.fontSize,
         },
         focused ? { borderColor: t.focusColor } : null,
+        // After focus: an invalid field stays marked while it is being fixed.
+        invalid ? { borderColor: t.errorColor } : null,
+        // The frame dims a framed field as a whole.
+        disabled && !framed ? { opacity: t.disabledOpacity } : null,
         style,
         // After the caller's style: a paragraph field keeps its 88px floor.
         multiline ? MULTILINE : null,
@@ -72,6 +100,24 @@ export function makeTextField(rn) {
       },
       ...rest,
     });
+    if (!framed) return input;
+    return React.createElement(
+      FieldFrame,
+      {
+        t,
+        label,
+        helper,
+        error: errorMessage(error),
+        disabled,
+        noteId,
+        onLabelPress: () => {
+          const node = inputRef.current;
+          if (node && typeof node.focus === "function") node.focus();
+        },
+        style: containerStyle,
+      },
+      input,
+    );
   });
 
   TextField.displayName = "TextField";

package/dist/text-field.js

@@ -5,4 +5,9 @@ import * as ReactNative from "react-native-web";
 import { makeTextField } from "./text-field-view.js";
 import { TextInput } from "./primitives.js";
 
-export const TextField = makeTextField({ ...ReactNative, TextInput });
+export const TextField = makeTextField({
+  TextInput,
+  View: ReactNative.View,
+  Text: ReactNative.Text,
+  Pressable: ReactNative.Pressable,
+});

package/dist/text-field.native.js

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

package/dist/web-modal.js

@@ -7,7 +7,8 @@
 // re-render rebuilt it, and its Escape and focus handling never re-armed.
 //
 // Implements only the `Modal` props `<Overlay>` passes: `visible`,
-// `onRequestClose` and `children`; it is never animated.
+// `onRequestClose`, the dialog's role and name, `initialFocusRef` and
+// `children`; it is never animated.
 
 import React from "react";
 import { createPortal } from "react-dom";
@@ -37,13 +38,25 @@ function tabStops(dialog) {
 }
 
 /**
- * @param {{visible?: boolean, onRequestClose?: () => void, children?: any}} props
+ * @param {{visible?: boolean, onRequestClose?: () => void, role?: string,
+ *   "aria-label"?: string, "aria-labelledby"?: string,
+ *   initialFocusRef?: {current: any}, children?: any}} props
  */
-export function WebModal({ visible = true, onRequestClose, children }) {
+export function WebModal({
+  visible = true,
+  onRequestClose,
+  role = "dialog",
+  "aria-label": ariaLabel,
+  "aria-labelledby": ariaLabelledBy,
+  initialFocusRef,
+  children,
+}) {
   const [container, setContainer] = React.useState(null);
   const dialogRef = React.useRef(null);
   const onCloseRef = React.useRef(onRequestClose);
   onCloseRef.current = onRequestClose;
+  const initialFocusRefRef = React.useRef(initialFocusRef);
+  initialFocusRefRef.current = initialFocusRef;
   // Taken before the dialog mounts, so a child that focuses itself on mount
   // cannot become the place focus returns to.
   const returnFocusRef = React.useRef(null);
@@ -67,7 +80,11 @@ export function WebModal({ visible = true, onRequestClose, children }) {
     openLayers.push(layer);
     const isTop = () => openLayers[openLayers.length - 1] === layer;
     const returnFocusTo = returnFocusRef.current;
-    if (!dialog.contains(document.activeElement)) {
+    const wanted = initialFocusRefRef.current;
+    const first = wanted && wanted.current;
+    if (first && typeof first.focus === "function") {
+      first.focus({ preventScroll: true });
+    } else if (!dialog.contains(document.activeElement)) {
       dialog.focus({ preventScroll: true });
     }
 
@@ -127,8 +144,10 @@ export function WebModal({ visible = true, onRequestClose, children }) {
       "div",
       {
         ref: dialogRef,
-        role: "dialog",
+        role,
         "aria-modal": "true",
+        "aria-label": ariaLabel,
+        "aria-labelledby": ariaLabelledBy,
         tabIndex: -1,
         style: layerStyle,
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.207.0",
+  "version": "0.212.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",

package/src/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" }),
@@ -723,6 +726,25 @@ const THEME_COMPONENTS = Object.freeze({
     }),
     targets: Object.freeze({}),
   }),
+  // Dialogs: `<Modal>` reads this scope directly, so it names the SDK component
+  // it styles and binds no widget field. `<Overlay>` reads the scrim alone.
+  modal: Object.freeze({
+    label: "Dialogs",
+    sdkComponents: Object.freeze(["Modal"]),
+    tokens: Object.freeze({
+      background: Object.freeze({ type: "color", uiDefault: "colors.surface" }),
+      titleColor: Object.freeze({ type: "color" }),
+      scrim: Object.freeze({
+        type: "color",
+        translucent: true,
+        note: "also the backdrop behind every <Overlay>",
+      }),
+      radius: Object.freeze({ type: "size", min: 0, max: 48, uiDefault: "radii.lg" }),
+      padding: Object.freeze({ type: "size", min: 0, max: 64, uiDefault: "spacing.lg" }),
+      shadow: Object.freeze({ type: "shadow" }),
+    }),
+    targets: Object.freeze({}),
+  }),
 });
 
 // sc-4505 — the value types a widget event payload field may declare. Narrower
@@ -2792,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",
   },
@@ -2886,7 +2908,15 @@ const PRIMITIVES = [
   {
     name: "Overlay",
     description:
-      'Screen-level overlay. `<Overlay visible={open} onRequestClose={() => setOpen(false)} size="md">…panel…</Overlay>`. THE way to open anything that must cover the SCREEN rather than the widget — a preview (PDF, image, video), a lightbox, a confirm dialog, a full detail panel. It renders OUTSIDE the widget layout box on both hosts (react-native-web portals it to the document root; native uses the OS modal), so no `overflow: hidden` card, scroll container or sibling widget can clip or cover it — which absolute positioning inside the widget cannot achieve on either host. Children stay in your own React tree, so state and hooks work normally. Props: `visible` (boolean, required to show), `onRequestClose` (fired by the backdrop press, the Escape key on web, and the Android back button — always wire it or the overlay cannot be closed), `size` ("sm" | "md" | "lg" | "full", default "md"; `full` runs edge to edge for media), `dismissOnBackdropPress` (default true), `accessibilityLabel`, and `style` for extra panel styles. The scrim, surface, radius, padding and elevation come from the workspace theme — never re-style them. Keep it for screen-level surfaces: a dropdown anchored to its trigger still belongs inside the widget.',
+      'Screen-level overlay. `<Overlay visible={open} onRequestClose={() => setOpen(false)} size="md">…panel…</Overlay>`. THE way to open anything that must cover the SCREEN rather than the widget and is not a dialog — a preview (PDF, image, video), a lightbox, a full-screen viewer. A dialog (a title, a close button, actions) is `<Modal>`, which is built on this. It renders OUTSIDE the widget layout box on both hosts (react-native-web portals it to the document root; native uses the OS modal), so no `overflow: hidden` card, scroll container or sibling widget can clip or cover it — which absolute positioning inside the widget cannot achieve on either host. Children stay in your own React tree, so state and hooks work normally. Props: `visible` (boolean, required to show), `onRequestClose` (fired by the backdrop press, the Escape key on web, and the Android back button — always wire it or the overlay cannot be closed), `size` ("sm" | "md" | "lg" | "full", default "md"; `full` runs edge to edge for media), `presentation` ("dialog", centred, the default | "sheet", anchored to the bottom edge), `dismissOnBackdropPress` (default true), `role` ("dialog" default | "alertdialog"; web only), `initialFocusRef` (web only), `accessibilityLabel` (names the dialog), `testID`, and `style` for extra panel styles. The scrim, surface, radius, padding and elevation come from the workspace theme (the scrim from Design > Components > Dialogs) — never re-style them. Keep it for screen-level surfaces: a dropdown anchored to its trigger still belongs inside the widget.',
+    rnComponent: null,
+    docsUrl: null,
+  },
+  // The standard dialog, built on `<Overlay>`, so widgets stop hand-building one.
+  {
+    name: "Modal",
+    description:
+      'Standard dialog. `<Modal visible={open} onRequestClose={() => setOpen(false)} title="Edit order" footer={<><Button variant="secondary" title="Cancel" onPress={() => setOpen(false)} /><Button title="Save" onPress={save} /></>}>…body…</Modal>`. THE way to open a dialog, a form in a pop-up, a detail panel or a bottom sheet: it draws the title, the close button, a body that scrolls when it is long, and a footer action row laid out below it, and its background, corner radius, padding, scrim, shadow and title colour come from the theme (Design > Components > Dialogs), so every dialog in the app matches. It is built on `<Overlay>`, so it renders OUTSIDE the widget layout box on both hosts and nothing can clip it. Never hand-build a header, a close button or an action row inside a bare `<Overlay>`; keep `<Overlay>` for surfaces that are not a dialog (a media or document preview, a lightbox). Props: `visible` (boolean), `onRequestClose` (fired by the close button, the backdrop press, the Escape key on web and the Android back button — always wire it), `dismissible` (default true; false hides the close button and stops the backdrop, Escape and Android back from closing it, for a dialog that must stay open while it saves — only while that work runs, and always restore it, or nobody can close the dialog), `title` (string), `footer` (the action buttons, laid out as one right-aligned row that wraps on a phone; omit for no footer), `presentation` ("dialog", centred, the default | "sheet", anchored to the bottom edge; keep a form with text inputs in "dialog" — in the exported app the keyboard handling of a sheet is not yet verified on a device), `size` ("sm" | "md" | "lg" | "full", default "md"), `dismissOnBackdropPress` (default true), `role` ("dialog" default | "alertdialog"; web only), `initialFocusRef` (a ref to the control focused on open; web only), `closeAccessibilityLabel` (default "Close" — pass your translated label), `accessibilityLabel` (names a dialog with no title) and `testID`. With no `onRequestClose` it draws no close button. Components rendered inside it read a theme re-inked for the background the dialog paints, so build the body as its own component. Do not wrap the body in your own `ScrollView` and do not re-style the panel.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -3026,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,
   },
@@ -5550,7 +5608,23 @@ const CONTRACT = deepFreeze({
   // 1.166.0: additive (sc-10927) — the `Banner` primitive (a themed inline
   //    error, warning, success or notice) and the `alert` component scope it
   //    reads.
-  version: "1.166.0",
+  // 1.169.0: additive (sc-10924) — the `Modal` primitive: the standard dialog
+  //    (title, close button, scrolling body, footer action row; `presentation`
+  //    "dialog" | "sheet") built on `Overlay`. New `themeComponents.modal`
+  //    scope (background, titleColor, scrim, radius, padding, shadow), read by
+  //    `Modal`; `Overlay` reads its `scrim` and gains `presentation`, `role`,
+  //    `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`.
+  // 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,