@colixsystems/widget-sdk 0.207.0 → 0.212.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;
 
 /**
@@ -3257,13 +3256,107 @@ export const Overlay: (props: {
   onRequestClose?: () => void;
   /** Panel width tier. `full` runs edge to edge. Defaults to `md`. */
   size?: "sm" | "md" | "lg" | "full";
+  /** Centred (`dialog`, the default) or anchored to the bottom edge (`sheet`). */
+  presentation?: OverlayPresentation;
   /** Set false when only an explicit control may close the overlay. */
   dismissOnBackdropPress?: boolean;
+  /**
+   * Set false when the content has its own close control: the backdrop stays
+   * pressable but leaves the tab order and the accessibility tree.
+   */
+  backdropAccessible?: boolean;
+  /** The web dialog node's role. Defaults to "dialog". No native equivalent. */
+  role?: "dialog" | "alertdialog";
+  /**
+   * Names the dialog: on the web the node that carries the role, in the
+   * exported app the panel (React Native's Modal carries no name).
+   */
   accessibilityLabel?: string;
+  /** The id of the element that names the dialog; wins over the label. Web only. */
+  accessibilityLabelledBy?: string;
   /** Label for the backdrop's dismiss target. Defaults to "Close". */
   closeAccessibilityLabel?: string;
+  /** Focused on open instead of the dialog itself. Web only; a no-op on native. */
+  initialFocusRef?: { current: any };
   /** Extra styles merged onto the themed panel. */
   style?: any;
+  /** Set on the panel. */
+  testID?: string;
+  children?: ReactNode;
+}) => any;
+
+export type OverlayPresentation = "dialog" | "sheet";
+
+/**
+ * The standard dialog, built on `<Overlay>`: a title, a close button, a body
+ * that scrolls when it is long, and a footer action row laid out below it.
+ * Its background, corner radius, padding, scrim, shadow and title colour come
+ * from the theme's `modal` scope (Design > Components > Dialogs), so every dialog in
+ * the app matches. Use it instead of hand-building a header and an action row
+ * inside a bare `<Overlay>`.
+ *
+ * A dialog that paints its own background hands what is rendered inside it a
+ * theme re-inked for that background, so SDK components and any component
+ * calling `useTheme()` inside the Modal stay readable.
+ *
+ * In the exported app the dialog pads a `sheet` by the bottom safe-area inset
+ * and a `full` dialog by the top and bottom ones, and wraps its panel in React
+ * Native's `KeyboardAvoidingView`. This is not yet verified on a device, and
+ * `KeyboardAvoidingView` inside a React Native `Modal` window is a known risk
+ * on Android: until it is verified, keep a form with text inputs in the
+ * default `dialog` presentation. A bare `<Overlay>` gets neither.
+ *
+ * @example
+ *   <Modal
+ *     visible={open}
+ *     onRequestClose={() => setOpen(false)}
+ *     title="Edit order"
+ *     footer={
+ *       <>
+ *         <Button variant="secondary" title="Cancel" onPress={() => setOpen(false)} />
+ *         <Button title="Save" onPress={save} />
+ *       </>
+ *     }
+ *   >
+ *     <TextField value={note} onChangeText={setNote} placeholder="Note" />
+ *   </Modal>
+ */
+export const Modal: (props: {
+  /** Nothing renders (and nothing is mounted) while this is false. */
+  visible?: boolean;
+  /**
+   * The close button, backdrop press, Escape (web) and Android back fire this.
+   * Omitted, no close button is drawn and only your own controls close it.
+   */
+  onRequestClose?: () => void;
+  /**
+   * Defaults to true. False while the dialog must stay open (a save in
+   * flight): no close button, and the backdrop, Escape and Android back do
+   * not fire `onRequestClose`. Only while that work runs, and always restore
+   * it: with no footer button or in-body control, nobody can close the dialog.
+   */
+  dismissible?: boolean;
+  /** With no title and no close button the dialog has no header row. */
+  title?: string;
+  /** The action buttons: one right-aligned row that wraps. Omit for no footer. */
+  footer?: ReactNode;
+  /** Centred (`dialog`, the default) or anchored to the bottom edge (`sheet`). */
+  presentation?: OverlayPresentation;
+  /** Panel width tier. `full` runs edge to edge. Defaults to `md`. */
+  size?: "sm" | "md" | "lg" | "full";
+  /** Set false when only the close button or a footer action may close it. */
+  dismissOnBackdropPress?: boolean;
+  /** Defaults to "dialog". Web only; native has no equivalent. */
+  role?: "dialog" | "alertdialog";
+  /** Focused on open instead of the dialog itself. Web only; a no-op on native. */
+  initialFocusRef?: { current: any };
+  /** Label for the close button. Defaults to "Close". */
+  closeAccessibilityLabel?: string;
+  /** Names a dialog that has no title; the title names it otherwise. */
+  accessibilityLabel?: string;
+  /** On the panel; the parts take `-close`, `-body` and `-footer`. */
+  testID?: string;
+  /** The body. It scrolls on its own: do not wrap it in a ScrollView. */
   children?: ReactNode;
 }) => any;
 
