@colixsystems/widget-sdk 0.206.0 → 0.210.0

package/README.md

@@ -83,7 +83,60 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.206.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.210.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.210.0 (contract 1.169.0)
+
+**New component `<Modal>` — the standard dialog.** Widgets that opened a dialog each built their own header, close button and action row inside a bare `<Overlay>`, so no two dialogs in an app matched and none could be restyled from the theme. `<Modal>` is that dialog, built once on `<Overlay>`:
+
+```jsx
+import { useState } from "react";
+import { Modal, Button, TextField } from "@colixsystems/widget-sdk";
+
+function AddNote({ onSave }) {
+  const [open, setOpen] = useState(false);
+  const [note, setNote] = useState("");
+  return (
+    <>
+      <Button title="Add note" onPress={() => setOpen(true)} />
+      <Modal
+        visible={open}
+        onRequestClose={() => setOpen(false)}
+        title="Add note"
+        footer={
+          <>
+            <Button variant="secondary" title="Cancel" onPress={() => setOpen(false)} />
+            <Button title="Save" onPress={() => onSave(note)} />
+          </>
+        }
+      >
+        <TextField value={note} onChangeText={setNote} placeholder="Note" accessibilityLabel="Note" />
+      </Modal>
+    </>
+  );
+}
+```
+
+It draws the title, a close button, a body that scrolls when it is long, and a footer action row laid out below it, and it renders outside the widget's layout box on both hosts exactly as `<Overlay>` does. Props: `visible`, `onRequestClose` (the close button, the backdrop press, Escape on web and the Android back button), `title`, `footer` (the action buttons, laid out as one right-aligned row that wraps; omit it for no footer), `presentation` (`dialog`, centred, the default | `sheet`, anchored to the bottom edge), `size` (`sm` | `md` | `lg` | `full`), `dismissOnBackdropPress`, `dismissible` (default true; false hides the close button and stops the backdrop, Escape and Android back from closing a dialog that must stay open, e.g. while it saves), `role` (`dialog` | `alertdialog`, web only), `initialFocusRef` (the control focused on open, web only), `closeAccessibilityLabel` (default `Close`), `accessibilityLabel` (names a dialog with no title) and `testID`. With no `onRequestClose` it draws no close button; with no title either, no header row. Use `dismissible={false}` only while that work runs and always restore it: with no footer button or in-body control, such a dialog cannot be closed. Do not wrap the body in your own `ScrollView`.
+
+A dialog that paints its own background hands whatever is rendered inside it a theme re-inked for that background, so SDK components and any component of yours calling `useTheme()` inside the `<Modal>` stay readable; text you style with the theme read *outside* the dialog does not follow, so build the body as its own component. 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.
+
+**New theme scope `modal`.** A dialog's `background`, `titleColor`, `scrim`, `radius`, `padding` and `shadow` are set app-wide under `themeConfig.components.modal` (Design > Components > Dialogs). `<Modal>` reads the scope itself, so the scope names it under `sdkComponents` and binds no `styleSchema` field. The `scrim` is always painted see-through: an opaque colour takes the default 55% alpha, and no scrim exceeds 85%. With no token set a `<Modal>` sits on exactly the panel and scrim `<Overlay>` has always drawn.
+
+**`<Overlay>` gains `presentation`, `role`, `initialFocusRef`, `backdropAccessible` and `testID`, and a themed scrim.** Its `accessibilityLabel` now names the web dialog node itself (the panel still carries it in the exported app). Apart from the scrim, a bare `<Overlay>` renders in the exported app exactly as before. `presentation="sheet"` anchors the panel to the bottom edge; `dialog` (the default) is the centred panel it always was. Its scrim now follows the `modal` scope's `scrim` token, and is unchanged when the token is unset. Keep `<Overlay>` for what is not a dialog: a media or document preview, a lightbox.
+
+The `<MarkdownInput>` link form now opens as a `<Modal>`. Hosts get `resolveModalTokens(theme, { size, presentation })`, `modalScopeDefaults(theme)` and `surfaceAwareTheme(theme, backgroundColor)` from `@colixsystems/widget-sdk/host`. Additive.
+
+### What's new in 0.207.0 (contract 1.166.0)
+
+**A themed inline message: `Banner`, and the `alert` theme scope.** `<Banner tone="error" title="Could not save" message={err.message} action={{ label: "Retry", onPress: save }} onDismiss={() => setErr(null)} />` draws the box a widget shows when something needs saying in place: a list that failed to load, a form that cannot be submitted yet, a read-only notice. `tone` is `info` (default), `success`, `warning` or `error`; `title`, `icon`, `action` and `onDismiss` are all optional, and a long `message` wraps. `title` and `message` take text, which the banner themes, or an element you built, which it renders as given. An `error` is marked as an alert, and the other tones as a polite status: the web and Android announce them when they appear, while iOS reads the banner in place. Its fill, text colour, border and corner radius come from **Design > Components > Alerts** (`themeConfig.components.alert`: `radius`, `borderWidth`, and `<tone>Background` / `<tone>TextColor` for each tone). Left unset, each tone is a soft tint of the theme's own status colour (`danger`, `success`, `warning`, `info`) with text that clears 4.5:1 on it, the same colours a toast of that kind is accented with, so the two agree. A background set without a text colour takes whichever of dark or light text has the higher contrast on it, measured as the fill appears over the surface when it is translucent.
+
+Use a banner for a message that belongs to a place and stays until it is resolved, and `useToast()` for a brief confirmation of something the user just did. The built-in Notifications and User Management widgets now render their error boxes through it.
+
+Like the `loading` scope, `alert` styles an SDK component rather than a widget's style field: it declares `sdkComponents: ["Banner"]` and an empty `targets`. `bannerScopeDefaults(theme)` on the `/host` entry returns what each token resolves to while unset.
+
+- **`CONTRACT.version` → `1.166.0`** (additive: the `Banner` primitive and the `alert` scope).
+- **Changed:** a pill tab's automatic active-label colour (a custom `activeColor` with no `activeTextColor`) is now chosen by contrast between a fixed dark ink (`#111827`) and white, measured over the surface when the accent is translucent. It was chosen between the theme's own text colour and white, which left the label unreadable on a dark theme. Apps whose theme text colour is not the default will see that label in the fixed ink instead of their text colour; an explicit `activeTextColor` still wins.
 
 ### What's new in 0.206.0 (contract 1.165.0)
 
