@colixsystems/widget-sdk 0.247.0 → 0.248.0

package/dist/filter-bar-view.js

@@ -0,0 +1,381 @@
+// The ONE implementation behind the `<FilterBar>` SDK primitive: a search
+// box and one compact dropdown per facet, composed from the SDK's own
+// `<SearchField>`, `<Select>`, `<Chip>`, `<Button>` and `<Modal>`, so every
+// part wears the app's look. The platform bindings (`filter-bar.js` /
+// `filter-bar.native.js`) differ only in which host's parts they pass.
+//
+// It measures its own unpadded box. Medium and wide lay out one toolbar row;
+// narrow, or a row too full for its dropdowns, is the search field and one
+// Filters button opening the facets in a sheet that applies on its Apply
+// button. The applied filters sit beneath as removable chips at every width.
+
+import React from "react";
+import { useContainerWidth, useHostTheme } from "./hooks.js";
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import { DEFAULT_SEARCH_DEBOUNCE_MS, createDebouncer, normaliseQuery } from "./select-search-logic.js";
+import {
+  FILTER_FACET_WIDTH,
+  FILTER_SEARCH_MIN_WIDTH,
+  appliedFacets,
+  chipLabel,
+  facetPlaceholder,
+  fillText,
+  filterBarLayout,
+  filtersButtonText,
+  sameFilters,
+  usableFacets,
+  withFacet,
+} from "./filter-bar-logic.js";
+
+const h = React.createElement;
+const NO_FILTERS = Object.freeze({});
+const MAX_UNECHOED = 20;
+
+function part(testID, name) {
+  return testID ? `${testID}-${name}` : undefined;
+}
+
+// Typed text reported once typing pauses; a clear or submit reports at once.
+function useQuery(query, onQueryChange, debounceMs) {
+  const given = typeof query === "string" ? query : "";
+  const [text, setText] = React.useState(given);
+  const reported = React.useRef(normaliseQuery(given));
+  // Reported queries the widget has not handed back yet, oldest first.
+  const unechoed = React.useRef([]);
+  const report = React.useRef(null);
+  report.current = (next) => {
+    if (next === reported.current) return;
+    reported.current = next;
+    unechoed.current = [...unechoed.current.slice(1 - MAX_UNECHOED), next];
+    if (typeof onQueryChange === "function") onQueryChange(next);
+  };
+  const delay = React.useRef(debounceMs);
+  delay.current = debounceMs;
+  const debouncer = React.useRef(null);
+  if (debouncer.current === null) {
+    debouncer.current = createDebouncer(() => delay.current, (next) => report.current(next));
+  }
+  React.useEffect(() => () => debouncer.current.cancel(), []);
+  // A query set from outside (a route param, a reset) replaces the typed text;
+  // a late hand-back of one this bar reported must not undo newer typing.
+  React.useEffect(() => {
+    const next = normaliseQuery(given);
+    const echo = unechoed.current.indexOf(next);
+    if (echo !== -1) {
+      unechoed.current = unechoed.current.slice(echo + 1);
+      return;
+    }
+    if (next === reported.current) return;
+    debouncer.current.cancel();
+    reported.current = next;
+    setText(given);
+  }, [given]);
+
+  const now = (next) => {
+    debouncer.current.cancel();
+    report.current(normaliseQuery(next));
+  };
+  const type = (next) => {
+    setText(next);
+    if (normaliseQuery(next) === "") now(next);
+    else debouncer.current.push(next);
+  };
+  const clear = () => {
+    setText("");
+    now("");
+  };
+  return { text, type, submit: () => now(text), clear };
+}
+
+/**
+ * Bind the shared filter bar to one host's parts.
+ *
+ * @param {{View: any, SearchField: any, Select: any, Chip: any, ChipGroup: any,
+ *   Button: any, Modal: any}} rn
+ */
+export function makeFilterBar(rn) {
+  const { View, SearchField, Select, Chip, ChipGroup, Button, Modal } = rn;
+
+  function FacetSelect({ facet, value, onPick, anyText, compact, testID }) {
+    const shared = {
+      title: facet.label,
+      searchable: facet.searchable === true,
+      testID,
+      ...(compact
+        ? {
+            accessibilityLabel: facet.label,
+            placeholder: facetPlaceholder(facet, anyText),
+            containerStyle: { width: FILTER_FACET_WIDTH, flexShrink: 0 },
+          }
+        : { label: facet.label, placeholder: anyText }),
+    };
+    if (facet.multiple) {
+      return h(Select, {
+        ...shared,
+        multiple: true,
+        options: facet.options,
+        values: Array.isArray(value) ? value : [],
+        onValuesChange: (next) => onPick(next),
+      });
+    }
+    // An "Any" choice first, so a single facet can be cleared where it is set.
+    return h(Select, {
+      ...shared,
+      options: [{ value: null, label: anyText }, ...facet.options],
+      value,
+      onValueChange: (next) => onPick(next),
+    });
+  }
+
+  function SortSelect({ sort, value, onPick, compact, testID }) {
+    const label = typeof sort.label === "string" ? sort.label : "Sort";
+    return h(Select, {
+      title: label,
+      options: Array.isArray(sort.options) ? sort.options : [],
+      value,
+      onValueChange: (next) => onPick(next),
+      testID,
+      ...(compact
+        ? {
+            accessibilityLabel: label,
+            placeholder: label,
+            containerStyle: { width: FILTER_FACET_WIDTH, flexShrink: 0 },
+          }
+        : { label, placeholder: label }),
+    });
+  }
+
+  function FilterBar({
+    query,
+    onQueryChange,
+    queryDebounceMs = DEFAULT_SEARCH_DEBOUNCE_MS,
+    facets,
+    value,
+    onChange,
+    sort,
+    searchPlaceholder = "Search",
+    anyText = "Any",
+    filtersText = "Filters",
+    activeCountText = "{count} active",
+    clearAllText = "Clear all",
+    applyText = "Apply",
+    clearText = "Clear",
+    activeFiltersText = "Active filters",
+    removeText = "Remove {label}",
+    closeAccessibilityLabel,
+    style,
+    testID,
+  }) {
+    const theme = useHostTheme() || DEFAULT_THEME_TOKENS;
+    const spacing = theme.spacing || DEFAULT_THEME_TOKENS.spacing;
+    const gap = spacing.sm;
+    const [width, onLayout] = useContainerWidth();
+    const list = usableFacets(facets);
+    const filters = value && typeof value === "object" ? value : NO_FILTERS;
+    const applied = appliedFacets(list, filters);
+    const hasSearch = typeof onQueryChange === "function";
+    const hasSort = !!sort && typeof sort.onChange === "function";
+    const search = useQuery(query, onQueryChange, queryDebounceMs);
+    const layout = filterBarLayout({
+      width,
+      dropdowns: list.length + (hasSort ? 1 : 0),
+      gap,
+      search: hasSearch,
+    });
+    const narrow = layout === "sheet";
+    const [open, setOpen] = React.useState(false);
+    const [draft, setDraft] = React.useState(NO_FILTERS);
+    const [draftSort, setDraftSort] = React.useState(undefined);
+
+    const change = (next) => {
+      if (!sameFilters(next, filters) && typeof onChange === "function") onChange(next);
+    };
+    const pickSort = (next) => {
+      if (hasSort && next !== sort.value) sort.onChange(next);
+    };
+    const clearAll = () => {
+      search.clear();
+      change({});
+    };
+    const firstSort = hasSort && Array.isArray(sort.options) && sort.options[0] ? sort.options[0].value : undefined;
+    const clearSheet = () => {
+      setDraft(NO_FILTERS);
+      if (hasSort) setDraftSort(firstSort);
+    };
+    const showSheet = () => {
+      setDraft(filters);
+      setDraftSort(hasSort ? sort.value : undefined);
+      setOpen(true);
+    };
+    const apply = () => {
+      setOpen(false);
+      change(draft);
+      pickSort(draftSort);
+    };
+
+    const searchField = hasSearch
+      ? h(SearchField, {
+          key: "search",
+          value: search.text,
+          onChangeText: search.type,
+          onSubmitEditing: search.submit,
+          placeholder: searchPlaceholder,
+          testID: part(testID, "search"),
+          containerStyle: { flex: 1, minWidth: narrow ? 0 : FILTER_SEARCH_MIN_WIDTH },
+        })
+      : null;
+
+    const dropdowns = narrow
+      ? []
+      : [
+          ...list.map((facet) =>
+            h(FacetSelect, {
+              key: `facet-${facet.key}`,
+              facet,
+              value: filters[facet.key],
+              onPick: (next) => change(withFacet(filters, facet.key, next)),
+              anyText,
+              compact: true,
+              testID: part(testID, `facet-${facet.key}`),
+            }),
+          ),
+          hasSort
+            ? h(SortSelect, {
+                key: "sort",
+                sort,
+                value: sort.value,
+                onPick: pickSort,
+                compact: true,
+                testID: part(testID, "sort"),
+              })
+            : null,
+        ];
+
+    const filtersButton =
+      narrow && (list.length > 0 || hasSort)
+        ? h(Button, {
+            key: "filters",
+            title: filtersButtonText(filtersText, applied.length),
+            accessibilityLabel:
+              applied.length > 0
+                ? `${filtersText}, ${fillText(activeCountText, "count", applied.length)}`
+                : filtersText,
+            icon: "sliders-horizontal",
+            variant: "secondary",
+            onPress: showSheet,
+            "aria-haspopup": "dialog",
+            "aria-expanded": open,
+            testID: part(testID, "filters"),
+          })
+        : null;
+
+    // Chips show at every width: a narrow user drops one without the sheet.
+    const chipSize = narrow ? "md" : "sm";
+    const chips =
+      applied.length > 0
+        ? h(
+            View,
+            {
+              key: "applied",
+              style: { flexDirection: "row", flexWrap: "wrap", alignItems: "center", gap },
+            },
+            h(
+              ChipGroup,
+              { accessibilityLabel: activeFiltersText, testID: part(testID, "chips") },
+              ...applied.map((facet) => {
+                const label = chipLabel(facet, filters[facet.key]);
+                return h(Chip, {
+                  key: facet.key,
+                  label,
+                  size: chipSize,
+                  onRemove: () => change(withFacet(filters, facet.key, undefined)),
+                  removeAccessibilityLabel: fillText(removeText, "label", label),
+                  testID: part(testID, `chip-${facet.key}`),
+                });
+              }),
+            ),
+            h(Button, {
+              title: clearAllText,
+              variant: "link",
+              onPress: clearAll,
+              testID: part(testID, "clear-all"),
+            }),
+          )
+        : null;
+
+    const sheet = narrow
+      ? h(
+          Modal,
+          {
+            key: "sheet",
+            visible: open,
+            onRequestClose: () => setOpen(false),
+            presentation: "sheet",
+            title: filtersText,
+            ...(closeAccessibilityLabel ? { closeAccessibilityLabel } : null),
+            testID: part(testID, "sheet"),
+            footer: h(
+              View,
+              { style: { flexDirection: "row", justifyContent: "flex-end", gap } },
+              h(Button, {
+                title: clearText,
+                variant: "ghost",
+                onPress: clearSheet,
+                testID: part(testID, "clear"),
+              }),
+              h(Button, { title: applyText, onPress: apply, testID: part(testID, "apply") }),
+            ),
+          },
+          h(
+            View,
+            { style: { gap: spacing.md } },
+            ...list.map((facet) =>
+              h(FacetSelect, {
+                key: facet.key,
+                facet,
+                value: draft[facet.key],
+                onPick: (next) => setDraft((own) => withFacet(own, facet.key, next)),
+                anyText,
+                compact: false,
+                testID: part(testID, `sheet-facet-${facet.key}`),
+              }),
+            ),
+            hasSort
+              ? h(SortSelect, {
+                  key: "sort",
+                  sort,
+                  value: draftSort,
+                  onPick: setDraftSort,
+                  compact: false,
+                  testID: part(testID, "sheet-sort"),
+                })
+              : null,
+          ),
+        )
+      : null;
+
+    return h(
+      View,
+      { style: [{ alignSelf: "stretch" }, style], testID },
+      h(
+        View,
+        { onLayout, style: { gap } },
+        h(
+          View,
+          {
+            style: { flexDirection: "row", alignItems: "center", gap },
+            testID: part(testID, narrow ? "compact" : "row"),
+          },
+          searchField,
+          ...dropdowns,
+          filtersButton,
+        ),
+        chips,
+      ),
+      sheet,
+    );
+  }
+
+  FilterBar.displayName = "FilterBar";
+  return FilterBar;
+}

