@colixsystems/widget-sdk 0.212.0 → 0.213.0

package/README.md

@@ -83,7 +83,52 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.212.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+`v0.213.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+
+### What's new in 0.213.0 (contract 1.172.0)
+
+**New component `<ConfirmDialog>` — the standard "are you sure?".** Widgets asked for confirmation each in their own way (a button that re-labels itself to be pressed twice, a hand-laid Yes / No row), so a delete looked and behaved differently from one widget to the next. `<ConfirmDialog>` is that prompt, built once as a preset of `<Modal>` and `<Button>`:
+
+```jsx
+import { useState } from "react";
+import { ConfirmDialog, Button, useToast } from "@colixsystems/widget-sdk";
+
+function DeleteOrder({ order, onDelete }) {
+  const [asking, setAsking] = useState(false);
+  const { showToast } = useToast();
+  return (
+    <>
+      <Button variant="danger" title="Delete" onPress={() => setAsking(true)} />
+      <ConfirmDialog
+        visible={asking}
+        tone="destructive"
+        title="Delete this order?"
+        message="This cannot be undone."
+        confirmLabel="Delete"
+        onCancel={() => setAsking(false)}
+        onConfirm={async () => {
+          try {
+            await onDelete(order.id);
+          } catch (err) {
+            showToast({ kind: "error", message: err.message });
+          }
+          setAsking(false);
+        }}
+      />
+    </>
+  );
+}
+```
+
+Props: `visible`, `title` (the question), `message` (what confirming does; text is drawn in the theme's body style, any other node as it is), `confirmLabel` and `cancelLabel`, `tone` (`default` | `destructive`), `busy`, `onConfirm`, `onCancel`, `closeAccessibilityLabel` and `testID` (the parts take `-message`, `-cancel`, `-confirm` and `-busy`, plus the Modal's own).
+
+- **Cancelling is the safe default.** The Cancel button, the close button, a backdrop press, Escape on web and the Android back button all fire `onCancel`, never `onConfirm`.
+- **`tone="destructive"`** draws the confirm button as the danger `<Button>`, so it takes its colours from the theme's `destructive` scope (Design > Components > Destructive), and on web opens with focus on Cancel. `default` draws the primary button and opens with focus on Confirm. Focus placement is web only.
+- **Busy.** Return the action's promise from `onConfirm` and the dialog stays busy until it settles: both buttons are disabled, a `<Spinner>` shows, nothing dismisses the dialog, and a second press is ignored. Pass `busy` yourself when the action runs elsewhere; the two combine. A rejected promise is **not** caught: handle the failure inside `onConfirm`, otherwise it is reported as an unhandled rejection. Either way the dialog becomes usable again.
+- **It never closes itself.** Set `visible` to false from `onCancel` and once the action is done.
+- **Labels follow the app's language.** Unset, the buttons read the app's shared `confirm`, `cancel` and `close` translations (the same ones `useI18n().t("cancel")` resolves), falling back to English. Prefer a `confirmLabel` that names the action: "Delete", "Remove", "Send".
+
+It adds no theme scope: the panel follows `modal`, the actions `button`, a destructive confirm `destructive`. `<Button>` now forwards a `ref` to its pressable, which is how the dialog places focus. Additive.
 
 ### What's new in 0.212.0 (contract 1.171.0)
 
@@ -2550,6 +2595,7 @@ import { defineWidget, validateManifest, useDatastoreQuery, Text, View } from "@
 - `WidgetTree({ node })` — component that renders an author-authored child node through the host's renderer; used by Tabs / Card / custom containers to host arbitrary child widgets.
 - `Text`, `View`, `Pressable`, `Image`, `ScrollView`, `TextInput`, `FlatList`, `SectionList`, `ActivityIndicator`, `Switch`, `StyleSheet`, `Linking`, `Icon`, `DateTimePicker` — re-exported from `react-native` (the RN primitives) or implemented in the SDK (`Icon` wraps `lucide-react-native`; `DateTimePicker` wraps `@react-native-community/datetimepicker` on native and renders `<input type="date|time|datetime-local">` directly on web because the RN library has no react-native-web mapping). The web build aliases `react-native` to `react-native-web` so the RN-re-exported primitives render in the browser without any per-platform code; the exported Expo app's Metro bundler resolves the real `react-native` library. `Linking` is a static API (`Linking.openURL(url)`) — use it for external URLs, and use `useNavigation().goTo(pageId)` for internal page navigation. See https://reactnative.dev/docs/ for per-component props.
 - `Overlay` — the screen-level overlay (sc-6607). `<Overlay visible={!!preview} onRequestClose={() => setPreview(null)} size="full">…</Overlay>` renders its children OUTSIDE the widget's layout box on both hosts (web portals it to the document root, native uses the OS modal), so no clipping card, `ScrollView` or neighbouring widget can cut off a document/media preview, lightbox or confirm dialog — which absolute positioning inside the widget cannot achieve on either platform. Children stay in your own React tree, so state and hooks work normally. `onRequestClose` carries the backdrop press, Escape on web, and the Android back button; `size` is `sm` | `md` (default) | `lg` | `full`; the scrim, surface, radius, padding and elevation come from the workspace theme. An anchored dropdown still belongs inside your own root.
+- `ConfirmDialog` — the standard confirmation prompt, a preset of `Modal` and `Button`. `<ConfirmDialog visible={asking} tone="destructive" title="Delete this order?" message="This cannot be undone." confirmLabel="Delete" onCancel={() => setAsking(false)} onConfirm={removeOrder} />` asks before a delete or any other action that cannot be undone. Cancel, the close button, the backdrop, Escape and the Android back button fire `onCancel`; a promise returned from `onConfirm` keeps it busy (buttons disabled, a second press ignored) until it settles. Props: `visible`, `title`, `message`, `confirmLabel`, `cancelLabel`, `tone` (`default` | `destructive`), `busy`, `onConfirm`, `onCancel`, `closeAccessibilityLabel`, `testID`. Use it instead of building a confirmation from `Modal` yourself.
 - `Modal` — the standard dialog, built on `Overlay`. `<Modal visible={open} onRequestClose={() => setOpen(false)} title="Edit order" footer={<Button title="Save" onPress={save} />}>…</Modal>` draws 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 an app matches. Props: `visible`, `onRequestClose`, `dismissible`, `title`, `footer`, `presentation` (`dialog` | `sheet`), `size` (`sm` | `md` | `lg` | `full`), `dismissOnBackdropPress`, `role`, `initialFocusRef`, `closeAccessibilityLabel`, `accessibilityLabel`, `testID`. Use it for every dialog instead of hand-building a header and an action row inside `Overlay`.
 - `RichText` — the formatted-content renderer (sc-6970). `<RichText value={post.body} />` parses the markdown subset (`**bold**`, `*italic*` / `_italic_`, `` `code` ``, `#`/`##`/`###` headings, `-`/`*` bullets, `1.` ordered items, one-line `![alt](src "large")` images) and renders it with SDK primitives, so formatted content reads the same in the web Player and the exported Expo app. `value` is markdown, NOT HTML — widgets have no `dangerouslySetInnerHTML` on either host, so tags in a content string render as literal tag soup; stored text that still holds legacy HTML is stripped to plain text rather than shown as markup. Props: `value`, `renderImage` (`({ src, alt, size }) => node` — supply it when images are filestore ids, because resolving one needs the scopes your own widget holds; without it only absolute `http(s)` URLs render), `style`, `testID`. Colour, type scale and leading come from the workspace theme — never re-style them.
 - `MarkdownInput` — the authoring half of `<RichText>` (sc-6970). `<MarkdownInput value={draft} onChange={setDraft} />` is a multi-line field, a toolbar whose buttons wrap the current SELECTION in markdown markers (bold, italic, code, H2, H3, bullets, numbered list, each toggling back off), and a live `<RichText>` preview of the result underneath — the way to let an app USER write formatted text, instead of a bare `TextInput` plus hand-rolled buttons that can only splice literal tags into the value. Props: `value`, `onChange(next)`, `placeholder`, `previewLabel` (default `Preview`), `showPreview` (default true), `renderImage` (passed through to the preview), `minHeight` (150) and `maxHeight` (280) so a long draft scrolls inside its box, `accessibilityLabel`, `style`, `testID`.