@@ -3526,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,12 +265,23 @@ 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.
 export { Spinner, Skeleton } from "./loading.js";
 // A themed inline message; follows the theme's `alert` scope.
 export { Banner } from "./banner.js";
+// The standard dialog, on `<Overlay>`; follows the theme's `modal` scope.
+export { Modal } from "./modal.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,12 +258,23 @@ 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.
 export { Spinner, Skeleton } from "./loading.native.js";
 // A themed inline message; follows the theme's `alert` scope.
 export { Banner } from "./banner.native.js";
+// The standard dialog, on `<Overlay>`; follows the theme's `modal` scope.
+export { Modal } from "./modal.native.js";
 // The semantic text tiers, shared with the built-in widgets.
 export {
   textRoleStyle,

package/dist/markdown-input-view.js

@@ -34,9 +34,9 @@ const TOOLS = Object.freeze([
   },
 ]);
 
-export function makeMarkdownInput(rn, RichText, Overlay) {
+export function makeMarkdownInput(rn, RichText, Modal, Button) {
   const { Text, View, Pressable, TextInput } = rn;
-  const MarkdownLinkDialog = makeMarkdownLinkDialog(rn, Overlay);
+  const MarkdownLinkDialog = makeMarkdownLinkDialog(rn, Modal, Button);
 
   function MarkdownInput({
     value,
@@ -210,7 +210,6 @@ export function makeMarkdownInput(rn, RichText, Overlay) {
         visible: linkOpen,
         onClose: () => setLinkOpen(false),
         onSubmit: insertLink,
-        tokens,
         pages,
         initialLabel: selected,
         testID,

package/dist/markdown-input.js

@@ -5,11 +5,13 @@
 import * as ReactNative from "react-native-web";
 import { makeMarkdownInput } from "./markdown-input-view.js";
 import { RichText } from "./richtext.js";
-import { Overlay } from "./overlay.js";
+import { Modal } from "./modal.js";
+import { Button } from "./button.js";
 import { TextInput } from "./primitives.js";
 
 export const MarkdownInput = makeMarkdownInput(
   { ...ReactNative, TextInput },
   RichText,
-  Overlay,
+  Modal,
+  Button,
 );

package/dist/markdown-input.native.js

@@ -5,12 +5,14 @@
 import { Text, View, Pressable, TextInput, ScrollView } from "react-native";
 import { makeMarkdownInput } from "./markdown-input-view.js";
 import { RichText } from "./richtext.native.js";
-import { Overlay } from "./overlay.native.js";
+import { Modal } from "./modal.native.js";
+import { Button } from "./button.native.js";
 
 // sc-7349: ScrollView joins the set for the link form's page list, which must
 // scroll rather than grow an app's every page past the panel.
 export const MarkdownInput = makeMarkdownInput(
   { Text, View, Pressable, TextInput, ScrollView },
   RichText,
-  Overlay,
+  Modal,
+  Button,
 );

package/dist/markdown-link-dialog.js

@@ -2,20 +2,22 @@
 //
 // A link needs a TARGET, and no selection can supply one: the author has to
 // name either a page in this app or an external address. That is a form, and a
-// form belongs in an `<Overlay>` — the SDK primitive that escapes the widget's
-// own clipping box on both hosts — not in a bespoke absolutely-positioned panel
-// the layout container would crop.
+// form belongs in a `<Modal>` — the SDK's standard dialog, which escapes the
+// widget's own clipping box on both hosts — not in a bespoke absolutely-
+// positioned panel the layout container would crop.
 //
 // Split out of markdown-input-view.js so each file stays one component's worth
 // of markup. Like every view module here it is bound per host by the caller
 // (see markdown-input.js / .native.js), so the two hosts cannot drift.
 
 import React from "react";
+import { useHostTheme } from "./hooks.js";
+import { resolveRichTextTokens } from "./richtext-tokens.js";
 
 // The page list scrolls rather than growing an app's 40 pages past the panel.
 const PAGE_LIST_MAX_HEIGHT = 180;
 
-export function makeMarkdownLinkDialog(rn, Overlay) {
+export function makeMarkdownLinkDialog(rn, Modal, Button) {
   const { Text, View, Pressable, TextInput, ScrollView } = rn;
 
   function Field({ label, tokens, children }) {
@@ -38,50 +40,12 @@ export function makeMarkdownLinkDialog(rn, Overlay) {
     );
   }
 
-  /**
-   * @param {object} props
-   * @param {boolean} props.visible
-   * @param {() => void} props.onClose
-   * @param {(result: {label: string, target: string}) => void} props.onSubmit
-   * @param {object} props.tokens — resolveRichTextTokens output.
-   * @param {Array<{id: string, name: string}>} props.pages — pickable pages;
-   *   empty means this host offered none, so only the URL mode is shown.
-   * @param {string} props.initialLabel — the author's current selection.
-   * @param {string} [props.testID]
-   */
-  function MarkdownLinkDialog({
-    visible,
-    onClose,
-    onSubmit,
-    tokens,
-    pages,
-    initialLabel,
-    testID,
-  }) {
-    const pageList = Array.isArray(pages) ? pages.filter((p) => p && p.id) : [];
-    const canPickPage = pageList.length > 0;
-
-    const [label, setLabel] = React.useState("");
-    const [url, setUrl] = React.useState("");
-    const [pageId, setPageId] = React.useState("");
-    const [mode, setMode] = React.useState("url");
-
-    // Re-seed on each open: the author's selection and the mode they should
-    // land in are both properties of THIS opening, not of the component.
-    React.useEffect(() => {
-      if (!visible) return;
-      setLabel(typeof initialLabel === "string" ? initialLabel : "");
-      setUrl("");
-      setPageId("");
-      setMode(canPickPage ? "page" : "url");
-    }, [visible, initialLabel, canPickPage]);
-
-    const target = mode === "page" ? pageId : url.trim();
-
-    const submit = () => {
-      if (!target) return;
-      if (typeof onSubmit === "function") onSubmit({ label, target });
-    };
+  // The form is its own component so its tokens resolve INSIDE the dialog: a
+  // dialog with its own background re-inks the theme its body reads.
+  function LinkForm({ form, pageList, canPickPage, testID }) {
+    const { label, setLabel, url, setUrl, pageId, setPageId, mode, setMode } = form;
+    const theme = useHostTheme();
+    const tokens = React.useMemo(() => resolveRichTextTokens(theme), [theme]);
 
     const inputStyle = {
       fontFamily: tokens.bodyFont,
@@ -130,49 +94,9 @@ export function makeMarkdownLinkDialog(rn, Overlay) {
         ),
       );
 
-    const action = (key, text, { primary, disabled, onPress }) =>
-      React.createElement(
-        Pressable,
-        {
-          key,
-          onPress,
-          disabled,
-          accessibilityRole: "button",
-          testID: testID ? `${testID}-${key}` : undefined,
-          style: {
-            paddingVertical: tokens.markerGap,
-            paddingHorizontal: tokens.padding,
-            marginLeft: tokens.markerGap,
-            borderWidth: 1,
-            borderColor: primary ? tokens.accent : tokens.border,
-            borderRadius: tokens.radius,
-            opacity: disabled ? 0.5 : 1,
-            ...(primary ? { backgroundColor: tokens.accent } : null),
-          },
-        },
-        React.createElement(
-          Text,
-          {
-            style: {
-              fontFamily: tokens.bodyFont,
-              fontSize: tokens.codeSize,
-              fontWeight: "500",
-              color: primary ? tokens.onAccent : tokens.color,
-            },
-          },
-          text,
-        ),
-      );
-
     return React.createElement(
-      Overlay,
-      {
-        visible: !!visible,
-        onRequestClose: onClose,
-        size: "sm",
-        accessibilityLabel: "Insert link",
-        testID: testID ? `${testID}-dialog` : undefined,
-      },
+      React.Fragment,
+      null,
       React.createElement(
         Field,
         { label: "Link text", tokens },
@@ -209,6 +133,8 @@ export function makeMarkdownLinkDialog(rn, Overlay) {
               ScrollView,
               {
                 accessibilityRole: "radiogroup",
+                // Inside the dialog's scrolling body; Android needs the opt-in.
+                nestedScrollEnabled: true,
                 style: {
                   maxHeight: PAGE_LIST_MAX_HEIGHT,
                   borderWidth: 1,
@@ -264,25 +190,85 @@ export function makeMarkdownLinkDialog(rn, Overlay) {
               testID: testID ? `${testID}-url` : undefined,
             }),
           ),
+    );
+  }
 
-      React.createElement(
-        View,
-        {
-          style: {
-            flexDirection: "row",
-            justifyContent: "flex-end",
-            marginTop: tokens.markerGap,
-          },
-        },
-        action("cancel", "Cancel", { onPress: onClose }),
-        // Disabled until there is somewhere to go — an empty target would
-        // write `[text]()`, which reads as a link and goes nowhere.
-        action("insert", "Insert link", {
-          primary: true,
-          disabled: !target,
-          onPress: submit,
-        }),
-      ),
+  /**
+   * @param {object} props
+   * @param {boolean} props.visible
+   * @param {() => void} props.onClose
+   * @param {(result: {label: string, target: string}) => void} props.onSubmit
+   * @param {Array<{id: string, name: string}>} props.pages — pickable pages;
+   *   empty means this host offered none, so only the URL mode is shown.
+   * @param {string} props.initialLabel — the author's current selection.
+   * @param {string} [props.testID]
+   */
+  function MarkdownLinkDialog({
+    visible,
+    onClose,
+    onSubmit,
+    pages,
+    initialLabel,
+    testID,
+  }) {
+    const pageList = Array.isArray(pages) ? pages.filter((p) => p && p.id) : [];
+    const canPickPage = pageList.length > 0;
+
+    const [label, setLabel] = React.useState("");
+    const [url, setUrl] = React.useState("");
+    const [pageId, setPageId] = React.useState("");
+    const [mode, setMode] = React.useState("url");
+
+    // Re-seed on each open: the author's selection and the mode they should
+    // land in are both properties of THIS opening, not of the component.
+    React.useEffect(() => {
+      if (!visible) return;
+      setLabel(typeof initialLabel === "string" ? initialLabel : "");
+      setUrl("");
+      setPageId("");
+      setMode(canPickPage ? "page" : "url");
+    }, [visible, initialLabel, canPickPage]);
+
+    const target = mode === "page" ? pageId : url.trim();
+
+    const submit = () => {
+      if (!target) return;
+      if (typeof onSubmit === "function") onSubmit({ label, target });
+    };
+
+    const action = (key, title, props) =>
+      React.createElement(Button, {
+        key,
+        title,
+        testID: testID ? `${testID}-${key}` : undefined,
+        ...props,
+      });
+
+    const actions = React.createElement(
+      React.Fragment,
+      null,
+      action("cancel", "Cancel", { variant: "secondary", onPress: onClose }),
+      // Disabled until there is somewhere to go — an empty target would
+      // write `[text]()`, which reads as a link and goes nowhere.
+      action("insert", "Insert link", { disabled: !target, onPress: submit }),
+    );
+
+    return React.createElement(
+      Modal,
+      {
+        visible: !!visible,
+        onRequestClose: onClose,
+        size: "sm",
+        title: "Insert link",
+        footer: actions,
+        testID: testID ? `${testID}-dialog` : undefined,
+      },
+      React.createElement(LinkForm, {
+        form: { label, setLabel, url, setUrl, pageId, setPageId, mode, setMode },
+        pageList,
+        canPickPage,
+        testID,
+      }),
     );
   }