@@ -2446,6 +2499,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.
+- `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`.
 - `parseMarkdown`, `markdownToPlainText`, `parseMarkdownImage`, `formatMarkdownImage`, `stripHtmlToMarkdown`, `MARKDOWN_IMAGE_SIZES` — the same grammar as pure helpers, for content you inspect rather than render: the block list, a marker-free projection (list previews, search, a11y labels), the one-line image form read and written, a legacy-HTML row normalised to markdown on read, and the closed size list (`small` | `medium` | `large` | `full`).
@@ -2453,6 +2507,7 @@ import { defineWidget, validateManifest, useDatastoreQuery, Text, View } from "@
 - `List`, `ListRow`, `ListHeader`, `EmptyState` — the themed list building blocks. `<ListRow title subtitle leading trailing onPress selected divider>` draws one record row from the theme's `list` scope (padding, height, gap, radius, background, divider); `<List>` spaces its rows and hands overrides down; `<ListHeader>` labels a table's columns on the rows' own inset; `<EmptyState icon title message>` is the "nothing here" panel. Never hand-roll a row or a header row from `View` + `Pressable`.
 - `Badge`, `Avatar`, `Progress`, `Stat`, `Divider` — the themed status pill, person picture, completion bar or ring, headline figure and rule the built-in widgets of the same names render through. Reach for them inside a record row instead of hand-rolling a pill or a circle from `View`.
 - `Card`, `Button`, `TextField` — the themed card surface, button and text field the built-in widgets render through. With no props each takes the app's look from Theme Settings (Cards, Buttons, Muted); never hand-roll one from `View` / `Pressable` / a bare `TextInput`.
+- `Banner` — the themed inline message. `<Banner tone message>` shows an error, warning, success or notice in place, styled by the theme's `alert` scope; `action` adds one button and `onDismiss` a close control. Use `useToast()` for a brief confirmation instead. Never hand-roll a tinted error box.
 - `Accordion`, `AccordionItem` — themed collapsible sections. `<Accordion><AccordionItem title subtitle trailing>…</AccordionItem></Accordion>` draws its surface from the theme's `card` scope and its headers and dividers from the `list` scope; one section open at a time, or `multiple`. Never hand-roll a collapsible from `Pressable` + a chevron.
 - `Spinner`, `Skeleton` — the themed loading states. `<Spinner size label>` for a pending action; `<Skeleton shape="text" | "block" | "circle" | "listRow">` (or a group of bones) for content whose layout you know. The spinner wears `colors.loader`, the skeleton follows the theme's `loading` scope; both stop under reduced motion and mark one busy region. Never use `ActivityIndicator` or hand-build placeholder bars.
 - `Tabs` — the themed tab strip. `<Tabs items value onChange>` draws a segmented control, pills or an underline as the theme's `tabs` scope says; render the selected panel yourself. Never hand-roll tabs from `Pressable` chips.

package/dist/banner-tokens.js