package/dist/button-view.js

@@ -100,8 +100,9 @@ export function makeButton(rn) {
    * @param {boolean} [props.hostThemed] — `fields` already carry the theme
    *   (a built-in the host folded); skip the second fold, which would add the
    *   Button widget's own scopes to a form submit or a Link action.
+   * @param {object} ref — forwarded to the pressable, so a caller can focus it.
    */
-  function Button({
+  const Button = React.forwardRef(function Button({
     title,
     variant = "primary",
     icon,
@@ -114,7 +115,7 @@ export function makeButton(rn) {
     hostThemed = false,
     accessibilityLabel,
     testID,
-  }) {
+  }, ref) {
     const theme = useHostTheme() || DEFAULT_THEME_TOKENS;
     const { colors, spacing, radii, typography } = theme;
     const f = hostThemed
@@ -192,6 +193,7 @@ export function makeButton(rn) {
     return React.createElement(
       Pressable,
       {
+        ref,
         onPress,
         disabled,
         accessibilityRole: "button",
@@ -202,7 +204,7 @@ export function makeButton(rn) {
       },
       children,
     );
-  }
+  });
 
   Button.displayName = "Button";
   return Button;

package/dist/confirm-dialog-view.js

@@ -0,0 +1,158 @@
+// The ONE implementation behind the `<ConfirmDialog>` SDK component: a preset
+// of `<Modal>` holding a message, a Cancel and a Confirm `<Button>`.
+//
+// Bound per host by confirm-dialog.js / confirm-dialog.native.js, which differ
+// only in where the primitives come from, so the two hosts cannot drift.
+
+import React from "react";
+import { useHostSharedText, useHostTheme } from "./hooks.js";
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import { textRoleStyle } from "./text-roles.js";
+
+function isThenable(value) {
+  return value != null && typeof value.then === "function";
+}
+
+function isText(value) {
+  return typeof value === "string" || typeof value === "number";
+}
+
+/**
+ * Bind the shared confirmation to one platform's primitives and to that
+ * host's `<Modal>`, `<Button>` and `<Spinner>`.
+ *
+ * @param {{Text: any}} rn
+ * @param {any} Modal — the host's bound `<Modal>`.
+ * @param {any} Button — the host's bound `<Button>`.
+ * @param {any} Spinner — the host's bound `<Spinner>`.
+ */
+export function makeConfirmDialog(rn, Modal, Button, Spinner) {
+  const { Text } = rn;
+
+  // Rendered inside the Modal, so it reads the theme the Modal re-inks.
+  function Message({ testID, children }) {
+    const theme = useHostTheme() || DEFAULT_THEME_TOKENS;
+    return React.createElement(
+      Text,
+      { testID, style: textRoleStyle("body", theme.typography, theme.colors) },
+      children,
+    );
+  }
+
+  /**
+   * The standard "are you sure?" prompt. Cancelling is the safe default: the
+   * close button, the backdrop, Escape (web) and the Android back button all
+   * fire `onCancel`, never `onConfirm`.
+   *
+   * @param {object} props
+   * @param {boolean} [props.visible] — nothing is mounted while false.
+   * @param {string} props.title — the question, e.g. "Delete this order?".
+   * @param {any} [props.message] — what confirming does; text is drawn in the
+   *   theme's body style, any other node is rendered as it is.
+   * @param {string} [props.confirmLabel] — default the app's "Confirm".
+   * @param {string} [props.cancelLabel] — default the app's "Cancel".
+   * @param {"default"|"destructive"} [props.tone] — `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.
+   * @param {boolean} [props.busy] — the confirmed action is running: both
+   *   buttons are disabled, a loading indicator shows, nothing closes it.
+   * @param {() => void|Promise<any>} [props.onConfirm] — a returned promise
+   *   keeps the dialog busy until it settles. A rejection is not caught.
+   * @param {() => void} [props.onCancel]
+   * @param {string} [props.closeAccessibilityLabel] — default the app's "Close".
+   * @param {string} [props.testID] — on the panel; the parts take `-message`,
+   *   `-cancel`, `-confirm` and `-busy`, plus the Modal's own.
+   */
+  function ConfirmDialog({
+    visible = false,
+    title,
+    message,
+    confirmLabel,
+    cancelLabel,
+    tone = "default",
+    busy = false,
+    onConfirm,
+    onCancel,
+    closeAccessibilityLabel,
+    testID,
+  }) {
+    const sharedConfirm = useHostSharedText("confirm", "Confirm");
+    const sharedCancel = useHostSharedText("cancel", "Cancel");
+    const sharedClose = useHostSharedText("close", "Close");
+    const [pending, setPending] = React.useState(false);
+    // Set before the re-render, so a second press in the same frame is ignored.
+    const inFlight = React.useRef(false);
+    const cancelRef = React.useRef(null);
+    const confirmRef = React.useRef(null);
+
+    const working = busy || pending;
+    const destructive = tone === "destructive";
+    const part = (name) => (testID ? `${testID}-${name}` : undefined);
+
+    const confirm = () => {
+      if (working || inFlight.current || typeof onConfirm !== "function") return;
+      const result = onConfirm();
+      if (!isThenable(result)) return;
+      inFlight.current = true;
+      setPending(true);
+      const settle = () => {
+        inFlight.current = false;
+        setPending(false);
+      };
+      result.then(settle, (error) => {
+        settle();
+        // Rethrown so a failure the caller did not handle is still reported.
+        throw error;
+      });
+    };
+
+    const cancel = () => {
+      if (working || inFlight.current) return;
+      if (typeof onCancel === "function") onCancel();
+    };
+
+    const footer = React.createElement(
+      React.Fragment,
+      null,
+      working ? React.createElement(Spinner, { testID: part("busy") }) : null,
+      React.createElement(Button, {
+        ref: cancelRef,
+        variant: "secondary",
+        title: cancelLabel ?? sharedCancel,
+        onPress: cancel,
+        disabled: working,
+        testID: part("cancel"),
+      }),
+      React.createElement(Button, {
+        ref: confirmRef,
+        variant: destructive ? "danger" : "primary",
+        title: confirmLabel ?? sharedConfirm,
+        onPress: confirm,
+        disabled: working,
+        testID: part("confirm"),
+      }),
+    );
+
+    return React.createElement(
+      Modal,
+      {
+        visible,
+        title,
+        footer,
+        role: "alertdialog",
+        size: "sm",
+        dismissible: !working,
+        onRequestClose: cancel,
+        initialFocusRef: destructive ? cancelRef : confirmRef,
+        closeAccessibilityLabel: closeAccessibilityLabel ?? sharedClose,
+        testID,
+      },
+      isText(message)
+        ? React.createElement(Message, { testID: part("message") }, message)
+        : message,
+    );
+  }
+
+  ConfirmDialog.displayName = "ConfirmDialog";
+  return ConfirmDialog;
+}

package/dist/confirm-dialog.js

@@ -0,0 +1,11 @@
+// `<ConfirmDialog>` (web). Binds ./confirm-dialog-view.js to react-native-web
+// and the web `<Modal>`, `<Button>` and `<Spinner>`; see ./primitives.js for
+// why not the bare specifier.
+
+import { Text } from "react-native-web";
+import { makeConfirmDialog } from "./confirm-dialog-view.js";
+import { Modal } from "./modal.js";
+import { Button } from "./button.js";
+import { Spinner } from "./loading.js";
+
+export const ConfirmDialog = makeConfirmDialog({ Text }, Modal, Button, Spinner);

package/dist/confirm-dialog.native.js

@@ -0,0 +1,11 @@
+// `<ConfirmDialog>` (native). Binds ./confirm-dialog-view.js to React Native's
+// own primitives and the native `<Modal>`, `<Button>` and `<Spinner>`; only the
+// imports differ from ./confirm-dialog.js.
+
+import { Text } from "react-native";
+import { makeConfirmDialog } from "./confirm-dialog-view.js";
+import { Modal } from "./modal.native.js";
+import { Button } from "./button.native.js";
+import { Spinner } from "./loading.native.js";
+
+export const ConfirmDialog = makeConfirmDialog({ Text }, Modal, Button, Spinner);

package/dist/contract.cjs

@@ -2920,6 +2920,13 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  {
+    name: "ConfirmDialog",
+    description:
+      'Standard confirmation prompt, a preset of `<Modal>`. `<ConfirmDialog visible={!!pending} tone="destructive" title="Delete this order?" message="This cannot be undone." confirmLabel={t("delete", "Delete")} onCancel={() => setPending(null)} onConfirm={async () => { await remove(pending.id); setPending(null); }} />`. THE way to ask "are you sure?" before a delete or any other action that cannot be undone, so every confirmation in the app has the same wording slots, button order and colours. Never hand-build one from a `<Modal>` or an `<Overlay>` with your own two buttons, never arm a button to be pressed twice, and never use `Alert.alert` or `window.confirm`. Props: `visible` (boolean), `title` (string, the question), `message` (what confirming does; text or a node), `confirmLabel` and `cancelLabel` (default the app\'s translated "Confirm" and "Cancel" — name the action: "Delete", "Remove", "Send"), `tone` ("default" | "destructive"; destructive draws the confirm button from the theme\'s Destructive colours and opens with focus on Cancel), `busy` (boolean; disables both buttons, shows a `<Spinner>` and keeps the dialog open), `onConfirm` (return the promise of the action and the dialog stays busy until it settles, with a second press ignored; a rejection is NOT caught, so catch a failure yourself and report it), `onCancel` (fired by the Cancel button, the close button, the backdrop press, the Escape key on web and the Android back button — cancelling is always the safe default), `closeAccessibilityLabel` and `testID`. The dialog never closes itself: set `visible` false from `onCancel` and after the action. Its panel follows the theme (Design > Components > Dialogs) and its buttons the Buttons and Destructive settings — do not re-style it.',
+    rnComponent: null,
+    docsUrl: null,
+  },
   // sc-8104 — the in-app emoji picker. Typed emoji always worked; what this
   // replaces is being forced out to the OS keyboard to find one.
   {
@@ -5628,7 +5635,12 @@ const CONTRACT = deepFreeze({
   //    switch, so an existing `<Switch>` with no colour props is repainted:
   //    its tracks follow the theme on both hosts and its "on" thumb is white
   //    on the web. A caller's `trackColor` / `thumbColor` still win.
-  version: "1.171.0",
+  // 1.172.0: additive (sc-10925) — the `ConfirmDialog` primitive: the standard
+  //    confirmation, a preset of `Modal` and `Button` (title, message, confirm
+  //    and cancel labels, `tone` "default" | "destructive", `busy`). No new
+  //    theme scope: the panel reads `modal`, the actions `button` and
+  //    `destructive`. `Button` forwards a ref to its pressable.
+  version: "1.172.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -2920,6 +2920,13 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  {
+    name: "ConfirmDialog",
+    description:
+      'Standard confirmation prompt, a preset of `<Modal>`. `<ConfirmDialog visible={!!pending} tone="destructive" title="Delete this order?" message="This cannot be undone." confirmLabel={t("delete", "Delete")} onCancel={() => setPending(null)} onConfirm={async () => { await remove(pending.id); setPending(null); }} />`. THE way to ask "are you sure?" before a delete or any other action that cannot be undone, so every confirmation in the app has the same wording slots, button order and colours. Never hand-build one from a `<Modal>` or an `<Overlay>` with your own two buttons, never arm a button to be pressed twice, and never use `Alert.alert` or `window.confirm`. Props: `visible` (boolean), `title` (string, the question), `message` (what confirming does; text or a node), `confirmLabel` and `cancelLabel` (default the app\'s translated "Confirm" and "Cancel" — name the action: "Delete", "Remove", "Send"), `tone` ("default" | "destructive"; destructive draws the confirm button from the theme\'s Destructive colours and opens with focus on Cancel), `busy` (boolean; disables both buttons, shows a `<Spinner>` and keeps the dialog open), `onConfirm` (return the promise of the action and the dialog stays busy until it settles, with a second press ignored; a rejection is NOT caught, so catch a failure yourself and report it), `onCancel` (fired by the Cancel button, the close button, the backdrop press, the Escape key on web and the Android back button — cancelling is always the safe default), `closeAccessibilityLabel` and `testID`. The dialog never closes itself: set `visible` false from `onCancel` and after the action. Its panel follows the theme (Design > Components > Dialogs) and its buttons the Buttons and Destructive settings — do not re-style it.',
+    rnComponent: null,
+    docsUrl: null,
+  },
   // sc-8104 — the in-app emoji picker. Typed emoji always worked; what this
   // replaces is being forced out to the OS keyboard to find one.
   {
@@ -5624,7 +5631,12 @@ const CONTRACT = deepFreeze({
   //    switch, so an existing `<Switch>` with no colour props is repainted:
   //    its tracks follow the theme on both hosts and its "on" thumb is white
   //    on the web. A caller's `trackColor` / `thumbColor` still win.
-  version: "1.171.0",
+  // 1.172.0: additive (sc-10925) — the `ConfirmDialog` primitive: the standard
+  //    confirmation, a preset of `Modal` and `Button` (title, message, confirm
+  //    and cancel labels, `tone` "default" | "destructive", `busy`). No new
+  //    theme scope: the panel reads `modal`, the actions `button` and
+  //    `destructive`. `Button` forwards a ref to its pressable.
+  version: "1.172.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/index.d.ts

@@ -3360,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;
@@ -3616,6 +3680,8 @@ 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;
 
 /**

package/dist/index.js

@@ -282,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

@@ -275,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.212.0",
+  "version": "0.213.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",

package/src/contract.js

@@ -2920,6 +2920,13 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  {
+    name: "ConfirmDialog",
+    description:
+      'Standard confirmation prompt, a preset of `<Modal>`. `<ConfirmDialog visible={!!pending} tone="destructive" title="Delete this order?" message="This cannot be undone." confirmLabel={t("delete", "Delete")} onCancel={() => setPending(null)} onConfirm={async () => { await remove(pending.id); setPending(null); }} />`. THE way to ask "are you sure?" before a delete or any other action that cannot be undone, so every confirmation in the app has the same wording slots, button order and colours. Never hand-build one from a `<Modal>` or an `<Overlay>` with your own two buttons, never arm a button to be pressed twice, and never use `Alert.alert` or `window.confirm`. Props: `visible` (boolean), `title` (string, the question), `message` (what confirming does; text or a node), `confirmLabel` and `cancelLabel` (default the app\'s translated "Confirm" and "Cancel" — name the action: "Delete", "Remove", "Send"), `tone` ("default" | "destructive"; destructive draws the confirm button from the theme\'s Destructive colours and opens with focus on Cancel), `busy` (boolean; disables both buttons, shows a `<Spinner>` and keeps the dialog open), `onConfirm` (return the promise of the action and the dialog stays busy until it settles, with a second press ignored; a rejection is NOT caught, so catch a failure yourself and report it), `onCancel` (fired by the Cancel button, the close button, the backdrop press, the Escape key on web and the Android back button — cancelling is always the safe default), `closeAccessibilityLabel` and `testID`. The dialog never closes itself: set `visible` false from `onCancel` and after the action. Its panel follows the theme (Design > Components > Dialogs) and its buttons the Buttons and Destructive settings — do not re-style it.',
+    rnComponent: null,
+    docsUrl: null,
+  },
   // sc-8104 — the in-app emoji picker. Typed emoji always worked; what this
   // replaces is being forced out to the OS keyboard to find one.
   {
@@ -5624,7 +5631,12 @@ const CONTRACT = deepFreeze({
   //    switch, so an existing `<Switch>` with no colour props is repainted:
   //    its tracks follow the theme on both hosts and its "on" thumb is white
   //    on the web. A caller's `trackColor` / `thumbColor` still win.
-  version: "1.171.0",
+  // 1.172.0: additive (sc-10925) — the `ConfirmDialog` primitive: the standard
+  //    confirmation, a preset of `Modal` and `Button` (title, message, confirm
+  //    and cancel labels, `tone` "default" | "destructive", `busy`). No new
+  //    theme scope: the panel reads `modal`, the actions `button` and
+  //    `destructive`. `Button` forwards a ref to its pressable.
+  version: "1.172.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,