package/dist/filter-bar.js

@@ -0,0 +1,15 @@
+// `<FilterBar>` (web). Binds ./filter-bar-view.js to react-native-web and the
+// web `<SearchField>`, `<Select>`, `<Chip>`, `<Button>` and `<Modal>`; see
+// ./primitives.js for why not the bare specifier.
+
+import * as ReactNative from "react-native-web";
+import { makeFilterBar } from "./filter-bar-view.js";
+import { SearchField } from "./search-field.js";
+import { Select } from "./select.js";
+import { Chip, ChipGroup } from "./chip.js";
+import { Button } from "./button.js";
+import { Modal } from "./modal.js";
+
+const { View } = ReactNative;
+
+export const FilterBar = makeFilterBar({ View, SearchField, Select, Chip, ChipGroup, Button, Modal });

package/dist/filter-bar.native.js

@@ -0,0 +1,13 @@
+// `<FilterBar>` (native). Binds ./filter-bar-view.js to React Native's `View`
+// and the native `<SearchField>`, `<Select>`, `<Chip>`, `<Button>` and
+// `<Modal>`; only the imports differ from ./filter-bar.js.
+
+import { View } from "react-native";
+import { makeFilterBar } from "./filter-bar-view.js";
+import { SearchField } from "./search-field.native.js";
+import { Select } from "./select.native.js";
+import { Chip, ChipGroup } from "./chip.native.js";
+import { Button } from "./button.native.js";
+import { Modal } from "./modal.native.js";
+
+export const FilterBar = makeFilterBar({ View, SearchField, Select, Chip, ChipGroup, Button, Modal });