@@ -0,0 +1,116 @@
+// The values `<Banner>` paints with, resolved from the theme's `alert`
+// component scope. Platform-free, like tabs-tokens.js, so both hosts draw one
+// banner from the same numbers and tests can pin them without a renderer.
+
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import { CONTRACT, deriveAccentTints, mixHex } from "./contract.js";
+import { compositeOver, readableInk } from "./readable-ink.js";
+import { normaliseThemeComponents } from "./theme-components.js";
+import { KIND_COLOR_ROLE } from "./toast-host.js";
+
+export const BANNER_TONES = Object.freeze(["info", "success", "warning", "error"]);
+export const DEFAULT_BANNER_TONE = "info";
+export const DEFAULT_BANNER_BORDER_WIDTH = 1;
+
+// The glyph a tone carries when the caller names none.
+export const BANNER_TONE_ICONS = Object.freeze({
+  info: "info",
+  success: "circle-check",
+  warning: "triangle-alert",
+  error: "circle-alert",
+});
+
+// How far the outline sits from the text colour toward the fill.
+const BORDER_FILL_WEIGHT = 0.7;
+
+export function normaliseBannerTone(tone) {
+  return BANNER_TONES.includes(tone) ? tone : DEFAULT_BANNER_TONE;
+}
+
+/** The `alert` scope's token names for one tone's fill and text. */
+export function bannerToneTokenNames(tone) {
+  return { background: `${tone}Background`, textColor: `${tone}TextColor` };
+}
+
+// The soft fill + readable text of a tone, from the status colour a toast of
+// the same kind is accented with.
+function defaultTonePair(colors, tone) {
+  const fallback = DEFAULT_THEME_TOKENS.colors;
+  const role = KIND_COLOR_ROLE[tone];
+  const tints = deriveAccentTints(
+    colors[role] || fallback[role],
+    colors.surface || fallback.surface,
+    colors.onSurface || fallback.onSurface,
+  );
+  return tints
+    ? { background: tints.primarySoft, textColor: tints.onPrimarySoft }
+    : { background: colors.surfaceMuted, textColor: colors.onSurface };
+}
+
+/**
+ * Resolve one banner: the theme's `alert` scope, then the tone's status
+ * colour. A themed fill with no themed text takes whichever of dark or light
+ * text has the higher contrast on it, so the message stays legible.
+ *
+ * @param {object} theme — the resolved workspace theme (`useTheme()` shape).
+ * @param {string} tone — `info` | `success` | `warning` | `error`.
+ */
+export function resolveBannerTokens(theme, tone) {
+  const base = theme && typeof theme === "object" ? theme : DEFAULT_THEME_TOKENS;
+  const fallback = DEFAULT_THEME_TOKENS;
+  const colors = base.colors || fallback.colors;
+  const radii = base.radii || fallback.radii;
+  const safeTone = normaliseBannerTone(tone);
+  const scope = normaliseThemeComponents(base.components).alert || {};
+  const names = bannerToneTokenNames(safeTone);
+  const derived = defaultTonePair(colors, safeTone);
+
+  const background = scope[names.background] ?? derived.background;
+  const textColor =
+    scope[names.textColor] ??
+    (scope[names.background] === undefined
+      ? derived.textColor
+      : readableInk(background, colors.surface));
+  return {
+    tone: safeTone,
+    background,
+    textColor,
+    borderColor: mixHex(
+      textColor,
+      compositeOver(background, colors.surface),
+      BORDER_FILL_WEIGHT,
+    ),
+    borderWidth: scope.borderWidth ?? DEFAULT_BANNER_BORDER_WIDTH,
+    radius: scope.radius ?? radii.md,
+    icon: BANNER_TONE_ICONS[safeTone],
+  };
+}
+
+// The tone a token belongs to and the resolved value it sets.
+function tokenReading(token) {
+  for (const tone of BANNER_TONES) {
+    const names = bannerToneTokenNames(tone);
+    if (token === names.background) return { tone, value: "background" };
+    if (token === names.textColor) return { tone, value: "textColor" };
+  }
+  return { tone: DEFAULT_BANNER_TONE, value: token };
+}
+
+/**
+ * What each `alert` token resolves to once THAT token is unset, keyed by token
+ * name, so the Studio previews the value each control would replace. The rest
+ * of the scope stays: a tone's default text depends on its themed fill.
+ *
+ * @param {object} theme — the resolved workspace theme (`useTheme()` shape).
+ */
+export function bannerScopeDefaults(theme) {
+  const base = theme && typeof theme === "object" ? theme : DEFAULT_THEME_TOKENS;
+  const scope = (base.components && base.components.alert) || {};
+  const out = {};
+  for (const token of Object.keys(CONTRACT.themeComponents.alert.tokens)) {
+    const { tone, value } = tokenReading(token);
+    const without = { ...base, components: { ...base.components, alert: { ...scope, [token]: undefined } } };
+    out[token] = resolveBannerTokens(without, tone)[value];
+  }
+  return out;
+}

package/dist/banner-view.js

