@colixsystems/widget-sdk 0.206.0 → 0.210.0

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/surface-theme.js

@@ -0,0 +1,108 @@
+// REQ-THEME-SURFACE: the theme a painted surface hands its subtree. Lives in
+// the SDK so the web Player's containers and `<Modal>` on both hosts re-ink
+// from one implementation.
+
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import {
+  INK_CONTRAST,
+  deriveSurfaceTokens,
+  inkForBackdrop,
+  isHexColor,
+} from "./contract.js";
+
+/**
+ * REQ-THEME-SURFACE: the token overrides a container's CHILDREN inherit.
+ *
+ * A container that paints its own `backgroundColor` becomes the surface its
+ * subtree sits on, so an unset text colour there must read against THAT fill
+ * rather than the page's. Without this, the only way to keep a heading legible
+ * inside a dark card was to write a literal hex onto the node — which is what
+ * froze a built app's appearance against its own theme.
+ *
+ * Returns the SAME reference when nothing changes, so an untouched page
+ * allocates nothing and every child sees the identical context value.
+ *
+ * A photo-backed container is deliberately NOT handled here: no colour can be
+ * derived from an image, so its subtree keeps what it inherited and the scrim
+ * plus an explicit light text colour carries the hero.
+ *
+ * The web Player calls this; the export's generated layout renderer mirrors
+ * it — the two hosts must not differ here (CLAUDE.md §8).
+ */
+export function surfaceAwareTheme(tenantTheme, backgroundColor) {
+  const surfaceTokens = deriveSurfaceTokens(backgroundColor);
+  if (!surfaceTokens) return tenantTheme;
+  const t = tenantTheme && typeof tenantTheme === "object" ? tenantTheme : {};
+  const typography = t.typography || null;
+  // The look's UNTOUCHED ink, carried forward so nesting stays idempotent. A
+  // band re-inks to the platform's light ink; a white card inside it must be
+  // judged against the LOOK's ink, or it can only ever land back on the
+  // platform default and the look's voice is lost one level in.
+  const base =
+    (typography && (typography.rolesBase || typography.roles)) || null;
+  // `base` when nothing needs replacing, which is what RESTORES the look's ink
+  // on a card nested inside an already-re-inked band. Falling through to the
+  // inherited `roles` there would leave the band's platform ink in place and
+  // the look could never come back.
+  const nextRoles = rolesOnSurface(base, surfaceTokens, backgroundColor) || base;
+  // sc-9346: buttons judge this fill against the surface the look was
+  // designed for, taken once at the outermost section and kept on nesting.
+  const colors = t.colors || {};
+  const backdropBase =
+    colors.backdropBase || colors.surface || DEFAULT_THEME_TOKENS.colors.surface;
+  const next = {
+    ...t,
+    colors: { ...colors, ...surfaceTokens, backdrop: backgroundColor, backdropBase },
+  };
+  if (typography && nextRoles && nextRoles !== typography.roles) {
+    next.typography = { ...typography, roles: nextRoles, rolesBase: base };
+  }
+  return next;
+}
+
+/**
+ * sc-8370: re-ink the type tiers for a surface their own ink cannot be read on.
+ *
+ * `roleColor` returns a tier's explicit hex before it ever consults the surface
+ * token, so patching `colors` alone cannot move text that carries one — and
+ * since sc-8131 every look states an ink for all six tiers, chosen against that
+ * colourway's PAGE background. A section painting its own fill is a different
+ * surface, and nothing re-derived the ink for it: a headline shipped dark on a
+ * dark opener band.
+ *
+ * The gate is MEASURED CONTRAST, not a light/dark polarity test. Polarity is
+ * the tempting rule and it is wrong in both directions. The platform's own
+ * predicate flips at luminance 0.55, while the real break-even between the two
+ * inks sits near 0.20 — so every mid-tone fill in that band reads as "wants
+ * light text" when dark text is in fact the stronger choice. On `#a8a29e`, a
+ * shipped preset secondary, a polarity rule swaps a look's ink at 7.0:1 for
+ * the platform's at 2.4:1: it would have turned a passing section into an AA
+ * failure, which is the very defect this function exists to remove.
+ *
+ * So a tier is left alone whenever it is already READABLE, which is what keeps
+ * a look's voice everywhere it works, and is replaced only where it is not AND
+ * the derived token is genuinely better. A wash with no good answer — a
+ * white-to-black band, whose midpoint favours neither ink — therefore keeps
+ * what it inherited instead of committing to a colour that is wrong for half
+ * the band.
+ *
+ * Returns null when nothing moves, so the caller leaves `typography` untouched
+ * and an unaffected page keeps its identical context value.
+ */
+function rolesOnSurface(roles, surfaceTokens, backgroundColor) {
+  let out = null;
+  for (const [role, seed] of Object.entries(
+    DEFAULT_THEME_TOKENS.typography.roles,
+  )) {
+    const current = roles && roles[role] && roles[role].color;
+    // A tier with no frozen ink already resolves through `colors` per render.
+    if (!isHexColor(current)) continue;
+    const derived = surfaceTokens[seed.colorToken];
+    // The quiet tiers are body-sized too, so they get no softer bar.
+    const ink = inkForBackdrop(current, derived, backgroundColor, INK_CONTRAST.text);
+    if (ink === current) continue;
+    if (!out) out = { ...roles };
+    out[role] = { ...roles[role], color: derived };
+  }
+  return out;
+}

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/dist/web-modal.js

