@colixsystems/widget-sdk 0.206.0 → 0.207.0

package/README.md

@@ -83,7 +83,18 @@ 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.207.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.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)
 
@@ -2453,6 +2464,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,25 @@ 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({}),
+  }),
 });
 
 // sc-4505 — the value types a widget event payload field may declare. Narrower
@@ -2962,6 +2981,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 +5551,10 @@ 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.
+  version: "1.166.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -704,6 +704,25 @@ 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({}),
+  }),
 });
 
 // sc-4505 — the value types a widget event payload field may declare. Narrower
@@ -2962,6 +2981,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 +5547,10 @@ 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.
+  version: "1.166.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/host.d.ts

@@ -39,6 +39,12 @@ 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>;
+
 /** Minimum contrast: `text` for labels (WCAG 1.4.3), `boundary` for edges (1.4.11). */
 export const INK_CONTRAST: Readonly<{ text: number; boundary: number }>;
 

package/dist/host.js

@@ -55,6 +55,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

@@ -3571,6 +3571,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,8 @@ 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 semantic text tiers, shared with the built-in widgets.
 export {
   textRoleStyle,

package/dist/index.native.js

@@ -263,6 +263,8 @@ 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 semantic text tiers, shared with the built-in widgets.
 export {
   textRoleStyle,

package/dist/readable-ink.js

@@ -0,0 +1,28 @@
+// The label colour for a fill an author chose. Picked by contrast between a
+// FIXED dark and a fixed light: the theme's own text colour is light on a
+// dark theme, so it cannot stand in for "the dark option".
+
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import { contrastRatio, hexAlphaPercent, isHexColor, mixHex } from "./contract.js";
+
+export const INK_DARK = DEFAULT_THEME_TOKENS.colors.onSurface;
+export const INK_LIGHT = "#ffffff";
+
+/** A fill as the opaque colour it shows once painted over `surface`. */
+export function compositeOver(fill, surface) {
+  if (!isHexColor(fill)) return fill;
+  const backdrop = isHexColor(surface) ? surface : DEFAULT_THEME_TOKENS.colors.surface;
+  return mixHex(backdrop, fill, hexAlphaPercent(fill) / 100);
+}
+
+/**
+ * Whichever of the dark and light ink has the higher contrast on `fill`. A
+ * translucent fill is measured as it appears over `surface`.
+ */
+export function readableInk(fill, surface) {
+  if (!isHexColor(fill)) return INK_DARK;
+  const painted = compositeOver(fill, surface);
+  return contrastRatio(painted, INK_DARK) >= contrastRatio(painted, INK_LIGHT)
+    ? INK_DARK
+    : INK_LIGHT;
+}

package/dist/tabs-tokens.js

@@ -3,7 +3,8 @@
 // the same numbers and tests can pin them without a renderer.
 
 import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
-import { CONTRACT, contrastRatio } from "./contract.js";
+import { CONTRACT } from "./contract.js";
+import { readableInk } from "./readable-ink.js";
 
 export const TAB_STYLES = CONTRACT.themeComponentTabStyles;
 
@@ -56,7 +57,7 @@ export function resolveTabsTokens(theme, overrides) {
       pick(overrides, scope, "activeTextColor") ??
       (style === "pill"
         ? ownAccent
-          ? readableOn(ownAccent, colors)
+          ? readableInk(ownAccent, colors.surface)
           : colors.onPrimary
         : activeColor),
     textColor: pick(overrides, scope, "textColor") ?? colors.onSurfaceMuted,
@@ -66,10 +67,3 @@ export function resolveTabsTokens(theme, overrides) {
     rule: colors.border,
   };
 }
-
-// A chosen accent carries the label that reads best on it, dark or light.
-function readableOn(fill, colors) {
-  const dark = colors.onSurface;
-  const light = "#ffffff";
-  return contrastRatio(fill, dark) >= contrastRatio(fill, light) ? dark : light;
-}

package/dist/toast-host.js

@@ -18,7 +18,7 @@ export const TOAST_DEFAULTS = Object.freeze({
 const KINDS = Object.freeze(["success", "error", "warning", "info"]);
 
 // `error` is the widget-facing kind; `danger` is the theme's colour role.
-const KIND_COLOR_ROLE = Object.freeze({
+export const KIND_COLOR_ROLE = Object.freeze({
   success: "success",
   error: "danger",
   warning: "warning",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.206.0",
+  "version": "0.207.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

@@ -704,6 +704,25 @@ 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({}),
+  }),
 });
 
 // sc-4505 — the value types a widget event payload field may declare. Narrower
@@ -2962,6 +2981,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 +5547,10 @@ 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.
+  version: "1.166.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,