@@ -0,0 +1,198 @@
+// The ONE implementation behind the `<Banner>` SDK primitive. The platform
+// bindings (`banner.js` / `banner.native.js`) differ only in where the
+// primitives come from, so the hosts cannot drift.
+//
+// Widgets each drew their own error box, so the same kind of message looked
+// different in every widget. This one reads the theme's `alert` scope.
+
+import React from "react";
+import { useHostTheme } from "./hooks.js";
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import { Icon } from "./icon.js";
+import { resolveBannerTokens } from "./banner-tokens.js";
+
+const ICON_SIZE = 18;
+const DISMISS_ICON_SIZE = 16;
+const LINE_MIN_HEIGHT = 24;
+// A real 36px target: the web host ignores hitSlop, so size carries it.
+const CONTROL_MIN_SIZE = 36;
+const CONTROL_HIT_SLOP = 4;
+
+const h = React.createElement;
+
+function isText(value) {
+  return typeof value === "string" || typeof value === "number";
+}
+
+function isShown(value) {
+  return value !== undefined && value !== null && value !== false && value !== "";
+}
+
+// An error is an alert on both hosts. The other tones are a polite live
+// region on the web and Android; iOS has no equivalent and reads them in place.
+function announcement(tone) {
+  return tone === "error"
+    ? { accessibilityRole: "alert", accessibilityLiveRegion: "assertive" }
+    : { role: "status", accessibilityLiveRegion: "polite" };
+}
+
+/**
+ * Bind the shared banner to one platform's primitives.
+ *
+ * @param {{View: any, Text: any, Pressable: any}} rn
+ */
+export function makeBanner(rn) {
+  const { View, Text, Pressable } = rn;
+
+  function BannerAction({ action, ink, typography, fallbackTestID }) {
+    return h(
+      Pressable,
+      {
+        onPress: action.onPress,
+        accessibilityRole: "button",
+        accessibilityLabel: action.accessibilityLabel || action.label,
+        hitSlop: CONTROL_HIT_SLOP,
+        testID: action.testID || fallbackTestID,
+        style: ({ pressed }) => [
+          {
+            minWidth: CONTROL_MIN_SIZE,
+            minHeight: CONTROL_MIN_SIZE,
+            paddingHorizontal: 4,
+            alignItems: "center",
+            justifyContent: "center",
+            flexShrink: 0,
+          },
+          pressed ? { opacity: 0.6 } : null,
+        ],
+      },
+      h(
+        Text,
+        {
+          style: {
+            color: ink,
+            fontFamily: typography.fontFamily,
+            fontSize: typography.sizes.sm,
+            fontWeight: "600",
+            textDecorationLine: "underline",
+          },
+        },
+        action.label,
+      ),
+    );
+  }
+
+  function BannerDismiss({ onDismiss, label, ink, testID }) {
+    return h(
+      Pressable,
+      {
+        onPress: onDismiss,
+        accessibilityRole: "button",
+        accessibilityLabel: label,
+        hitSlop: CONTROL_HIT_SLOP,
+        testID,
+        style: ({ pressed }) => [
+          {
+            minWidth: CONTROL_MIN_SIZE,
+            minHeight: CONTROL_MIN_SIZE,
+            alignItems: "center",
+            justifyContent: "center",
+            flexShrink: 0,
+          },
+          pressed ? { opacity: 0.6 } : null,
+        ],
+      },
+      h(Icon, { name: "x", size: DISMISS_ICON_SIZE, color: ink }),
+    );
+  }
+
+  function Banner({
+    tone,
+    title,
+    message,
+    icon,
+    action,
+    onDismiss,
+    dismissAccessibilityLabel = "Dismiss",
+    theme: explicitTheme,
+    style,
+    testID,
+  }) {
+    const hostTheme = useHostTheme();
+    // A Studio preview renders outside a widget context, so it passes its own.
+    const theme = explicitTheme || hostTheme || DEFAULT_THEME_TOKENS;
+    const t = resolveBannerTokens(theme, tone);
+    const spacing = theme.spacing || DEFAULT_THEME_TOKENS.spacing;
+    const typography = theme.typography || DEFAULT_THEME_TOKENS.typography;
+    const glyph = icon === false || icon === null ? null : icon || t.icon;
+    const hasAction =
+      action && isShown(action.label) && typeof action.onPress === "function";
+    const hasDismiss = typeof onDismiss === "function";
+    // Text sits level with a control when the row has one.
+    const lineMinHeight = hasAction || hasDismiss ? CONTROL_MIN_SIZE : LINE_MIN_HEIGHT;
+    const text = {
+      color: t.textColor,
+      fontFamily: typography.fontFamily,
+      fontSize: typography.sizes.sm,
+    };
+    // Text is wrapped and themed; an element the caller built renders as given.
+    const slot = (value, style) => {
+      if (!isShown(value)) return null;
+      return isText(value) ? h(Text, { style }, value) : value;
+    };
+
+    return h(
+      View,
+      {
+        ...announcement(t.tone),
+        testID,
+        style: [
+          {
+            flexDirection: "row",
+            alignItems: "flex-start",
+            gap: spacing.sm,
+            paddingVertical: spacing.sm,
+            paddingHorizontal: spacing.md,
+            borderRadius: t.radius,
+            borderWidth: t.borderWidth,
+            borderColor: t.borderColor,
+            backgroundColor: t.background,
+          },
+          style,
+        ],
+      },
+      glyph
+        ? h(
+            View,
+            { style: { minHeight: lineMinHeight, justifyContent: "center" } },
+            h(Icon, { name: glyph, size: ICON_SIZE, color: t.textColor }),
+          )
+        : null,
+      h(
+        View,
+        // minWidth 0 lets a long message wrap instead of pushing the row wide.
+        { style: { flex: 1, minWidth: 0, minHeight: lineMinHeight, justifyContent: "center", gap: 2 } },
+        slot(title, { ...text, fontWeight: "600" }),
+        slot(message, text),
+      ),
+      hasAction
+        ? h(BannerAction, {
+            action,
+            ink: t.textColor,
+            typography,
+            fallbackTestID: testID ? `${testID}-action` : undefined,
+          })
+        : null,
+      hasDismiss
+        ? h(BannerDismiss, {
+            onDismiss,
+            label: dismissAccessibilityLabel,
+            ink: t.textColor,
+            testID: testID ? `${testID}-dismiss` : undefined,
+          })
+        : null,
+    );
+  }
+
+  Banner.displayName = "Banner";
+  return Banner;
+}

