@colixsystems/widget-sdk 0.237.0 → 0.238.0

package/README.md

@@ -84,7 +84,26 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`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**.
+`v0.238.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.238.0 (contract 1.192.0)
+
+**A standard upload field: `<FileUpload>`.** Widgets wrapped the headless `<FilePicker>` round buttons they drew themselves, so every upload control looked different. `<FileUpload>` is one view bound to each host's own `FilePicker`: the app's button inside the input field (Design > Components > Buttons and Inputs), the chosen files listed with their size and a remove control, and the form controls' `label`, `helper`, `error` and `disabled`. A file that `accept` rules out is refused with an error. It never uploads itself: call `upload(file)` from `useFilestoreUpload` in `onPick` and pass `uploading`, which shows an indeterminate spinner and locks the field. With `multiple`, `onPick` receives an array of the new files; `files` + `onFilesChange` let you own the list. On the web a file can also be dropped onto the field; React Native has no file drop, so on a device the button, which opens the system document picker, is the control. `<FilePicker>` gains `onFocus` / `onBlur`, and `FilePicker.isSupported` is documented as true on both hosts.
+
+```jsx
+const { upload, uploading } = useFilestoreUpload({ spaceType: "project" });
+<FileUpload label="Attachment" accept="application/pdf,image/*" uploading={uploading} onPick={(file) => upload(file)} />
+```
+
+**Lists of cards and row actions.** `<List variant="card">` turns every `<ListRow>` into its own card: the surface follows Design > Components > Cards and the inside follows Lists, so a list of cards matches the rest of the app without wrapping rows in `<Card>` by hand. Buttons that act on one record go in `<ListRow actions>`, which stay outside the row's own tap target. `defaults` on `<List>` / `<ListRow>` is a widget's own row look, used only where the theme's Lists settings are unset. Existing rows render unchanged.
+
+**Pick several with `<Select multiple>`.** `Select` takes `multiple` with `values` / `onValuesChange(values, options)`: the same field and option sheet, a tick box beside each option, and a Done button that hands you the new array in listed order (only when it changed). Closing the sheet by the backdrop, Escape or Android back keeps the previous choice. The trigger shows the picked labels as compact chips while they fit on its line, otherwise "N selected" (`selectedCountText`; `doneText` translates the button). On the web the list is multiselectable and Space or Enter toggles the focused option. For a handful of options always on show, use `<ChipGroup selection="multiple">` instead.
+
+```jsx
+<Select multiple label={t("tags", "Tags")} values={tags} onValuesChange={setTags}
+  doneText={t("done", "Done")} selectedCountText={(n) => `${n} ${t("picked", "picked")}`}
+  options={[{ value: "red", label: "Red" }, { value: "blue", label: "Blue" }]} />
+```
 
 ### What's new in 0.237.0 (contract 1.191.0)
 
@@ -2930,7 +2949,7 @@ import { defineWidget, validateManifest, useDatastoreQuery, Text, View } from "@
 - `Banner` — the themed inline message. `<Banner tone message>` shows an error, warning, success or notice in place, styled by the theme's `alert` scope; `action` adds one button and `onDismiss` a close control. Use `useToast()` for a brief confirmation instead. Never hand-roll a tinted error box.
 - `Accordion`, `AccordionItem` — themed collapsible sections. `<Accordion><AccordionItem title subtitle trailing>…</AccordionItem></Accordion>` draws its surface from the theme's `card` scope and its headers and dividers from the `list` scope; one section open at a time, or `multiple`. Never hand-roll a collapsible from `Pressable` + a chevron.
 - `Spinner`, `Skeleton` — the themed loading states. `<Spinner size label>` for a pending action; `<Skeleton shape="text" | "block" | "circle" | "listRow">` (or a group of bones) for content whose layout you know. The spinner wears `colors.loader`, the skeleton follows the theme's `loading` scope; both stop under reduced motion and mark one busy region. Never use `ActivityIndicator` or hand-build placeholder bars.
-- `Checkbox`, `Switch`, `Select`, `SearchField` — the themed tick box, on/off toggle, single-choice picker and search box. Like `TextField` they follow the theme's `muted` scope, 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`.
+- `Checkbox`, `Switch`, `Select`, `SearchField` — the themed tick box, on/off toggle, 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; with `multiple` it takes `values` / `onValuesChange`, ticks options in the same sheet and commits them on Done. 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/checkbox-view.js

@@ -28,6 +28,33 @@ import { makeFieldFrame } from "./form-control-view.js";
 
 const h = React.createElement;
 
+/**
+ * The tick box itself, drawn by `<Checkbox>` and by each option of a
+ * `<Select multiple>`, so the two always look alike.
+ *
+ * @param {any} View — the host's View primitive.
+ * @param {object} t — resolved form-control tokens.
+ * @param {{checked: boolean, invalid?: boolean}} state
+ */
+export function checkboxBox(View, t, { checked, invalid = false }) {
+  return h(
+    View,
+    {
+      style: {
+        width: CHECKBOX_SIZE,
+        height: CHECKBOX_SIZE,
+        alignItems: "center",
+        justifyContent: "center",
+        borderWidth: 1,
+        borderRadius: Math.min(t.radius, CHECKBOX_MAX_RADIUS),
+        borderColor: checked ? t.accent : invalid ? t.errorColor : t.borderColor,
+        backgroundColor: checked ? t.accent : t.background,
+      },
+    },
+    checked ? h(Icon, { name: "check", size: 16, color: t.onAccent }) : null,
+  );
+}
+
 /**
  * Bind the shared checkbox to one platform's primitives.
  *
@@ -103,22 +130,7 @@ export function makeCheckbox(rn) {
       h(
         View,
         { style: focusHaloStyle(t, focused, radius) },
-        h(
-          View,
-          {
-            style: {
-              width: CHECKBOX_SIZE,
-              height: CHECKBOX_SIZE,
-              alignItems: "center",
-              justifyContent: "center",
-              borderWidth: 1,
-              borderRadius: radius,
-              borderColor: checked ? t.accent : invalid ? t.errorColor : t.borderColor,
-              backgroundColor: checked ? t.accent : t.background,
-            },
-          },
-          checked ? h(Icon, { name: "check", size: 16, color: t.onAccent }) : null,
-        ),
+        checkboxBox(View, t, { checked, invalid }),
       ),
       isText(label)
         ? h(

package/dist/contract.cjs

@@ -622,7 +622,7 @@ const THEME_COMPONENTS = Object.freeze({
   muted: Object.freeze({
     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" }),
@@ -3145,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,
   },
@@ -3255,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,
   },
@@ -3388,7 +3385,7 @@ const PRIMITIVES = [
   {
     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 > 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.',
+      '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,
   },
@@ -3420,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 = [
@@ -6076,7 +6081,11 @@ const CONTRACT = deepFreeze({
   //    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",
+  // 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,

package/dist/contract.js

@@ -622,7 +622,7 @@ const THEME_COMPONENTS = Object.freeze({
   muted: Object.freeze({
     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" }),
@@ -3145,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,
   },
@@ -3255,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,
   },
@@ -3388,7 +3385,7 @@ const PRIMITIVES = [
   {
     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 > 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.',
+      '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,
   },
@@ -3420,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 = [
@@ -6072,7 +6077,11 @@ const CONTRACT = deepFreeze({
   //    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",
+  // 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,

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