@colixsystems/widget-sdk 0.210.0 → 0.213.0

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;
 
 /**
@@ -3361,6 +3360,70 @@ export const Modal: (props: {
   children?: ReactNode;
 }) => any;
 
+export type ConfirmDialogTone = "default" | "destructive";
+
+/**
+ * The standard confirmation prompt: a preset of `<Modal>` with a message, a
+ * Cancel and a Confirm `<Button>`. Use it before a delete or any other action
+ * that cannot be undone, so every confirmation in the app looks and behaves
+ * the same. Cancelling is the safe default: the Cancel button, the close
+ * button, the backdrop, Escape (web) and the Android back button all fire
+ * `onCancel`, never `onConfirm`.
+ *
+ * It adds no theme scope: the panel follows `modal`, the actions `button`,
+ * and a destructive confirm the `destructive` scope. It never closes itself;
+ * set `visible` false from `onCancel` and once the action is done.
+ *
+ * @example
+ *   <ConfirmDialog
+ *     visible={!!pending}
+ *     tone="destructive"
+ *     title="Delete this order?"
+ *     message="This cannot be undone."
+ *     confirmLabel="Delete"
+ *     onCancel={() => setPending(null)}
+ *     onConfirm={async () => {
+ *       await remove(pending.id);
+ *       setPending(null);
+ *     }}
+ *   />
+ */
+export const ConfirmDialog: (props: {
+  /** Nothing renders (and nothing is mounted) while this is false. */
+  visible?: boolean;
+  /** The question, e.g. "Delete this order?". */
+  title: string;
+  /** What confirming does. Text is drawn in the theme's body style. */
+  message?: ReactNode;
+  /** Defaults to the app's translated "Confirm". Name the action instead. */
+  confirmLabel?: string;
+  /** Defaults to the app's translated "Cancel". */
+  cancelLabel?: string;
+  /**
+   * `destructive` draws the confirm button from the theme's Destructive
+   * colours and, on web, opens with focus on Cancel. `default` opens with
+   * focus on Confirm. Focus placement is web only.
+   */
+  tone?: ConfirmDialogTone;
+  /**
+   * The confirmed action is running: both buttons are disabled, a loading
+   * indicator shows, and the backdrop, Escape and Android back do nothing.
+   */
+  busy?: boolean;
+  /**
+   * Return the action's promise and the dialog stays busy until it settles,
+   * ignoring a second press. A rejection is not caught: handle the failure
+   * here, or it is reported as an unhandled rejection.
+   */
+  onConfirm?: () => void | Promise<unknown>;
+  /** The Cancel and close buttons, backdrop, Escape (web) and Android back. */
+  onCancel?: () => void;
+  /** Label for the close button. Defaults to the app's translated "Close". */
+  closeAccessibilityLabel?: string;
+  /** On the panel; the parts take `-message`, `-cancel`, `-confirm` and `-busy`. */
+  testID?: string;
+}) => any;
+
 /** Per-list row overrides; unset values follow Theme Settings > Lists. */
 export interface ListRowTokens {
   rowPadding?: number;
@@ -3617,22 +3680,155 @@ export const Button: (props: {
   labelStyle?: any;
   accessibilityLabel?: string;
   testID?: string;
+  /** Forwarded to the pressable, so you can focus the button. */
+  ref?: { current: any } | ((node: any) => void);
 }) => 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.
@@ -274,6 +282,8 @@ export { Spinner, Skeleton } from "./loading.js";
 export { Banner } from "./banner.js";
 // The standard dialog, on `<Overlay>`; follows the theme's `modal` scope.
 export { Modal } from "./modal.js";
+// The standard confirmation, a preset of `<Modal>` and `<Button>`.
+export { ConfirmDialog } from "./confirm-dialog.js";
 // The semantic text tiers, shared with the built-in widgets.
 export {
   textRoleStyle,

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.
@@ -267,6 +275,8 @@ export { Spinner, Skeleton } from "./loading.native.js";
 export { Banner } from "./banner.native.js";
 // The standard dialog, on `<Overlay>`; follows the theme's `modal` scope.
 export { Modal } from "./modal.native.js";
+// The standard confirmation, a preset of `<Modal>` and `<Button>`.
+export { ConfirmDialog } from "./confirm-dialog.native.js";
 // The semantic text tiers, shared with the built-in widgets.
 export {
   textRoleStyle,

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