@colixsystems/widget-sdk 0.246.0 → 0.248.0

package/dist/select-search-logic.js

@@ -0,0 +1,150 @@
+// The searchable `<Select>` rules that need no renderer: when a typed query
+// is sent, which answer is still wanted, what the sheet shows meanwhile, and
+// the labels it keeps for picked values the current page no longer holds.
+// Both hosts share them, and the node suite tests them.
+
+import { normaliseThemeComponents } from "./theme-components.js";
+
+/** How long typing must pause before the query is sent, in ms. */
+export const DEFAULT_SEARCH_DEBOUNCE_MS = 250;
+
+/** A typed query as it is sent: trimmed, never null. */
+export function normaliseQuery(text) {
+  return typeof text === "string" ? text.trim() : "";
+}
+
+/**
+ * A trailing debounce: `push` restarts the wait, and only the last text
+ * pushed is delivered, once typing pauses. `cancel` drops a pending one.
+ *
+ * @param {number|(() => number)} delay — ms, or a getter read at each push
+ *   so a changed delay applies to the next pause; below 0 counts as 0.
+ * @param {(query: string) => void} deliver
+ * @param {{setTimeout: Function, clearTimeout: Function}} [timers]
+ */
+export function createDebouncer(delay, deliver, timers = globalThis) {
+  const waitFor = () => {
+    const ms = typeof delay === "function" ? delay() : delay;
+    return Number.isFinite(ms) && ms > 0 ? ms : 0;
+  };
+  let pending = null;
+  const cancel = () => {
+    if (pending !== null) timers.clearTimeout(pending);
+    pending = null;
+  };
+  return {
+    push(text) {
+      cancel();
+      pending = timers.setTimeout(() => {
+        pending = null;
+        deliver(normaliseQuery(text));
+      }, waitFor());
+    },
+    cancel,
+  };
+}
+
+/**
+ * Numbers each request so only the latest one's answer is used; an answer to
+ * a query the person has already typed past is dropped.
+ */
+export function createRequestGate() {
+  let latest = 0;
+  return {
+    begin: () => ++latest,
+    isCurrent: (ticket) => ticket === latest,
+  };
+}
+
+/**
+ * The options whose label holds the query, case-insensitively; all of them
+ * for an empty query. For a list that is searched where it is held.
+ *
+ * @param {Array<{label: unknown}>} options
+ * @param {string} query
+ */
+export function filterOptions(options, query) {
+  const list = Array.isArray(options) ? options : [];
+  const needle = normaliseQuery(query).toLocaleLowerCase();
+  if (!needle) return list;
+  return list.filter((option) =>
+    String(option && option.label != null ? option.label : "")
+      .toLocaleLowerCase()
+      .includes(needle),
+  );
+}
+
+/**
+ * What the sheet's body shows: a spinner while the answer is pending, the
+ * error, the "nothing matches" note for a query with no result, the empty
+ * note for no options at all, else the list.
+ *
+ * @param {{loading?: boolean, error?: boolean, query?: string, count: number}} state
+ * @returns {"loading"|"error"|"noResults"|"empty"|"list"}
+ */
+export function sheetBody({ loading, error, query, count }) {
+  if (loading) return "loading";
+  if (error) return "error";
+  if (count > 0) return "list";
+  return normaliseQuery(query) ? "noResults" : "empty";
+}
+
+// 1 and "1" are two values; the key keeps them apart.
+function valueKey(value) {
+  return `${typeof value}:${value}`;
+}
+
+/**
+ * A copy of `known` (value key → option) holding every option in `lists`,
+ * later lists winning. A searchable select remembers each option it has
+ * shown, so a picked one keeps its label after a search drops it.
+ *
+ * @param {Map<string, object>} known
+ * @param {...Array<{value: string|number}>} lists
+ */
+export function rememberOptions(known, ...lists) {
+  const next = new Map(known instanceof Map ? known : []);
+  for (const list of lists) {
+    for (const option of Array.isArray(list) ? list : []) {
+      if (option && (typeof option.value === "string" || typeof option.value === "number")) {
+        next.set(valueKey(option.value), option);
+      }
+    }
+  }
+  return next;
+}
+
+/** The remembered option for one value, or undefined. */
+export function knownOption(known, value) {
+  return known instanceof Map ? known.get(valueKey(value)) : undefined;
+}
+
+/**
+ * The remembered options for `values`, in their order; a value nothing has
+ * named is left out rather than shown by its raw value.
+ *
+ * @param {Map<string, object>} known
+ * @param {Array<string|number>} values
+ */
+export function knownOptions(known, values) {
+  return (Array.isArray(values) ? values : [])
+    .map((value) => knownOption(known, value))
+    .filter(Boolean);
+}
+
+/**
+ * The row size a searchable sheet takes from the theme's `list` scope: only
+ * the values the theme sets, so an unthemed list keeps the option row's own.
+ *
+ * @param {object} theme — the resolved workspace theme.
+ * @returns {{minHeight?: number, paddingHorizontal?: number}}
+ */
+export function searchRowOverrides(theme) {
+  const components = theme && typeof theme === "object" ? theme.components : undefined;
+  const list = normaliseThemeComponents({ list: components && components.list }).list || {};
+  const out = {};
+  // A row stays a 44px target however small the theme draws list rows.
+  if (Number.isFinite(list.rowMinHeight)) out.minHeight = Math.max(44, list.rowMinHeight);
+  if (Number.isFinite(list.rowPadding)) out.paddingHorizontal = list.rowPadding;
+  return out;
+}

package/dist/select-view.js

@@ -6,9 +6,11 @@
 // `<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";
+import { useHostSharedText, useHostTheme } from "./hooks.js";
 import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
 import { Icon } from "./icon.js";
 import { TEXT_FIELD_TOKEN_NAMES } from "./text-field-tokens.js";
@@ -20,6 +22,7 @@ import {
   selectedOption,
 } from "./form-control-tokens.js";
 import {
+  DRAWS_FIELD_FRAME,
   errorMessage,
   hasNote,
   isShown,
@@ -41,6 +44,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 +68,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 +83,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 +119,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 +179,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 +287,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,
@@ -247,6 +348,7 @@ export function makeSelect(rn) {
       helper,
       error,
       disabled = false,
+      required = false,
       accessibilityLabel,
       closeAccessibilityLabel,
       style,
@@ -254,6 +356,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;
@@ -264,6 +376,7 @@ export function makeSelect(rn) {
       else rest[key] = own;
     }
     const t = resolveFormControlTokens(theme, overrides);
+    const requiredWord = useHostSharedText("required", "Required");
     const [open, setOpen] = React.useState(false);
     // Null until the person ticks something: an untouched sheet follows `values`.
     const [ownDraft, setDraft] = React.useState(null);
@@ -272,13 +385,31 @@ 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;
-    const name = spokenLabel(accessibilityLabel, label);
+    const name = spokenLabel(accessibilityLabel, label, required ? requiredWord : null);
     const shown = current ? current.label : placeholder;
     const spokenChoice = multiple
       ? picked.length > 0
@@ -296,7 +427,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) => {
@@ -325,6 +456,7 @@ export function makeSelect(rn) {
         helper,
         error: errorMessage(error),
         disabled,
+        required,
         noteId,
         onLabelPress: () => focusNode(triggerRef.current),
         style: containerStyle,
@@ -421,11 +553,112 @@ 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),
         }),
       ),
     );
   });
 
   Select.displayName = "Select";
+  Select[DRAWS_FIELD_FRAME] = true;
   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 });