@colixsystems/widget-sdk 0.207.0 → 0.212.0

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" }),
@@ -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,

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;
+}

package/dist/hooks.js

@@ -89,6 +89,19 @@ export function BackdropScope({ basis, children }) {
   return React.createElement(HostWidgetContext.Provider, { value }, children);
 }
 
+/**
+ * @internal — hands a subtree `theme` in place of the host's (`<Modal>` uses
+ * it for the theme re-inked for its own background). No theme, no change.
+ */
+export function ThemeScope({ theme, children }) {
+  const ctx = useContext(HostWidgetContext);
+  const value = useMemo(
+    () => (theme && ctx ? { ...ctx, workspace: { ...ctx.workspace, theme } } : ctx),
+    [ctx, theme],
+  );
+  return React.createElement(HostWidgetContext.Provider, { value }, children);
+}
+
 // Exported for ./toast.js + future hook modules outside hooks.js. Internal
 // utility — widget code should not import this directly.
 export function useWidgetContextOrThrow(hookName) {

package/dist/host.d.ts

@@ -45,6 +45,13 @@ export function normaliseThemeComponents(raw: unknown): ThemeComponents;
  */
 export function bannerScopeDefaults(theme: unknown): Record<string, string | number>;
 
+/**
+ * The theme a surface painting `backgroundColor` hands its subtree: surface
+ * tokens derived for that fill, and any type tier whose own ink cannot be read
+ * on it re-inked. Returns `theme` itself when the colour is unusable.
+ */
+export function surfaceAwareTheme<T>(theme: T, backgroundColor: unknown): T;
+
 /** Minimum contrast: `text` for labels (WCAG 1.4.3), `boundary` for edges (1.4.11). */
 export const INK_CONTRAST: Readonly<{ text: number; boundary: number }>;
 
@@ -152,6 +159,45 @@ export interface ToastControllerOptions {
   clearTimer?: (handle: unknown) => void;
 }
 
+/** What one `<Modal>` paints with; see `resolveModalTokens`. */
+export interface ModalTokens {
+  size: "sm" | "md" | "lg" | "full";
+  presentation: "dialog" | "sheet";
+  scrim: string;
+  /** The `background` token as set (it may be see-through), else the surface. */
+  background: string;
+  /** What the panel paints: `background` composited over the overlay surface. */
+  panelColor: string;
+  /** `panelColor` when a background is set, for re-inking the body; else null. */
+  bodyBackdrop: string | null;
+  radius: number;
+  padding: number;
+  /** The themed elevation as a style, or null for the overlay's own. */
+  shadow: Record<string, unknown> | null;
+  /** The elevation level in force: the themed one, else the overlay's. */
+  shadowLevel: "none" | "sm" | "md" | "lg";
+  titleColor: string;
+  closeColor: string;
+  sectionGap: number;
+  actionGap: number;
+}
+
+/**
+ * The look of the SDK `<Modal>` under a resolved theme: its `modal` component
+ * scope over the overlay's defaults. For a host previewing Theme Settings >
+ * Dialogs with the values the dialog itself paints.
+ */
+export function resolveModalTokens(
+  theme: unknown,
+  options?: { size?: string; presentation?: string },
+): ModalTokens;
+
+/**
+ * What the `modal` scope's tokens without a `uiDefault` path resolve to while
+ * unset: the scrim, and the title colour on the background currently set.
+ */
+export function modalScopeDefaults(theme: unknown): { scrim: string; titleColor: string };
+
 export const TOAST_DEFAULTS: { durationMs: number; maxVisible: number };
 
 export function normalizeToastKind(kind: unknown): ToastKind;

package/dist/host.js

@@ -42,12 +42,16 @@ export {
 // Host plumbing, deliberately off the author entry point: a widget reads the
 // already-correct `useTheme().colors`, it never derives them itself.
 export { deriveSurfaceTokens, inkForBackdrop, INK_CONTRAST } from "./contract.js";
+export { surfaceAwareTheme } from "./surface-theme.js";
 
 // REQ-WSDK-PLATFORM §6: the host half of `useToast()` — the queue, the
 // auto-dismiss timing, and the themed values a toast is painted with. The
 // widget-facing hook only forwards to `ctx.toast.showToast`; the host owns the
 // surface, and sharing everything but the JSX is what keeps the web Player and
 // the Expo export rendering the same notification (CLAUDE.md §8).
+// The dialog's resolved look, for the Studio's Design > Components > Dialogs preview.
+export { resolveModalTokens, modalScopeDefaults } from "./modal-tokens.js";
+
 export {
   createToastController,
   resolveToastTokens,