@colixsystems/widget-sdk 0.237.0 → 0.239.0

package/dist/select-view.js

@@ -4,7 +4,8 @@
 //
 // The trigger wears the field `<TextField>` does. The options open in
 // `<Overlay>`, at screen level, so no card or scroll container the widget
-// sits in can clip them; a long list scrolls inside the sheet.
+// sits in can clip them; a long list scrolls inside the sheet. With
+// `multiple` the same sheet ticks options into a draft that Done commits.
 
 import React from "react";
 import { useHostTheme } from "./hooks.js";
@@ -29,17 +30,34 @@ import {
   spokenLabel,
 } from "./form-control-logic.js";
 import { makeFieldFrame } from "./form-control-view.js";
+import { checkboxBox } from "./checkbox-view.js";
+import {
+  committedValues,
+  defaultSelectedCountText,
+  initialFocusIndex,
+  pickedOptions,
+  sameValues,
+  toggleValue,
+  triggerSummary,
+  valueList,
+} from "./select-logic.js";
 
 const h = React.createElement;
 const NAVIGATION_KEYS = ["ArrowDown", "ArrowUp", "Home", "End"];
+// Wide enough that no picked chip shrinks while it is measured.
+const MEASURE_SPAN = 10000;
+// A compact chip that fits the field's own line, so the trigger keeps its height.
+const TRIGGER_CHIP_STYLE = Object.freeze({ minHeight: 0, paddingVertical: 2 });
+const UNMEASURED = Object.freeze({ available: null, needed: null });
 
 /**
  * Bind the shared select to one platform's primitives.
  *
- * @param {{View: any, Text: any, Pressable: any, ScrollView: any, Platform: any, Overlay: any}} rn
+ * @param {{View: any, Text: any, Pressable: any, ScrollView: any, Platform: any,
+ *   Overlay: any, Button: any, Chip: any}} rn
  */
 export function makeSelect(rn) {
-  const { View, Text, Pressable, ScrollView, Platform, Overlay } = rn;
+  const { View, Text, Pressable, ScrollView, Platform, Overlay, Button, Chip } = rn;
   const FieldFrame = makeFieldFrame(rn);
 
   // Keyboard focus is a web concern: a device moves its reader's focus into
@@ -48,11 +66,11 @@ export function makeSelect(rn) {
     if (Platform.OS === "web" && node && typeof node.focus === "function") node.focus();
   }
 
-  function OptionSheet({ t, options, value, title, emptyText, listId, onPick, testID }) {
+  function OptionSheet(props) {
+    const { t, options, isPicked, multiple, title, emptyText, listId, onPick, testID, footer } =
+      props;
     const nodes = React.useRef([]);
-    const chosen = options.findIndex((option) => option.value === value);
-    const firstEnabled = options.findIndex((option) => !option.disabled);
-    const initial = chosen !== -1 && !options[chosen].disabled ? chosen : firstEnabled;
+    const initial = initialFocusIndex(options, isPicked);
     // Focus lands on the current choice once, when the sheet mounts it; the
     // browser scrolls a focused option into view in a long list.
     const pendingFocus = React.useRef(true);
@@ -81,12 +99,13 @@ export function makeSelect(rn) {
               nativeID: listId,
               // Web only: native has no listbox, and ignores an unknown `role`.
               role: "listbox",
+              ...(multiple ? { "aria-multiselectable": true } : null),
               accessibilityLabel: isText(title) ? String(title) : undefined,
               keyboardShouldPersistTaps: "handled",
               testID: testID ? `${testID}-options` : undefined,
             },
             ...options.map((option, index) => {
-              const selected = option.value === value;
+              const selected = isPicked(option);
               // The web host still delivers keys to a disabled Pressable.
               const pick = () => {
                 if (!option.disabled) onPick(option);
@@ -121,7 +140,7 @@ export function makeSelect(rn) {
                     {
                       flexDirection: "row",
                       alignItems: "center",
-                      justifyContent: "space-between",
+                      justifyContent: multiple ? "flex-start" : "space-between",
                       gap: t.rowGap,
                       minHeight: CONTROL_MIN_TARGET,
                       paddingHorizontal: t.paddingHorizontal,
@@ -132,15 +151,93 @@ export function makeSelect(rn) {
                     option.disabled ? { opacity: t.disabledOpacity } : null,
                   ],
                 },
+                multiple ? checkboxBox(View, t, { checked: selected }) : null,
                 h(
                   Text,
                   { style: [text, { flexShrink: 1 }, selected ? { fontWeight: "600" } : null] },
                   option.label,
                 ),
-                selected ? h(Icon, { name: "check", size: 18, color: t.accent }) : null,
+                selected && !multiple ? h(Icon, { name: "check", size: 18, color: t.accent }) : null,
               );
             }),
           ),
+      footer || null,
+    );
+  }
+
+  function DoneFooter({ doneText, onDone, testID }) {
+    return h(
+      View,
+      { style: { flexDirection: "row", justifyContent: "flex-end" } },
+      h(Button, { title: doneText, onPress: onDone, testID: testID ? `${testID}-done` : undefined }),
+    );
+  }
+
+  // Chips when they fit the field's one line, else the count; measured on
+  // both hosts, so a narrow trigger never grows to hold them.
+  function MultiSummary({ t, picked, placeholder, selectedCountText, testID }) {
+    const [widths, setWidths] = React.useState(UNMEASURED);
+    const countText =
+      typeof selectedCountText === "function" ? selectedCountText : defaultSelectedCountText;
+    const measure = (key) => (event) => {
+      const width = event.nativeEvent.layout.width;
+      setWidths((own) => (own[key] === width ? own : { ...own, [key]: width }));
+    };
+    const mode = triggerSummary({ picked: picked.length, ...widths });
+    const text = { fontFamily: t.fontFamily, fontSize: t.fontSize };
+    const chips = () =>
+      picked.map((option) =>
+        h(Chip, {
+          key: `${typeof option.value}:${option.value}`,
+          label: option.label,
+          size: "sm",
+          style: TRIGGER_CHIP_STYLE,
+        }),
+      );
+    return h(
+      View,
+      {
+        onLayout: measure("available"),
+        style: { flexGrow: 1, flexShrink: 1, minWidth: 0, overflow: "hidden" },
+        testID: testID ? `${testID}-summary` : undefined,
+      },
+      mode === "chips"
+        ? h(View, { style: { flexDirection: "row", gap: t.gap } }, ...chips())
+        : h(
+            Text,
+            {
+              numberOfLines: 1,
+              style: { ...text, color: mode === "count" ? t.textColor : t.placeholderColor },
+            },
+            mode === "count" ? countText(picked.length) : placeholder,
+          ),
+      picked.length > 0
+        ? h(
+            View,
+            {
+              "aria-hidden": true,
+              importantForAccessibility: "no-hide-descendants",
+              accessibilityElementsHidden: true,
+              style: {
+                position: "absolute",
+                top: 0,
+                left: 0,
+                width: MEASURE_SPAN,
+                opacity: 0,
+                pointerEvents: "none",
+              },
+            },
+            h(
+              View,
+              {
+                onLayout: measure("needed"),
+                style: { flexDirection: "row", alignSelf: "flex-start", gap: t.gap },
+                testID: testID ? `${testID}-measure` : undefined,
+              },
+              ...chips(),
+            ),
+          )
+        : null,
     );
   }
 
@@ -148,6 +245,11 @@ export function makeSelect(rn) {
     const {
       value,
       onValueChange,
+      multiple = false,
+      values,
+      onValuesChange,
+      selectedCountText = defaultSelectedCountText,
+      doneText = "Done",
       options,
       placeholder = "Select",
       title,
@@ -174,6 +276,8 @@ export function makeSelect(rn) {
     }
     const t = resolveFormControlTokens(theme, overrides);
     const [open, setOpen] = React.useState(false);
+    // Null until the person ticks something: an untouched sheet follows `values`.
+    const [ownDraft, setDraft] = React.useState(null);
     const [focused, setFocused] = React.useState(false);
     const triggerRef = React.useRef(null);
     const setRef = React.useMemo(() => shareRef(ref, triggerRef), [ref]);
@@ -181,14 +285,41 @@ export function makeSelect(rn) {
     const noteId = React.useId();
     const list = Array.isArray(options) ? options.filter(Boolean) : [];
     const current = selectedOption(list, value);
+    const picked = multiple ? pickedOptions(list, values) : [];
+    const draft = ownDraft === null ? valueList(values) : ownDraft;
     const invalid = isShown(error);
     const sheetTitle = isShown(title) ? title : isText(label) ? label : undefined;
     const name = spokenLabel(accessibilityLabel, label);
     const shown = current ? current.label : placeholder;
+    const spokenChoice = multiple
+      ? picked.length > 0
+        ? picked.map((option) => option.label).filter(isText).join(", ")
+        : placeholder
+      : shown;
     const show = () => {
-      if (!disabled) setOpen(true);
+      if (disabled) return;
+      if (multiple) setDraft(null);
+      setOpen(true);
     };
+    // Closing any other way leaves the draft behind: only Done commits it.
     const close = () => setOpen(false);
+    const done = () => {
+      const next = committedValues(list, draft);
+      close();
+      if (!sameValues(next, valueList(values)) && typeof onValuesChange === "function") {
+        onValuesChange(next, pickedOptions(list, next));
+      }
+    };
+    const pick = (option) => {
+      if (multiple) {
+        setDraft((own) => toggleValue(own === null ? valueList(values) : own, option.value));
+        return;
+      }
+      close();
+      if (option.value !== value && typeof onValueChange === "function") {
+        onValueChange(option.value, option);
+      }
+    };
     // The option that held focus is gone once the sheet closes. After the
     // sheet unmounts, or its focus trap would pull focus straight back in.
     const wasOpen = React.useRef(false);
@@ -239,7 +370,8 @@ export function makeSelect(rn) {
           ...(invalid ? { "aria-invalid": true } : null),
           ...(hasNote({ helper, error }) ? { "aria-describedby": noteId } : null),
           // The choice is part of the name: a button's own label replaces its text.
-          accessibilityLabel: [name, isText(shown) ? shown : null].filter(Boolean).join(", ") || undefined,
+          accessibilityLabel:
+            [name, isText(spokenChoice) ? spokenChoice : null].filter(Boolean).join(", ") || undefined,
           testID,
           style: [
             {
@@ -260,19 +392,21 @@ export function makeSelect(rn) {
             style,
           ],
         },
-        h(
-          Text,
-          {
-            numberOfLines: 1,
-            style: {
-              flexShrink: 1,
-              color: current ? t.textColor : t.placeholderColor,
-              fontFamily: t.fontFamily,
-              fontSize: t.fontSize,
-            },
-          },
-          shown,
-        ),
+        multiple
+          ? h(MultiSummary, { t, picked, placeholder, selectedCountText, testID })
+          : h(
+              Text,
+              {
+                numberOfLines: 1,
+                style: {
+                  flexShrink: 1,
+                  color: current ? t.textColor : t.placeholderColor,
+                  fontFamily: t.fontFamily,
+                  fontSize: t.fontSize,
+                },
+              },
+              shown,
+            ),
         h(Icon, { name: "chevron-down", size: 18, color: t.placeholderColor }),
       ),
       h(
@@ -293,17 +427,16 @@ export function makeSelect(rn) {
         h(OptionSheet, {
           t,
           options: list,
-          value,
+          multiple,
+          isPicked: multiple
+            ? (option) => draft.includes(option.value)
+            : (option) => option.value === value,
           title: sheetTitle,
           emptyText,
           listId,
           testID,
-          onPick: (option) => {
-            close();
-            if (option.value !== value && typeof onValueChange === "function") {
-              onValueChange(option.value, option);
-            }
-          },
+          onPick: pick,
+          footer: multiple ? h(DoneFooter, { doneText, onDone: done, testID }) : null,
         }),
       ),
     );

package/dist/select.js

@@ -1,9 +1,12 @@
 // `<Select>` (web). Binds ./select-view.js to react-native-web and the web
-// `<Overlay>`; see ./primitives.js for why not the bare specifier.
+// `<Overlay>`, `<Button>` and `<Chip>`; see ./primitives.js for why not the
+// bare specifier.
 
 import * as ReactNative from "react-native-web";
 import { makeSelect } from "./select-view.js";
 import { Overlay } from "./overlay.js";
+import { Button } from "./button.js";
+import { Chip } from "./chip.js";
 
 export const Select = makeSelect({
   View: ReactNative.View,
@@ -12,4 +15,6 @@ export const Select = makeSelect({
   ScrollView: ReactNative.ScrollView,
   Platform: ReactNative.Platform,
   Overlay,
+  Button,
+  Chip,
 });

package/dist/select.native.js

@@ -1,9 +1,11 @@
 // `<Select>` (native). Binds ./select-view.js to React Native's own
-// primitives and the native `<Overlay>`; only the imports differ from
-// ./select.js.
+// primitives and the native `<Overlay>`, `<Button>` and `<Chip>`; only the
+// imports differ from ./select.js.
 
 import { View, Text, Pressable, ScrollView, Platform } from "react-native";
 import { makeSelect } from "./select-view.js";
 import { Overlay } from "./overlay.native.js";
+import { Button } from "./button.native.js";
+import { Chip } from "./chip.native.js";
 
-export const Select = makeSelect({ View, Text, Pressable, ScrollView, Platform, Overlay });
+export const Select = makeSelect({ View, Text, Pressable, ScrollView, Platform, Overlay, Button, Chip });

package/package.json

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

@@ -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" }),
@@ -1203,6 +1203,8 @@ const HOOKS = [
       openLink: "(link: string) => boolean",
       goToStartPage:
         "() => void — opens the signed-in user's own start page, the page the app opens on for them (it can differ per user, since page access is restricted per group). Use it for a 'back to start' or 'home' button instead of hard-coding a page. A no-op where there is no live router (the Studio canvas, a badge counter).",
+      scrollToSection:
+        "(sectionId: string) => void — scrolls THIS page to one of its sections (a root section or a layout container), landing its top just below any pinned site header; smooth unless the visitor prefers reduced motion. Take the id from a `sectionRef` prop the author picks; never hard-code a node id. An unknown, deleted or hidden section is a no-op, and so is the Studio canvas.",
       goBack: "() => void",
       push: "(pageIdOrSlug: string, params?: object) => void",
       replace: "(pageIdOrSlug: string, params?: object) => void",
@@ -3145,16 +3147,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 +3254,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 +3387,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 +3419,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 +6079,14 @@ 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>`.
+  // 1.193.0: additive (sc-11821) — `useNavigation().scrollToSection(id)`
+  //    scrolls the page to one of its sections on both hosts, and the
+  //    `sectionRef` propertySchema type gives the author a section picker.
+  version: "1.193.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,