@colixsystems/widget-sdk 0.210.0 → 0.212.0

package/dist/form-control-view.js

@@ -0,0 +1,98 @@
+// What every form control shares on screen: the label above it and the helper
+// or error below it. One frame, so `<TextField>`, `<Checkbox>`, `<Switch>`,
+// `<Select>` and `<SearchField>` cannot drift apart. Its rules, which need no
+// renderer, live in ./form-control-logic.js.
+
+import React from "react";
+import { errorMessage, isShown, isText } from "./form-control-logic.js";
+
+const h = React.createElement;
+
+/**
+ * Bind the shared frame to one platform's primitives.
+ *
+ * @param {{View: any, Text: any, Pressable: any}} rn
+ */
+export function makeFieldFrame(rn) {
+  const { View, Text, Pressable } = rn;
+
+  /**
+   * @param {object} props
+   * @param {object} props.t — resolved form-control tokens.
+   * @param {any} [props.label] — text, or an element rendered as given.
+   * @param {any} [props.helper]
+   * @param {any} [props.error] — a message replaces the helper; `true` shows none.
+   * @param {string} [props.noteId] — the id the control's `aria-describedby` names.
+   * @param {() => void} [props.onLabelPress] — a text label then acts for the control.
+   * @param {boolean} [props.noteDisabled] — dim the note alone, when the
+   *   control dims itself and `disabled` would dim it twice.
+   */
+  function FieldFrame({
+    t,
+    label,
+    helper,
+    error,
+    disabled,
+    noteId,
+    onLabelPress,
+    noteDisabled,
+    style,
+    children,
+  }) {
+    const message = errorMessage(error);
+    const note = message || (isShown(helper) ? helper : null);
+    const labelText = isText(label)
+      ? h(
+          Text,
+          {
+            style: {
+              color: t.labelColor,
+              fontFamily: t.fontFamily,
+              fontSize: t.labelSize,
+              fontWeight: "500",
+            },
+          },
+          label,
+        )
+      : null;
+    return h(
+      View,
+      { style: [{ gap: t.gap }, disabled ? { opacity: t.disabledOpacity } : null, style] },
+      labelText && typeof onLabelPress === "function"
+        ? h(
+            Pressable,
+            {
+              onPress: onLabelPress,
+              disabled,
+              // The control is the one stop for a keyboard and a reader.
+              tabIndex: -1,
+              accessible: false,
+              style: { alignSelf: "flex-start" },
+            },
+            labelText,
+          )
+        : labelText || (isShown(label) ? label : null),
+      children,
+      isText(note)
+        ? h(
+            Text,
+            {
+              nativeID: noteId,
+              // Announced where the host can: the web and Android.
+              ...(message ? { accessibilityLiveRegion: "polite" } : null),
+              style: {
+                color: message ? t.errorColor : t.helperColor,
+                fontFamily: t.fontFamily,
+                fontSize: t.helperSize,
+                ...(noteDisabled ? { opacity: t.disabledOpacity } : null),
+              },
+            },
+            note,
+          )
+        : note,
+    );
+  }
+
+  FieldFrame.displayName = "FieldFrame";
+  return FieldFrame;
+}

package/dist/index.d.ts

@@ -3167,7 +3167,6 @@ export const TextInput: any;
 export const FlatList: any;
 export const SectionList: any;
 export const ActivityIndicator: any;
-export const Switch: any;
 export const StyleSheet: any;
 
 /**
@@ -3620,19 +3619,150 @@ export const Button: (props: {
 }) => any;
 
 /**
- * Themed text-entry field (Theme Settings > Muted). Every TextInput prop works.
- *
- * @example
- *   <TextField value={name} onChangeText={setName} placeholder="Your name" accessibilityLabel="Name" />
+ * What every form control shares: the label drawn with it (and read by a
+ * screen reader), a hint below it, and an error that replaces the hint and
+ * marks the control. `error: true` marks it without a message.
  */
