@colixsystems/widget-sdk 0.207.0 → 0.210.0

package/dist/overlay-tokens.js

@@ -7,16 +7,28 @@
 // thing tests can pin rather than a literal buried in JSX.
 
 import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import { hexAlphaPercent, withHexAlpha } from "./contract.js";
+import { normaliseThemeComponents } from "./theme-components.js";
 
 export const OVERLAY_SIZES = Object.freeze(["sm", "md", "lg", "full"]);
 
+// `dialog` is centred; `sheet` rises from the bottom edge of the screen.
+export const OVERLAY_PRESENTATIONS = Object.freeze(["dialog", "sheet"]);
+
 export const OVERLAY_DEFAULTS = Object.freeze({
   size: "md",
+  presentation: "dialog",
+  elevation: "lg",
   // Slate-black at 55%: dark enough to mute a busy page behind the panel,
   // light enough that the page still reads as "still there, just behind".
   scrim: "rgba(15, 23, 42, 0.55)",
   // Breathing room between the panel and the screen edge on a phone.
   screenPadding: 16,
+  // Scrim kept visible above a sheet, so it reads as a layer over the page.
+  sheetTopGap: 48,
+  // A themed scrim with no alpha takes the default's; none may hide the page.
+  scrimAlphaPercent: 55,
+  scrimAlphaMaxPercent: 85,
 });
 
 // `full` deliberately has no ceiling — a media/PDF preview wants the screen.
@@ -31,6 +43,48 @@ export function normaliseOverlaySize(size) {
   return OVERLAY_SIZES.indexOf(size) === -1 ? OVERLAY_DEFAULTS.size : size;
 }
 
+export function normaliseOverlayPresentation(presentation) {
+  return OVERLAY_PRESENTATIONS.indexOf(presentation) === -1
+    ? OVERLAY_DEFAULTS.presentation
+    : presentation;
+}
+
+/**
+ * The theme's validated `modal` component scope (Design > Components > Dialogs):
+ * `<Modal>` paints from all of it, `<Overlay>` from its scrim alone.
+ *
+ * @param {object} theme — the resolved workspace theme (`useTheme()` shape).
+ * @returns {Record<string, string|number>} the set tokens; `{}` when none.
+ */
+export function modalThemeScope(theme) {
+  const components = theme && typeof theme === "object" ? theme.components : null;
+  return normaliseThemeComponents({ modal: components && components.modal }).modal || {};
+}
+
+/**
+ * The scrim a themed colour really paints: always see-through, so a theme (or
+ * a planner) that names an opaque colour dims the page instead of hiding it.
+ */
+export function themedScrim(color) {
+  if (!color) return OVERLAY_DEFAULTS.scrim;
+  const alpha = hexAlphaPercent(color);
+  const { scrimAlphaPercent, scrimAlphaMaxPercent } = OVERLAY_DEFAULTS;
+  return withHexAlpha(
+    color,
+    alpha >= 100 ? scrimAlphaPercent : Math.min(alpha, scrimAlphaMaxPercent),
+  );
+}
+
+/**
+ * The panel's corners: all four for a dialog, the top two for a sheet, which
+ * meets the screen edge with square ones.
+ */
+export function overlayCornerStyle(radius, presentation) {
+  return presentation === "sheet"
+    ? { borderTopLeftRadius: radius, borderTopRightRadius: radius }
+    : { borderRadius: radius };
+}
+
 /**
  * Resolve the values one overlay is painted with, from the workspace theme.
  *
@@ -39,25 +93,35 @@ export function normaliseOverlaySize(size) {
  *
  * @param {object} theme — the resolved workspace theme (`useTheme()` shape).
  * @param {string} size — `sm` | `md` | `lg` | `full`.
+ * @param {string} [presentation] — `dialog` | `sheet`; `full` is always a dialog.
  */
