@colixsystems/widget-sdk 0.246.0 → 0.247.0

package/dist/select-view.js

@@ -6,6 +6,8 @@
 // `<Overlay>`, at screen level, so no card or scroll container the widget
 // 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.
+// Searchable, the sheet leads with a `<SearchField>`: the list filters where
+// it is held, or each pause in typing asks `onSearch` / async `options`.
 
 import React from "react";
 import { useHostTheme } from "./hooks.js";
@@ -41,6 +43,18 @@ import {
   triggerSummary,
   valueList,
 } from "./select-logic.js";
+import {
+  DEFAULT_SEARCH_DEBOUNCE_MS,
+  createDebouncer,
+  createRequestGate,
+  filterOptions,
+  knownOption,
+  knownOptions,
+  normaliseQuery,
+  rememberOptions,
+  searchRowOverrides,
+  sheetBody,
+} from "./select-search-logic.js";
 
 const h = React.createElement;
 // Wide enough that no picked chip shrinks while it is measured.
@@ -53,10 +67,12 @@ 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, Button: any, Chip: any}} rn
+ *   Overlay: any, Button: any, Chip: any, SearchField?: any, Spinner?: any}} rn
+ *   — `SearchField` and `Spinner` are needed only by a searchable select.
  */
 export function makeSelect(rn) {
-  const { View, Text, Pressable, ScrollView, Platform, Overlay, Button, Chip } = rn;
+  const { View, Text, Pressable, ScrollView, Platform, Overlay, Button, Chip, SearchField, Spinner } =
+    rn;
   const FieldFrame = makeFieldFrame(rn);
 
   // Keyboard focus is a web concern: a device moves its reader's focus into
@@ -66,14 +82,31 @@ export function makeSelect(rn) {
   }
 
   function OptionSheet(props) {
-    const { t, options, isPicked, multiple, title, emptyText, listId, onPick, testID, footer } =
-      props;
+    const {
+      t,
+      options,
+      isPicked,
+      multiple,
+      title,
+      emptyText,
+      listId,
+      onPick,
+      testID,
+      footer,
+      search,
+      body = options.length === 0 ? "empty" : "list",
+      bodyText,
+      rowStyle,
+    } = props;
     const nodes = React.useRef([]);
     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);
+    // browser scrolls a focused option into view in a long list. A search
+    // field takes that first focus instead.
+    const pendingFocus = React.useRef(!search);
     const text = { fontFamily: t.fontFamily, fontSize: t.fontSize, color: t.popover.textColor };
+    const note = { ...text, color: t.helperColor, paddingHorizontal: t.paddingHorizontal };
+    const focusFirst = () => focusNode(nodes.current[initialFocusIndex(options, () => false)]);
 
     return h(
       View,
@@ -85,11 +118,23 @@ export function makeSelect(rn) {
             title,
           )
         : null,
-      options.length === 0
+      search ? search(focusFirst) : null,
+      body === "loading"
+        ? h(
+            View,
+            { style: { paddingVertical: t.rowGap }, testID: testID ? `${testID}-loading` : undefined },
+            h(Spinner, { size: "sm", label: bodyText }),
+          )
+        : body !== "list"
         ? h(
             Text,
-            { style: { ...text, color: t.helperColor, paddingHorizontal: t.paddingHorizontal } },
-            emptyText,
+            {
+              style: body === "error" ? { ...note, color: t.errorColor } : note,
+              // Results arrive after typing; a status line says what came back.
+              ...(search ? { role: "status", accessibilityLiveRegion: "polite" } : null),
+              testID: search && testID ? `${testID}-${body}` : undefined,
+            },
+            body === "empty" ? emptyText : bodyText,
           )
         : h(
             ScrollView,
@@ -133,17 +178,28 @@ export function makeSelect(rn) {
                   "aria-selected": selected,
                   "aria-disabled": !!option.disabled,
                   testID: option.testID,
-                  style: ({ pressed }) =>
-                    optionRowStyle(t, {
+                  style: ({ pressed }) => [
+                    ...optionRowStyle(t, {
                       pressed,
                       disabled: option.disabled,
                       justifyContent: multiple ? "flex-start" : "space-between",
                     }),
+                    rowStyle,
+                  ],
                 },
                 multiple ? checkboxBox(View, t, { checked: selected }) : null,
+                option.leading ? h(View, { style: { flexShrink: 0 } }, option.leading) : null,
                 h(
                   Text,
-                  { style: [text, { flexShrink: 1 }, selected ? { fontWeight: "600" } : null] },
+                  {
+                    style: [
+                      text,
+                      { flexShrink: 1 },
+                      // Keeps the check mark at the end once a leading node is drawn.
+                      option.leading ? { flexGrow: 1 } : null,
+                      selected ? { fontWeight: "600" } : null,
+                    ],
+                  },
                   option.label,
                 ),
                 selected && !multiple ? h(Icon, { name: "check", size: 18, color: t.accent }) : null,
@@ -230,6 +286,50 @@ export function makeSelect(rn) {
     );
   }
 
+  // The sheet's search field and what it shows instead of the list.
+  function searchSheetProps({ theme, search, count, loading, failed, texts, testID }) {
+    const body = sheetBody({ loading, error: failed, query: search.text, count });
+    return {
+      body,
+      bodyText:
+        body === "loading"
+          ? texts.loadingText
+          : body === "error"
+          ? texts.loadErrorText
+          : texts.noResultsText,
+      rowStyle: searchRowOverrides(theme),
+      search: (focusFirst) =>
+        h(SheetSearchField, {
+          value: search.text,
+          onChangeText: search.type,
+          placeholder: texts.searchPlaceholder,
+          onArrowDown: focusFirst,
+          testID: testID ? `${testID}-search` : undefined,
+        }),
+    };
+  }
+
+  function SheetSearchField({ value, onChangeText, placeholder, onArrowDown, testID }) {
+    const node = React.useRef(null);
+    React.useEffect(() => {
+      focusNode(node.current);
+    }, []);
+    return h(SearchField, {
+      ref: node,
+      value,
+      onChangeText,
+      placeholder,
+      // Down from the field reaches the first option, as in a combobox.
+      onKeyPress: (event) => {
+        const key = event && event.nativeEvent ? event.nativeEvent.key : undefined;
+        if (key !== "ArrowDown") return;
+        if (typeof event.preventDefault === "function") event.preventDefault();
+        onArrowDown();
+      },
+      testID,
+    });
+  }
+
   const Select = React.forwardRef(function Select(props, ref) {
     const {
       value,
@@ -254,6 +354,16 @@ export function makeSelect(rn) {
       testID,
       onFocus,
       onBlur,
+      searchable: searchableProp = false,
+      onSearch,
+      searchDebounceMs = DEFAULT_SEARCH_DEBOUNCE_MS,
+      loading: loadingProp = false,
+      optionsError,
+      selectedOptions,
+      searchPlaceholder = "Search",
+      noResultsText = "No results",
+      loadingText = "Loading…",
+      loadErrorText = "Could not load the options",
       ...others
     } = props;
     const theme = useHostTheme() || DEFAULT_THEME_TOKENS;
@@ -272,9 +382,27 @@ export function makeSelect(rn) {
     const setRef = React.useMemo(() => shareRef(ref, triggerRef), [ref]);
     const listId = React.useId();
     const noteId = React.useId();
-    const list = Array.isArray(options) ? options.filter(Boolean) : [];
-    const current = selectedOption(list, value);
-    const picked = multiple ? pickedOptions(list, values) : [];
+    const search = useSearchState({
+      open,
+      options,
+      searchable: searchableProp,
+      onSearch,
+      debounceMs: searchDebounceMs,
+    });
+    const { searchable } = search;
+    const held = search.fetched
+      ? search.fetched.options
+      : Array.isArray(options)
+      ? options.filter(Boolean)
+      : [];
+    const list = search.filtersHeld ? filterOptions(held, search.text) : held;
+    // Searchable, a picked option keeps its label after a search drops it.
+    const known = React.useRef(new Map());
+    if (searchable) known.current = rememberOptions(known.current, selectedOptions, held);
+    const optionsFor = (own) =>
+      searchable ? knownOptions(known.current, own) : pickedOptions(list, own);
+    const current = searchable ? knownOption(known.current, value) : selectedOption(list, value);
+    const picked = multiple ? optionsFor(values) : [];
     const draft = ownDraft === null ? valueList(values) : ownDraft;
     const invalid = isShown(error);
     const sheetTitle = isShown(title) ? title : isText(label) ? label : undefined;
@@ -296,7 +424,7 @@ export function makeSelect(rn) {
       const next = committedValues(list, draft);
       close();
       if (!sameValues(next, valueList(values)) && typeof onValuesChange === "function") {
-        onValuesChange(next, pickedOptions(list, next));
+        onValuesChange(next, optionsFor(next));
       }
     };
     const pick = (option) => {
@@ -421,6 +549,23 @@ export function makeSelect(rn) {
           testID,
           onPick: pick,
           footer: multiple ? h(DoneFooter, { doneText, onDone: done, testID }) : null,
+          ...(searchable
+            ? searchSheetProps({
+                theme,
+                search,
+                count: list.length,
+                loading:
+                  search.pending || (search.fetched ? search.fetched.loading : !!loadingProp),
+                failed: search.fetched ? search.fetched.error : isShown(optionsError),
+                texts: {
+                  searchPlaceholder,
+                  noResultsText,
+                  loadingText,
+                  loadErrorText: typeof optionsError === "string" ? optionsError : loadErrorText,
+                },
+                testID,
+              })
+            : null),
         }),
       ),
     );
@@ -429,3 +574,86 @@ export function makeSelect(rn) {
   Select.displayName = "Select";
   return Select;
 }
+
+/**
+ * A searchable select's query: the text typed into the sheet, sent after a
+ * pause to `onSearch` or to async `options`, whose latest answer it keeps.
+ * Opening the sheet starts from an empty query; a plain select is inert here.
+ */
+function useSearchState({ open, options, searchable, onSearch, debounceMs }) {
+  const asyncOptions = typeof options === "function";
+  const remote = typeof onSearch === "function" || asyncOptions;
+  const enabled = !!searchable || remote;
+  const [text, setText] = React.useState("");
+  // The query last handed on; typed text that differs is still pending.
+  const [sentQuery, setSentQuery] = React.useState("");
+  const [fetched, setFetched] = React.useState({ options: [], loading: false, error: false });
+  const latest = React.useRef({ onSearch, options });
+  latest.current = { onSearch, options };
+  const gate = React.useRef(null);
+  if (gate.current === null) gate.current = createRequestGate();
+  const mounted = React.useRef(false);
+  // Set in the body too: StrictMode runs the cleanup, then the effect again.
+  React.useEffect(() => {
+    mounted.current = true;
+    return () => {
+      mounted.current = false;
+    };
+  }, []);
+
+  const send = React.useCallback((query) => {
+    setSentQuery(query);
+    const own = latest.current;
+    if (typeof own.onSearch === "function") own.onSearch(query);
+    if (typeof own.options !== "function") return;
+    const ticket = gate.current.begin();
+    setFetched((state) => ({ ...state, loading: true, error: false }));
+    Promise.resolve()
+      .then(() => own.options(query))
+      .then(
+        (rows) => {
+          if (!mounted.current || !gate.current.isCurrent(ticket)) return;
+          const list = Array.isArray(rows) ? rows.filter(Boolean) : [];
+          setFetched({ options: list, loading: false, error: false });
+        },
+        () => {
+          if (!mounted.current || !gate.current.isCurrent(ticket)) return;
+          setFetched({ options: [], loading: false, error: true });
+        },
+      );
+  }, []);
+
+  const delay = React.useRef(debounceMs);
+  delay.current = debounceMs;
+  const debouncer = React.useRef(null);
+  if (debouncer.current === null) debouncer.current = createDebouncer(() => delay.current, send);
+  React.useEffect(() => () => debouncer.current.cancel(), []);
+
+  // Each opening starts from an empty query, asked for at once; it is
+  // cleared on closing so the next opening never draws the old filter.
+  React.useEffect(() => {
+    if (!enabled) return;
+    if (!open) {
+      debouncer.current.cancel();
+      setText("");
+      return;
+    }
+    if (remote) send("");
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [open, enabled, remote]);
+
+  const type = (next) => {
+    const own = typeof next === "string" ? next : "";
+    setText(own);
+    if (remote) debouncer.current.push(own);
+  };
+
+  return {
+    searchable: enabled,
+    filtersHeld: enabled && !remote,
+    text: enabled ? text : "",
+    pending: remote && normaliseQuery(text) !== sentQuery,
+    type,
+    fetched: asyncOptions ? fetched : null,
+  };
+}

package/dist/select.js

@@ -1,12 +1,14 @@
 // `<Select>` (web). Binds ./select-view.js to react-native-web and the web
-// `<Overlay>`, `<Button>` and `<Chip>`; see ./primitives.js for why not the
-// bare specifier.
+// `<Overlay>`, `<Button>`, `<Chip>`, `<SearchField>` and `<Spinner>`; 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";
+import { SearchField } from "./search-field.js";
+import { Spinner } from "./loading.js";
 
 export const Select = makeSelect({
   View: ReactNative.View,
@@ -17,4 +19,6 @@ export const Select = makeSelect({
   Overlay,
   Button,
   Chip,
+  SearchField,
+  Spinner,
 });

package/dist/select.native.js

@@ -1,11 +1,13 @@
 // `<Select>` (native). Binds ./select-view.js to React Native's own
-// primitives and the native `<Overlay>`, `<Button>` and `<Chip>`; only the
-// imports differ from ./select.js.
+// primitives and the native `<Overlay>`, `<Button>`, `<Chip>`,
+// `<SearchField>` and `<Spinner>`; 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";
+import { SearchField } from "./search-field.native.js";
+import { Spinner } from "./loading.native.js";
 
-export const Select = makeSelect({ View, Text, Pressable, ScrollView, Platform, Overlay, Button, Chip });
+export const Select = makeSelect({ View, Text, Pressable, ScrollView, Platform, Overlay, Button, Chip, SearchField, Spinner });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.246.0",
+  "version": "0.247.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", "FileUpload", "RadioGroup"]),
+    sdkComponents: Object.freeze(["TextField", "Checkbox", "Switch", "Select", "SearchField", "FileUpload", "RadioGroup", "PeoplePicker"]),
     tokens: Object.freeze({
       background: Object.freeze({ type: "color", uiDefault: "colors.surfaceMuted" }),
       textColor: Object.freeze({ type: "color", uiDefault: "colors.onSurfaceMuted" }),
@@ -641,7 +641,7 @@ const THEME_COMPONENTS = Object.freeze({
   // radius and shadow keep the `<Overlay>` panel's own.
   popover: Object.freeze({
     label: "Dropdown menus",
-    sdkComponents: Object.freeze(["Select", "Menu", "Popover", "Tooltip"]),
+    sdkComponents: Object.freeze(["Select", "Menu", "Popover", "Tooltip", "PeoplePicker"]),
     tokens: Object.freeze({
       background: Object.freeze({ type: "color", uiDefault: "colors.surface" }),
       textColor: Object.freeze({ type: "color", uiDefault: "colors.onSurface" }),
@@ -784,6 +784,25 @@ const THEME_COMPONENTS = Object.freeze({
     }),
     targets: Object.freeze({}),
   }),
+  // Charts: `<Chart>` reads this scope directly, so it names the SDK
+  // component it styles and binds no widget field. Unset series colours
+  // follow the theme's own colours, so their defaults are derived.
+  chart: Object.freeze({
+    label: "Charts",
+    sdkComponents: Object.freeze(["Chart"]),
+    tokens: Object.freeze({
+      series1: Object.freeze({ type: "color" }),
+      series2: Object.freeze({ type: "color" }),
+      series3: Object.freeze({ type: "color" }),
+      series4: Object.freeze({ type: "color" }),
+      series5: Object.freeze({ type: "color" }),
+      series6: Object.freeze({ type: "color" }),
+      axisColor: Object.freeze({ type: "color", uiDefault: "colors.onSurfaceMuted" }),
+      gridColor: Object.freeze({ type: "color", uiDefault: "colors.border" }),
+      barRadius: Object.freeze({ type: "size", min: 0, max: 24, uiDefault: "radii.sm" }),
+    }),
+    targets: Object.freeze({}),
+  }),
 });
 
 // sc-4505 — the value types a widget event payload field may declare. Narrower
@@ -2536,7 +2555,8 @@ const HOOKS = [
       "Returns { groups, loading, error, refetch, create, remove, addMember, " +
       "removeMember }. list returns the { data, meta } envelope verbatim — the " +
       "hook unwraps res.data; rows are snake_case. Reads need groups.read:*; " +
-      "mutations need groups.write:*.",
+      "mutations need groups.write:*. query { q?, ids?, limit?, offset? }: " +
+      "`ids` (1 to 100) names the groups behind ids you already hold.",
     returnShape: {
       groups: "Array<{ id, name, member_count }>  // snake_case rows; unwrapped from { data, meta }",
       loading: "boolean",
@@ -3377,6 +3397,13 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  {
+    name: "Chart",
+    description:
+      'Themed chart. `<Chart type="bar" data={groups.map((g) => ({ label: String(g.group), value: Number(g.sum) || 0 }))} loading={loading} valueFormat="compact" />`. Use it by default to plot a table\'s figures: feed it ONE `useDatastoreAggregate` call (`groups` for a breakdown by a column, `buckets` for a series over time) mapped to `[{ label, value }]`. `type` is "bar" (default), "hbar" (horizontal bars, for long category names), "line", "area", "donut" (the parts of a whole) or "sparkline" (a small line inside a tile, with no axes). It measures its own width and redraws when its container resizes, shows a `<Skeleton>` while `loading` and an `<EmptyState>` when there is nothing to plot, draws a legend for a donut and for several series, and gives a screen reader a one-line summary followed by the values. Its series colours, axis and label colour, gridline colour and bar corners come from the app\'s chart look (Design > Components > Charts), falling back to the theme\'s colours, so pass no colours of your own. Props: `data` (`[{ label, value }]`, or one number per series key), `series` (`[{ key, label, color? }]` for several series sharing one `data`: bars stand side by side, lines and areas overlay; a donut and a sparkline draw the first), `type`, `valueFormat` ("number" default | "compact", 1.2k | "percent", which appends % to a value already in percent, 42 reads 42% | a function of the number; used for the axis, the legend and the spoken values, grouped for the app\'s language), `height` (px, default 220; 48 for a sparkline), `loading`, `emptyTitle` (default the shared "No results" text) and `emptyMessage`, `accessibilityLabel` (replaces the spoken summary sentence; pass your translated title), `moreText` (`(count) => string`, the tail of a long spoken value list, default "and N more"; pass it translated), `style`, `testID`. When the request needs a chart it cannot draw (a scatter plot, a gantt or timeline, brushing or tapping a bar to filter), build your own with react-native-svg in the app\'s look (see DRAWING A CHART), painting it with `chartColors(useTheme())`: `series(i)` and `seriesOpacity(i)` for the i-th series, `axis` and `grid`, the colours `<Chart>` uses.',
+    rnComponent: null,
+    docsUrl: null,
+  },
   {
     name: "Divider",
     description:
@@ -3384,6 +3411,13 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  {
+    name: "Grid",
+    description:
+      'Balanced lines of cells sized from the grid\'s own measured width. `<Grid minCellWidth={240}>{items.map((item) => <Card key={item.id} style={{ flex: 1 }}>…</Card>)}</Grid>` — use it by default for a card grid, a tile or stat row, and a grid of definite-size cells (calendar days, seats, swatches); when the layout needs what it cannot express (masonry, a bento layout whose cells span lines), lay it out yourself with `useContainerWidth()`. It measures an inner box with no padding, so padding in its `style` is never counted into the width. `balance` "cards" (default): as many cells per line as fit at `minCellWidth` (240 when unset), every line but the last full and the last padded with empty cells so its cards keep the width above (6 that fit 5 are 3 + 3). "tiles": the remainder spreads over every line and each line stretches (5 at 4 per line are 3 + 2, never 4 + 1); the per-line ceiling is `maxColumns`, or what fits at `minCellWidth`, or else 4 / 3 / 2 for the wide / medium / narrow width tier. `columns` fixes the count per line. `cell={{ min, max }}` makes definite-size cells as large as fit up to `max` (never below `min`, 32 when unset) in a block centred in the grid (a block whose `min` cells cannot fit starts at the leading edge, so only its far end is cut off), `square` makes them as tall as wide: `<Grid columns={7} cell={{ min: 32, max: 64 }} square gap="xs">`. Props: `children` (one cell each; each keeps its own look and theme scope, and a child with `flex: 1` fills its cell\'s height so a line of cards ends level), `balance`, `minCellWidth`, `maxColumns`, `columns`, `cell`, `square`, `gap` (a theme spacing name, default "md", or a number), `style` (the outer box), `testID`, `accessibilityLabel`. A layout that depends on the width draws nothing until it is measured. In a row, give it `style={{ flex: 1, minWidth: 0 }}` so it has a width to measure.',
+    rnComponent: null,
+    docsUrl: null,
+  },
   {
     name: "Banner",
     description:
@@ -3464,7 +3498,7 @@ const PRIMITIVES = [
   {
     name: "Select",
     description:
-      '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 default 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. Use it rather than a dropdown of your own; when the request needs options it cannot show (colour swatches, photos with two-line captions), put a small swatch or photo picker in a `<Popover>` at its button, or a long or full-screen option list in a `<Modal>` (an emoji choice is `<EmojiPicker>`) — never an absolutely positioned list, which the widget\'s container clips on both hosts. MULTIPLE: `<Select multiple label="Tags" values={tags} onValuesChange={setTags} options={tagOptions} />` — the default 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.',
+      '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 default 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. Use it rather than a dropdown of your own; when the request needs options it cannot show (colour swatches, photos with two-line captions), put a small swatch or photo picker in a `<Popover>` at its button, or a long or full-screen option list in a `<Modal>` (an emoji choice is `<EmojiPicker>`) — never an absolutely positioned list, which the widget\'s container clips on both hosts. MULTIPLE: `<Select multiple label="Tags" values={tags} onValuesChange={setTags} options={tagOptions} />` — the default 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. SEARCHABLE: a long list the user should type to narrow. `searchable` filters the given `options` by label as they type; `onSearch(query)` hands you the trimmed query when the sheet opens (\"\") and once typing pauses (`searchDebounceMs`, default 250), and you answer with new `options` and `loading` meanwhile (`optionsError` when it failed); or pass `options` as an async function of the query and Select fetches, keeping only the latest answer. The sheet then leads with the app\'s search field (Design > Components > Search fields), shows a spinner while loading, `noResultsText` (default \"No results\") when a query finds nothing and `loadErrorText` on failure, and its rows take the Lists row height and padding when the theme sets them. It remembers the label of every option it has shown; pass `selectedOptions` for a saved value the first page may not hold, or the trigger shows the placeholder. An option may carry `leading` (an `<Avatar>`, an icon) drawn before its label. Picking people, groups or a table\'s records is `<PeoplePicker>`, which does all of this for you.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -3475,6 +3509,13 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  {
+    name: "PeoplePicker",
+    description:
+      'Searchable picker of people, groups or records. `<PeoplePicker label="Assignee" value={assignee} onValueChange={setAssignee} />` — use it by default whenever the user picks a workspace user (an assignee, a reviewer, a recipient), a group (`source="groups"`), or a related record of a table they should search (`source="records" table={tableId}`, named by the table\'s identification column or `labelColumn`). It is a searchable `<Select>`: the same field, sheet, `label` / `helper` / `error` / `disabled`, and `multiple` with `values` / `onValuesChange`. Nothing loads until the sheet opens, each pause in typing searches on the server (never one page filtered in the widget), each user or group row leads with an `<Avatar>` (`avatarColumn` names a record\'s photo column; `showAvatars={false}` hides them), `excludeIds` leaves ids out (the current members), `groupId` limits users to one group, `filter` narrows records, and `pageSize` (default 50) sets the page. A saved value outside the first page is looked up once by id, so the trigger shows its name — `loadingText` meanwhile, `unknownText` (default "Unknown") when it is gone — never the raw id. Values are the row ids, exactly what a USER, USER_GROUP or RELATION column stores. Scopes: `directory.read:users` for users, `groups.read:*` for groups, the table\'s `datastore.read` scope for records. When the request needs what it cannot do — a people list that stays on screen with an action per row, a picker of users with presence dots or a role column — build your own with `useDirectory` / `useGroups` and the app\'s look.',
+    rnComponent: null,
+    docsUrl: null,
+  },
   {
     name: "RadioGroup",
     description:
@@ -4540,7 +4581,7 @@ const VETTED_IMPORTS = [
     platforms: ["web", "native"],
     category: "drawing",
     description:
-      "SVG path generators — `line`, `area`, `arc`, `pie`, `curve*`. Each returns a path string you hand to the vetted react-native-svg's `<Path d={…} />`, so a bespoke line/area/donut chart renders identically in the Player and the Expo export from ONE source file. Pure JS.",
+      "SVG path generators — `line`, `area`, `arc`, `pie`, `curve*`. Each returns a path string you hand to the vetted react-native-svg's `<Path d={…} />`, so a chart `<Chart>` does not draw renders identically in the Player and the Expo export from ONE source file. Pure JS.",
   },
   {
     specifier: "d3-array",
@@ -6210,7 +6251,10 @@ const CONTRACT = deepFreeze({
   //    `<Menu>`, `<Popover>`, `<Tooltip>` (popover scope gains radius,
   //    shadow), `<IconButton>`, Button ghost/link/size/busy/selected and
   //    trigger pass-through, `<FileImage>`, `Avatar fileId`, `<RadioGroup>`.
-  version: "1.200.0",
+  // 1.201.0: additive (sc-12070, sc-12071, sc-12072) — new `<Grid>`,
+  //    `<Chart>` + `chart` theme scope + `chartColors`, `<PeoplePicker>`,
+  //    searchable `<Select>`; `useGroups` takes `ids`.
+  version: "1.201.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,