package/dist/banner.js

@@ -0,0 +1,7 @@
+// `<Banner>` (web). Binds ./banner-view.js to react-native-web; see
+// ./primitives.js for why not the bare specifier.
+
+import * as ReactNative from "react-native-web";
+import { makeBanner } from "./banner-view.js";
+
+export const Banner = makeBanner(ReactNative);

package/dist/banner.native.js

@@ -0,0 +1,7 @@
+// `<Banner>` (native). Binds ./banner-view.js to React Native's own
+// primitives; only the import differs from ./banner.js.
+
+import { View, Text, Pressable } from "react-native";
+import { makeBanner } from "./banner-view.js";
+
+export const Banner = makeBanner({ View, Text, Pressable });

package/dist/contract.cjs

@@ -704,6 +704,44 @@ const THEME_COMPONENTS = Object.freeze({
     }),
     targets: Object.freeze({}),
   }),
+  // Inline messages: `<Banner>` reads this scope directly, so it names the
+  // SDK component it styles and binds no widget field.
+  alert: Object.freeze({
+    label: "Alerts",
+    sdkComponents: Object.freeze(["Banner"]),
+    tokens: Object.freeze({
+      radius: Object.freeze({ type: "size", min: 0, max: 32, uiDefault: "radii.md" }),
+      borderWidth: Object.freeze({ type: "size", min: 0, max: 4 }),
+      infoBackground: Object.freeze({ type: "color" }),
+      infoTextColor: Object.freeze({ type: "color" }),
+      successBackground: Object.freeze({ type: "color" }),
+      successTextColor: Object.freeze({ type: "color" }),
+      warningBackground: Object.freeze({ type: "color" }),
+      warningTextColor: Object.freeze({ type: "color" }),
+      errorBackground: Object.freeze({ type: "color" }),
+      errorTextColor: Object.freeze({ type: "color" }),
+    }),
+    targets: Object.freeze({}),
+  }),
+  // Dialogs: `<Modal>` reads this scope directly, so it names the SDK component
+  // it styles and binds no widget field. `<Overlay>` reads the scrim alone.
+  modal: Object.freeze({
+    label: "Dialogs",
+    sdkComponents: Object.freeze(["Modal"]),
+    tokens: Object.freeze({
+      background: Object.freeze({ type: "color", uiDefault: "colors.surface" }),
+      titleColor: Object.freeze({ type: "color" }),
+      scrim: Object.freeze({
+        type: "color",
+        translucent: true,
+        note: "also the backdrop behind every <Overlay>",
+      }),
+      radius: Object.freeze({ type: "size", min: 0, max: 48, uiDefault: "radii.lg" }),
+      padding: Object.freeze({ type: "size", min: 0, max: 64, uiDefault: "spacing.lg" }),
+      shadow: Object.freeze({ type: "shadow" }),
+    }),
+    targets: Object.freeze({}),
+  }),
 });
 
 // sc-4505 — the value types a widget event payload field may declare. Narrower
