@colixsystems/widget-sdk 0.236.0 → 0.238.0

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,9 +620,9 @@ 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"]),
+    sdkComponents: Object.freeze(["TextField", "Checkbox", "Switch", "Select", "SearchField", "FileUpload"]),
     tokens: Object.freeze({
       background: Object.freeze({ type: "color", uiDefault: "colors.surfaceMuted" }),
       textColor: Object.freeze({ type: "color", uiDefault: "colors.onSurfaceMuted" }),
@@ -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",
   },
@@ -3127,16 +3145,13 @@ const PRIMITIVES = [
     rnComponent: "@react-native-community/datetimepicker",
     docsUrl: "https://github.com/react-native-datetimepicker/datetimepicker",
   },
-  // sc-1378 — `<FilePicker accept onPick>` lets a widget surface a native
-  // file-picker on the web Player so end users can upload files to the
-  // backend (paired with useFilestoreUpload). Web wraps
-  // a hidden DOM `<input type="file">`; native renders a disabled trigger
-  // and exposes `FilePicker.isSupported = false` until a vetted Expo
-  // picker pin lands.
+  // sc-1378 — `<FilePicker accept onPick>` opens the system file picker so
+  // end users can upload files (paired with useFilestoreUpload). Web wraps a
+  // hidden DOM `<input type="file">`; native wraps expo-document-picker.
   {
     name: "FilePicker",
     description:
-      'End-user file picker primitive. `<FilePicker accept="image/*" multiple={false} disabled={false} onPick={(file) => …}>…trigger…</FilePicker>`. Children render as the visible click target (a Pressable + Icon + Text is the common shape) and are wrapped in a hidden-input <label> so the click reaches the file dialog without any ref plumbing. Pair with useFilestoreUpload to upload the picked File to the end-user filestore. `FilePicker.isSupported` is `true` on the web Player and `false` on the native Expo export — widgets should branch on it to hide the trigger when uploads are not yet wired natively.',
+      'End-user file picker primitive. `<FilePicker accept="image/*" multiple={false} disabled={false} onPick={(file) => …}>…trigger…</FilePicker>`. Children render as the visible click target (a Pressable + Icon + Text is the common shape) and are wrapped in a hidden-input <label> so the click reaches the file dialog without any ref plumbing. Pair with useFilestoreUpload to upload the picked File to the end-user filestore. `onFocus` / `onBlur` report the picker\'s keyboard focus, so a trigger you draw can show it. `FilePicker.isSupported` is `true` on the web Player and on the native Expo export, which opens the system document picker; a host without a picker sets it `false`, so disable the trigger and say why. For an upload field use `<FileUpload>`, which draws the button, the chosen files and the uploading and error states around this picker; the bare FilePicker is for a trigger that is not a field, such as a photo the user taps to replace.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -3202,7 +3217,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,
   },
@@ -3237,14 +3252,14 @@ const PRIMITIVES = [
   {
     name: "List",
     description:
-      "Themed list container. `<List>{rows.map((r) => <ListRow key={r.id} title={r.name} />)}</List>`. Spaces and insets its `<ListRow>` children the way the app's look says (flush rows with hairlines, or separated rounded rows), and hands any row override you pass (`rowPadding`, `rowMinHeight`, `gap`, `radius`, `background`, `dividerColor`, `dividerWidth`) down to every row. Props: those overrides, `style`, `testID`. Put it inside a `ScrollView` (or bound its height) for long lists.",
+      "Themed list container. `<List>{rows.map((r) => <ListRow key={r.id} title={r.name} />)}</List>`. Spaces and insets its `<ListRow>` children the way the app's look says (flush rows with hairlines, or separated rounded rows), and hands any row override you pass (`rowPadding`, `rowMinHeight`, `gap`, `radius`, `background`, `dividerColor`, `dividerWidth`) down to every row. `<List variant=\"card\">` draws EVERY row as its own card instead: THE way to build a list of cards (one record per card, stacked in one column). Each card's surface (fill, border, corner radius, padding, shadow, gradient) is the app's card look (Design > Components > Cards), what is inside it (height, the leading / body / trailing arrangement) is its Lists look (Design > Components > Lists), and the cards are spaced by the Lists gap, or a small step when that is unset; never wrap hand-made rows in `<Card>`s for this. `defaults` takes the same keys as the overrides and is used only where the app's Lists settings leave a value unset (a built-in widget keeps its own row look with it); leave it out in a new widget so the app decides. Props: those overrides, `variant` (\"plain\" default | \"card\"), `defaults`, `style`, `testID`. Put it inside a `ScrollView` (or bound its height) for long lists.",
     rnComponent: null,
     docsUrl: null,
   },
   {
     name: "ListRow",
     description:
-      'Themed list row. `<ListRow title={item.name} subtitle={item.email} leading={<Icon name="user" size={20} />} trailing={<Text>…</Text>} onPress={() => open(item)} selected={item.id === selectedId} />`. THE way to draw one row of records: its padding, minimum height, divider, corner radius and background come from the theme\'s Lists settings, so every list in the app matches — never hand-roll a row from `View` + `Pressable`. Props: `title`, `subtitle` (rendered in the subtitle / caption text tiers), `leading` / `trailing` nodes, `children` (replaces the title block: a single `View` child — your own row of cells — spans the full width between `leading` and `trailing`; anything else, such as several cells, sits in the row as given, which is the shape a table row takes under a `<ListHeader>`), `onPress` (makes it a button with a press state), `selected`, `disabled`, `divider` (default true; pass false on the last row), `accessibilityLabel`, `style`, `testID`, plus the same per-row overrides `<List>` takes. Declare `listRowPadding` / `listRowRadius` / … style fields and pass them through to let an author override one widget.',
+      'Themed list row. `<ListRow title={item.name} subtitle={item.email} leading={<Icon name="user" size={20} />} trailing={<Text>…</Text>} onPress={() => open(item)} selected={item.id === selectedId} />`. THE way to draw one row of records: its padding, minimum height, divider, corner radius and background come from the theme\'s Lists settings, so every list in the app matches — never hand-roll a row from `View` + `Pressable`. Props: `title`, `subtitle` (rendered in the subtitle / caption text tiers), `leading` / `trailing` nodes, `children` (replaces the title block: a single `View` child — your own row of cells — spans the full width between `leading` and `trailing`; anything else, such as several cells, sits in the row as given, which is the shape a table row takes under a `<ListHeader>`), `onPress` (makes it a button with a press state), `actions` (the row\'s OWN buttons, such as remove, move up or sign: drawn after `trailing` and, on a row with `onPress`, kept OUTSIDE its tap target so each stays a separate button the keyboard and a screen reader reach; never put a `Pressable` in `trailing` of a pressable row), `selected`, `disabled`, `divider` (default true; pass false on the last row), `accessibilityLabel`, `style`, `testID`, `defaults`, plus the same per-row overrides `<List>` takes. Inside a `<List variant="card">` the row is drawn as one card. Declare `listRowPadding` / `listRowRadius` / … style fields and pass them through to let an author override one widget.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -3349,35 +3364,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 picker for ONE value of a known list, or several with `multiple`. `<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. MULTIPLE: `<Select multiple label="Tags" values={tags} onValuesChange={setTags} options={tagOptions} />` — THE way to let the user pick SEVERAL of a known list. The same trigger and sheet; each option shows a tick box and toggles, the listbox is multiselectable on the web, and the sheet\'s Done button commits the choice through `onValuesChange(values, options)` (values in listed order, called only when they changed); closing the sheet any other way (backdrop, Escape, Android back) keeps the previous choice. Space toggles the focused option on the web. The trigger shows the picked labels as small chips while they fit on its one line, otherwise "N selected" (`selectedCountText(count)` to translate it), and `placeholder` while nothing is picked; `doneText` (default "Done") names the button. In this mode `value` / `onValueChange` are ignored. A handful of options always shown inline is a `<ChipGroup selection="multiple">` of `<Chip>`s instead.',
     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,
   },
@@ -3402,6 +3417,14 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  // sc-11751 — the standard upload field, built on `<FilePicker>`.
+  {
+    name: "FileUpload",
+    description:
+      'Themed file chooser. `<FileUpload label="Attachments" accept="image/*,.pdf" multiple files={files} onFilesChange={setFiles} />` — THE way to let the user pick files to upload, whether they upload at once or with a form. It is built on `<FilePicker>`: a button (Design > Components > Buttons) inside the app\'s input field (Design > Components > Inputs), the chosen files listed under it with their name, size and a remove control, and the same `label` / `helper` / `error` / `disabled` as every form control. The button opens the system file picker on both hosts and is the only way in on a device; on the web a file can also be dropped onto the field. A picked or dropped file that `accept` rules out is not added and the field shows an error. It uploads nothing itself: call `upload(file)` from `useFilestoreUpload` in `onPick` (or when the form is submitted) and pass `uploading` while it runs; the field then shows a `<Spinner>` with "Uploading…" and locks (no percentage is reported). Props: `accept` (an HTML accept value: "image/*", ".pdf", "application/pdf"), `multiple` (default false: a new pick replaces the file), `files` + `onFilesChange(files)` to own the list (omit both and it keeps its own; pass `files={[]}` to list nothing), `onPick(file)` (an array when `multiple`) once per pick or drop with only the new files, `onRemove(file, index)`, `onReject(files, reason)` (reason "type" for a file `accept` rules out, "count" for the files beyond the first when not `multiple`), `uploading`, `label`, `helper`, `error` (a message, or `true`), `disabled`, `buttonLabel` (default "Choose file" / "Choose files"), `buttonVariant` ("primary" | "secondary" | "outlined", the default), `uploadingLabel`, `emptyLabel`, `dropLabel`, `rejectedMessage`, `singleFileMessage`, `unsupportedMessage`, `removeAccessibilityLabel`, `accessibilityLabel`, `style` (the field), `containerStyle`, `testID` (also tags `<testID>-button`, `<testID>-file-<i>` and `<testID>-remove-<i>`). Pass translated copy for every label. Never hand-build an upload control from `<FilePicker>` plus your own button, file list or "Uploading…" text.',
+    rnComponent: null,
+    docsUrl: null,
+  },
 ];
 
 const CATEGORIES = [
@@ -6049,7 +6072,16 @@ 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.
+  // 1.192.0: additive (sc-11751, sc-11752, sc-11758) — new `<FileUpload>`
+  //    on `<FilePicker>` (which gains onFocus/onBlur; `muted` lists it).
+  //    `<List variant="card">`, `<ListRow actions>`, `defaults` on both.
+  //    `<Select multiple values onValuesChange>`.
+  version: "1.192.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -6065,6 +6097,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/file-upload-logic.js

@@ -0,0 +1,178 @@
+// `<FileUpload>`'s pure rules: how a size reads, whether a file matches an
+// HTML `accept` value, and how a pick joins the chosen list. No renderer
+// here, so the node suite tests them and both hosts share them.
+
+const SIZE_UNITS = ["KB", "MB", "GB", "TB"];
+
+/**
+ * A byte count as people read it: "512 B", "1.5 KB", "12 MB". Null when the
+ * host gave no usable size, so the caller shows nothing rather than "0 B".
+ *
+ * @param {unknown} bytes
+ */
+export function formatFileSize(bytes) {
+  if (typeof bytes !== "number" || !Number.isFinite(bytes) || bytes < 0) return null;
+  if (bytes < 1024) return `${Math.round(bytes)} B`;
+  let value = bytes / 1024;
+  let unit = 0;
+  while (value >= 1024 && unit < SIZE_UNITS.length - 1) {
+    value /= 1024;
+    unit += 1;
+  }
+  const rounded = value < 10 ? Math.round(value * 10) / 10 : Math.round(value);
+  // 1023.95 KB rounds to 1024, which reads better as the next unit.
+  if (rounded >= 1024 && unit < SIZE_UNITS.length - 1) return `1 ${SIZE_UNITS[unit + 1]}`;
+  return `${rounded} ${SIZE_UNITS[unit]}`;
+}
+
+/**
+ * The tokens of an HTML `accept` value, lower-cased: ".pdf", "image/*",
+ * "application/pdf". Empty when every file is accepted.
+ *
+ * @param {unknown} accept
+ */
+export function parseAccept(accept) {
+  if (typeof accept !== "string") return [];
+  const tokens = accept
+    .split(",")
+    .map((token) => token.trim().toLowerCase().split(";")[0].trim())
+    .filter(Boolean);
+  return tokens.some((token) => token === "*" || token === "*/*") ? [] : tokens;
+}
+
+// What a host reports for a file whose type it could not tell.
+const UNKNOWN_TYPES = new Set(["", "application/octet-stream"]);
+
+function fileType(file) {
+  return file && typeof file.type === "string" ? file.type.trim().toLowerCase().split(";")[0] : "";
+}
+
+function fileName(file) {
+  return file && typeof file.name === "string" ? file.name.toLowerCase() : "";
+}
+
+/**
+ * Whether `file` matches `accept`, read as the browser reads the attribute.
+ *
+ * A file whose type the host could not tell passes a type-only `accept`:
+ * the server, which sniffs the bytes, stays the authority on those, so a
+ * real document is never refused here for a missing type.
+ *
+ * @param {{name?: string, type?: string}} file
+ * @param {unknown} accept
+ */
+export function isAccepted(file, accept) {
+  const tokens = parseAccept(accept);
+  if (tokens.length === 0) return true;
+  const type = fileType(file);
+  const name = fileName(file);
+  const matches = tokens.some((token) => {
+    if (token.startsWith(".")) return name.endsWith(token);
+    if (token.endsWith("/*")) return type.startsWith(token.slice(0, -1));
+    return type === token;
+  });
+  if (matches) return true;
+  const byExtension = tokens.some((token) => token.startsWith("."));
+  return UNKNOWN_TYPES.has(type) && !byExtension;
+}
+
+/**
+ * Split picked or dropped files into the ones `accept` admits and the rest.
+ *
+ * @param {unknown} picked — one file or an array of them.
+ * @param {unknown} accept
+ */
+export function partitionAccepted(picked, accept) {
+  const list = toFileList(picked);
+  const accepted = [];
+  const rejected = [];
+  for (const file of list) (isAccepted(file, accept) ? accepted : rejected).push(file);
+  return { accepted, rejected };
+}
+
+/** One file or an array of them, as an array without holes. */
+export function toFileList(picked) {
+  if (Array.isArray(picked)) return picked.filter(Boolean);
+  return picked ? [picked] : [];
+}
+
+/** A key that tells two chosen files apart in a list. */
+export function fileKey(file, index) {
+  const name = file && typeof file.name === "string" ? file.name : "file";
+  const size = file && typeof file.size === "number" ? file.size : "";
+  return `${index}:${name}:${size}`;
+}
+
+function sameFile(a, b) {
+  if (a === b) return true;
+  return (
+    Boolean(a && b) &&
+    a.name === b.name &&
+    a.size === b.size &&
+    (a.lastModified === undefined || a.lastModified === b.lastModified) &&
+    (a.uri === undefined || a.uri === b.uri)
+  );
+}
+
+/**
+ * The picked files that are new to the list. One file replaces the list, so
+ * it is always new; with `multiple` a file already listed, or picked twice at
+ * once, is not.
+ *
+ * @param {Array<object>} current
+ * @param {Array<object>} accepted — the picked files that passed `accept`.
+ * @param {boolean} multiple
+ */
+export function newlyPicked(current, accepted, multiple) {
+  if (accepted.length === 0) return [];
+  if (!multiple) return [accepted[0]];
+  const seen = Array.isArray(current) ? [...current] : [];
+  const added = [];
+  for (const file of accepted) {
+    if (seen.some((kept) => sameFile(kept, file))) continue;
+    seen.push(file);
+    added.push(file);
+  }
+  return added;
+}
+
+/**
+ * The chosen list after a pick: one file replaces the list, several join it
+ * without adding the same file twice.
+ *
+ * @param {Array<object>} current
+ * @param {Array<object>} accepted — the picked files that passed `accept`.
+ * @param {boolean} multiple
+ */
+export function mergePicked(current, accepted, multiple) {
+  const now = Array.isArray(current) ? current : [];
+  const added = newlyPicked(now, accepted, multiple);
+  if (added.length === 0) return now;
+  return multiple ? [...now, ...added] : added;
+}
+
+/**
+ * What one pick or drop does: the files to add and send to `onPick`, the
+ * ones `accept` refused, and in single mode the files beyond the first.
+ *
+ * @param {Array<object>} current — the listed files.
+ * @param {unknown} picked — one file or an array of them.
+ * @param {unknown} accept
+ * @param {boolean} multiple
+ */
+export function planPick(current, picked, accept, multiple) {
+  const now = Array.isArray(current) ? current : [];
+  const { accepted, rejected } = partitionAccepted(picked, accept);
+  const added = newlyPicked(now, accepted, multiple);
+  return {
+    added,
+    rejected,
+    extra: multiple ? [] : accepted.slice(1),
+    next: mergePicked(now, accepted, multiple),
+  };
+}
+
+/** What `onPick` receives: one file, or an array when `multiple`. */
+export function pickPayload(accepted, multiple) {
+  return multiple ? accepted : accepted[0];
+}