@colixsystems/widget-sdk 0.210.0 → 0.212.0

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/switch-view.js

@@ -0,0 +1,149 @@
+// The ONE implementation behind the `<Switch>` SDK primitive. The platform
+// bindings (`switch.js` / `switch.native.js`) differ only in where the
+// primitives come from, so the hosts cannot drift.
+//
+// It is the platform's own switch, so it keeps the role, state, keys and
+// disabled look each host gives it; this view adds the theme's track colours,
+// a label, a helper and an error.
+
+import React from "react";
+import { useHostTheme } from "./hooks.js";
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import {
+  CONTROL_MIN_TARGET,
+  focusHaloStyle,
+  resolveFormControlTokens,
+  resolveSwitchColors,
+} from "./form-control-tokens.js";
+import {
+  errorMessage,
+  hasNote,
+  isShown,
+  isText,
+  needsFrame,
+  spokenLabel,
+} from "./form-control-logic.js";
+import { makeFieldFrame } from "./form-control-view.js";
+
+const h = React.createElement;
+const TRACK_RADIUS = 16;
+
+/**
+ * Bind the shared switch to one platform's primitives.
+ *
+ * @param {{View: any, Text: any, Pressable: any, Switch: any}} rn
+ */
+export function makeSwitch(rn) {
+  const { View, Text, Pressable, Switch: PlatformSwitch } = rn;
+  const FieldFrame = makeFieldFrame(rn);
+
+  const Switch = React.forwardRef(function Switch(props, ref) {
+    const {
+      value = false,
+      onValueChange,
+      label,
+      helper,
+      error,
+      disabled = false,
+      accessibilityLabel,
+      trackColor,
+      ios_backgroundColor: iosBackgroundColor,
+      containerStyle,
+      ...rest
+    } = props;
+    const theme = useHostTheme() || DEFAULT_THEME_TOKENS;
+    const t = resolveFormControlTokens(theme);
+    const [focused, setFocused] = React.useState(false);
+    const noteId = React.useId();
+    const on = Boolean(value);
+    const invalid = isShown(error);
+    const noted = hasNote({ helper, error });
+    const colors = resolveSwitchColors(t, { trackColor, iosBackgroundColor, invalid });
+
+    // The thumb is left to the platform unless the caller colours it.
+    const control = h(PlatformSwitch, {
+      ...rest,
+      ref,
+      value: on,
+      onValueChange,
+      disabled,
+      trackColor: colors.trackColor,
+      ios_backgroundColor: colors.iosBackgroundColor,
+      accessibilityLabel: spokenLabel(accessibilityLabel, label),
+      ...(invalid ? { "aria-invalid": true } : null),
+      ...(noted ? { "aria-describedby": noteId } : null),
+    });
+    if (!needsFrame({ label, helper, error })) return control;
+
+    const toggle = () => {
+      if (!disabled && typeof onValueChange === "function") onValueChange(!on);
+    };
+    const row = h(
+      View,
+      {
+        style: {
+          flexDirection: "row",
+          alignItems: "center",
+          justifyContent: "space-between",
+          gap: t.rowGap,
+          minHeight: CONTROL_MIN_TARGET,
+        },
+      },
+      isShown(label)
+        ? h(
+            Pressable,
+            {
+              onPress: toggle,
+              disabled,
+              // The switch itself is the one stop for a keyboard and a reader.
+              tabIndex: -1,
+              accessible: false,
+              style: [
+                { flexShrink: 1, minHeight: CONTROL_MIN_TARGET, justifyContent: "center" },
+                // The control dims itself on each host; only the label is ours.
+                disabled ? { opacity: t.disabledOpacity } : null,
+              ],
+            },
+            isText(label)
+              ? h(
+                  Text,
+                  {
+                    style: {
+                      color: t.labelColor,
+                      fontFamily: t.fontFamily,
+                      fontSize: t.fontSize,
+                    },
+                  },
+                  label,
+                )
+              : label,
+          )
+        : null,
+      h(
+        View,
+        {
+          // Focus events bubble from the control on the web host.
+          onFocus: () => setFocused(true),
+          onBlur: () => setFocused(false),
+          style: focusHaloStyle(t, focused, TRACK_RADIUS),
+        },
+        control,
+      ),
+    );
+    return h(
+      FieldFrame,
+      {
+        t,
+        helper,
+        error: errorMessage(error),
+        noteId,
+        noteDisabled: disabled,
+        style: containerStyle,
+      },
+      row,
+    );
+  });
+
+  Switch.displayName = "Switch";
+  return Switch;
+}