-export const TextField: (props: {
+export interface FormControlProps {
+  label?: ReactNode;
+  helper?: ReactNode;
+  error?: ReactNode | boolean;
+  disabled?: boolean;
+  /** Required when there is no text `label`. */
+  accessibilityLabel?: string;
+  testID?: string;
+}
+
+/** Per-control overrides of the theme's `muted` scope. */
+export interface FormFieldOverrides {
   background?: string;
   textColor?: string;
   borderColor?: string;
   radius?: number;
   height?: number;
+}
+
+/**
+ * Themed text-entry field (Design > Components > Muted). Every TextInput prop
+ * works.
+ *
+ * @example
+ *   <TextField label="Name" value={name} onChangeText={setName} placeholder="Your name" />
+ */
+export const TextField: (props: FormControlProps & FormFieldOverrides & {
   multiline?: boolean;
   style?: any;
+  /** The box around a labelled field. */
+  containerStyle?: any;
+  [prop: string]: any;
+}) => any;
+
+/**
+ * Themed tick box: the input surface, filled with the primary colour when
+ * checked. One 44px target with the checkbox role and state on both hosts.
+ *
+ * @example
+ *   <Checkbox label="Remember me" value={remember} onValueChange={setRemember} />
+ */
+export const Checkbox: (props: FormControlProps & {
+  value?: boolean;
+  onValueChange?: (next: boolean) => void;
+  /** The row. */
+  style?: any;
+  /** The box around a row that shows a helper or an error. */
+  containerStyle?: any;
+  [prop: string]: any;
+}) => any;
+
+/**
+ * Themed on/off toggle: the platform's own switch with the theme's track
+ * colours. Every React Native `Switch` prop works: a `trackColor` overrides
+ * the theme for the states it names, and the thumb is the platform's unless
+ * `thumbColor` is passed. Without a label, helper or error it renders the
+ * bare switch.
+ *
+ * @example
+ *   <Switch label="Email me updates" value={on} onValueChange={setOn} />
+ */
+export const Switch: (props: FormControlProps & {
+  value?: boolean;
+  onValueChange?: (next: boolean) => void;
+  trackColor?: { false?: string; true?: string };
+  thumbColor?: string;
+  style?: any;
+  /** The box around a labelled switch. */
+  containerStyle?: any;
+  [prop: string]: any;
+}) => any;
+
+export interface SelectOption<V extends string | number = string | number> {
+  value: V;
+  label: string;
+  disabled?: boolean;
+  testID?: string;
+}
+
+/**
+ * Themed single-choice picker. The trigger is the input field, a button that
+ * opens a dialog; its options open at screen level (through `Overlay`) in a
+ * sheet painted from the `popover` scope, so no container clips them and a
+ * long list scrolls. Each option has the option role; the list is a listbox
+ * on the web only. Other props land on the trigger.
+ *
+ * @example
+ *   <Select label="Status" value={status} onValueChange={setStatus}
+ *     options={[{ value: "open", label: "Open" }, { value: "done", label: "Done" }]} />
+ */
+export const Select: <V extends string | number = string | number>(
+  props: FormControlProps & FormFieldOverrides & {
+    options: Array<SelectOption<V>>;
+    value?: V | null;
+    onValueChange?: (value: V, option: SelectOption<V>) => void;
+    /** Shown while nothing is chosen. Default "Select". */
+    placeholder?: string;
+    /** The sheet's heading. Defaults to a text `label`. */
+    title?: string;
+    /** Shown in the sheet when `options` is empty. Default "No options". */
+    emptyText?: string;
+    closeAccessibilityLabel?: string;
+    /** The trigger. */
+    style?: any;
+    containerStyle?: any;
+    [prop: string]: any;
+  },
+) => any;
+
+/**
+ * Space-key activation for a control whose role is not a button: on the web a
+ * `Pressable` answers Space only for a button. Native ignores `onKeyDown`.
+ *
+ * @example
+ *   <Pressable accessibilityRole="radio" onPress={pick} onKeyDown={spaceActivates(pick)} />
+ */
+export function spaceActivates(
+  onPress: () => void,
+): (event: { key: string; repeat?: boolean; preventDefault: () => void }) => void;
+
+/**
+ * Themed search box: a `TextField` with a search glyph, the search key and a
+ * clear control. Every `TextField` prop works.
+ *
+ * @example
+ *   <SearchField value={query} onChangeText={setQuery} placeholder="Search orders" />
+ */
+export const SearchField: (props: FormControlProps & {
+  value?: string;
+  onChangeText?: (text: string) => void;
+  /** Called after the clear control empties the field. */
+  onClear?: () => void;
+  /** Default "Search". */
+  placeholder?: string;
+  /** Default "Clear search". */
+  clearAccessibilityLabel?: string;
+  /** The input. */
+  style?: any;
+  /** The box around it; use it for `flex: 1` in a toolbar. */
+  containerStyle?: any;
   [prop: string]: any;
 }) => any;
 

package/dist/index.js

@@ -167,7 +167,6 @@ export {
   FlatList,
   SectionList,
   ActivityIndicator,
-  Switch,
   StyleSheet,
   Linking,
   Icon,
@@ -266,6 +265,15 @@ export {
 export { TextField } from "./text-field.js";
 // Themed collapsible sections, drawn from the `card` and `list` scopes.
 export { Accordion, AccordionItem } from "./accordion.js";
+// The themed form controls; they follow the theme's `muted` scope as
+// `<TextField>` does, and `popover` for the Select's options. `<Switch>` is
+// the platform's own.
+export { Checkbox } from "./checkbox.js";
+export { Switch } from "./switch.js";
+export { Select } from "./select.js";
+export { SearchField } from "./search-field.js";
+// Space for a control whose role is not a button; a no-op on native.
+export { spaceActivates } from "./form-control-logic.js";
 // A themed tab strip; follows the theme's `tabs` scope.
 export { Tabs } from "./tabs.js";
 // Themed loading states; follow the theme's `loading` scope.

package/dist/index.native.js

@@ -160,7 +160,6 @@ export {
   FlatList,
   SectionList,
   ActivityIndicator,
-  Switch,
   StyleSheet,
   Linking,
   Icon,
@@ -259,6 +258,15 @@ export {
 export { TextField } from "./text-field.native.js";
 // Themed collapsible sections, drawn from the `card` and `list` scopes.
 export { Accordion, AccordionItem } from "./accordion.native.js";
+// The themed form controls; they follow the theme's `muted` scope as
+// `<TextField>` does, and `popover` for the Select's options. `<Switch>` is
+// the platform's own.
+export { Checkbox } from "./checkbox.native.js";
+export { Switch } from "./switch.native.js";
+export { Select } from "./select.native.js";
+export { SearchField } from "./search-field.native.js";
+// Space for a control whose role is not a button; a no-op on native.
+export { spaceActivates } from "./form-control-logic.js";
 // A themed tab strip; follows the theme's `tabs` scope.
 export { Tabs } from "./tabs.native.js";
 // Themed loading states; follow the theme's `loading` scope.

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 });