@@ -2867,7 +2905,15 @@ const PRIMITIVES = [
   {
     name: "Overlay",
     description:
-      'Screen-level overlay. `<Overlay visible={open} onRequestClose={() => setOpen(false)} size="md">…panel…</Overlay>`. THE way to open anything that must cover the SCREEN rather than the widget — a preview (PDF, image, video), a lightbox, a confirm dialog, a full detail panel. It renders OUTSIDE the widget layout box on both hosts (react-native-web portals it to the document root; native uses the OS modal), so no `overflow: hidden` card, scroll container or sibling widget can clip or cover it — which absolute positioning inside the widget cannot achieve on either host. Children stay in your own React tree, so state and hooks work normally. Props: `visible` (boolean, required to show), `onRequestClose` (fired by the backdrop press, the Escape key on web, and the Android back button — always wire it or the overlay cannot be closed), `size` ("sm" | "md" | "lg" | "full", default "md"; `full` runs edge to edge for media), `dismissOnBackdropPress` (default true), `accessibilityLabel`, and `style` for extra panel styles. The scrim, surface, radius, padding and elevation come from the workspace theme — never re-style them. Keep it for screen-level surfaces: a dropdown anchored to its trigger still belongs inside the widget.',
+      'Screen-level overlay. `<Overlay visible={open} onRequestClose={() => setOpen(false)} size="md">…panel…</Overlay>`. THE way to open anything that must cover the SCREEN rather than the widget and is not a dialog — a preview (PDF, image, video), a lightbox, a full-screen viewer. A dialog (a title, a close button, actions) is `<Modal>`, which is built on this. It renders OUTSIDE the widget layout box on both hosts (react-native-web portals it to the document root; native uses the OS modal), so no `overflow: hidden` card, scroll container or sibling widget can clip or cover it — which absolute positioning inside the widget cannot achieve on either host. Children stay in your own React tree, so state and hooks work normally. Props: `visible` (boolean, required to show), `onRequestClose` (fired by the backdrop press, the Escape key on web, and the Android back button — always wire it or the overlay cannot be closed), `size` ("sm" | "md" | "lg" | "full", default "md"; `full` runs edge to edge for media), `presentation` ("dialog", centred, the default | "sheet", anchored to the bottom edge), `dismissOnBackdropPress` (default true), `role` ("dialog" default | "alertdialog"; web only), `initialFocusRef` (web only), `accessibilityLabel` (names the dialog), `testID`, and `style` for extra panel styles. The scrim, surface, radius, padding and elevation come from the workspace theme (the scrim from Design > Components > Dialogs) — never re-style them. Keep it for screen-level surfaces: a dropdown anchored to its trigger still belongs inside the widget.',
+    rnComponent: null,
+    docsUrl: null,
+  },
+  // The standard dialog, built on `<Overlay>`, so widgets stop hand-building one.
+  {
+    name: "Modal",
+    description:
+      'Standard dialog. `<Modal visible={open} onRequestClose={() => setOpen(false)} title="Edit order" footer={<><Button variant="secondary" title="Cancel" onPress={() => setOpen(false)} /><Button title="Save" onPress={save} /></>}>…body…</Modal>`. THE way to open a dialog, a form in a pop-up, a detail panel or a bottom sheet: it draws the title, the close button, a body that scrolls when it is long, and a footer action row laid out below it, and its background, corner radius, padding, scrim, shadow and title colour come from the theme (Design > Components > Dialogs), so every dialog in the app matches. It is built on `<Overlay>`, so it renders OUTSIDE the widget layout box on both hosts and nothing can clip it. Never hand-build a header, a close button or an action row inside a bare `<Overlay>`; keep `<Overlay>` for surfaces that are not a dialog (a media or document preview, a lightbox). Props: `visible` (boolean), `onRequestClose` (fired by the close button, the backdrop press, the Escape key on web and the Android back button — always wire it), `dismissible` (default true; false hides the close button and stops the backdrop, Escape and Android back from closing it, for a dialog that must stay open while it saves — only while that work runs, and always restore it, or nobody can close the dialog), `title` (string), `footer` (the action buttons, laid out as one right-aligned row that wraps on a phone; omit for no footer), `presentation` ("dialog", centred, the default | "sheet", anchored to the bottom edge; keep a form with text inputs in "dialog" — in the exported app the keyboard handling of a sheet is not yet verified on a device), `size` ("sm" | "md" | "lg" | "full", default "md"), `dismissOnBackdropPress` (default true), `role` ("dialog" default | "alertdialog"; web only), `initialFocusRef` (a ref to the control focused on open; web only), `closeAccessibilityLabel` (default "Close" — pass your translated label), `accessibilityLabel` (names a dialog with no title) and `testID`. With no `onRequestClose` it draws no close button. Components rendered inside it read a theme re-inked for the background the dialog paints, so build the body as its own component. Do not wrap the body in your own `ScrollView` and do not re-style the panel.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -2962,6 +3008,13 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  {
+    name: "Banner",
+    description:
+      'Themed inline message. `<Banner tone="error" title="Could not save" message={err.message} action={{ label: "Retry", onPress: save }} onDismiss={() => setErr(null)} />`. THE way to show an error, warning, success or notice that belongs to a place in the widget and stays until it is resolved: a list that failed to load, a form the user cannot submit yet, a "read-only" or "offline" notice. Render it where the problem is — above the list or form it concerns. Use `useToast()` instead for a brief confirmation of something the user just did ("Saved", "Deleted") that needs no decision and may disappear on its own; never both for one event. Its fill, text colour, border and corner radius come from the app\'s theme per tone (Design > Components > Alerts), so never hand-roll a tinted box from `View` + a border + a hex. Props: `tone` ("info" default | "success" | "warning" | "error"), `title` (optional, one short line) and `message` (wraps — never truncate it): text, or an element you built when part of it needs its own styling, `icon` (a lucide name replacing the tone\'s own glyph, or `false` for none), `action` (`{ label, onPress, accessibilityLabel?, testID? }`, ONE action such as Retry), `onDismiss` (pass it to show a close control; you hide the banner in the handler), `dismissAccessibilityLabel` (default "Dismiss" — pass a translated one), `style` (spacing around it), `testID`. An `error` is marked as an alert, and the other tones as a polite status: the web and Android announce them when they appear, while iOS reads the banner in place.',
+    rnComponent: null,
+    docsUrl: null,
+  },
   {
     name: "Accordion",
     description:
@@ -5525,7 +5578,18 @@ const CONTRACT = deepFreeze({
   //    and `useOnlineVisibility()` read who of a record's members is online
   //    and the viewer's own switch, through the new `ctx.directory.presence`.
   //    A `datastoreTemplate` table may declare `presence: true`.
-  version: "1.165.0",
+  // 1.166.0: additive (sc-10927) — the `Banner` primitive (a themed inline
+  //    error, warning, success or notice) and the `alert` component scope it
+  //    reads.
+  // 1.169.0: additive (sc-10924) — the `Modal` primitive: the standard dialog
+  //    (title, close button, scrolling body, footer action row; `presentation`
+  //    "dialog" | "sheet") built on `Overlay`. New `themeComponents.modal`
+  //    scope (background, titleColor, scrim, radius, padding, shadow), read by
+  //    `Modal`; `Overlay` reads its `scrim` and gains `presentation`, `role`,
+  //    `initialFocusRef`, `backdropAccessible` and `testID`. A scope may now
+  //    name `sdkComponents` and bind no widget field; a colour token may be
+  //    `translucent` (always painted see-through) and carry a `note`.
+  version: "1.169.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -704,6 +704,44 @@ const THEME_COMPONENTS = Object.freeze({
     }),
     targets: Object.freeze({}),
   }),
