@colixsystems/widget-sdk 0.207.0 → 0.212.0

package/dist/search-field-view.js

@@ -0,0 +1,155 @@
+// The ONE implementation behind the `<SearchField>` SDK primitive. It is
+// `<TextField>` with a search glyph and a clear control, so it wears the same
+// field and takes the same props; the platform bindings (`search-field.js` /
+// `search-field.native.js`) differ only in where the primitives come from.
+
+import React from "react";
+import { useHostTheme } from "./hooks.js";
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import { Icon } from "./icon.js";
+import { resolveFormControlTokens } from "./form-control-tokens.js";
+import {
+  errorMessage,
+  hasNote,
+  isShown,
+  shareRef,
+  spokenLabel,
+} from "./form-control-logic.js";
+import { makeFieldFrame } from "./form-control-view.js";
+
+const h = React.createElement;
+const GLYPH_SIZE = 18;
+// The glyph and the clear control each own a strip this wide inside the field.
+const ADORNMENT_WIDTH = 40;
+// A real target: the web host ignores hitSlop, so size carries it.
+const CLEAR_MIN_SIZE = 36;
+
+/**
+ * Bind the shared search field to one platform's primitives.
+ *
+ * @param {{View: any, Text: any, Pressable: any, TextField: any}} rn
+ */
+export function makeSearchField(rn) {
+  const { View, Pressable, TextField } = rn;
+  const FieldFrame = makeFieldFrame(rn);
+
+  const SearchField = React.forwardRef(function SearchField(props, ref) {
+    const {
+      value,
+      onChangeText,
+      onClear,
+      placeholder = "Search",
+      clearAccessibilityLabel = "Clear search",
+      label,
+      helper,
+      error,
+      disabled = false,
+      accessibilityLabel,
+      style,
+      containerStyle,
+      testID,
+      ...rest
+    } = props;
+    const theme = useHostTheme() || DEFAULT_THEME_TOKENS;
+    const t = resolveFormControlTokens(theme);
+    const inputRef = React.useRef(null);
+    const setRef = React.useMemo(() => shareRef(ref, inputRef), [ref]);
+    const noteId = React.useId();
+    const focusInput = () => {
+      const input = inputRef.current;
+      if (input && typeof input.focus === "function") input.focus();
+    };
+    const hasText = typeof value === "string" && value.length > 0;
+    const clear = () => {
+      if (typeof onChangeText === "function") onChangeText("");
+      if (typeof onClear === "function") onClear();
+      focusInput();
+    };
+
+    return h(
+      FieldFrame,
+      {
+        t,
+        label,
+        helper,
+        error: errorMessage(error),
+        disabled,
+        noteId,
+        onLabelPress: focusInput,
+        style: containerStyle,
+      },
+      h(
+        View,
+        { style: { justifyContent: "center" } },
+        h(TextField, {
+          ref: setRef,
+          value,
+          onChangeText,
+          placeholder,
+          // The frame dims the whole control, glyph included.
+          ...(disabled ? { editable: false, "aria-disabled": true } : null),
+          error: isShown(error),
+          ...(hasNote({ helper, error }) ? { "aria-describedby": noteId } : null),
+          // `role` names it on the web; `accessibilityRole` on a device.
+          role: "searchbox",
+          accessibilityRole: "search",
+          accessibilityLabel: spokenLabel(accessibilityLabel, label) || placeholder,
+          enterKeyHint: "search",
+          autoCapitalize: "none",
+          autoCorrect: false,
+          testID,
+          ...rest,
+          style: [
+            { paddingLeft: ADORNMENT_WIDTH },
+            hasText && !disabled ? { paddingRight: ADORNMENT_WIDTH } : null,
+            style,
+          ],
+        }),
+        h(
+          View,
+          {
+            style: {
+              position: "absolute",
+              left: 0,
+              top: 0,
+              bottom: 0,
+              width: ADORNMENT_WIDTH,
+              alignItems: "center",
+              justifyContent: "center",
+              pointerEvents: "none",
+            },
+          },
+          h(Icon, { name: "search", size: GLYPH_SIZE, color: t.placeholderColor }),
+        ),
+        hasText && !disabled
+          ? h(
+              Pressable,
+              {
+                onPress: clear,
+                accessibilityRole: "button",
+                accessibilityLabel: clearAccessibilityLabel,
+                testID: testID ? `${testID}-clear` : undefined,
+                style: ({ pressed }) => [
+                  {
+                    position: "absolute",
+                    right: 2,
+                    top: 0,
+                    bottom: 0,
+                    minWidth: CLEAR_MIN_SIZE,
+                    minHeight: CLEAR_MIN_SIZE,
+                    alignItems: "center",
+                    justifyContent: "center",
+                  },
+                  pressed ? { opacity: 0.6 } : null,
+                ],
+              },
+              h(Icon, { name: "x", size: GLYPH_SIZE, color: t.placeholderColor }),
+            )
+          : null,
+      ),
+    );
+  });
+
+  SearchField.displayName = "SearchField";
+  return SearchField;
+}

