@colixsystems/widget-sdk 0.245.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";
@@ -13,10 +15,9 @@ import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
 import { Icon } from "./icon.js";
 import { TEXT_FIELD_TOKEN_NAMES } from "./text-field-tokens.js";
 import {
-  CONTROL_MIN_TARGET,
   FIELD_OUTLINE_OFF,
   fieldStateStyle,
-  nextOptionIndex,
+  optionRowStyle,
   resolveFormControlTokens,
   selectedOption,
 } from "./form-control-tokens.js";
@@ -25,10 +26,11 @@ import {
   hasNote,
   isShown,
   isText,
+  optionKeyDown,
   shareRef,
-  spaceActivates,
   spokenLabel,
 } from "./form-control-logic.js";
+import { popoverPanelStyle } from "./popover-tokens.js";
 import { makeFieldFrame } from "./form-control-view.js";
 import { checkboxBox } from "./checkbox-view.js";
 import {
@@ -41,9 +43,20 @@ 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;
-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.
@@ -54,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
@@ -67,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,
@@ -86,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,
@@ -123,38 +167,39 @@ export function makeSelect(rn) {
                     }
                   },
                   onPress: pick,
-                  onKeyDown: (event) => {
-                    if (NAVIGATION_KEYS.includes(event.key)) {
-                      event.preventDefault();
-                      focusNode(nodes.current[nextOptionIndex(options, index, event.key)]);
-                      return;
-                    }
-                    spaceActivates(pick)(event);
-                  },
+                  onKeyDown: optionKeyDown({
+                    options,
+                    index,
+                    focusAt: (next) => focusNode(nodes.current[next]),
+                    activate: pick,
+                  }),
                   disabled: option.disabled,
                   role: "option",
                   "aria-selected": selected,
                   "aria-disabled": !!option.disabled,
                   testID: option.testID,
                   style: ({ pressed }) => [
-                    {
-                      flexDirection: "row",
-                      alignItems: "center",
+                    ...optionRowStyle(t, {
+                      pressed,
+                      disabled: option.disabled,
                       justifyContent: multiple ? "flex-start" : "space-between",
-                      gap: t.rowGap,
-                      minHeight: CONTROL_MIN_TARGET,
-                      paddingHorizontal: t.paddingHorizontal,
-                      paddingVertical: t.paddingVertical,
-                      borderRadius: t.radius,
-                    },
-                    pressed ? { opacity: 0.7 } : null,
-                    option.disabled ? { opacity: t.disabledOpacity } : null,
+                    }),
+                    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,
@@ -241,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,
@@ -265,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;
@@ -283,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;
@@ -307,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) => {
@@ -417,12 +534,7 @@ export function makeSelect(rn) {
           size: "sm",
           accessibilityLabel: isText(sheetTitle) ? String(sheetTitle) : name,
           ...(closeAccessibilityLabel ? { closeAccessibilityLabel } : null),
-          style: {
-            backgroundColor: t.popover.background,
-            borderWidth: 1,
-            borderColor: t.popover.borderColor,
-            padding: t.rowGap,
-          },
+          style: { ...popoverPanelStyle(t.popover, "dialog"), padding: t.rowGap },
         },
         h(OptionSheet, {
           t,
@@ -437,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),
         }),
       ),
     );
@@ -445,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/dist/tabs-tokens.js

@@ -67,3 +67,62 @@ export function resolveTabsTokens(theme, overrides) {
     rule: colors.border,
   };
 }