+  // Inline messages: `<Banner>` reads this scope directly, so it names the
+  // SDK component it styles and binds no widget field.
+  alert: Object.freeze({
+    label: "Alerts",
+    sdkComponents: Object.freeze(["Banner"]),
+    tokens: Object.freeze({
+      radius: Object.freeze({ type: "size", min: 0, max: 32, uiDefault: "radii.md" }),
+      borderWidth: Object.freeze({ type: "size", min: 0, max: 4 }),
+      infoBackground: Object.freeze({ type: "color" }),
+      infoTextColor: Object.freeze({ type: "color" }),
+      successBackground: Object.freeze({ type: "color" }),
+      successTextColor: Object.freeze({ type: "color" }),
+      warningBackground: Object.freeze({ type: "color" }),
+      warningTextColor: Object.freeze({ type: "color" }),
+      errorBackground: Object.freeze({ type: "color" }),
+      errorTextColor: Object.freeze({ type: "color" }),
+    }),
+    targets: Object.freeze({}),
+  }),
+  // Dialogs: `<Modal>` reads this scope directly, so it names the SDK component
+  // it styles and binds no widget field. `<Overlay>` reads the scrim alone.
+  modal: Object.freeze({
+    label: "Dialogs",
+    sdkComponents: Object.freeze(["Modal"]),
+    tokens: Object.freeze({
+      background: Object.freeze({ type: "color", uiDefault: "colors.surface" }),
+      titleColor: Object.freeze({ type: "color" }),
+      scrim: Object.freeze({
+        type: "color",
+        translucent: true,
+        note: "also the backdrop behind every <Overlay>",
+      }),
+      radius: Object.freeze({ type: "size", min: 0, max: 48, uiDefault: "radii.lg" }),
+      padding: Object.freeze({ type: "size", min: 0, max: 64, uiDefault: "spacing.lg" }),
+      shadow: Object.freeze({ type: "shadow" }),
+    }),
+    targets: Object.freeze({}),
+  }),
 });
 
 // sc-4505 — the value types a widget event payload field may declare. Narrower