package/dist/search-field.js

@@ -0,0 +1,13 @@
+// `<SearchField>` (web). Binds ./search-field-view.js to react-native-web and
+// the web `<TextField>`; see ./primitives.js for why not the bare specifier.
+
+import * as ReactNative from "react-native-web";
+import { makeSearchField } from "./search-field-view.js";
+import { TextField } from "./text-field.js";
+
+export const SearchField = makeSearchField({
+  View: ReactNative.View,
+  Text: ReactNative.Text,
+  Pressable: ReactNative.Pressable,
+  TextField,
+});

package/dist/search-field.native.js

@@ -0,0 +1,9 @@
+// `<SearchField>` (native). Binds ./search-field-view.js to React Native's own
+// primitives and the native `<TextField>`; only the imports differ from
+// ./search-field.js.
+
+import { View, Text, Pressable } from "react-native";
+import { makeSearchField } from "./search-field-view.js";
+import { TextField } from "./text-field.native.js";
+
+export const SearchField = makeSearchField({ View, Text, Pressable, TextField });

package/dist/select-view.js

@@ -0,0 +1,312 @@
+// The ONE implementation behind the `<Select>` SDK primitive. The platform
+// bindings (`select.js` / `select.native.js`) differ only in where the
+// primitives come from, so the hosts cannot drift.
+//
+// The trigger wears the field `<TextField>` does. The options open in
+// `<Overlay>`, at screen level, so no card or scroll container the widget
+// sits in can clip them; a long list scrolls inside the sheet.
+
+import React from "react";
+import { 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";
+import {
+  CONTROL_MIN_TARGET,
+  nextOptionIndex,
+  resolveFormControlTokens,
+  selectedOption,
+} from "./form-control-tokens.js";
+import {
+  errorMessage,
+  hasNote,
+  isShown,
+  isText,
+  shareRef,
+  spaceActivates,
+  spokenLabel,
+} from "./form-control-logic.js";
+import { makeFieldFrame } from "./form-control-view.js";
+
+const h = React.createElement;
+const NAVIGATION_KEYS = ["ArrowDown", "ArrowUp", "Home", "End"];
+
+/**
+ * Bind the shared select to one platform's primitives.
+ *
+ * @param {{View: any, Text: any, Pressable: any, ScrollView: any, Platform: any, Overlay: any}} rn
+ */
+export function makeSelect(rn) {
+  const { View, Text, Pressable, ScrollView, Platform, Overlay } = rn;
+  const FieldFrame = makeFieldFrame(rn);
+
+  // Keyboard focus is a web concern: a device moves its reader's focus into
+  // the sheet by itself, and a programmatic focus there would fight it.
+  function focusNode(node) {
+    if (Platform.OS === "web" && node && typeof node.focus === "function") node.focus();
+  }
+
+  function OptionSheet({ t, options, value, title, emptyText, listId, onPick, testID }) {
+    const nodes = React.useRef([]);
+    const chosen = options.findIndex((option) => option.value === value);
+    const firstEnabled = options.findIndex((option) => !option.disabled);
+    const initial = chosen !== -1 && !options[chosen].disabled ? chosen : firstEnabled;
+    // 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);
+    const text = { fontFamily: t.fontFamily, fontSize: t.fontSize, color: t.popover.textColor };
+
+    return h(
+      View,
+      { style: { flexShrink: 1, gap: t.rowGap } },
+      isShown(title)
+        ? h(
+            Text,
+            { style: { ...text, fontWeight: "600", paddingHorizontal: t.paddingHorizontal } },
+            title,
+          )
+        : null,
+      options.length === 0
+        ? h(
+            Text,
+            { style: { ...text, color: t.helperColor, paddingHorizontal: t.paddingHorizontal } },
+            emptyText,
+          )
+        : h(
+            ScrollView,
+            {
+              style: { flexShrink: 1 },
+              nativeID: listId,
+              // Web only: native has no listbox, and ignores an unknown `role`.
+              role: "listbox",
+              accessibilityLabel: isText(title) ? String(title) : undefined,
+              keyboardShouldPersistTaps: "handled",
+              testID: testID ? `${testID}-options` : undefined,
+            },
+            ...options.map((option, index) => {
+              const selected = option.value === value;
+              // The web host still delivers keys to a disabled Pressable.
+              const pick = () => {
+                if (!option.disabled) onPick(option);
+              };
+              return h(
+                Pressable,
+                {
+                  // 1 and "1" are different values.
+                  key: `${typeof option.value}:${option.value}`,
+                  ref: (node) => {
+                    nodes.current[index] = node;
+                    if (node && index === initial && pendingFocus.current) {
+                      pendingFocus.current = false;
+                      focusNode(node);
+                    }
+                  },
+                  onPress: pick,
+                  onKeyDown: (event) => {
+                    if (NAVIGATION_KEYS.includes(event.key)) {
+                      event.preventDefault();
+                      focusNode(nodes.current[nextOptionIndex(options, index, event.key)]);
+                      return;
+                    }
+                    spaceActivates(pick)(event);
+                  },
+                  disabled: option.disabled,
+                  role: "option",
+                  "aria-selected": selected,
+                  "aria-disabled": !!option.disabled,
+                  testID: option.testID,
+                  style: ({ pressed }) => [
+                    {
+                      flexDirection: "row",
+                      alignItems: "center",
+                      justifyContent: "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,
+                  ],
+                },
+                h(
+                  Text,
+                  { style: [text, { flexShrink: 1 }, selected ? { fontWeight: "600" } : null] },
+                  option.label,
+                ),
+                selected ? h(Icon, { name: "check", size: 18, color: t.accent }) : null,
+              );
+            }),
+          ),
+    );
+  }
+
+  const Select = React.forwardRef(function Select(props, ref) {
+    const {
+      value,
+      onValueChange,
+      options,
+      placeholder = "Select",
+      title,
+      emptyText = "No options",
+      label,
+      helper,
+      error,
+      disabled = false,
+      accessibilityLabel,
+      closeAccessibilityLabel,
+      style,
+      containerStyle,
+      testID,
+      onFocus,
+      onBlur,
+      ...others
+    } = props;
+    const theme = useHostTheme() || DEFAULT_THEME_TOKENS;
+    const overrides = {};
+    const rest = {};
+    for (const [key, own] of Object.entries(others)) {
+      if (TEXT_FIELD_TOKEN_NAMES.includes(key)) overrides[key] = own;
+      else rest[key] = own;
+    }
+    const t = resolveFormControlTokens(theme, overrides);
+    const [open, setOpen] = React.useState(false);
+    const [focused, setFocused] = React.useState(false);
+    const triggerRef = React.useRef(null);
+    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 invalid = isShown(error);
+    const sheetTitle = isShown(title) ? title : isText(label) ? label : undefined;
+    const name = spokenLabel(accessibilityLabel, label);
+    const shown = current ? current.label : placeholder;
+    const show = () => {
+      if (!disabled) setOpen(true);
+    };
+    const close = () => setOpen(false);
+    // The option that held focus is gone once the sheet closes. After the
+    // sheet unmounts, or its focus trap would pull focus straight back in.
+    const wasOpen = React.useRef(false);
+    React.useEffect(() => {
+      if (wasOpen.current && !open) focusNode(triggerRef.current);
+      wasOpen.current = open;
+    }, [open]);
+
+    return h(
+      FieldFrame,
+      {
+        t,
+        label,
+        helper,
+        error: errorMessage(error),
+        disabled,
+        noteId,
+        onLabelPress: () => focusNode(triggerRef.current),
+        style: containerStyle,
+      },
+      h(
+        Pressable,
+        {
+          ...rest,
+          ref: setRef,
+          onPress: show,
+          onKeyDown: (event) => {
+            if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+              event.preventDefault();
+              show();
+            }
+          },
+          onFocus: (event) => {
+            setFocused(true);
+            if (typeof onFocus === "function") onFocus(event);
+          },
+          onBlur: (event) => {
+            setFocused(false);
+            if (typeof onBlur === "function") onBlur(event);
+          },
+          disabled,
+          // A button that opens a dialog: the options are a sheet, not a popup.
+          accessibilityRole: "button",
+          "aria-haspopup": "dialog",
+          "aria-expanded": open,
+          ...(open ? { "aria-controls": listId } : null),
+          "aria-disabled": disabled,
+          ...(invalid ? { "aria-invalid": true } : null),
+          ...(hasNote({ helper, error }) ? { "aria-describedby": noteId } : null),
+          // The choice is part of the name: a button's own label replaces its text.
+          accessibilityLabel: [name, isText(shown) ? shown : null].filter(Boolean).join(", ") || undefined,
+          testID,
+          style: [
+            {
+              flexDirection: "row",
+              alignItems: "center",
+              justifyContent: "space-between",
+              gap: t.rowGap,
+              minHeight: t.height,
+              paddingHorizontal: t.paddingHorizontal,
+              paddingVertical: t.paddingVertical,
+              borderWidth: 1,
+              borderColor: t.borderColor,
+              borderRadius: t.radius,
+              backgroundColor: t.background,
+            },
+            focused ? { borderColor: t.focusColor } : null,
+            invalid ? { borderColor: t.errorColor } : null,
+            style,
+          ],
+        },
+        h(
+          Text,
+          {
+            numberOfLines: 1,
+            style: {
+              flexShrink: 1,
+              color: current ? t.textColor : t.placeholderColor,
+              fontFamily: t.fontFamily,
+              fontSize: t.fontSize,
+            },
+          },
+          shown,
+        ),
+        h(Icon, { name: "chevron-down", size: 18, color: t.placeholderColor }),
+      ),
+      h(
+        Overlay,
+        {
+          visible: open,
+          onRequestClose: close,
+          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,
+          },
+        },
+        h(OptionSheet, {
+          t,
+          options: list,
+          value,
+          title: sheetTitle,
+          emptyText,
+          listId,
+          testID,
+          onPick: (option) => {
+            close();
+            if (option.value !== value && typeof onValueChange === "function") {
+              onValueChange(option.value, option);
+            }
+          },
+        }),
+      ),
+    );
+  });
+
+  Select.displayName = "Select";
+  return Select;
+}