@@ -7,7 +7,8 @@
 // re-render rebuilt it, and its Escape and focus handling never re-armed.
 //
 // Implements only the `Modal` props `<Overlay>` passes: `visible`,
-// `onRequestClose` and `children`; it is never animated.
+// `onRequestClose`, the dialog's role and name, `initialFocusRef` and
+// `children`; it is never animated.
 
 import React from "react";
 import { createPortal } from "react-dom";
@@ -37,13 +38,25 @@ function tabStops(dialog) {
 }
 
 /**
- * @param {{visible?: boolean, onRequestClose?: () => void, children?: any}} props
+ * @param {{visible?: boolean, onRequestClose?: () => void, role?: string,
+ *   "aria-label"?: string, "aria-labelledby"?: string,
+ *   initialFocusRef?: {current: any}, children?: any}} props
  */
-export function WebModal({ visible = true, onRequestClose, children }) {
+export function WebModal({
+  visible = true,
+  onRequestClose,
+  role = "dialog",
+  "aria-label": ariaLabel,
+  "aria-labelledby": ariaLabelledBy,
+  initialFocusRef,
+  children,
+}) {
   const [container, setContainer] = React.useState(null);
   const dialogRef = React.useRef(null);
   const onCloseRef = React.useRef(onRequestClose);
   onCloseRef.current = onRequestClose;
+  const initialFocusRefRef = React.useRef(initialFocusRef);
+  initialFocusRefRef.current = initialFocusRef;
   // Taken before the dialog mounts, so a child that focuses itself on mount
   // cannot become the place focus returns to.
   const returnFocusRef = React.useRef(null);
@@ -67,7 +80,11 @@ export function WebModal({ visible = true, onRequestClose, children }) {
     openLayers.push(layer);
     const isTop = () => openLayers[openLayers.length - 1] === layer;
     const returnFocusTo = returnFocusRef.current;
-    if (!dialog.contains(document.activeElement)) {
+    const wanted = initialFocusRefRef.current;
+    const first = wanted && wanted.current;
+    if (first && typeof first.focus === "function") {
+      first.focus({ preventScroll: true });
+    } else if (!dialog.contains(document.activeElement)) {
       dialog.focus({ preventScroll: true });
     }
 
@@ -127,8 +144,10 @@ export function WebModal({ visible = true, onRequestClose, children }) {
       "div",
       {
         ref: dialogRef,
-        role: "dialog",
+        role,
         "aria-modal": "true",
+        "aria-label": ariaLabel,
+        "aria-labelledby": ariaLabelledBy,
         tabIndex: -1,
         style: layerStyle,
       },

package/package.json

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