package/dist/form-control-logic.js

@@ -12,10 +12,27 @@ export function isText(value) {
   return typeof value === "string" || typeof value === "number";
 }
 
-/** The spoken name of a control: its own label, else its visible one. */
-export function spokenLabel(accessibilityLabel, label) {
+/**
+ * The spoken name of a control: its own label, else its visible one. A
+ * required control's visible label is followed by `requiredWord`, because
+ * the drawn mark is hidden from readers and a device has no `aria-required`.
+ */
+export function spokenLabel(accessibilityLabel, label, requiredWord) {
   if (isShown(accessibilityLabel)) return accessibilityLabel;
-  return isText(label) ? String(label) : undefined;
+  if (!isText(label)) return undefined;
+  return isShown(requiredWord) ? `${label}, ${requiredWord}` : String(label);
+}
+
+/**
+ * The static a form control carries when `<FormField>` should hand it its
+ * label, helper, error and `required` instead of framing it a second time.
+ */
+export const DRAWS_FIELD_FRAME = "drawsFieldFrame";
+
+/** Whether `element` is a form control that frames its own label. */
+export function drawsOwnFrame(element) {
+  const type = element && element.type;
+  return Boolean(type && (typeof type === "function" || typeof type === "object") && type[DRAWS_FIELD_FRAME]);
 }
 
 /** An `error` that carries a message (`true` only marks the control). */

package/dist/form-control-view.js

@@ -8,6 +8,13 @@ import { errorMessage, isShown, isText } from "./form-control-logic.js";
 
 const h = React.createElement;
 
+// Readers hear the required word in the control's name instead.
+const HIDDEN_FROM_READERS = {
+  "aria-hidden": true,
+  accessibilityElementsHidden: true,
+  importantForAccessibility: "no-hide-descendants",
+};
+
 /**
  * Bind the shared frame to one platform's primitives.
  *
@@ -28,6 +35,9 @@ export function makeFieldFrame(rn) {
    *   control dims itself and `disabled` would dim it twice.
    * @param {boolean} [props.alertOnError] — an error interrupts, as an alert,
    *   for one that follows an action rather than typing.
+   * @param {boolean} [props.required] — a mark after a text label.
+   * @param {string} [props.spokenRequired] — the required word the label
+   *   itself speaks, when no control's name carries it.
    */
   function FieldFrame({
     t,
@@ -39,15 +49,22 @@ export function makeFieldFrame(rn) {
     onLabelPress,
     noteDisabled,
     alertOnError,
+    required,
+    spokenRequired,
     style,
     children,
   }) {
     const message = errorMessage(error);
     const note = message || (isShown(helper) ? helper : null);
+    const marked = required === true;
     const labelText = isText(label)
       ? h(
           Text,
           {
+            // A device reads the nested mark aloud unless the name excludes it.
+            ...(marked
+              ? { accessibilityLabel: isText(spokenRequired) ? `${label}, ${spokenRequired}` : String(label) }
+              : null),
             style: {
               color: t.labelColor,
               fontFamily: t.fontFamily,
@@ -56,6 +73,7 @@ export function makeFieldFrame(rn) {
             },
           },
           label,
+          marked ? h(Text, { ...HIDDEN_FROM_READERS, style: { color: t.errorColor } }, " *") : null,
         )
       : null;
     return h(

package/dist/form-layout-logic.js

@@ -0,0 +1,92 @@
+// The `<Form>` layout rules, without a renderer: how many columns a form's
+// fields take at each width tier, how wide a form may grow, and which
+// children take a whole line. They are the rules the AI widget builder is
+// taught for a form it lays out by hand, so the two cannot disagree.
+
+import { widthTier } from "./container-width.js";
+
+/** A form wider than this is a wall of giant inputs; it centres instead. */
+export const FORM_MAX_WIDTH = 1000;
+/** More fields to a line and each is too narrow to read or tap. */
+export const MAX_FORM_COLUMNS = 3;
+export const DEFAULT_FORM_GAP = "md";
+
+function columnCeiling(columns) {
+  const n = Math.floor(Number(columns));
+  if (columns === undefined || columns === null || columns === "auto" || !Number.isFinite(n)) {
+    return MAX_FORM_COLUMNS;
+  }
+  return Math.min(MAX_FORM_COLUMNS, Math.max(1, n));
+}
+
+/**
+ * How many fields share a line: one when narrow, at most two at medium, and
+ * the ceiling (`columns`, else three) when wide.
+ *
+ * @param {"auto"|number|undefined} columns
+ * @param {number} width — the form's measured width; 0 is not yet measured.
+ */
+export function formColumns(columns, width) {
+  const ceiling = columnCeiling(columns);
+  const tier = widthTier(width);
+  if (tier === "narrow") return 1;
+  if (tier === "medium") return Math.min(2, ceiling);
+  return ceiling;
+}
+
+/**
+ * How many fields of a `<FieldRow>` share its line: all of them, up to three,
+ * except when narrow, where they stack.
+ */
+export function fieldRowColumns(count, width) {
+  if (widthTier(width) === "narrow") return 1;
+  return Math.min(MAX_FORM_COLUMNS, Math.max(1, Math.floor(count) || 1));
+}
+
+/**
+ * The form's cap: `FORM_MAX_WIDTH` by default, a positive number as given, or
+ * none for `null` (a form in a side panel or a card that sets its own measure).
+ */
+export function formMaxWidth(maxWidth) {
+  if (maxWidth === null) return undefined;
+  const n = Number(maxWidth);
+  return maxWidth !== undefined && Number.isFinite(n) && n > 0 ? n : FORM_MAX_WIDTH;
+}
+
+/** A `<FormActions>` row at medium and wide; a full-width stack when narrow. */
+export function actionsStack(width) {
+  return widthTier(width) === "narrow";
+}
+
+/**
+ * Split a form's children into the runs it draws: fields share lines in a
+ * run, and a child that takes the whole line stands alone between runs.
+ *
+ * @param {boolean[]} fullLine — per child, whether it takes the whole line.
+ * @returns {Array<{full: boolean, indices: number[]}>}
+ */
+export function formRuns(fullLine) {
+  const runs = [];
+  fullLine.forEach((full, index) => {
+    const last = runs[runs.length - 1];
+    if (!full && last && !last.full) last.indices.push(index);
+    else runs.push({ full: Boolean(full), indices: [index] });
+  });
+  return runs;
+}
+
+/**
+ * Which props `<FormField>` hands a control that frames its own label: each of
+ * its own, unless the control already sets that prop itself.
+ *
+ * @param {object} field — the FormField's `label`, `required`, `helper`, `error`.
+ * @param {object} own — the control's props.
+ */
+export function handedFieldProps(field, own) {
+  const handed = {};
+  // A prop the control sets itself, even `disabled={false}`, wins.
+  for (const key of ["label", "required", "helper", "error", "disabled", "testID"]) {
+    if (own[key] === undefined && field[key] !== undefined) handed[key] = field[key];
+  }
+  return handed;
+}