@colixsystems/widget-sdk 0.236.0 → 0.237.0

package/README.md

@@ -84,7 +84,13 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.236.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.237.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.237.0 (contract 1.191.0)
+
+**Search boxes have a look of their own.** A new `search` scope on `CONTRACT.themeComponents` (Design > Components > Search fields) restyles every `<SearchField>`: `iconPosition` (`"start"` | `"end"` | `"none"`), `radius` (0–48, so a pill), `background`, `borderColor` and `height`. Each token falls back to the input look (`muted`, Design > Components > Inputs) when unset, so with none set every search box looks exactly as before. `<SearchField iconPosition>` overrides the theme for one field; any `TextField` look prop you pass still wins over the theme. At the end, the clear control takes the icon's place while the field has text, so the two never overlap. Leave the look to the theme: do not pass your own radius, background, border or height, and never add a magnifier icon yourself. `searchScopeDefaults(theme)` on `@colixsystems/widget-sdk/host` gives the Studio the input look each unset token keeps.
+
+**Clearer section names.** Design > Components now names the scopes for what they restyle: `muted` is **Inputs**, `popover` **Dropdown menus**, `destructive` **Danger buttons**, `ring` **Button outline** (a permanent border on the Button widget, not a focus style) and `accent` **Labels**. Only the labels changed; the scope keys are the same.
 
 ### What's new in 0.236.0 (contract 1.190.0)
 