@@ -2867,7 +2905,15 @@ const PRIMITIVES = [
   {
     name: "Overlay",
     description:
-      'Screen-level overlay. `<Overlay visible={open} onRequestClose={() => setOpen(false)} size="md">…panel…</Overlay>`. THE way to open anything that must cover the SCREEN rather than the widget — a preview (PDF, image, video), a lightbox, a confirm dialog, a full detail panel. It renders OUTSIDE the widget layout box on both hosts (react-native-web portals it to the document root; native uses the OS modal), so no `overflow: hidden` card, scroll container or sibling widget can clip or cover it — which absolute positioning inside the widget cannot achieve on either host. Children stay in your own React tree, so state and hooks work normally. Props: `visible` (boolean, required to show), `onRequestClose` (fired by the backdrop press, the Escape key on web, and the Android back button — always wire it or the overlay cannot be closed), `size` ("sm" | "md" | "lg" | "full", default "md"; `full` runs edge to edge for media), `dismissOnBackdropPress` (default true), `accessibilityLabel`, and `style` for extra panel styles. The scrim, surface, radius, padding and elevation come from the workspace theme — never re-style them. Keep it for screen-level surfaces: a dropdown anchored to its trigger still belongs inside the widget.',
+      'Screen-level overlay. `<Overlay visible={open} onRequestClose={() => setOpen(false)} size="md">…panel…</Overlay>`. THE way to open anything that must cover the SCREEN rather than the widget and is not a dialog — a preview (PDF, image, video), a lightbox, a full-screen viewer. A dialog (a title, a close button, actions) is `<Modal>`, which is built on this. It renders OUTSIDE the widget layout box on both hosts (react-native-web portals it to the document root; native uses the OS modal), so no `overflow: hidden` card, scroll container or sibling widget can clip or cover it — which absolute positioning inside the widget cannot achieve on either host. Children stay in your own React tree, so state and hooks work normally. Props: `visible` (boolean, required to show), `onRequestClose` (fired by the backdrop press, the Escape key on web, and the Android back button — always wire it or the overlay cannot be closed), `size` ("sm" | "md" | "lg" | "full", default "md"; `full` runs edge to edge for media), `presentation` ("dialog", centred, the default | "sheet", anchored to the bottom edge), `dismissOnBackdropPress` (default true), `role` ("dialog" default | "alertdialog"; web only), `initialFocusRef` (web only), `accessibilityLabel` (names the dialog), `testID`, and `style` for extra panel styles. The scrim, surface, radius, padding and elevation come from the workspace theme (the scrim from Design > Components > Dialogs) — never re-style them. Keep it for screen-level surfaces: a dropdown anchored to its trigger still belongs inside the widget.',
+    rnComponent: null,
+    docsUrl: null,
+  },
+  // The standard dialog, built on `<Overlay>`, so widgets stop hand-building one.
+  {
+    name: "Modal",
+    description:
+      'Standard dialog. `<Modal visible={open} onRequestClose={() => setOpen(false)} title="Edit order" footer={<><Button variant="secondary" title="Cancel" onPress={() => setOpen(false)} /><Button title="Save" onPress={save} /></>}>…body…</Modal>`. THE way to open a dialog, a form in a pop-up, a detail panel or a bottom sheet: it draws the title, the close button, a body that scrolls when it is long, and a footer action row laid out below it, and its background, corner radius, padding, scrim, shadow and title colour come from the theme (Design > Components > Dialogs), so every dialog in the app matches. It is built on `<Overlay>`, so it renders OUTSIDE the widget layout box on both hosts and nothing can clip it. Never hand-build a header, a close button or an action row inside a bare `<Overlay>`; keep `<Overlay>` for surfaces that are not a dialog (a media or document preview, a lightbox). Props: `visible` (boolean), `onRequestClose` (fired by the close button, the backdrop press, the Escape key on web and the Android back button — always wire it), `dismissible` (default true; false hides the close button and stops the backdrop, Escape and Android back from closing it, for a dialog that must stay open while it saves — only while that work runs, and always restore it, or nobody can close the dialog), `title` (string), `footer` (the action buttons, laid out as one right-aligned row that wraps on a phone; omit for no footer), `presentation` ("dialog", centred, the default | "sheet", anchored to the bottom edge; keep a form with text inputs in "dialog" — in the exported app the keyboard handling of a sheet is not yet verified on a device), `size` ("sm" | "md" | "lg" | "full", default "md"), `dismissOnBackdropPress` (default true), `role` ("dialog" default | "alertdialog"; web only), `initialFocusRef` (a ref to the control focused on open; web only), `closeAccessibilityLabel` (default "Close" — pass your translated label), `accessibilityLabel` (names a dialog with no title) and `testID`. With no `onRequestClose` it draws no close button. Components rendered inside it read a theme re-inked for the background the dialog paints, so build the body as its own component. Do not wrap the body in your own `ScrollView` and do not re-style the panel.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -2962,6 +3008,13 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  {
+    name: "Banner",
+    description:
+      'Themed inline message. `<Banner tone="error" title="Could not save" message={err.message} action={{ label: "Retry", onPress: save }} onDismiss={() => setErr(null)} />`. THE way to show an error, warning, success or notice that belongs to a place in the widget and stays until it is resolved: a list that failed to load, a form the user cannot submit yet, a "read-only" or "offline" notice. Render it where the problem is — above the list or form it concerns. Use `useToast()` instead for a brief confirmation of something the user just did ("Saved", "Deleted") that needs no decision and may disappear on its own; never both for one event. Its fill, text colour, border and corner radius come from the app\'s theme per tone (Design > Components > Alerts), so never hand-roll a tinted box from `View` + a border + a hex. Props: `tone` ("info" default | "success" | "warning" | "error"), `title` (optional, one short line) and `message` (wraps — never truncate it): text, or an element you built when part of it needs its own styling, `icon` (a lucide name replacing the tone\'s own glyph, or `false` for none), `action` (`{ label, onPress, accessibilityLabel?, testID? }`, ONE action such as Retry), `onDismiss` (pass it to show a close control; you hide the banner in the handler), `dismissAccessibilityLabel` (default "Dismiss" — pass a translated one), `style` (spacing around it), `testID`. An `error` is marked as an alert, and the other tones as a polite status: the web and Android announce them when they appear, while iOS reads the banner in place.',
+    rnComponent: null,
+    docsUrl: null,
+  },
   {
     name: "Accordion",
     description:
@@ -5521,7 +5574,18 @@ const CONTRACT = deepFreeze({
   //    and `useOnlineVisibility()` read who of a record's members is online
   //    and the viewer's own switch, through the new `ctx.directory.presence`.
   //    A `datastoreTemplate` table may declare `presence: true`.
-  version: "1.165.0",
+  // 1.166.0: additive (sc-10927) — the `Banner` primitive (a themed inline
+  //    error, warning, success or notice) and the `alert` component scope it
+  //    reads.
+  // 1.169.0: additive (sc-10924) — the `Modal` primitive: the standard dialog
+  //    (title, close button, scrolling body, footer action row; `presentation`
+  //    "dialog" | "sheet") built on `Overlay`. New `themeComponents.modal`
+  //    scope (background, titleColor, scrim, radius, padding, shadow), read by
+  //    `Modal`; `Overlay` reads its `scrim` and gains `presentation`, `role`,
+  //    `initialFocusRef`, `backdropAccessible` and `testID`. A scope may now
+  //    name `sdkComponents` and bind no widget field; a colour token may be
+  //    `translucent` (always painted see-through) and carry a `note`.
+  version: "1.169.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,