@colixsystems/widget-sdk 0.206.0 → 0.210.0

package/dist/hooks.js

@@ -89,6 +89,19 @@ export function BackdropScope({ basis, children }) {
   return React.createElement(HostWidgetContext.Provider, { value }, children);
 }
 
+/**
+ * @internal — hands a subtree `theme` in place of the host's (`<Modal>` uses
+ * it for the theme re-inked for its own background). No theme, no change.
+ */
+export function ThemeScope({ theme, children }) {
+  const ctx = useContext(HostWidgetContext);
+  const value = useMemo(
+    () => (theme && ctx ? { ...ctx, workspace: { ...ctx.workspace, theme } } : ctx),
+    [ctx, theme],
+  );
+  return React.createElement(HostWidgetContext.Provider, { value }, children);
+}
+
 // Exported for ./toast.js + future hook modules outside hooks.js. Internal
 // utility — widget code should not import this directly.
 export function useWidgetContextOrThrow(hookName) {

package/dist/host.d.ts

@@ -39,6 +39,19 @@ export type ThemeWidgetStyles = Record<string, ThemeComponentStyle>;
  */
 export function normaliseThemeComponents(raw: unknown): ThemeComponents;
 
+/**
+ * What each token of the `alert` component scope resolves to while unset,
+ * keyed by token name: the values `<Banner>` paints an unthemed app with.
+ */
+export function bannerScopeDefaults(theme: unknown): Record<string, string | number>;
+
+/**
+ * The theme a surface painting `backgroundColor` hands its subtree: surface
+ * tokens derived for that fill, and any type tier whose own ink cannot be read
+ * on it re-inked. Returns `theme` itself when the colour is unusable.
+ */
+export function surfaceAwareTheme<T>(theme: T, backgroundColor: unknown): T;
+
 /** Minimum contrast: `text` for labels (WCAG 1.4.3), `boundary` for edges (1.4.11). */
 export const INK_CONTRAST: Readonly<{ text: number; boundary: number }>;
 
@@ -146,6 +159,45 @@ export interface ToastControllerOptions {
   clearTimer?: (handle: unknown) => void;
 }
 
+/** What one `<Modal>` paints with; see `resolveModalTokens`. */
+export interface ModalTokens {
+  size: "sm" | "md" | "lg" | "full";
+  presentation: "dialog" | "sheet";
+  scrim: string;
+  /** The `background` token as set (it may be see-through), else the surface. */
+  background: string;
+  /** What the panel paints: `background` composited over the overlay surface. */
+  panelColor: string;
+  /** `panelColor` when a background is set, for re-inking the body; else null. */
+  bodyBackdrop: string | null;
+  radius: number;
+  padding: number;
+  /** The themed elevation as a style, or null for the overlay's own. */
+  shadow: Record<string, unknown> | null;
+  /** The elevation level in force: the themed one, else the overlay's. */
+  shadowLevel: "none" | "sm" | "md" | "lg";
+  titleColor: string;
+  closeColor: string;
+  sectionGap: number;
+  actionGap: number;
+}
+
+/**
+ * The look of the SDK `<Modal>` under a resolved theme: its `modal` component
+ * scope over the overlay's defaults. For a host previewing Theme Settings >
+ * Dialogs with the values the dialog itself paints.
+ */
+export function resolveModalTokens(
+  theme: unknown,
+  options?: { size?: string; presentation?: string },
+): ModalTokens;
+
+/**
+ * What the `modal` scope's tokens without a `uiDefault` path resolve to while
+ * unset: the scrim, and the title colour on the background currently set.
+ */
+export function modalScopeDefaults(theme: unknown): { scrim: string; titleColor: string };
+
 export const TOAST_DEFAULTS: { durationMs: number; maxVisible: number };
 
 export function normalizeToastKind(kind: unknown): ToastKind;

package/dist/host.js

@@ -42,12 +42,16 @@ export {
 // Host plumbing, deliberately off the author entry point: a widget reads the
 // already-correct `useTheme().colors`, it never derives them itself.
 export { deriveSurfaceTokens, inkForBackdrop, INK_CONTRAST } from "./contract.js";
+export { surfaceAwareTheme } from "./surface-theme.js";
 
 // REQ-WSDK-PLATFORM §6: the host half of `useToast()` — the queue, the
 // auto-dismiss timing, and the themed values a toast is painted with. The
 // widget-facing hook only forwards to `ctx.toast.showToast`; the host owns the
 // surface, and sharing everything but the JSX is what keeps the web Player and
 // the Expo export rendering the same notification (CLAUDE.md §8).
+// The dialog's resolved look, for the Studio's Design > Components > Dialogs preview.
+export { resolveModalTokens, modalScopeDefaults } from "./modal-tokens.js";
+
 export {
   createToastController,
   resolveToastTokens,
@@ -55,6 +59,10 @@ export {
   TOAST_DEFAULTS,
 } from "./toast-host.js";
 
+// What each `alert` scope token resolves to while unset, for the Studio's
+// Design page to preview beside its controls.
+export { bannerScopeDefaults } from "./banner-tokens.js";
+
 // REQ-NAV-STRUCTURE: the navigation resolver both hosts draw their chrome from.
 // `normaliseNavigation` turns a stored `theme_config.navigation` block into the
 // resolved `{ menuType }` — always `sidebar` since sc-7352 retired the other

package/dist/index.d.ts

@@ -3257,13 +3257,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;
 
@@ -3571,6 +3665,40 @@ export const Tabs: (props: {
   testID?: string;
 }) => any;
 
+export type BannerTone = "info" | "success" | "warning" | "error";
+
+/**
+ * Themed inline message: an error, warning, success or notice that stays in
+ * place until it is resolved. Its fill, text colour, border and corners come
+ * from the theme's `alert` scope, so every banner in the app matches. An
+ * `error` is marked as an alert and the other tones as a polite status: the
+ * web and Android announce them when they appear, iOS reads them in place.
+ * For a brief confirmation that may disappear on its own, use `useToast()`.
+ *
+ * @example
+ *   <Banner tone="error" message={error.message} action={{ label: "Retry", onPress: refetch }} />
+ */
+export const Banner: (props: {
+  /** Default "info". */
+  tone?: BannerTone;
+  /** Text is themed; an element renders as given. */
+  title?: ReactNode;
+  /** Text wraps onto as many lines as it needs; an element renders as given. */
+  message?: ReactNode;
+  /** A lucide name replacing the tone's glyph, or `false` for none. */
+  icon?: string | false | null;
+  action?: { label: string; onPress: () => void; accessibilityLabel?: string; testID?: string };
+  /** Shows a close control; hide the banner in the handler. */
+  onDismiss?: () => void;
+  /** Default "Dismiss". */
+  dismissAccessibilityLabel?: string;
+  /** For hosts rendering outside a widget context; widgets omit it. */
+  theme?: any;
+  style?: any;
+  /** The action and close control default to `<testID>-action` / `<testID>-dismiss`. */
+  testID?: string;
+}) => any;
+
 /**
  * Themed collapsible sections. The surface comes from the theme's `card`
  * scope and the headers and dividers from its `list` scope, so every

package/dist/index.js

@@ -270,6 +270,10 @@ export { Accordion, AccordionItem } from "./accordion.js";
 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

@@ -263,6 +263,10 @@ export { Accordion, AccordionItem } from "./accordion.native.js";
 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,
+      }),
     );
   }