-export function resolveOverlayTokens(theme, size) {
+export function resolveOverlayTokens(theme, size, presentation) {
   const safeSize = normaliseOverlaySize(size);
+  const isFull = safeSize === "full";
+  const safePresentation = isFull
+    ? OVERLAY_DEFAULTS.presentation
+    : normaliseOverlayPresentation(presentation);
+  const isSheet = safePresentation === "sheet";
   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 spacing = base.spacing || fallback.spacing;
-  const elevation = (base.elevation || fallback.elevation).lg || {};
+  const elevation =
+    (base.elevation || fallback.elevation)[OVERLAY_DEFAULTS.elevation] || {};
 
   return {
     size: safeSize,
-    scrim: OVERLAY_DEFAULTS.scrim,
+    presentation: safePresentation,
+    scrim: themedScrim(modalThemeScope(base).scrim),
     surface: colors.surface || fallback.colors.surface,
-    radius: safeSize === "full" ? 0 : radii.lg || fallback.radii.lg,
+    radius: isFull ? 0 : radii.lg || fallback.radii.lg,
     padding: spacing.lg || fallback.spacing.lg,
     // A `full` overlay runs edge to edge; every other size keeps a margin so
     // the scrim stays visible and the panel reads as a layer, not a screen.
-    screenPadding: safeSize === "full" ? 0 : OVERLAY_DEFAULTS.screenPadding,
+    screenPadding: isFull || isSheet ? 0 : OVERLAY_DEFAULTS.screenPadding,
+    topGap: isSheet ? OVERLAY_DEFAULTS.sheetTopGap : 0,
+    verticalAlign: isSheet ? "flex-end" : "center",
     maxWidth: SIZE_MAX_WIDTH[safeSize],
     elevation,
   };

package/dist/overlay-view.js

@@ -16,30 +16,51 @@
 
 import React from "react";
 import { useHostTheme } from "./hooks.js";
-import { resolveOverlayTokens } from "./overlay-tokens.js";
+import { overlayCornerStyle, resolveOverlayTokens } from "./overlay-tokens.js";
+
+// Kept clickable, but out of the tab order and the accessibility tree.
+const SILENT_BACKDROP = {
+  accessible: false,
+  focusable: false,
+  tabIndex: -1,
+  "aria-hidden": true,
+  importantForAccessibility: "no",
+};
 
 /**
  * Bind the shared overlay component to one platform's primitives.
  *
- * @param {{Modal: any, View: any, Pressable: any, StyleSheet: any}} rn
+ * `namesPanel` is for a host whose `Modal` cannot carry the accessible name
+ * (React Native's): the panel carries it there, the dialog node on the web.
+ *
+ * @param {{Modal: any, View: any, Pressable: any, StyleSheet: any,
+ *   namesPanel?: boolean}} rn
  */
 export function makeOverlay(rn) {
   const { Modal, View, Pressable, StyleSheet } = rn;
+  const namesPanel = Boolean(rn.namesPanel);
 
   function Overlay({
     visible = false,
     onRequestClose,
     size = "md",
+    presentation = "dialog",
     dismissOnBackdropPress = true,
+    backdropAccessible = true,
+    role = "dialog",
     accessibilityLabel,
+    accessibilityLabelledBy,
     closeAccessibilityLabel = "Close",
+    initialFocusRef,
+    panelFrame: PanelFrame,
     style,
+    testID,
     children,
   }) {
     const theme = useHostTheme();
     const tokens = React.useMemo(
-      () => resolveOverlayTokens(theme, size),
-      [theme, size],
+      () => resolveOverlayTokens(theme, size, presentation),
+      [theme, size, presentation],
     );
     const requestClose = React.useCallback(() => {
       if (typeof onRequestClose === "function") onRequestClose();
@@ -52,8 +73,9 @@ export function makeOverlay(rn) {
     const backdrop = {
       flex: 1,
       alignItems: "center",
-      justifyContent: "center",
+      justifyContent: tokens.verticalAlign,
       padding: tokens.screenPadding,
+      ...(tokens.topGap ? { paddingTop: tokens.topGap } : null),
       backgroundColor: tokens.scrim,
     };
     const panel = {
@@ -64,11 +86,21 @@ export function makeOverlay(rn) {
       flexShrink: 1,
       ...(tokens.maxWidth ? { maxWidth: tokens.maxWidth } : { flex: 1 }),
       backgroundColor: tokens.surface,
-      borderRadius: tokens.radius,
+      ...overlayCornerStyle(tokens.radius, tokens.presentation),
       padding: tokens.padding,
       ...tokens.elevation,
     };
 
+    const panelNode = React.createElement(
+      View,
+      {
+        style: [panel, style],
+        accessibilityLabel: namesPanel ? accessibilityLabel : undefined,
+        testID,
+      },
+      children,
+    );
+
     return React.createElement(
       Modal,
       {
@@ -77,6 +109,10 @@ export function makeOverlay(rn) {
         // Not animated: a sheet must answer the tap that opened it at once.
         animationType: "none",
         onRequestClose: requestClose,
+        role: role === "alertdialog" ? "alertdialog" : "dialog",
+        "aria-label": accessibilityLabelledBy ? undefined : accessibilityLabel,
+        "aria-labelledby": accessibilityLabelledBy,
+        initialFocusRef,
       },
       React.createElement(
         View,
@@ -85,18 +121,18 @@ export function makeOverlay(rn) {
           ? React.createElement(Pressable, {
               style: StyleSheet.absoluteFill,
               onPress: requestClose,
-              accessibilityRole: "button",
-              accessibilityLabel: closeAccessibilityLabel,
+              ...(backdropAccessible
+                ? {
+                    accessibilityRole: "button",
+                    accessibilityLabel: closeAccessibilityLabel,
+                  }
+                : SILENT_BACKDROP),
             })
           : null,
-        React.createElement(
-          View,
-          {
-            style: [panel, style],
-            accessibilityLabel,
-          },
-          children,
-        ),
+        // @internal `panelFrame`: `<Modal>` wraps its panel, never the scrim.
+        PanelFrame
+          ? React.createElement(PanelFrame, { verticalAlign: tokens.verticalAlign }, panelNode)
+          : panelNode,
       ),
     );
   }

package/dist/overlay.native.js

@@ -8,4 +8,11 @@
 import { Modal, View, Pressable, StyleSheet } from "react-native";
 import { makeOverlay } from "./overlay-view.js";
 
-export const Overlay = makeOverlay({ Modal, View, Pressable, StyleSheet });
+// RN's `Modal` forwards no ARIA props, so the panel carries the name here.
+export const Overlay = makeOverlay({
+  Modal,
+  View,
+  Pressable,
+  StyleSheet,
+  namesPanel: true,
+});

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/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.207.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

@@ -723,6 +723,25 @@ const THEME_COMPONENTS = Object.freeze({
     }),
     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
@@ -2886,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,
   },
@@ -5550,7 +5577,15 @@ const CONTRACT = deepFreeze({
   // 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",
+  // 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,