@colixsystems/widget-sdk 0.86.0 → 0.88.0

package/dist/contract.js

@@ -72,6 +72,9 @@ const DEFAULT_THEME_TOKENS = Object.freeze({
   }),
   elevation: ELEVATION,
   spacing: Object.freeze({ xs: 4, sm: 8, md: 16, lg: 24, xl: 32 }),
+  // REQ-THEME-LOOK: multiplies every layout spacing value at render. 1 is
+  // unchanged, so a theme that never sets it renders exactly as before.
+  spacingScale: 1,
   radii: Object.freeze({ sm: 4, md: 8, lg: 16, pill: 9999 }),
   typography: Object.freeze({
     fontFamily:
@@ -86,6 +89,12 @@ const DEFAULT_THEME_TOKENS = Object.freeze({
   // host so ONE channel carries them to the Player and the export. Empty by
   // default — an unconfigured theme resolves to no component overrides.
   components: Object.freeze({}),
+  // REQ-THEME-ELEMENT: the tenant's per-WIDGET-TYPE style values, keyed by
+  // manifest id. `components` above restyles a whole scope through a shared
+  // vocabulary, which only reaches a widget the vocabulary knows about; this
+  // reaches ANY widget by naming it, using that widget's OWN styleSchema field
+  // names. Empty by default.
+  widgetStyles: Object.freeze({}),
 });
 
 // REQ-THEME-15 (sc-1497) — per-component style tokens. The global palette is a
@@ -130,6 +139,32 @@ const THEME_COMPONENT_GRADIENT = Object.freeze({
   defaultAngle: 180,
 });
 
+// REQ-THEME-LOOK: the app-wide SPACING MULTIPLIER. Layout spacing lives on the
+// NODES -- a container states its own `padding` / `gap` / `margin` -- so a plain
+// theme key could never make an existing app breathe: every node already
+// carried a value and there was no default left to change. This scales those
+// node values at RENDER time instead, on both hosts, which is why it moves a
+// page that was authored long ago. SPACING only -- never radii, font sizes or
+// minHeight -- so a look keeps its shape while its air moves, and the author’s
+// relative proportions survive: a tight table stays tighter than the card
+// beside it.
+// REQ-THEME-ELEMENT: bounds on the per-widget-type style map. `theme_config` is
+// an unbounded JSON bag that an UNAUTHENTICATED GET /tenant/config returns on
+// every cold Player start and that the compiler bakes verbatim into the native
+// export -- so a map that grows with the widget catalog needs a stated ceiling.
+// Declared here so the coercer, the Studio control and the planner prompt agree.
+const THEME_WIDGET_STYLES = Object.freeze({
+  // One entry per widget TYPE, not per instance, so this is generous.
+  maxWidgets: 200,
+  // Matches the styleSchema field cap the widget agent is held to.
+  maxFieldsPerWidget: 12,
+});
+const THEME_SPACING_SCALE = Object.freeze({
+  min: 0.5,
+  max: 2,
+  default: 1,
+});
+
 // The card-surface field names shared by every widget that paints its own card
 // (frontend/src/components/widgets/_shared/cardStyle.js CARD_STYLE_SCHEMA).
 const CARD_SURFACE_FIELDS = Object.freeze({
@@ -159,6 +194,23 @@ const FORM_SUBMIT_FIELDS = Object.freeze({
   gradient: "submitGradient",
 });
 
+// REQ-THEME-WIDGET: the card fields whose NAMES are unambiguous, so they bind to
+// ANY widget that reads them -- including a Mason-generated one, whose id can
+// never appear in a hand-maintained allowlist. That allowlist is why "make the
+// cards darker" reached the nine built-ins and nothing else.
+//
+// `shadow` is deliberately ABSENT: its name is bare and shared with the button
+// scope, so binding it by name would cross the scopes. The bare names stay on
+// the allowlist for exactly that reason -- `appstudio.image` also reads a
+// `background` field, and the button scope must not leak into it.
+const CARD_UNIVERSAL_FIELDS = Object.freeze({
+  background: "cardBackground",
+  borderColor: "cardBorderColor",
+  radius: "cardRadius",
+  padding: "cardPadding",
+  gradient: "cardGradient",
+});
+
 const THEME_COMPONENTS = Object.freeze({
   button: Object.freeze({
     label: "Buttons",
@@ -187,6 +239,7 @@ const THEME_COMPONENTS = Object.freeze({
   }),
   card: Object.freeze({
     label: "Cards",
+    universalFields: CARD_UNIVERSAL_FIELDS,
     tokens: Object.freeze({
       background: Object.freeze({ type: "color", uiDefault: "colors.surface" }),
       borderColor: Object.freeze({ type: "color", uiDefault: "colors.border" }),
@@ -243,8 +296,18 @@ const HOOKS = [
     signature: "useTheme()",
     returnShape: {
       colors:
-        "{ primary, onPrimary, secondary, onSecondary, surface, onSurface, surfaceMuted, onSurfaceMuted, border, danger, success, warning, info }",
+        "{ primary, onPrimary, secondary, onSecondary, surface, onSurface, surfaceMuted, onSurfaceMuted, border, danger, success, warning, info } — " +
+        "REQ-THEME-SURFACE: the surface group (surface / surfaceMuted / onSurface / " +
+        "onSurfaceMuted / border) describes the surface your widget SITS ON, not the " +
+        "page: a container painting its own background re-derives them for its " +
+        "subtree. Read them and your text is readable wherever the widget lands; " +
+        "there is nothing to opt into.",
       spacing: "{ xs, sm, md, lg, xl }",
+      spacingScale:
+        "number — the app-wide spacing multiplier (REQ-THEME-LOOK, default 1). " +
+        "HOST-OWNED: the host already scales layout spacing by it. Read it only " +
+        "if your widget draws its own internal spacing and wants to breathe with " +
+        "the rest of the app.",
       radii: "{ sm, md, lg, pill }",
       typography: "{ fontFamily, sizes: { xs, sm, md, lg, xl, xxl } }",
       components:
@@ -436,6 +499,7 @@ const HOOKS = [
     signature: "useNavigation()",
     returnShape: {
       goTo: "(pageId: string, params?: object) => void",
+      openLink: "(link: string) => boolean",
       goBack: "() => void",
       push: "(pageId: string, params?: object) => void",
       replace: "(pageId: string, params?: object) => void",
@@ -650,7 +714,7 @@ const HOOKS = [
       signedAt: "string | null",
       verdict: "{ valid, checks, content_status, ... } | null",
       loading: "boolean",
-      error: "PermissionError | null",
+      error: "PermissionError | null  // { code, message, retryable }",
       initiate: "() => Promise<{ signature_id, qr, auto_start_token, status }>",
       refresh: "() => Promise<void>",
       cancel: "() => Promise<void>",
@@ -760,9 +824,12 @@ const HOOKS = [
     name: "useDatastoreMutation",
     signature: "useDatastoreMutation(tableId)",
     returnShape: {
-      create: "(record) => Promise<Record>  // rejects with DatastoreError",
-      update: "(id, partial) => Promise<Record>  // rejects with DatastoreError",
-      delete: "(id) => Promise<void>  // rejects with DatastoreError",
+      create:
+        "(record) => Promise<Record>  // rejects with DatastoreError { code, message, retryable } — render the message when retryable is false, never 'try again'",
+      update:
+        "(id, partial) => Promise<Record>  // rejects with DatastoreError { code, message, retryable } — render the message when retryable is false, never 'try again'",
+      delete:
+        "(id) => Promise<void>  // rejects with DatastoreError { code, message, retryable } — render the message when retryable is false, never 'try again'",
     },
     requiredContextSlice: ["datastore.records"],
     scopes: ["datastore.write:*"],
@@ -878,7 +945,7 @@ const HOOKS = [
     returnShape: {
       users: "Array<{ id, name, email?, role, is_active }>  // snake_case rows; unwrapped from { data, meta }",
       loading: "boolean",
-      error: "DirectoryError | null",
+      error: "DirectoryError | null  // { code, message, retryable }",
       refetch: "() => Promise<void>",
       invite:
         "({ email, name, group_ids? }) => Promise<Invite>  // rejects with DirectoryError",
@@ -907,7 +974,7 @@ const HOOKS = [
     returnShape: {
       groups: "Array<{ id, name, member_count }>  // snake_case rows; unwrapped from { data, meta }",
       loading: "boolean",
-      error: "DirectoryError | null",
+      error: "DirectoryError | null  // { code, message, retryable }",
       refetch: "() => Promise<void>",
       create:
         "({ name }) => Promise<Group>  // rejects with DirectoryError",
@@ -946,7 +1013,7 @@ const HOOKS = [
       message: "string | null",
       loading: "boolean",
       statusLoading: "boolean",
-      error: "DirectoryError | null",
+      error: "DirectoryError | null  // { code, message, retryable }",
       startLink: "() => Promise<{ order_ref, qr, auto_start_token, status }>",
       refresh: "() => Promise<void>",
       cancel: "() => Promise<void>",
@@ -1028,7 +1095,7 @@ const HOOKS = [
       permissions:
         "Array<{ id, user_id, group_id, can_read, can_write, can_delete, can_grant }>  // snake_case rows; unwrapped from { data, meta }",
       loading: "boolean",
-      error: "PermissionError | null",
+      error: "PermissionError | null  // { code, message, retryable }",
       grant:
         "({ user_id?, group_id?, can_read?, can_write?, can_delete?, can_grant? }) => Promise<RecordPermission>  // rejects with PermissionError",
       revoke:
@@ -1091,10 +1158,12 @@ const HOOKS = [
     description:
       "Surfaces a short auto-dismissing notification. Returns { showToast }. " +
       "showToast({ kind: 'success' | 'error' | 'info' | 'warning', message }) " +
-      "asks the host to render a workspace-themed toast. If the host hasn't " +
-      "wired a renderer, the web variant dispatches an 'appstudio:widget-toast' " +
-      "CustomEvent on window; native logs to the console. The widget never " +
-      "owns the toast UI — that's the host's responsibility.",
+      "renders a workspace-themed toast. Both shipping hosts paint it — the " +
+      "web Player and the exported Expo app — so a confirmation you raise IS " +
+      "seen by the user; use it to confirm every write. The widget never owns " +
+      "the toast UI, so never build your own banner or call Alert.alert for a " +
+      "routine save. An authoring preview (the Studio canvas) wires no " +
+      "renderer, and there the call is simply a no-op.",
     returnShape: {
       showToast: "({ kind, message }) => void",
     },
@@ -1658,9 +1727,10 @@ const WIDGET_CONTEXT_SHAPE = {
     description:
       "Optional host toast slot. { showToast({ kind, message }): void }. " +
       "The host populates this to render workspace-themed notifications " +
-      "from any widget that calls useToast(). When omitted the SDK falls " +
-      "back to dispatching an 'appstudio:widget-toast' CustomEvent on web " +
-      "and console.log on native.",
+      "from any widget that calls useToast(). Both rendering hosts wire it " +
+      "(the web Player and the compiler's native WidgetHost); authoring " +
+      "surfaces omit it, and the SDK then falls back to dispatching an " +
+      "'appstudio:widget-toast' CustomEvent on web and console.log on native.",
     required: false,
     fields: { showToast: "function" },
   },
@@ -2635,6 +2705,28 @@ const CONTRACT = deepFreeze({
   //    public endpoint instead, which skips the cache, the metering and the
   //    workspace's provider. Publishing the host list here keeps the linter,
   //    the Developer guide and the agent prompt reading one source.
+  // 1.52.0: additive (REQ-THEME-LOOK) -- `themeTokens.spacingScale` (default 1)
+  //    and `themeSpacingScale`, its clamp bounds. A spacing control in the
+  //    Studio could reach nothing that mattered, because layout spacing is
+  //    authored ONTO each node (`padding` / `gap` / `margin`) rather than
+  //    inherited from the theme -- so no theme key could make a built app
+  //    breathe. Both hosts now multiply a node’s resolved spacing by this scale
+  //    at render. SPACING only: radii, font sizes and minHeight are untouched,
+  //    so a look keeps its shape and the author’s proportions hold. Additive:
+  //    no export changed signature and a theme without the key resolves to 1,
+  //    rendering identically to before.
+  // 1.53.0: fix (REQ-THEME-17) -- `isHexColor` accepts the 8-digit
+  //    `#RRGGBBAA` form. The Studio has put an opacity row on every colour
+  //    field since sc-4158, so a brand colour or a page background routinely
+  //    arrives with alpha -- and this predicate rejecting it made
+  //    `themeConfigToTokens` DROP the key, so a translucent dark background
+  //    stopped reaching deriveSurfaceTokens and every panel fell back to white.
+  //    A second, alpha-aware predicate already existed beside it for gradients,
+  //    which is why the asymmetry kept being rediscovered surface by surface;
+  //    there is now one. `hexChannels` ignores the alpha pair, so contrast and
+  //    the derived tints still reason about the opaque colour while the value
+  //    keeps its transparency. Widening only: every input accepted before is
+  //    accepted now, and unchanged.
   // 1.54.0: additive (sc-4399, epic 4395) — `useContainerWidth()` +
   //    `isNarrowWidth(width)` / `NARROW_WIDTH_PX`. Built-in widgets laid
   //    themselves out at a fixed size — UserManagement's rows alone carried
@@ -2666,7 +2758,36 @@ const CONTRACT = deepFreeze({
   //    Developer guide have always said, so a widget written against the
   //    declared shape destructured a function and threw on first interaction.
   //    Declared as a bare callable now; no runtime behaviour changed.
-  version: "1.60.1",
+  // 1.61.0: additive (REQ-THEME-SURFACE / -CARD / -WIDGET / -ELEMENT) -- the
+  //    theme reaches the elements an app is built from. Four things it could
+  //    not touch before, and one mechanism each:
+  //    * `deriveSurfaceTokens` (host export) -- the surface/text/border set is
+  //      derived per PAINTED SURFACE, not once per page, so an UNSET text
+  //      colour is readable inside a coloured container. It was a hand-mirrored
+  //      copy per host; now one symmetric implementation (a light fill resolves
+  //      to the light tokens instead of returning null).
+  //    * `themeComponents.card.universalFields` -- the card scope's unambiguous
+  //      field NAMES bind to any widget that declares them, so a widget whose id
+  //      can never appear in a hand-maintained allowlist still follows "Cards".
+  //      The bare names (`background`, `textColor`, `color`, `fontSize`,
+  //      `shadow`) keep the allowlist: they mean different things per scope.
+  //      `applyThemeComponentStyle` takes an optional 4th `styleSchema` so the
+  //      name-bound fields land only on a widget that reads them.
+  //    * `themeTokens.widgetStyles` + `themeWidgetStyles` bounds +
+  //      `normaliseWidgetStyles` (host export) -- app-wide values keyed by
+  //      widget MANIFEST ID and then by that widget's OWN styleSchema field
+  //      names, so `panelFill` is as reachable as `cardBackground`: no shared
+  //      vocabulary, no allowlist, no naming requirement. Validated
+  //      structurally, because the key space is a workspace's widget catalog
+  //      rather than this contract, and bounded because `theme_config` is
+  //      unbounded, read unauthenticated on every cold Player start, and baked
+  //      verbatim into the native export.
+  //    Precedence: contract default -> palette -> `components.<scope>` ->
+  //    `widgetStyles[manifestId]` -> the author's per-instance `props.style`.
+  //    Naming one widget is strictly more specific than restyling a scope, and
+  //    the Properties Panel stays the final word. Additive throughout: a theme
+  //    that sets none of it resolves exactly as before.
+  version: "1.62.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -2681,6 +2802,8 @@ const CONTRACT = deepFreeze({
   themeComponentShadows: THEME_COMPONENT_SHADOWS,
   themeComponentTextTransforms: THEME_COMPONENT_TEXT_TRANSFORMS,
   themeComponentGradient: THEME_COMPONENT_GRADIENT,
+  themeSpacingScale: THEME_SPACING_SCALE,
+  themeWidgetStyles: THEME_WIDGET_STYLES,
   widgetContextShape: WIDGET_CONTEXT_SHAPE,
   bundleExportContract: BUNDLE_EXPORT_CONTRACT,
   bannedApis: BANNED_APIS,
@@ -2720,12 +2843,31 @@ function requiredContextKeys() {
 // one source removes that drift (CLAUDE.md §3).
 // ---------------------------------------------------------------------------
 
-const HEX_RE = /^#[0-9a-f]{3}([0-9a-f]{3})?$/i;
+// REQ-THEME-17 / sc-4158 — 3, 6 or 8 digits. The 8-digit form carries alpha,
+// and this predicate accepting it is load-bearing: the Studio puts an opacity
+// row on every colour field, so `primaryColor` and `backgroundColor` routinely
+// arrive as `#RRGGBBAA`. While this rejected them, `themeConfigToTokens` DROPPED
+// the key outright — a translucent page background stopped reaching
+// deriveSurfaceTokens and every panel in the app fell back to white.
+//
+// There used to be a second, alpha-aware predicate beside this one for
+// gradients, which is how the asymmetry kept being rediscovered: each new
+// alpha-carrying surface met the strict one first. There is now only this.
+const HEX_RE = /^#(?:[0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
 
 function isHexColor(value) {
   return typeof value === "string" && HEX_RE.test(value);
 }
 
+/**
+ * The R/G/B bytes, with any alpha pair IGNORED.
+ *
+ * Deliberate: everything downstream of this is luminance maths — contrast,
+ * readable text, derived tints — and none of it can composite without knowing
+ * the backdrop, which a token table does not have. Alpha survives in the VALUE
+ * (the host hands `#RRGGBBAA` straight to the renderer); it just takes no part
+ * in deciding whether a colour reads as light or dark.
+ */
 function hexChannels(hex) {
   let h = hex.slice(1);
   if (h.length === 3) {
@@ -2810,6 +2952,54 @@ function deriveAccentTints(primary, surface, onSurface) {
   };
 }
 
+// REQ-THEME-SURFACE: how far a derived surface travels toward white, and the
+// light-on-dark text pair a dark surface carries.
+const SURFACE_LIFT = Object.freeze({ surface: 0.1, surfaceMuted: 0.05, border: 0.18 });
+const DARK_SURFACE_TEXT = Object.freeze({
+  onSurface: "#f8fafc",
+  onSurfaceMuted: "#cbd5e1",
+});
+
+/**
+ * REQ-THEME-DARK: the coherent surface / text / border set one background wants.
+ * A dark background lifts its panels toward white and goes light-on-dark; a
+ * light one resolves to the contract's own light tokens.
+ *
+ * REQ-THEME-SURFACE: applied to the PAGE background and — because every surface
+ * a page is built from may paint its own fill — to a CONTAINER background too.
+ * That is what makes an UNSET text colour readable inside a dark card on a light
+ * page, which is in turn what lets a built app follow its theme instead of
+ * carrying a baked-in hex for every heading.
+ *
+ * Returns all five keys together, never a subset: layering a dark card's text
+ * colour over a light ancestor's surface is exactly how light-on-light happens.
+ * `null` only when the colour is unusable, letting the caller keep what it had.
+ */
+function deriveSurfaceTokens(backgroundColor) {
+  if (!isHexColor(backgroundColor)) return null;
+  // "Dark" = the background wants light text (same luminance test as the
+  // on-color contrast picker).
+  const wantsLightText =
+    readableTextColor(backgroundColor, "__dark__", "__light__") === "__light__";
+  if (!wantsLightText) {
+    const base = DEFAULT_THEME_TOKENS.colors;
+    return {
+      surface: base.surface,
+      surfaceMuted: base.surfaceMuted,
+      onSurface: base.onSurface,
+      onSurfaceMuted: base.onSurfaceMuted,
+      border: base.border,
+    };
+  }
+  return {
+    surface: mixHex(backgroundColor, "#ffffff", SURFACE_LIFT.surface),
+    surfaceMuted: mixHex(backgroundColor, "#ffffff", SURFACE_LIFT.surfaceMuted),
+    onSurface: DARK_SURFACE_TEXT.onSurface,
+    onSurfaceMuted: DARK_SURFACE_TEXT.onSurfaceMuted,
+    border: mixHex(backgroundColor, "#ffffff", SURFACE_LIFT.border),
+  };
+}
+
 /**
  * Map a CSS-style gradient angle (0 = to top, 90 = to right) to the
  * `{ start, end }` unit vectors `expo-linear-gradient` expects (origin at
@@ -2828,9 +3018,10 @@ function gradientAngleToVector(angle) {
   };
 }
 
-// Alpha is allowed here (unlike HEX_RE) because the Mason build runner already
-// persists 8-digit component colours; the host must not drop what it accepted.
-const GRADIENT_HEX_RE = /^#(?:[0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+// Gradients used to need their own alpha-aware predicate because HEX_RE was not.
+// HEX_RE is now, so this is the same check by another name — kept only as a
+// local alias so the call sites below read as before.
+const GRADIENT_HEX_RE = HEX_RE;
 
 /**
  * sc-3727 — normalise a component `gradient` to `{ from, to, angle }`, or `null`.
@@ -2855,8 +3046,33 @@ function normaliseComponentGradient(raw) {
   return { from, to, angle: ((deg % 360) + 360) % 360 };
 }
 
+// REQ-THEME-LOOK: coerce a theme's spacing scale into the usable band. Shared
+// because BOTH hosts multiply node spacing by it and a disagreement here would
+// re-space an exported page against the Player. Anything absent, non-finite or
+// out of band resolves to 1 (unchanged) rather than throwing -- `theme_config`
+// is a JSON bag a workspace admin can PUT verbatim.
+function clampSpacingScale(value) {
+  // Absent means UNSET, not "as tight as possible" — Number(null) and Number("")
+  // are both 0, which would otherwise clamp an untouched theme to the minimum.
+  if (value === null || value === undefined || value === "") {
+    return THEME_SPACING_SCALE.default;
+  }
+  const n = typeof value === "number" ? value : Number(value);
+  if (!Number.isFinite(n)) return THEME_SPACING_SCALE.default;
+  return Math.min(Math.max(n, THEME_SPACING_SCALE.min), THEME_SPACING_SCALE.max);
+}
+
+// REQ-THEME-LOOK: apply that scale to ONE spacing value. Rounded to whole
+// pixels so a scaled gap stays on the same pixel grid as an unscaled one.
+function scaleSpacing(value, scale) {
+  if (typeof value !== "number" || !Number.isFinite(value)) return value;
+  return Math.round(value * clampSpacingScale(scale));
+}
+
 export {
   CONTRACT,
+  clampSpacingScale,
+  scaleSpacing,
   isHookAllowed,
   requiredContextKeys,
   isHexColor,
@@ -2864,6 +3080,7 @@ export {
   contrastRatio,
   readableTextColor,
   deriveAccentTints,
+  deriveSurfaceTokens,
   gradientAngleToVector,
   normaliseComponentGradient,
   formatMoneyIn,