+
+const SEGMENT_INSET = 4;
+
+/**
+ * The segmented strip's surfaces: the muted bar, its inset and each segment.
+ * `<Tabs>` and a segmented `<RadioGroup>` both draw from it, so they match.
+ * A concentric outer radius keeps the inset chip's corners parallel, and the
+ * active segment is outlined as well as lifted: a shadow alone disappears on
+ * a dark theme.
+ *
+ * @param {object} t — resolved tab tokens.
+ * @param {object} theme — the resolved workspace theme.
+ */
+export function segmentedStripStyles(t, theme) {
+  const elevation = (theme && theme.elevation) || DEFAULT_THEME_TOKENS.elevation;
+  return {
+    bar: {
+      backgroundColor: t.barBackground,
+      borderRadius: t.radius + 2,
+      alignSelf: "flex-start",
+      maxWidth: "100%",
+    },
+    content: { padding: SEGMENT_INSET, gap: SEGMENT_INSET },
+    item: (active) => ({
+      borderRadius: t.radius,
+      borderWidth: 1,
+      borderColor: active ? t.rule : "transparent",
+      ...(active ? { backgroundColor: t.activeSurface, ...(elevation.sm || {}) } : null),
+    }),
+  };
+}
+
+/** One tab or segment's box, before its style's own surface. */
+export const TAB_ITEM_LAYOUT = Object.freeze({
+  flexDirection: "row",
+  alignItems: "center",
+  justifyContent: "center",
+  gap: 6,
+  minHeight: 44,
+  paddingHorizontal: 12,
+  paddingVertical: 8,
+});
+
+/**
+ * A tab or segment's label.
+ *
+ * @param {object} t — resolved tab tokens.
+ * @param {object} theme — the resolved workspace theme.
+ * @param {boolean} active
+ */
+export function tabLabelStyle(t, theme, active) {
+  const typography = (theme && theme.typography) || DEFAULT_THEME_TOKENS.typography;
+  return {
+    fontFamily: typography.fontFamily,
+    fontSize: typography.sizes.sm,
+    fontWeight: active ? "600" : "500",
+    color: active ? t.activeTextColor : t.textColor,
+  };
+}

package/dist/tabs-view.js

@@ -10,13 +10,15 @@ import React from "react";
 import { useHostTheme } from "./hooks.js";
 import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
 import { Icon } from "./icon.js";
-import { resolveTabsTokens } from "./tabs-tokens.js";
-
-const SEGMENT_INSET = 4;
+import {
+  TAB_ITEM_LAYOUT,
+  resolveTabsTokens,
+  segmentedStripStyles,
+  tabLabelStyle,
+} from "./tabs-tokens.js";
 
 function stripStyles(t, theme) {
   const spacing = theme.spacing || DEFAULT_THEME_TOKENS.spacing;
-  const elevation = theme.elevation || DEFAULT_THEME_TOKENS.elevation;
   if (t.style === "pill") {
     // An idle chip is outlined: a muted fill vanishes on a white card.
     return {
@@ -42,26 +44,7 @@ function stripStyles(t, theme) {
       }),
     };
   }
-  // A concentric outer radius keeps the inset chip's corners parallel. The
-  // bar hugs its segments, and the active one is outlined as well as lifted
-  // because a shadow alone disappears on a dark theme.
-  return {
-    bar: {
-      backgroundColor: t.barBackground,
-      borderRadius: t.radius + 2,
-      alignSelf: "flex-start",
-      maxWidth: "100%",
-    },
-    content: { padding: SEGMENT_INSET, gap: SEGMENT_INSET },
-    item: (active) => ({
-      borderRadius: t.radius,
-      borderWidth: 1,
-      borderColor: active ? t.rule : "transparent",
-      ...(active
-        ? { backgroundColor: t.activeSurface, ...(elevation.sm || {}) }
-        : null),
-    }),
-  };
+  return segmentedStripStyles(t, theme);
 }
 
 /**
@@ -98,7 +81,6 @@ export function makeTabs(rn) {
       textColor,
       radius,
     });
-    const typography = theme.typography || DEFAULT_THEME_TOKENS.typography;
     const strip = stripStyles(t, theme);
 
     return React.createElement(
@@ -130,15 +112,7 @@ export function makeTabs(rn) {
             "aria-disabled": !!item.disabled,
             testID: item.testID,
             style: [
-              {
-                flexDirection: "row",
-                alignItems: "center",
-                justifyContent: "center",
-                gap: 6,
-                minHeight: 44,
-                paddingHorizontal: 12,
-                paddingVertical: 8,
-              },
+              TAB_ITEM_LAYOUT,
               strip.item(active),
               item.disabled ? { opacity: 0.5 } : null,
             ],
@@ -148,15 +122,7 @@ export function makeTabs(rn) {
             : null,
           React.createElement(
             Text,
-            {
-              numberOfLines: 1,
-              style: {
-                fontFamily: typography.fontFamily,
-                fontSize: typography.sizes.sm,
-                fontWeight: active ? "600" : "500",
-                color: ink,
-              },
-            },
+            { numberOfLines: 1, style: tabLabelStyle(t, theme, active) },
             item.label,
           ),
         );