@@ -1190,7 +1196,7 @@ A binding may now carry an opacity: `"theme:colors.primary/20"` is the primary b
 ```
 
 - **`<Card>`** takes the app's card look (Theme Settings > Cards) with no props. Override one card with `background`, `borderColor`, `radius`, `padding`, `shadow` or `gradient`, or pass `style={props.style}` when your widget declares the `card*` style fields. `as={Pressable}` makes the whole card pressable.
-- **`<Button>`** follows Theme Settings > Buttons (and Destructive / Focus ring). `variant` is `primary` | `secondary` | `outlined` | `danger`; `icon` / `iconPosition` add a lucide glyph; omit `onPress` for a visual inside something pressable; `fields` overrides one button's surface.
+- **`<Button>`** follows Design > Components > Buttons (and Danger buttons / Button outline). `variant` is `primary` | `secondary` | `outlined` | `danger`; `icon` / `iconPosition` add a lucide glyph; omit `onPress` for a visual inside something pressable; `fields` overrides one button's surface.
 - **`<TextField>`** is a `TextInput` in the app's input look (Theme Settings > Muted, which gains a **`height`** token); `multiline` grows to a ceiling, then scrolls.
 
 The card and button resolvers (`cardOverlay`, `shadowStyle`, `marginStyle`, `buttonSurfaceOverlay`, …) are exported too. Additive: the built-in widgets render exactly as before.
@@ -2920,11 +2926,11 @@ import { defineWidget, validateManifest, useDatastoreQuery, Text, View } from "@
 - `isSafeMarkdownImageSrc`, `isHttpImageSrc`, `normaliseMarkdownImageSize`, `readMarkdownAlt` — the image half of that grammar, for a widget rendering images itself via `renderImage`. `isSafeMarkdownImageSrc` is the same allowlist the parser applies (an `http(s)` URL or a filestore id; a `javascript:` scheme is refused), so the widget and the parser cannot disagree about which src is renderable.
 - `List`, `ListRow`, `ListHeader`, `EmptyState` — the themed list building blocks. `<ListRow title subtitle leading trailing onPress selected divider>` draws one record row from the theme's `list` scope (padding, height, gap, radius, background, divider); `<List>` spaces its rows and hands overrides down; `<ListHeader>` labels a table's columns on the rows' own inset; `<EmptyState icon title message>` is the "nothing here" panel. Never hand-roll a row or a header row from `View` + `Pressable`.
 - `Badge`, `Avatar`, `Progress`, `Stat`, `Divider` — the themed status pill, person picture, completion bar or ring, headline figure and rule the built-in widgets of the same names render through. Reach for them inside a record row instead of hand-rolling a pill or a circle from `View`.
-- `Card`, `Button`, `TextField` — the themed card surface, button and text field the built-in widgets render through. With no props each takes the app's look from Theme Settings (Cards, Buttons, Muted); never hand-roll one from `View` / `Pressable` / a bare `TextInput`.
+- `Card`, `Button`, `TextField` — the themed card surface, button and text field the built-in widgets render through. With no props each takes the app's look from Design > Components (Cards, Buttons, Inputs); never hand-roll one from `View` / `Pressable` / a bare `TextInput`.
 - `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`.
+- `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, Design > Components > Inputs (and `popover`, Dropdown menus, for the Select's option sheet; `SearchField` also reads `search`, Search fields, for its glyph position, corner radius, background, border colour and height, each falling back to Inputs) 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.
 - `Chip`, `ChipGroup` — the themed filter chip, tag or pill. `<Chip label selected onPress onRemove disabled>` follows the theme's `chip` scope; `<ChipGroup>` spaces and wraps its chips and, with `selection="single"`, announces them as one choice. Never hand-roll a chip from `Pressable` + a pill radius.
 - `textRoleStyle(role, typography, colors)`, `TEXT_ROLES` — the style of a semantic text tier, shared with the built-in widgets.

package/dist/contract.cjs

@@ -275,6 +275,9 @@ function formatThemeColorTokenRef(path, percent) {
 // The looks a `tabs.style` token may name; `<Tabs>` draws each.
 const THEME_TAB_STYLES = Object.freeze(["segmented", "pill", "underline"]);
 
+// Where `<SearchField>` draws its magnifier; "start" is the look it always had.
+const THEME_SEARCH_ICON_POSITIONS = Object.freeze(["start", "end", "none"]);
+
 const THEME_COMPONENT_SHADOWS = Object.freeze(["none", "sm", "md", "lg"]);
 
 // sc-3857 — the `textTransform` token's closed enum, matching the per-instance
@@ -585,7 +588,7 @@ const THEME_COMPONENTS = Object.freeze({
   // than its `color` field, which the `text` scope already owns -- two
   // scopes writing the same field on the same widget would race.
   accent: Object.freeze({
-    label: "Accent",
+    label: "Labels",
     tokens: Object.freeze({
       background: Object.freeze({ type: "color", uiDefault: "colors.primarySoft" }),
       borderColor: Object.freeze({ type: "color", uiDefault: "colors.primary" }),
@@ -602,7 +605,7 @@ const THEME_COMPONENTS = Object.freeze({
   // sc-5392 -- the Button widget's danger/delete variant. Separate token set
   // from `button` above so "make the buttons coral" never recolours Delete.
   destructive: Object.freeze({
-    label: "Destructive",
+    label: "Danger buttons",
     tokens: Object.freeze({
       background: Object.freeze({ type: "color", uiDefault: "colors.danger" }),
       textColor: Object.freeze({ type: "color", uiDefault: "colors.onPrimary" }),
@@ -617,7 +620,7 @@ const THEME_COMPONENTS = Object.freeze({
   // scope) rather than to Text/Label/Data Value, whose `color` field the
   // `text` scope already owns.
   muted: Object.freeze({
-    label: "Muted",
+    label: "Inputs",
     // The SDK's form controls read this scope directly, in every widget.
     sdkComponents: Object.freeze(["TextField", "Checkbox", "Switch", "Select", "SearchField"]),
     tokens: Object.freeze({
@@ -636,7 +639,7 @@ const THEME_COMPONENTS = Object.freeze({
   // sc-5392 -- dropdown/menu surfaces. The form widgets' choice-field option
   // list is the closest thing the built-in catalog has to a popover panel.
   popover: Object.freeze({
-    label: "Popover",
+    label: "Dropdown menus",
     sdkComponents: Object.freeze(["Select"]),
     tokens: Object.freeze({
       background: Object.freeze({ type: "color", uiDefault: "colors.surface" }),
@@ -648,11 +651,26 @@ const THEME_COMPONENTS = Object.freeze({
       "appstudio.form-builder": POPOVER_FIELDS,
     }),
   }),
-  // sc-5392 -- the app-wide focus-visible outline. A themed emphasis border
+  // Search boxes: `<SearchField>` reads this scope directly. Every token is
+  // unset by default and falls back to the `muted` field it draws.
+  search: Object.freeze({
+    label: "Search fields",
+    sdkComponents: Object.freeze(["SearchField"]),
+    tokens: Object.freeze({
+      iconPosition: Object.freeze({ type: "enum", values: THEME_SEARCH_ICON_POSITIONS }),
+      // 48 is past half the tallest field, so its ceiling draws a pill.
+      radius: Object.freeze({ type: "size", min: 0, max: 48 }),
+      background: Object.freeze({ type: "color" }),
+      borderColor: Object.freeze({ type: "color" }),
+      height: Object.freeze({ type: "size", min: 32, max: 72 }),
+    }),
+    targets: Object.freeze({}),
+  }),
+  // sc-5392 -- not a keyboard focus style: a permanent emphasis border
   // on the Button widget, applied after its variant colours and beaten by the
   // widget's own per-instance `borderColor` (REQ-THEME-13 stays final).
   ring: Object.freeze({
-    label: "Focus ring",
+    label: "Button outline",
     tokens: Object.freeze({
       color: Object.freeze({ type: "color", uiDefault: "colors.primary" }),
       width: Object.freeze({ type: "size", min: 0, max: 8 }),
@@ -3093,7 +3111,7 @@ const PRIMITIVES = [
   {
     name: "Switch",
     description:
-      '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`.',
+      '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 > Inputs). `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",
   },
@@ -3202,7 +3220,7 @@ const PRIMITIVES = [
   {
     name: "ConfirmDialog",
     description:
-      'Standard confirmation prompt, a preset of `<Modal>`. `<ConfirmDialog visible={!!pending} tone="destructive" title="Delete this order?" message="This cannot be undone." confirmLabel={t("delete", "Delete")} onCancel={() => setPending(null)} onConfirm={async () => { await remove(pending.id); setPending(null); }} />`. THE way to ask "are you sure?" before a delete or any other action that cannot be undone, so every confirmation in the app has the same wording slots, button order and colours. Never hand-build one from a `<Modal>` or an `<Overlay>` with your own two buttons, never arm a button to be pressed twice, and never use `Alert.alert` or `window.confirm`. Props: `visible` (boolean), `title` (string, the question), `message` (what confirming does; text or a node), `confirmLabel` and `cancelLabel` (default the app\'s translated "Confirm" and "Cancel" — name the action: "Delete", "Remove", "Send"), `tone` ("default" | "destructive"; destructive draws the confirm button from the theme\'s Destructive colours and opens with focus on Cancel), `busy` (boolean; disables both buttons, shows a `<Spinner>` and keeps the dialog open), `onConfirm` (return the promise of the action and the dialog stays busy until it settles, with a second press ignored; a rejection is NOT caught, so catch a failure yourself and report it), `onCancel` (fired by the Cancel button, the close button, the backdrop press, the Escape key on web and the Android back button — cancelling is always the safe default), `closeAccessibilityLabel` and `testID`. The dialog never closes itself: set `visible` false from `onCancel` and after the action. Its panel follows the theme (Design > Components > Dialogs) and its buttons the Buttons and Destructive settings — do not re-style it.',
+      'Standard confirmation prompt, a preset of `<Modal>`. `<ConfirmDialog visible={!!pending} tone="destructive" title="Delete this order?" message="This cannot be undone." confirmLabel={t("delete", "Delete")} onCancel={() => setPending(null)} onConfirm={async () => { await remove(pending.id); setPending(null); }} />`. THE way to ask "are you sure?" before a delete or any other action that cannot be undone, so every confirmation in the app has the same wording slots, button order and colours. Never hand-build one from a `<Modal>` or an `<Overlay>` with your own two buttons, never arm a button to be pressed twice, and never use `Alert.alert` or `window.confirm`. Props: `visible` (boolean), `title` (string, the question), `message` (what confirming does; text or a node), `confirmLabel` and `cancelLabel` (default the app\'s translated "Confirm" and "Cancel" — name the action: "Delete", "Remove", "Send"), `tone` ("default" | "destructive"; destructive draws the confirm button from the theme\'s Danger buttons colours and opens with focus on Cancel), `busy` (boolean; disables both buttons, shows a `<Spinner>` and keeps the dialog open), `onConfirm` (return the promise of the action and the dialog stays busy until it settles, with a second press ignored; a rejection is NOT caught, so catch a failure yourself and report it), `onCancel` (fired by the Cancel button, the close button, the backdrop press, the Escape key on web and the Android back button — cancelling is always the safe default), `closeAccessibilityLabel` and `testID`. The dialog never closes itself: set `visible` false from `onCancel` and after the action. Its panel follows the theme (Design > Components > Dialogs) and its buttons the Buttons and Destructive settings — do not re-style it.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -3349,35 +3367,35 @@ const PRIMITIVES = [
   {
     name: "Button",
     description:
-      'Themed button. `<Button title="Save" onPress={save} />` — THE way to draw a button: its fill, label colour, border, corner radius, padding, weight, shadow and gradient come from the app\'s button look (Theme Settings > Buttons, and Destructive / Focus ring for the danger variant and emphasis border), so it matches the built-in Button widget. Props: `title`, `onPress` (omit it for a purely visual button inside something else that is pressable), `variant` ("primary" default | "secondary" | "outlined" | "danger"), `icon` (a lucide name) with `iconPosition` ("leading" | "trailing"), `disabled`, `accessibilityLabel`, `testID`, `style` (extra container style, e.g. `alignSelf`) and `labelStyle`. Pass `fields` — `{ background, textColor, borderColor, borderWidth, paddingX, paddingY, radius, fontWeight, fontSize, shadow, gradient }` — to override one button, e.g. from style fields your widget declares. On a section that paints its own fill (`theme.colors.backdrop` there), a variant colour that the section makes unreadable takes that section\'s text colour, as its text does: an outlined label and border, a secondary whose fill disappears becomes outlined, and a primary or danger fill turns inverse (that text colour as its fill, its own colour as its label). A white or lightly tinted panel changes nothing, and a button inside a `<Card>` is measured against that card. A colour you pass in `fields`, `style` or `labelStyle`, or that the app\'s button look sets, is never changed. Never hand-roll a button from `Pressable` + background + radius.',
+      'Themed button. `<Button title="Save" onPress={save} />` — THE way to draw a button: its fill, label colour, border, corner radius, padding, weight, shadow and gradient come from the app\'s button look (Design > Components > Buttons, and Danger buttons / Button outline for the danger variant and emphasis border), so it matches the built-in Button widget. Props: `title`, `onPress` (omit it for a purely visual button inside something else that is pressable), `variant` ("primary" default | "secondary" | "outlined" | "danger"), `icon` (a lucide name) with `iconPosition` ("leading" | "trailing"), `disabled`, `accessibilityLabel`, `testID`, `style` (extra container style, e.g. `alignSelf`) and `labelStyle`. Pass `fields` — `{ background, textColor, borderColor, borderWidth, paddingX, paddingY, radius, fontWeight, fontSize, shadow, gradient }` — to override one button, e.g. from style fields your widget declares. On a section that paints its own fill (`theme.colors.backdrop` there), a variant colour that the section makes unreadable takes that section\'s text colour, as its text does: an outlined label and border, a secondary whose fill disappears becomes outlined, and a primary or danger fill turns inverse (that text colour as its fill, its own colour as its label). A white or lightly tinted panel changes nothing, and a button inside a `<Card>` is measured against that card. A colour you pass in `fields`, `style` or `labelStyle`, or that the app\'s button look sets, is never changed. Never hand-roll a button from `Pressable` + background + radius.',
     rnComponent: null,
     docsUrl: null,
   },
   {
     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. `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`.',
+      '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 (Design > Components > Inputs), 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 "✓".',
+      '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 > Inputs) 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.',
+      '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 > Inputs) showing the chosen label; pressing it opens the options at SCREEN level, in a sheet painted from Design > Components > Dropdown menus, 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.',
+      '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 props, same `label` / `helper` / `error` / `disabled`, the input look restyled by Design > Components > Search fields) 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). Where the glyph sits (start, end or hidden), the corner radius, background, border colour and height come from the app; `iconPosition` ("start" | "end" | "none") overrides the glyph for one field, and at the end the clear control takes the glyph\'s place while there is text. Debounce the query yourself before you fetch. Never hand-roll a search box from a `TextInput` + an icon, and never add a magnifier of your own.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -6053,7 +6071,12 @@ const CONTRACT = deepFreeze({
   //    calendar sheet instead of the browser's date popup; both hosts show
   //    the value in the app's language with a clear button. New optional
   //    props: placeholder, clearLabel, doneLabel, closeAccessibilityLabel, testID.
-  version: "1.190.0",
+  // 1.191.0: additive (sc-11759) — `themeComponents.search` styles every
+  //    `<SearchField>`: icon position, corner radius, background, border
+  //    colour, height, each falling back to the `muted` field. The field
+  //    takes an `iconPosition` prop. Scope labels renamed (sc-11763); keys
+  //    unchanged.
+  version: "1.191.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -6069,6 +6092,7 @@ const CONTRACT = deepFreeze({
   themeColorTokens: THEME_COLOR_TOKENS,
   themeComponents: THEME_COMPONENTS,
   themeComponentTabStyles: THEME_TAB_STYLES,
+  themeComponentSearchIconPositions: THEME_SEARCH_ICON_POSITIONS,
   themeComponentShadows: THEME_COMPONENT_SHADOWS,
   themeComponentTextTransforms: THEME_COMPONENT_TEXT_TRANSFORMS,
   themeComponentGradient: THEME_COMPONENT_GRADIENT,

package/dist/contract.js

@@ -275,6 +275,9 @@ function formatThemeColorTokenRef(path, percent) {
 // The looks a `tabs.style` token may name; `<Tabs>` draws each.
 const THEME_TAB_STYLES = Object.freeze(["segmented", "pill", "underline"]);
 
+// Where `<SearchField>` draws its magnifier; "start" is the look it always had.
+const THEME_SEARCH_ICON_POSITIONS = Object.freeze(["start", "end", "none"]);
+
 const THEME_COMPONENT_SHADOWS = Object.freeze(["none", "sm", "md", "lg"]);
 
 // sc-3857 — the `textTransform` token's closed enum, matching the per-instance
@@ -585,7 +588,7 @@ const THEME_COMPONENTS = Object.freeze({
   // than its `color` field, which the `text` scope already owns -- two
   // scopes writing the same field on the same widget would race.
   accent: Object.freeze({
-    label: "Accent",
+    label: "Labels",
     tokens: Object.freeze({
       background: Object.freeze({ type: "color", uiDefault: "colors.primarySoft" }),
       borderColor: Object.freeze({ type: "color", uiDefault: "colors.primary" }),
@@ -602,7 +605,7 @@ const THEME_COMPONENTS = Object.freeze({
   // sc-5392 -- the Button widget's danger/delete variant. Separate token set
   // from `button` above so "make the buttons coral" never recolours Delete.
   destructive: Object.freeze({
-    label: "Destructive",
+    label: "Danger buttons",
     tokens: Object.freeze({
       background: Object.freeze({ type: "color", uiDefault: "colors.danger" }),
       textColor: Object.freeze({ type: "color", uiDefault: "colors.onPrimary" }),
@@ -617,7 +620,7 @@ const THEME_COMPONENTS = Object.freeze({
   // scope) rather than to Text/Label/Data Value, whose `color` field the
   // `text` scope already owns.
   muted: Object.freeze({
-    label: "Muted",
+    label: "Inputs",
     // The SDK's form controls read this scope directly, in every widget.
     sdkComponents: Object.freeze(["TextField", "Checkbox", "Switch", "Select", "SearchField"]),
     tokens: Object.freeze({
@@ -636,7 +639,7 @@ const THEME_COMPONENTS = Object.freeze({
   // sc-5392 -- dropdown/menu surfaces. The form widgets' choice-field option
   // list is the closest thing the built-in catalog has to a popover panel.
   popover: Object.freeze({
-    label: "Popover",
+    label: "Dropdown menus",
     sdkComponents: Object.freeze(["Select"]),
     tokens: Object.freeze({
       background: Object.freeze({ type: "color", uiDefault: "colors.surface" }),
@@ -648,11 +651,26 @@ const THEME_COMPONENTS = Object.freeze({
       "appstudio.form-builder": POPOVER_FIELDS,
     }),
   }),
-  // sc-5392 -- the app-wide focus-visible outline. A themed emphasis border
+  // Search boxes: `<SearchField>` reads this scope directly. Every token is
+  // unset by default and falls back to the `muted` field it draws.
+  search: Object.freeze({
+    label: "Search fields",
+    sdkComponents: Object.freeze(["SearchField"]),
+    tokens: Object.freeze({
+      iconPosition: Object.freeze({ type: "enum", values: THEME_SEARCH_ICON_POSITIONS }),
+      // 48 is past half the tallest field, so its ceiling draws a pill.
+      radius: Object.freeze({ type: "size", min: 0, max: 48 }),
+      background: Object.freeze({ type: "color" }),
+      borderColor: Object.freeze({ type: "color" }),
+      height: Object.freeze({ type: "size", min: 32, max: 72 }),
+    }),
+    targets: Object.freeze({}),
+  }),
+  // sc-5392 -- not a keyboard focus style: a permanent emphasis border
   // on the Button widget, applied after its variant colours and beaten by the
   // widget's own per-instance `borderColor` (REQ-THEME-13 stays final).
   ring: Object.freeze({
-    label: "Focus ring",
+    label: "Button outline",
     tokens: Object.freeze({
       color: Object.freeze({ type: "color", uiDefault: "colors.primary" }),
       width: Object.freeze({ type: "size", min: 0, max: 8 }),
@@ -3093,7 +3111,7 @@ const PRIMITIVES = [
   {
     name: "Switch",
     description:
-      '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`.',
+      '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 > Inputs). `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",
   },
@@ -3202,7 +3220,7 @@ const PRIMITIVES = [
   {
     name: "ConfirmDialog",
     description:
-      'Standard confirmation prompt, a preset of `<Modal>`. `<ConfirmDialog visible={!!pending} tone="destructive" title="Delete this order?" message="This cannot be undone." confirmLabel={t("delete", "Delete")} onCancel={() => setPending(null)} onConfirm={async () => { await remove(pending.id); setPending(null); }} />`. THE way to ask "are you sure?" before a delete or any other action that cannot be undone, so every confirmation in the app has the same wording slots, button order and colours. Never hand-build one from a `<Modal>` or an `<Overlay>` with your own two buttons, never arm a button to be pressed twice, and never use `Alert.alert` or `window.confirm`. Props: `visible` (boolean), `title` (string, the question), `message` (what confirming does; text or a node), `confirmLabel` and `cancelLabel` (default the app\'s translated "Confirm" and "Cancel" — name the action: "Delete", "Remove", "Send"), `tone` ("default" | "destructive"; destructive draws the confirm button from the theme\'s Destructive colours and opens with focus on Cancel), `busy` (boolean; disables both buttons, shows a `<Spinner>` and keeps the dialog open), `onConfirm` (return the promise of the action and the dialog stays busy until it settles, with a second press ignored; a rejection is NOT caught, so catch a failure yourself and report it), `onCancel` (fired by the Cancel button, the close button, the backdrop press, the Escape key on web and the Android back button — cancelling is always the safe default), `closeAccessibilityLabel` and `testID`. The dialog never closes itself: set `visible` false from `onCancel` and after the action. Its panel follows the theme (Design > Components > Dialogs) and its buttons the Buttons and Destructive settings — do not re-style it.',
+      'Standard confirmation prompt, a preset of `<Modal>`. `<ConfirmDialog visible={!!pending} tone="destructive" title="Delete this order?" message="This cannot be undone." confirmLabel={t("delete", "Delete")} onCancel={() => setPending(null)} onConfirm={async () => { await remove(pending.id); setPending(null); }} />`. THE way to ask "are you sure?" before a delete or any other action that cannot be undone, so every confirmation in the app has the same wording slots, button order and colours. Never hand-build one from a `<Modal>` or an `<Overlay>` with your own two buttons, never arm a button to be pressed twice, and never use `Alert.alert` or `window.confirm`. Props: `visible` (boolean), `title` (string, the question), `message` (what confirming does; text or a node), `confirmLabel` and `cancelLabel` (default the app\'s translated "Confirm" and "Cancel" — name the action: "Delete", "Remove", "Send"), `tone` ("default" | "destructive"; destructive draws the confirm button from the theme\'s Danger buttons colours and opens with focus on Cancel), `busy` (boolean; disables both buttons, shows a `<Spinner>` and keeps the dialog open), `onConfirm` (return the promise of the action and the dialog stays busy until it settles, with a second press ignored; a rejection is NOT caught, so catch a failure yourself and report it), `onCancel` (fired by the Cancel button, the close button, the backdrop press, the Escape key on web and the Android back button — cancelling is always the safe default), `closeAccessibilityLabel` and `testID`. The dialog never closes itself: set `visible` false from `onCancel` and after the action. Its panel follows the theme (Design > Components > Dialogs) and its buttons the Buttons and Destructive settings — do not re-style it.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -3349,35 +3367,35 @@ const PRIMITIVES = [
   {
     name: "Button",
     description:
-      'Themed button. `<Button title="Save" onPress={save} />` — THE way to draw a button: its fill, label colour, border, corner radius, padding, weight, shadow and gradient come from the app\'s button look (Theme Settings > Buttons, and Destructive / Focus ring for the danger variant and emphasis border), so it matches the built-in Button widget. Props: `title`, `onPress` (omit it for a purely visual button inside something else that is pressable), `variant` ("primary" default | "secondary" | "outlined" | "danger"), `icon` (a lucide name) with `iconPosition` ("leading" | "trailing"), `disabled`, `accessibilityLabel`, `testID`, `style` (extra container style, e.g. `alignSelf`) and `labelStyle`. Pass `fields` — `{ background, textColor, borderColor, borderWidth, paddingX, paddingY, radius, fontWeight, fontSize, shadow, gradient }` — to override one button, e.g. from style fields your widget declares. On a section that paints its own fill (`theme.colors.backdrop` there), a variant colour that the section makes unreadable takes that section\'s text colour, as its text does: an outlined label and border, a secondary whose fill disappears becomes outlined, and a primary or danger fill turns inverse (that text colour as its fill, its own colour as its label). A white or lightly tinted panel changes nothing, and a button inside a `<Card>` is measured against that card. A colour you pass in `fields`, `style` or `labelStyle`, or that the app\'s button look sets, is never changed. Never hand-roll a button from `Pressable` + background + radius.',
+      'Themed button. `<Button title="Save" onPress={save} />` — THE way to draw a button: its fill, label colour, border, corner radius, padding, weight, shadow and gradient come from the app\'s button look (Design > Components > Buttons, and Danger buttons / Button outline for the danger variant and emphasis border), so it matches the built-in Button widget. Props: `title`, `onPress` (omit it for a purely visual button inside something else that is pressable), `variant` ("primary" default | "secondary" | "outlined" | "danger"), `icon` (a lucide name) with `iconPosition` ("leading" | "trailing"), `disabled`, `accessibilityLabel`, `testID`, `style` (extra container style, e.g. `alignSelf`) and `labelStyle`. Pass `fields` — `{ background, textColor, borderColor, borderWidth, paddingX, paddingY, radius, fontWeight, fontSize, shadow, gradient }` — to override one button, e.g. from style fields your widget declares. On a section that paints its own fill (`theme.colors.backdrop` there), a variant colour that the section makes unreadable takes that section\'s text colour, as its text does: an outlined label and border, a secondary whose fill disappears becomes outlined, and a primary or danger fill turns inverse (that text colour as its fill, its own colour as its label). A white or lightly tinted panel changes nothing, and a button inside a `<Card>` is measured against that card. A colour you pass in `fields`, `style` or `labelStyle`, or that the app\'s button look sets, is never changed. Never hand-roll a button from `Pressable` + background + radius.',
     rnComponent: null,
     docsUrl: null,
   },
   {
     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. `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`.',
+      '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 (Design > Components > Inputs), 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 "✓".',
+      '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 > Inputs) 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.',
+      '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 > Inputs) showing the chosen label; pressing it opens the options at SCREEN level, in a sheet painted from Design > Components > Dropdown menus, 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.',
+      '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 props, same `label` / `helper` / `error` / `disabled`, the input look restyled by Design > Components > Search fields) 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). Where the glyph sits (start, end or hidden), the corner radius, background, border colour and height come from the app; `iconPosition` ("start" | "end" | "none") overrides the glyph for one field, and at the end the clear control takes the glyph\'s place while there is text. Debounce the query yourself before you fetch. Never hand-roll a search box from a `TextInput` + an icon, and never add a magnifier of your own.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -6049,7 +6067,12 @@ const CONTRACT = deepFreeze({
   //    calendar sheet instead of the browser's date popup; both hosts show
   //    the value in the app's language with a clear button. New optional
   //    props: placeholder, clearLabel, doneLabel, closeAccessibilityLabel, testID.
-  version: "1.190.0",
+  // 1.191.0: additive (sc-11759) — `themeComponents.search` styles every
+  //    `<SearchField>`: icon position, corner radius, background, border
+  //    colour, height, each falling back to the `muted` field. The field
+  //    takes an `iconPosition` prop. Scope labels renamed (sc-11763); keys
+  //    unchanged.
+  version: "1.191.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -6065,6 +6088,7 @@ const CONTRACT = deepFreeze({
   themeColorTokens: THEME_COLOR_TOKENS,
   themeComponents: THEME_COMPONENTS,
   themeComponentTabStyles: THEME_TAB_STYLES,
+  themeComponentSearchIconPositions: THEME_SEARCH_ICON_POSITIONS,
   themeComponentShadows: THEME_COMPONENT_SHADOWS,
   themeComponentTextTransforms: THEME_COMPONENT_TEXT_TRANSFORMS,
   themeComponentGradient: THEME_COMPONENT_GRADIENT,

package/dist/host.d.ts

@@ -51,6 +51,12 @@ export function bannerScopeDefaults(theme: unknown): Record<string, string | num
  */
 export function chipScopeDefaults(theme: unknown): Record<string, string | number>;
 
+/**
+ * What each token of the `search` component scope resolves to while unset,
+ * keyed by token name: the input look `<SearchField>` falls back to.
+ */
+export function searchScopeDefaults(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

package/dist/host.js

@@ -54,6 +54,8 @@ export { resolveModalTokens, modalScopeDefaults } from "./modal-tokens.js";
 // What each `chip` scope token resolves to while unset, for the Studio's
 // Design page to preview beside its controls.
 export { chipScopeDefaults } from "./chip-tokens.js";
+// The input look each unset `search` token falls back to, for the same page.
+export { searchScopeDefaults } from "./search-field-tokens.js";
 
 export {
   createToastController,

package/dist/index.d.ts

@@ -3939,7 +3939,7 @@ export type ButtonVariant = "primary" | "secondary" | "outlined" | "danger";
 export const BUTTON_VARIANTS: readonly ButtonVariant[];
 
 /**
- * Themed button (Theme Settings > Buttons, Destructive, Focus ring). Omit
+ * Themed button (Design > Components > Buttons, Danger buttons, Button outline). Omit
  * `onPress` for a purely visual button inside something pressable.
  *
  * @example
@@ -4000,7 +4000,7 @@ export interface FormFieldOverrides {
 }
 
 /**
- * Themed text-entry field (Design > Components > Muted). Every TextInput prop
+ * Themed text-entry field (Design > Components > Inputs). Every TextInput prop
  * works.
  *
  * @example
@@ -4100,9 +4100,14 @@ export function spaceActivates(
   onPress: () => void,
 ): (event: { key: string; repeat?: boolean; preventDefault: () => void }) => void;
 
+/** Where `<SearchField>` draws its search glyph. */
+export type SearchIconPosition = "start" | "end" | "none";
+
 /**
  * Themed search box: a `TextField` with a search glyph, the search key and a
- * clear control. Every `TextField` prop works.
+ * clear control. Every `TextField` prop works. It wears the input look,
+ * restyled by the theme's `search` scope (glyph position, corner radius,
+ * background, border colour, height); each unset token keeps the input look.
  *
  * @example
  *   <SearchField value={query} onChangeText={setQuery} placeholder="Search orders" />
@@ -4110,6 +4115,11 @@ export function spaceActivates(
 export const SearchField: (props: FormControlProps & {
   value?: string;
   onChangeText?: (text: string) => void;
+  /**
+   * Overrides the theme's glyph position for this field. At "end" the clear
+   * control takes the glyph's place while the field has text.
+   */
+  iconPosition?: SearchIconPosition;
   /** Called after the clear control empties the field. */
   onClear?: () => void;
   /** Default "Search". */

package/dist/search-field-tokens.js

@@ -0,0 +1,85 @@
+// What `<SearchField>` draws from the theme's `search` scope: where its
+// magnifier sits, and the field look it lays over `<TextField>`'s `muted` one.
+// Platform-free, so both hosts lay the field out from the same answer.
+
+import { CONTRACT } from "./contract.js";
+import { normaliseThemeComponents } from "./theme-components.js";
+import { resolveTextFieldTokens } from "./text-field-tokens.js";
+
+export const SEARCH_ICON_POSITIONS = CONTRACT.themeComponentSearchIconPositions;
+export const DEFAULT_SEARCH_ICON_POSITION = "start";
+
+// The `search` tokens that restyle the field; each is a `<TextField>` override.
+export const SEARCH_FIELD_LOOK_TOKENS = Object.freeze([
+  "background",
+  "borderColor",
+  "radius",
+  "height",
+]);
+
+function searchScope(theme) {
+  const components = theme && typeof theme === "object" ? theme.components : undefined;
+  return normaliseThemeComponents({ search: components && components.search }).search || {};
+}
+
+/**
+ * The magnifier's position: the field's own prop, then the theme, then start.
+ *
+ * @param {unknown} own — the `iconPosition` prop.
+ * @param {unknown} themed — the theme's `search.iconPosition`.
+ */
+export function searchIconPosition(own, themed) {
+  if (SEARCH_ICON_POSITIONS.includes(own)) return own;
+  if (SEARCH_ICON_POSITIONS.includes(themed)) return themed;
+  return DEFAULT_SEARCH_ICON_POSITION;
+}
+
+/**
+ * Resolve one search field. `field` holds only the tokens the theme set, so
+ * an unset one leaves `<TextField>` on the `muted` look it always drew.
+ *
+ * @param {object} theme — the resolved workspace theme (`useTheme()` shape).
+ * @param {{ iconPosition?: string }} [own] — the field's own props.
+ * @returns {{ iconPosition: string, field: Record<string, string|number> }}
+ */
+export function resolveSearchFieldTokens(theme, own) {
+  const scope = searchScope(theme);
+  const field = {};
+  for (const name of SEARCH_FIELD_LOOK_TOKENS) {
+    if (scope[name] !== undefined) field[name] = scope[name];
+  }
+  return {
+    iconPosition: searchIconPosition(own && own.iconPosition, scope.iconPosition),
+    field,
+  };
+}
+
+/**
+ * Where the glyph and the clear control go. At the end, the clear control
+ * takes the glyph's slot while there is text, so the two never overlap.
+ *
+ * @param {string} iconPosition — a resolved SEARCH_ICON_POSITIONS value.
+ * @param {boolean} clearable — the field has text and is enabled.
+ * @returns {{ glyph: "start"|"end"|null, padStart: boolean, padEnd: boolean }}
+ */
+export function searchFieldLayout(iconPosition, clearable) {
+  const glyphAtEnd = iconPosition === "end" && !clearable;
+  return {
+    glyph: iconPosition === "start" ? "start" : glyphAtEnd ? "end" : null,
+    padStart: iconPosition === "start",
+    padEnd: clearable || iconPosition === "end",
+  };
+}
+
+/**
+ * What each `search` token resolves to while unset, keyed by token name, for
+ * the Studio to preview: the `muted` field the search box falls back to.
+ *
+ * @param {object} theme — the resolved workspace theme.
+ */
+export function searchScopeDefaults(theme) {
+  const field = resolveTextFieldTokens(theme);
+  const out = { iconPosition: DEFAULT_SEARCH_ICON_POSITION };
+  for (const name of SEARCH_FIELD_LOOK_TOKENS) out[name] = field[name];
+  return out;
+}

package/dist/search-field-view.js

@@ -1,13 +1,15 @@
 // The ONE implementation behind the `<SearchField>` SDK primitive. It is
 // `<TextField>` with a search glyph and a clear control, so it wears the same
-// field and takes the same props; the platform bindings (`search-field.js` /
-// `search-field.native.js`) differ only in where the primitives come from.
+// field and takes the same props, plus the theme's `search` look; the platform
+// bindings (`search-field.js` / `search-field.native.js`) differ only in where
+// the primitives come from.
 
 import React from "react";
 import { useHostTheme } from "./hooks.js";
 import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
 import { Icon } from "./icon.js";
 import { resolveFormControlTokens } from "./form-control-tokens.js";
+import { resolveSearchFieldTokens, searchFieldLayout } from "./search-field-tokens.js";
 import {
   errorMessage,
   hasNote,
@@ -24,6 +26,17 @@ const ADORNMENT_WIDTH = 40;
 // A real target: the web host ignores hitSlop, so size carries it.
 const CLEAR_MIN_SIZE = 36;
 
+function adornmentSlot(side) {
+  return {
+    position: "absolute",
+    top: 0,
+    bottom: 0,
+    alignItems: "center",
+    justifyContent: "center",
+    ...(side === "start" ? { left: 0 } : { right: 0 }),
+  };
+}
+
 /**
  * Bind the shared search field to one platform's primitives.
  *
@@ -45,6 +58,7 @@ export function makeSearchField(rn) {
       error,
       disabled = false,
       accessibilityLabel,
+      iconPosition,
       style,
       containerStyle,
       testID,
@@ -52,6 +66,7 @@ export function makeSearchField(rn) {
     } = props;
     const theme = useHostTheme() || DEFAULT_THEME_TOKENS;
     const t = resolveFormControlTokens(theme);
+    const search = resolveSearchFieldTokens(theme, { iconPosition });
     const inputRef = React.useRef(null);
     const setRef = React.useMemo(() => shareRef(ref, inputRef), [ref]);
     const noteId = React.useId();
@@ -60,6 +75,8 @@ export function makeSearchField(rn) {
       if (input && typeof input.focus === "function") input.focus();
     };
     const hasText = typeof value === "string" && value.length > 0;
+    const clearable = hasText && !disabled;
+    const layout = searchFieldLayout(search.iconPosition, clearable);
     const clear = () => {
       if (typeof onChangeText === "function") onChangeText("");
       if (typeof onClear === "function") onClear();
@@ -98,30 +115,30 @@ export function makeSearchField(rn) {
           autoCapitalize: "none",
           autoCorrect: false,
           testID,
+          // The field's own props beat the theme's search look.
+          ...search.field,
           ...rest,
           style: [
-            { paddingLeft: ADORNMENT_WIDTH },
-            hasText && !disabled ? { paddingRight: ADORNMENT_WIDTH } : null,
+            layout.padStart ? { paddingLeft: ADORNMENT_WIDTH } : null,
+            layout.padEnd ? { paddingRight: ADORNMENT_WIDTH } : null,
             style,
           ],
         }),
-        h(
-          View,
-          {
-            style: {
-              position: "absolute",
-              left: 0,
-              top: 0,
-              bottom: 0,
-              width: ADORNMENT_WIDTH,
-              alignItems: "center",
-              justifyContent: "center",
-              pointerEvents: "none",
-            },
-          },
-          h(Icon, { name: "search", size: GLYPH_SIZE, color: t.placeholderColor }),
-        ),
-        hasText && !disabled
+        layout.glyph
+          ? h(
+              View,
+              {
+                testID: testID ? `${testID}-icon` : undefined,
+                style: {
+                  ...adornmentSlot(layout.glyph),
+                  width: ADORNMENT_WIDTH,
+                  pointerEvents: "none",
+                },
+              },
+              h(Icon, { name: "search", size: GLYPH_SIZE, color: t.placeholderColor }),
+            )
+          : null,
+        clearable
           ? h(
               Pressable,
               {
@@ -131,14 +148,10 @@ export function makeSearchField(rn) {
                 testID: testID ? `${testID}-clear` : undefined,
                 style: ({ pressed }) => [
                   {
-                    position: "absolute",
+                    ...adornmentSlot("end"),
                     right: 2,
-                    top: 0,
-                    bottom: 0,
                     minWidth: CLEAR_MIN_SIZE,
                     minHeight: CLEAR_MIN_SIZE,
-                    alignItems: "center",
-                    justifyContent: "center",
                   },
                   pressed ? { opacity: 0.6 } : null,
                 ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.236.0",
+  "version": "0.237.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

@@ -275,6 +275,9 @@ function formatThemeColorTokenRef(path, percent) {
 // The looks a `tabs.style` token may name; `<Tabs>` draws each.
 const THEME_TAB_STYLES = Object.freeze(["segmented", "pill", "underline"]);
 
+// Where `<SearchField>` draws its magnifier; "start" is the look it always had.
+const THEME_SEARCH_ICON_POSITIONS = Object.freeze(["start", "end", "none"]);
+
 const THEME_COMPONENT_SHADOWS = Object.freeze(["none", "sm", "md", "lg"]);
 
 // sc-3857 — the `textTransform` token's closed enum, matching the per-instance
@@ -585,7 +588,7 @@ const THEME_COMPONENTS = Object.freeze({
   // than its `color` field, which the `text` scope already owns -- two
   // scopes writing the same field on the same widget would race.
   accent: Object.freeze({
-    label: "Accent",
+    label: "Labels",
     tokens: Object.freeze({
       background: Object.freeze({ type: "color", uiDefault: "colors.primarySoft" }),
       borderColor: Object.freeze({ type: "color", uiDefault: "colors.primary" }),
@@ -602,7 +605,7 @@ const THEME_COMPONENTS = Object.freeze({
   // sc-5392 -- the Button widget's danger/delete variant. Separate token set
   // from `button` above so "make the buttons coral" never recolours Delete.
   destructive: Object.freeze({
-    label: "Destructive",
+    label: "Danger buttons",
     tokens: Object.freeze({
       background: Object.freeze({ type: "color", uiDefault: "colors.danger" }),
       textColor: Object.freeze({ type: "color", uiDefault: "colors.onPrimary" }),
@@ -617,7 +620,7 @@ const THEME_COMPONENTS = Object.freeze({
   // scope) rather than to Text/Label/Data Value, whose `color` field the
   // `text` scope already owns.
   muted: Object.freeze({
-    label: "Muted",
+    label: "Inputs",
     // The SDK's form controls read this scope directly, in every widget.
     sdkComponents: Object.freeze(["TextField", "Checkbox", "Switch", "Select", "SearchField"]),
     tokens: Object.freeze({
@@ -636,7 +639,7 @@ const THEME_COMPONENTS = Object.freeze({
   // sc-5392 -- dropdown/menu surfaces. The form widgets' choice-field option
   // list is the closest thing the built-in catalog has to a popover panel.
   popover: Object.freeze({
-    label: "Popover",
+    label: "Dropdown menus",
     sdkComponents: Object.freeze(["Select"]),
     tokens: Object.freeze({
       background: Object.freeze({ type: "color", uiDefault: "colors.surface" }),
@@ -648,11 +651,26 @@ const THEME_COMPONENTS = Object.freeze({
       "appstudio.form-builder": POPOVER_FIELDS,
     }),
   }),
-  // sc-5392 -- the app-wide focus-visible outline. A themed emphasis border
+  // Search boxes: `<SearchField>` reads this scope directly. Every token is
+  // unset by default and falls back to the `muted` field it draws.
+  search: Object.freeze({
+    label: "Search fields",
+    sdkComponents: Object.freeze(["SearchField"]),
+    tokens: Object.freeze({
+      iconPosition: Object.freeze({ type: "enum", values: THEME_SEARCH_ICON_POSITIONS }),
+      // 48 is past half the tallest field, so its ceiling draws a pill.
+      radius: Object.freeze({ type: "size", min: 0, max: 48 }),
+      background: Object.freeze({ type: "color" }),
+      borderColor: Object.freeze({ type: "color" }),
+      height: Object.freeze({ type: "size", min: 32, max: 72 }),
+    }),
+    targets: Object.freeze({}),
+  }),
+  // sc-5392 -- not a keyboard focus style: a permanent emphasis border
   // on the Button widget, applied after its variant colours and beaten by the
   // widget's own per-instance `borderColor` (REQ-THEME-13 stays final).
   ring: Object.freeze({
-    label: "Focus ring",
+    label: "Button outline",
     tokens: Object.freeze({
       color: Object.freeze({ type: "color", uiDefault: "colors.primary" }),
       width: Object.freeze({ type: "size", min: 0, max: 8 }),
@@ -3093,7 +3111,7 @@ const PRIMITIVES = [
   {
     name: "Switch",
     description:
-      '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`.',
+      '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 > Inputs). `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",
   },
@@ -3202,7 +3220,7 @@ const PRIMITIVES = [
   {
     name: "ConfirmDialog",
     description:
-      'Standard confirmation prompt, a preset of `<Modal>`. `<ConfirmDialog visible={!!pending} tone="destructive" title="Delete this order?" message="This cannot be undone." confirmLabel={t("delete", "Delete")} onCancel={() => setPending(null)} onConfirm={async () => { await remove(pending.id); setPending(null); }} />`. THE way to ask "are you sure?" before a delete or any other action that cannot be undone, so every confirmation in the app has the same wording slots, button order and colours. Never hand-build one from a `<Modal>` or an `<Overlay>` with your own two buttons, never arm a button to be pressed twice, and never use `Alert.alert` or `window.confirm`. Props: `visible` (boolean), `title` (string, the question), `message` (what confirming does; text or a node), `confirmLabel` and `cancelLabel` (default the app\'s translated "Confirm" and "Cancel" — name the action: "Delete", "Remove", "Send"), `tone` ("default" | "destructive"; destructive draws the confirm button from the theme\'s Destructive colours and opens with focus on Cancel), `busy` (boolean; disables both buttons, shows a `<Spinner>` and keeps the dialog open), `onConfirm` (return the promise of the action and the dialog stays busy until it settles, with a second press ignored; a rejection is NOT caught, so catch a failure yourself and report it), `onCancel` (fired by the Cancel button, the close button, the backdrop press, the Escape key on web and the Android back button — cancelling is always the safe default), `closeAccessibilityLabel` and `testID`. The dialog never closes itself: set `visible` false from `onCancel` and after the action. Its panel follows the theme (Design > Components > Dialogs) and its buttons the Buttons and Destructive settings — do not re-style it.',
+      'Standard confirmation prompt, a preset of `<Modal>`. `<ConfirmDialog visible={!!pending} tone="destructive" title="Delete this order?" message="This cannot be undone." confirmLabel={t("delete", "Delete")} onCancel={() => setPending(null)} onConfirm={async () => { await remove(pending.id); setPending(null); }} />`. THE way to ask "are you sure?" before a delete or any other action that cannot be undone, so every confirmation in the app has the same wording slots, button order and colours. Never hand-build one from a `<Modal>` or an `<Overlay>` with your own two buttons, never arm a button to be pressed twice, and never use `Alert.alert` or `window.confirm`. Props: `visible` (boolean), `title` (string, the question), `message` (what confirming does; text or a node), `confirmLabel` and `cancelLabel` (default the app\'s translated "Confirm" and "Cancel" — name the action: "Delete", "Remove", "Send"), `tone` ("default" | "destructive"; destructive draws the confirm button from the theme\'s Danger buttons colours and opens with focus on Cancel), `busy` (boolean; disables both buttons, shows a `<Spinner>` and keeps the dialog open), `onConfirm` (return the promise of the action and the dialog stays busy until it settles, with a second press ignored; a rejection is NOT caught, so catch a failure yourself and report it), `onCancel` (fired by the Cancel button, the close button, the backdrop press, the Escape key on web and the Android back button — cancelling is always the safe default), `closeAccessibilityLabel` and `testID`. The dialog never closes itself: set `visible` false from `onCancel` and after the action. Its panel follows the theme (Design > Components > Dialogs) and its buttons the Buttons and Destructive settings — do not re-style it.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -3349,35 +3367,35 @@ const PRIMITIVES = [
   {
     name: "Button",
     description:
-      'Themed button. `<Button title="Save" onPress={save} />` — THE way to draw a button: its fill, label colour, border, corner radius, padding, weight, shadow and gradient come from the app\'s button look (Theme Settings > Buttons, and Destructive / Focus ring for the danger variant and emphasis border), so it matches the built-in Button widget. Props: `title`, `onPress` (omit it for a purely visual button inside something else that is pressable), `variant` ("primary" default | "secondary" | "outlined" | "danger"), `icon` (a lucide name) with `iconPosition` ("leading" | "trailing"), `disabled`, `accessibilityLabel`, `testID`, `style` (extra container style, e.g. `alignSelf`) and `labelStyle`. Pass `fields` — `{ background, textColor, borderColor, borderWidth, paddingX, paddingY, radius, fontWeight, fontSize, shadow, gradient }` — to override one button, e.g. from style fields your widget declares. On a section that paints its own fill (`theme.colors.backdrop` there), a variant colour that the section makes unreadable takes that section\'s text colour, as its text does: an outlined label and border, a secondary whose fill disappears becomes outlined, and a primary or danger fill turns inverse (that text colour as its fill, its own colour as its label). A white or lightly tinted panel changes nothing, and a button inside a `<Card>` is measured against that card. A colour you pass in `fields`, `style` or `labelStyle`, or that the app\'s button look sets, is never changed. Never hand-roll a button from `Pressable` + background + radius.',
+      'Themed button. `<Button title="Save" onPress={save} />` — THE way to draw a button: its fill, label colour, border, corner radius, padding, weight, shadow and gradient come from the app\'s button look (Design > Components > Buttons, and Danger buttons / Button outline for the danger variant and emphasis border), so it matches the built-in Button widget. Props: `title`, `onPress` (omit it for a purely visual button inside something else that is pressable), `variant` ("primary" default | "secondary" | "outlined" | "danger"), `icon` (a lucide name) with `iconPosition` ("leading" | "trailing"), `disabled`, `accessibilityLabel`, `testID`, `style` (extra container style, e.g. `alignSelf`) and `labelStyle`. Pass `fields` — `{ background, textColor, borderColor, borderWidth, paddingX, paddingY, radius, fontWeight, fontSize, shadow, gradient }` — to override one button, e.g. from style fields your widget declares. On a section that paints its own fill (`theme.colors.backdrop` there), a variant colour that the section makes unreadable takes that section\'s text colour, as its text does: an outlined label and border, a secondary whose fill disappears becomes outlined, and a primary or danger fill turns inverse (that text colour as its fill, its own colour as its label). A white or lightly tinted panel changes nothing, and a button inside a `<Card>` is measured against that card. A colour you pass in `fields`, `style` or `labelStyle`, or that the app\'s button look sets, is never changed. Never hand-roll a button from `Pressable` + background + radius.',
     rnComponent: null,
     docsUrl: null,
   },
   {
     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. `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`.',
+      '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 (Design > Components > Inputs), 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 "✓".',
+      '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 > Inputs) 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.',
+      '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 > Inputs) showing the chosen label; pressing it opens the options at SCREEN level, in a sheet painted from Design > Components > Dropdown menus, 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.',
+      '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 props, same `label` / `helper` / `error` / `disabled`, the input look restyled by Design > Components > Search fields) 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). Where the glyph sits (start, end or hidden), the corner radius, background, border colour and height come from the app; `iconPosition` ("start" | "end" | "none") overrides the glyph for one field, and at the end the clear control takes the glyph\'s place while there is text. Debounce the query yourself before you fetch. Never hand-roll a search box from a `TextInput` + an icon, and never add a magnifier of your own.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -6049,7 +6067,12 @@ const CONTRACT = deepFreeze({
   //    calendar sheet instead of the browser's date popup; both hosts show
   //    the value in the app's language with a clear button. New optional
   //    props: placeholder, clearLabel, doneLabel, closeAccessibilityLabel, testID.
-  version: "1.190.0",
+  // 1.191.0: additive (sc-11759) — `themeComponents.search` styles every
+  //    `<SearchField>`: icon position, corner radius, background, border
+  //    colour, height, each falling back to the `muted` field. The field
+  //    takes an `iconPosition` prop. Scope labels renamed (sc-11763); keys
+  //    unchanged.
+  version: "1.191.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -6065,6 +6088,7 @@ const CONTRACT = deepFreeze({
   themeColorTokens: THEME_COLOR_TOKENS,
   themeComponents: THEME_COMPONENTS,
   themeComponentTabStyles: THEME_TAB_STYLES,
+  themeComponentSearchIconPositions: THEME_SEARCH_ICON_POSITIONS,
   themeComponentShadows: THEME_COMPONENT_SHADOWS,
   themeComponentTextTransforms: THEME_COMPONENT_TEXT_TRANSFORMS,
   themeComponentGradient: THEME_COMPONENT_GRADIENT,