package/dist/switch.js

@@ -0,0 +1,80 @@
+// `<Switch>` (web). Binds ./switch-view.js to react-native-web; see
+// ./primitives.js for why not the bare specifier.
+//
+// This host's switch differs from a device's in ways the shared view cannot
+// see, so they are bridged here and nowhere else:
+//  - it takes `activeTrackColor` and a STRING `trackColor` (the off colour),
+//    and ignores both once it is handed the `{ false, true }` object;
+//  - it colours an "on" thumb from `activeThumbColor`, not `thumbColor`;
+//  - it stops greying a disabled switch once it is given any track colour;
+//  - it forwards only a label to its `<input>`, dropping the other ARIA props.
+
+import React from "react";
+import * as ReactNative from "react-native-web";
+import { makeSwitch } from "./switch-view.js";
+import { DISABLED_OPACITY } from "./form-control-tokens.js";
+import { shareRef } from "./form-control-logic.js";
+
+const ON_THUMB_COLOR = "#ffffff";
+// A caller's own `style.opacity` comes later in the list and wins.
+const DIMMED = { opacity: DISABLED_OPACITY };
+
+function isSet(value) {
+  return value !== undefined && value !== null;
+}
+
+/** The caller's colours in the object form the shared view merges. */
+export function webTrackColor(trackColor, activeTrackColor) {
+  if (trackColor && typeof trackColor === "object") return trackColor;
+  const own = {};
+  if (typeof trackColor === "string") own.false = trackColor;
+  if (isSet(activeTrackColor)) own.true = activeTrackColor;
+  return Object.keys(own).length > 0 ? own : undefined;
+}
+
+const INPUT_ARIA = ["aria-describedby", "aria-invalid"];
+
+const PlatformSwitch = React.forwardRef(function PlatformSwitch(props, ref) {
+  const { "aria-describedby": describedBy, "aria-invalid": invalid, ...rest } = props;
+  const inputRef = React.useRef(null);
+  const setRef = React.useMemo(() => shareRef(ref, inputRef), [ref]);
+  React.useEffect(() => {
+    const input = inputRef.current;
+    if (!input || typeof input.setAttribute !== "function") return;
+    const values = { "aria-describedby": describedBy, "aria-invalid": invalid ? "true" : null };
+    for (const name of INPUT_ARIA) {
+      if (isSet(values[name])) input.setAttribute(name, values[name]);
+      else input.removeAttribute(name);
+    }
+  }, [describedBy, invalid]);
+  return React.createElement(ReactNative.Switch, {
+    activeThumbColor: rest.thumbColor ?? ON_THUMB_COLOR,
+    ...rest,
+    ref: setRef,
+  });
+});
+
+const ThemedSwitch = makeSwitch({
+  View: ReactNative.View,
+  Text: ReactNative.Text,
+  Pressable: ReactNative.Pressable,
+  Switch: PlatformSwitch,
+});
+
+export const Switch = React.forwardRef(function Switch(props, ref) {
+  const { trackColor, activeTrackColor, style, ...rest } = props;
+  const ownColours =
+    isSet(trackColor) ||
+    isSet(activeTrackColor) ||
+    isSet(rest.thumbColor) ||
+    isSet(rest.activeThumbColor);
+  return React.createElement(ThemedSwitch, {
+    ...rest,
+    ref,
+    trackColor: webTrackColor(trackColor, activeTrackColor),
+    // Only a switch that left its colours to us lost the host's grey look.
+    style: rest.disabled && !ownColours ? [DIMMED, style] : style,
+  });
+});
+
+Switch.displayName = "Switch";

package/dist/switch.native.js

@@ -0,0 +1,7 @@
+// `<Switch>` (native). Binds ./switch-view.js to React Native's own
+// primitives; only the import differs from ./switch.js.
+
+import { View, Text, Pressable, Switch as PlatformSwitch } from "react-native";
+import { makeSwitch } from "./switch-view.js";
+
+export const Switch = makeSwitch({ View, Text, Pressable, Switch: PlatformSwitch });

package/dist/text-field-view.js

@@ -1,14 +1,21 @@
 // The ONE text-entry field, behind the `<TextField>` SDK primitive and the
-// built-in form fields. The bindings differ only in where `TextInput` comes
+// built-in form fields. The bindings differ only in where the primitives come
 // from, so the hosts cannot drift.
 
 import React from "react";
 import { useHostTheme } from "./hooks.js";
 import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import { TEXT_FIELD_TOKEN_NAMES } from "./text-field-tokens.js";