package/dist/select.js

@@ -0,0 +1,15 @@
+// `<Select>` (web). Binds ./select-view.js to react-native-web and the web
+// `<Overlay>`; 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";
+
+export const Select = makeSelect({
+  View: ReactNative.View,
+  Text: ReactNative.Text,
+  Pressable: ReactNative.Pressable,
+  ScrollView: ReactNative.ScrollView,
+  Platform: ReactNative.Platform,
+  Overlay,
+});

package/dist/select.native.js

@@ -0,0 +1,9 @@
+// `<Select>` (native). Binds ./select-view.js to React Native's own
+// primitives and the native `<Overlay>`; 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";
+
+export const Select = makeSelect({ View, Text, Pressable, ScrollView, Platform, Overlay });

package/dist/surface-theme.js

@@ -0,0 +1,108 @@
+// REQ-THEME-SURFACE: the theme a painted surface hands its subtree. Lives in
+// the SDK so the web Player's containers and `<Modal>` on both hosts re-ink
+// from one implementation.
+
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import {
+  INK_CONTRAST,
+  deriveSurfaceTokens,
+  inkForBackdrop,
+  isHexColor,
+} from "./contract.js";
+
+/**
+ * REQ-THEME-SURFACE: the token overrides a container's CHILDREN inherit.
+ *
+ * A container that paints its own `backgroundColor` becomes the surface its
+ * subtree sits on, so an unset text colour there must read against THAT fill
+ * rather than the page's. Without this, the only way to keep a heading legible
+ * inside a dark card was to write a literal hex onto the node — which is what
+ * froze a built app's appearance against its own theme.
+ *
+ * Returns the SAME reference when nothing changes, so an untouched page
+ * allocates nothing and every child sees the identical context value.
+ *
+ * A photo-backed container is deliberately NOT handled here: no colour can be
+ * derived from an image, so its subtree keeps what it inherited and the scrim
+ * plus an explicit light text colour carries the hero.
+ *
+ * The web Player calls this; the export's generated layout renderer mirrors
+ * it — the two hosts must not differ here (CLAUDE.md §8).
+ */
+export function surfaceAwareTheme(tenantTheme, backgroundColor) {
+  const surfaceTokens = deriveSurfaceTokens(backgroundColor);
+  if (!surfaceTokens) return tenantTheme;
+  const t = tenantTheme && typeof tenantTheme === "object" ? tenantTheme : {};
+  const typography = t.typography || null;
+  // The look's UNTOUCHED ink, carried forward so nesting stays idempotent. A
+  // band re-inks to the platform's light ink; a white card inside it must be
+  // judged against the LOOK's ink, or it can only ever land back on the
+  // platform default and the look's voice is lost one level in.
+  const base =
+    (typography && (typography.rolesBase || typography.roles)) || null;
+  // `base` when nothing needs replacing, which is what RESTORES the look's ink
+  // on a card nested inside an already-re-inked band. Falling through to the
+  // inherited `roles` there would leave the band's platform ink in place and
+  // the look could never come back.
+  const nextRoles = rolesOnSurface(base, surfaceTokens, backgroundColor) || base;
+  // sc-9346: buttons judge this fill against the surface the look was
+  // designed for, taken once at the outermost section and kept on nesting.
+  const colors = t.colors || {};
+  const backdropBase =
+    colors.backdropBase || colors.surface || DEFAULT_THEME_TOKENS.colors.surface;
+  const next = {
+    ...t,
+    colors: { ...colors, ...surfaceTokens, backdrop: backgroundColor, backdropBase },
+  };
+  if (typography && nextRoles && nextRoles !== typography.roles) {
+    next.typography = { ...typography, roles: nextRoles, rolesBase: base };
+  }
+  return next;
+}
+
+/**
+ * sc-8370: re-ink the type tiers for a surface their own ink cannot be read on.
+ *
+ * `roleColor` returns a tier's explicit hex before it ever consults the surface
+ * token, so patching `colors` alone cannot move text that carries one — and
+ * since sc-8131 every look states an ink for all six tiers, chosen against that
+ * colourway's PAGE background. A section painting its own fill is a different
+ * surface, and nothing re-derived the ink for it: a headline shipped dark on a
+ * dark opener band.
+ *
+ * The gate is MEASURED CONTRAST, not a light/dark polarity test. Polarity is
+ * the tempting rule and it is wrong in both directions. The platform's own
+ * predicate flips at luminance 0.55, while the real break-even between the two
+ * inks sits near 0.20 — so every mid-tone fill in that band reads as "wants
+ * light text" when dark text is in fact the stronger choice. On `#a8a29e`, a
+ * shipped preset secondary, a polarity rule swaps a look's ink at 7.0:1 for
+ * the platform's at 2.4:1: it would have turned a passing section into an AA
+ * failure, which is the very defect this function exists to remove.
+ *
+ * So a tier is left alone whenever it is already READABLE, which is what keeps
+ * a look's voice everywhere it works, and is replaced only where it is not AND
+ * the derived token is genuinely better. A wash with no good answer — a
+ * white-to-black band, whose midpoint favours neither ink — therefore keeps
+ * what it inherited instead of committing to a colour that is wrong for half
+ * the band.
+ *
+ * Returns null when nothing moves, so the caller leaves `typography` untouched
+ * and an unaffected page keeps its identical context value.
+ */
+function rolesOnSurface(roles, surfaceTokens, backgroundColor) {
+  let out = null;
+  for (const [role, seed] of Object.entries(
+    DEFAULT_THEME_TOKENS.typography.roles,
+  )) {
+    const current = roles && roles[role] && roles[role].color;
+    // A tier with no frozen ink already resolves through `colors` per render.
+    if (!isHexColor(current)) continue;
+    const derived = surfaceTokens[seed.colorToken];
+    // The quiet tiers are body-sized too, so they get no softer bar.
+    const ink = inkForBackdrop(current, derived, backgroundColor, INK_CONTRAST.text);
+    if (ink === current) continue;
+    if (!out) out = { ...roles };
+    out[role] = { ...roles[role], color: derived };
+  }
+  return out;
+}