+import { resolveFormControlTokens } from "./form-control-tokens.js";
 import {
-  resolveTextFieldTokens,
-  TEXT_FIELD_TOKEN_NAMES,
-} from "./text-field-tokens.js";
+  errorMessage,
+  hasNote,
+  isShown,
+  needsFrame,
+  shareRef,
+  spokenLabel,
+} from "./form-control-logic.js";
+import { makeFieldFrame } from "./form-control-view.js";
 
 // A paragraph field grows to a ceiling, then scrolls inside itself.
 const MULTILINE = { minHeight: 88, maxHeight: 220, textAlignVertical: "top" };
@@ -16,10 +23,11 @@ const MULTILINE = { minHeight: 88, maxHeight: 220, textAlignVertical: "top" };
 /**
  * Bind the shared field to one platform's primitives.
  *
- * @param {{TextInput: any}} rn
+ * @param {{TextInput: any, View: any, Text: any, Pressable: any}} rn
  */
 export function makeTextField(rn) {
   const { TextInput } = rn;
+  const FieldFrame = makeFieldFrame(rn);
 
   const TextField = React.forwardRef(function TextField(props, ref) {
     const {
@@ -28,6 +36,12 @@ export function makeTextField(rn) {
       placeholderTextColor,
       onFocus,
       onBlur,
+      label,
+      helper,
+      error,
+      disabled = false,
+      containerStyle,
+      accessibilityLabel,
       ...others
     } = props;
     const theme = useHostTheme() || DEFAULT_THEME_TOKENS;
@@ -39,11 +53,21 @@ export function makeTextField(rn) {
       if (TEXT_FIELD_TOKEN_NAMES.includes(key)) overrides[key] = value;
       else rest[key] = value;
     }
-    const t = resolveTextFieldTokens(theme, overrides);
-    return React.createElement(TextInput, {
-      ref,
+    const t = resolveFormControlTokens(theme, overrides);
+    const invalid = isShown(error);
+    const framed = needsFrame({ label, helper, error });
+    const inputRef = React.useRef(null);
+    // Stable, so the host does not detach and re-attach the node every render.
+    const setRef = React.useMemo(() => shareRef(ref, inputRef), [ref]);
+    const noteId = React.useId();
+    const input = React.createElement(TextInput, {
+      ref: setRef,
       multiline,
       placeholderTextColor: placeholderTextColor || t.placeholderColor,
+      accessibilityLabel: spokenLabel(accessibilityLabel, label),
+      ...(disabled ? { editable: false, "aria-disabled": true } : null),
+      ...(invalid ? { "aria-invalid": true } : null),
+      ...(hasNote({ helper, error }) ? { "aria-describedby": noteId } : null),
       style: [
         {
           borderWidth: 1,
@@ -58,6 +82,10 @@ export function makeTextField(rn) {
           fontSize: t.fontSize,
         },
         focused ? { borderColor: t.focusColor } : null,
+        // After focus: an invalid field stays marked while it is being fixed.
+        invalid ? { borderColor: t.errorColor } : null,
+        // The frame dims a framed field as a whole.
+        disabled && !framed ? { opacity: t.disabledOpacity } : null,
         style,
         // After the caller's style: a paragraph field keeps its 88px floor.
         multiline ? MULTILINE : null,
@@ -72,6 +100,24 @@ export function makeTextField(rn) {
       },
       ...rest,
     });
+    if (!framed) return input;
+    return React.createElement(
+      FieldFrame,
+      {
+        t,
+        label,
+        helper,
+        error: errorMessage(error),
+        disabled,
+        noteId,
+        onLabelPress: () => {
+          const node = inputRef.current;
+          if (node && typeof node.focus === "function") node.focus();
+        },
+        style: containerStyle,
+      },
+      input,
+    );
   });
 
   TextField.displayName = "TextField";

package/dist/text-field.js

@@ -5,4 +5,9 @@ import * as ReactNative from "react-native-web";
 import { makeTextField } from "./text-field-view.js";
 import { TextInput } from "./primitives.js";
 
-export const TextField = makeTextField({ ...ReactNative, TextInput });
+export const TextField = makeTextField({
+  TextInput,
+  View: ReactNative.View,
+  Text: ReactNative.Text,
+  Pressable: ReactNative.Pressable,
+});