@colixsystems/widget-sdk 0.68.0 → 0.69.0

package/README.md

@@ -61,9 +61,10 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 - **`useTheme()` gains a `components` slice.** It is HOST-OWNED plumbing, not an author API: by the time your component renders, the host has already folded the matching tokens into `props.style`. Do not read `theme.components` and do not re-apply it — you would double-apply the theme and defeat the author's own styling.
 - **New host-only exports on `@colixsystems/widget-sdk/host`:** `normaliseThemeComponents(raw)` and `applyThemeComponentStyle(manifestId, theme, props)`. These are the platform-host surface (the web Player / Studio canvas and the exported Expo app), never the author API — one implementation, so the two hosts cannot diverge.
-- **`CONTRACT.themeComponents` / `CONTRACT.themeComponentShadows`** publish the vocabulary: each scope's tokens, their value types and ranges, and the widget → style-field bindings. `themeTokens.components` defaults to `{}`.
+- **`CONTRACT.themeComponents` / `CONTRACT.themeComponentShadows` / `CONTRACT.themeComponentGradient`** publish the vocabulary: each scope's tokens, their value types and ranges, and the widget → style-field bindings. `themeTokens.components` defaults to `{}`.
+- **The `button` and `card` scopes carry a `gradient` token (sc-3727)** — `{ from: "#hex", to: "#hex", angle: 0-359 }`, painted through the `<Gradient>` primitive. It reaches a widget as an ordinary style field (`gradient`, `cardGradient`, `submitGradient`), so the author rule is unchanged: read `props.style`, and treat an explicit `null` as "this instance opted out of the app-wide gradient" rather than as unset.
 
-`CONTRACT.version` → `1.45.0`. Additive; no existing export changed signature, and an unthemed app renders identically.
+`CONTRACT.version` → `1.46.0`. Additive; no existing export changed signature, and an unthemed app renders identically.
 
 ### What's new in 0.66.0
 

package/dist/contract.cjs

@@ -107,6 +107,17 @@ const DEFAULT_THEME_TOKENS = Object.freeze({
 // cannot drift between what Mason may emit and what a host actually applies.
 const THEME_COMPONENT_SHADOWS = Object.freeze(["none", "sm", "md", "lg"]);
 
+// sc-3727 — the `gradient` token's value shape: two hex stops plus a CSS-degree
+// angle, the same grammar as `themeConfig.backgroundGradient` minus the radial
+// variant (a component fill projects through `<Gradient>`, which is linear-only
+// on both hosts). Declared once so the coercion, the Studio control and the
+// planner prompt agree on the bounds.
+const THEME_COMPONENT_GRADIENT = Object.freeze({
+  angleMin: 0,
+  angleMax: 359,
+  defaultAngle: 180,
+});
+
 // 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({
@@ -115,6 +126,7 @@ const CARD_SURFACE_FIELDS = Object.freeze({
   radius: "cardRadius",
   padding: "cardPadding",
   shadow: "shadow",
+  gradient: "cardGradient",
 });
 
 // A form widget's submit button — the `button` scope reaches it through the
@@ -122,6 +134,7 @@ const CARD_SURFACE_FIELDS = Object.freeze({
 const FORM_SUBMIT_FIELDS = Object.freeze({
   background: "submitBackground",
   textColor: "submitTextColor",
+  gradient: "submitGradient",
 });
 
 const THEME_COMPONENTS = Object.freeze({
@@ -134,6 +147,7 @@ const THEME_COMPONENTS = Object.freeze({
       radius: Object.freeze({ type: "size", min: 0, max: 48, uiDefault: "radii.sm" }),
       fontSize: Object.freeze({ type: "size", min: 8, max: 96, uiDefault: "typography.sizes.sm" }),
       shadow: Object.freeze({ type: "shadow" }),
+      gradient: Object.freeze({ type: "gradient" }),
     }),
     targets: Object.freeze({
       "appstudio.button": Object.freeze({
@@ -143,6 +157,7 @@ const THEME_COMPONENTS = Object.freeze({
         radius: "radius",
         fontSize: "fontSize",
         shadow: "shadow",
+        gradient: "gradient",
       }),
       "appstudio.form-input": FORM_SUBMIT_FIELDS,
       "appstudio.form-builder": FORM_SUBMIT_FIELDS,
@@ -156,6 +171,7 @@ const THEME_COMPONENTS = Object.freeze({
       radius: Object.freeze({ type: "size", min: 0, max: 48, uiDefault: "radii.md" }),
       padding: Object.freeze({ type: "size", min: 0, max: 64, uiDefault: "spacing.md" }),
       shadow: Object.freeze({ type: "shadow" }),
+      gradient: Object.freeze({ type: "gradient" }),
     }),
     targets: Object.freeze({
       "appstudio.user": CARD_SURFACE_FIELDS,
@@ -166,6 +182,7 @@ const THEME_COMPONENTS = Object.freeze({
       "appstudio.notifications": CARD_SURFACE_FIELDS,
       "appstudio.form-input": CARD_SURFACE_FIELDS,
       "appstudio.form-builder": CARD_SURFACE_FIELDS,
+      "appstudio.user-management": CARD_SURFACE_FIELDS,
     }),
   }),
   text: Object.freeze({
@@ -2150,7 +2167,21 @@ const CONTRACT = deepFreeze({
   //    (`@colixsystems/widget-sdk/host`), never the author surface. Additive: no
   //    export changed signature and a theme with no `components` key resolves to
   //    an empty override, rendering identically to before.
-  version: "1.45.0",
+  // 1.46.0: additive (sc-3727) — a `gradient` token type on the per-component
+  //    vocabulary. The `button` and `card` scopes each gain a `gradient` token
+  //    whose value is `{ from: "#hex", to: "#hex", angle: 0-359 }` — the
+  //    `backgroundGradient` grammar minus the radial variant, because a component
+  //    fill paints through the `<Gradient>` primitive, which is linear on both
+  //    hosts. `themeComponentGradient` publishes the angle bounds + default so the
+  //    coercion, the Studio control and the planner prompt cannot disagree. The
+  //    token binds to per-instance style fields the target widgets read
+  //    (`gradient` on Button, `cardGradient` on every card surface,
+  //    `submitGradient` on a form's submit button), so the theme value is a
+  //    DEFAULT an author overrides per instance — or suppresses with an explicit
+  //    null, which is how one button stays flat while the rest are gradiented.
+  //    Additive: no export changed signature and a theme with no gradient token
+  //    renders exactly as before.
+  version: "1.46.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -2163,6 +2194,7 @@ const CONTRACT = deepFreeze({
   themeTokens: DEFAULT_THEME_TOKENS,
   themeComponents: THEME_COMPONENTS,
   themeComponentShadows: THEME_COMPONENT_SHADOWS,
+  themeComponentGradient: THEME_COMPONENT_GRADIENT,
   widgetContextShape: WIDGET_CONTEXT_SHAPE,
   bundleExportContract: BUNDLE_EXPORT_CONTRACT,
   bannedApis: BANNED_APIS,
@@ -2305,6 +2337,33 @@ 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;
+
+/**
+ * sc-3727 — normalise a component `gradient` to `{ from, to, angle }`, or `null`.
+ *
+ * ONE validator for a value arriving by two routes — the theme token and the
+ * author's never-coerced per-instance `props.style` — so `set_theme` and the
+ * renderer cannot disagree about the same value (CLAUDE.md §3). Both stops are
+ * required: a one-stop gradient would paint a fill the author never chose. The
+ * hex grammar is also the injection guard — these stops are interpolated into
+ * CSS and into generated export source.
+ */
+function normaliseComponentGradient(raw) {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const from = typeof raw.from === "string" ? raw.from.trim() : "";
+  const to = typeof raw.to === "string" ? raw.to.trim() : "";
+  if (!GRADIENT_HEX_RE.test(from) || !GRADIENT_HEX_RE.test(to)) return null;
+  const { defaultAngle } = THEME_COMPONENT_GRADIENT;
+  // Read once — a second read of an accessor could return a different value and
+  // land NaN in a style.
+  const angle = raw.angle;
+  const deg = Number.isFinite(angle) ? Math.round(angle) : defaultAngle;
+  return { from, to, angle: ((deg % 360) + 360) % 360 };
+}
+
 module.exports = {
   CONTRACT,
   isHookAllowed,
@@ -2315,6 +2374,7 @@ module.exports = {
   readableTextColor,
   deriveAccentTints,
   gradientAngleToVector,
+  normaliseComponentGradient,
   widgetTranslationPrefix,
   widgetTranslationKey,
   sharedTranslationPrefix,

package/dist/contract.js

@@ -107,6 +107,17 @@ const DEFAULT_THEME_TOKENS = Object.freeze({
 // cannot drift between what Mason may emit and what a host actually applies.
 const THEME_COMPONENT_SHADOWS = Object.freeze(["none", "sm", "md", "lg"]);
 
+// sc-3727 — the `gradient` token's value shape: two hex stops plus a CSS-degree
+// angle, the same grammar as `themeConfig.backgroundGradient` minus the radial
+// variant (a component fill projects through `<Gradient>`, which is linear-only
+// on both hosts). Declared once so the coercion, the Studio control and the
+// planner prompt agree on the bounds.
+const THEME_COMPONENT_GRADIENT = Object.freeze({
+  angleMin: 0,
+  angleMax: 359,
+  defaultAngle: 180,
+});
+
 // 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({
@@ -115,6 +126,7 @@ const CARD_SURFACE_FIELDS = Object.freeze({
   radius: "cardRadius",
   padding: "cardPadding",
   shadow: "shadow",
+  gradient: "cardGradient",
 });
 
 // A form widget's submit button — the `button` scope reaches it through the
@@ -122,6 +134,7 @@ const CARD_SURFACE_FIELDS = Object.freeze({
 const FORM_SUBMIT_FIELDS = Object.freeze({
   background: "submitBackground",
   textColor: "submitTextColor",
+  gradient: "submitGradient",
 });
 
 const THEME_COMPONENTS = Object.freeze({
@@ -134,6 +147,7 @@ const THEME_COMPONENTS = Object.freeze({
       radius: Object.freeze({ type: "size", min: 0, max: 48, uiDefault: "radii.sm" }),
       fontSize: Object.freeze({ type: "size", min: 8, max: 96, uiDefault: "typography.sizes.sm" }),
       shadow: Object.freeze({ type: "shadow" }),
+      gradient: Object.freeze({ type: "gradient" }),
     }),
     targets: Object.freeze({
       "appstudio.button": Object.freeze({
@@ -143,6 +157,7 @@ const THEME_COMPONENTS = Object.freeze({
         radius: "radius",
         fontSize: "fontSize",
         shadow: "shadow",
+        gradient: "gradient",
       }),
       "appstudio.form-input": FORM_SUBMIT_FIELDS,
       "appstudio.form-builder": FORM_SUBMIT_FIELDS,
@@ -156,6 +171,7 @@ const THEME_COMPONENTS = Object.freeze({
       radius: Object.freeze({ type: "size", min: 0, max: 48, uiDefault: "radii.md" }),
       padding: Object.freeze({ type: "size", min: 0, max: 64, uiDefault: "spacing.md" }),
       shadow: Object.freeze({ type: "shadow" }),
+      gradient: Object.freeze({ type: "gradient" }),
     }),
     targets: Object.freeze({
       "appstudio.user": CARD_SURFACE_FIELDS,
@@ -166,6 +182,7 @@ const THEME_COMPONENTS = Object.freeze({
       "appstudio.notifications": CARD_SURFACE_FIELDS,
       "appstudio.form-input": CARD_SURFACE_FIELDS,
       "appstudio.form-builder": CARD_SURFACE_FIELDS,
+      "appstudio.user-management": CARD_SURFACE_FIELDS,
     }),
   }),
   text: Object.freeze({
@@ -2150,7 +2167,21 @@ const CONTRACT = deepFreeze({
   //    (`@colixsystems/widget-sdk/host`), never the author surface. Additive: no
   //    export changed signature and a theme with no `components` key resolves to
   //    an empty override, rendering identically to before.
-  version: "1.45.0",
+  // 1.46.0: additive (sc-3727) — a `gradient` token type on the per-component
+  //    vocabulary. The `button` and `card` scopes each gain a `gradient` token
+  //    whose value is `{ from: "#hex", to: "#hex", angle: 0-359 }` — the
+  //    `backgroundGradient` grammar minus the radial variant, because a component
+  //    fill paints through the `<Gradient>` primitive, which is linear on both
+  //    hosts. `themeComponentGradient` publishes the angle bounds + default so the
+  //    coercion, the Studio control and the planner prompt cannot disagree. The
+  //    token binds to per-instance style fields the target widgets read
+  //    (`gradient` on Button, `cardGradient` on every card surface,
+  //    `submitGradient` on a form's submit button), so the theme value is a
+  //    DEFAULT an author overrides per instance — or suppresses with an explicit
+  //    null, which is how one button stays flat while the rest are gradiented.
+  //    Additive: no export changed signature and a theme with no gradient token
+  //    renders exactly as before.
+  version: "1.46.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -2163,6 +2194,7 @@ const CONTRACT = deepFreeze({
   themeTokens: DEFAULT_THEME_TOKENS,
   themeComponents: THEME_COMPONENTS,
   themeComponentShadows: THEME_COMPONENT_SHADOWS,
+  themeComponentGradient: THEME_COMPONENT_GRADIENT,
   widgetContextShape: WIDGET_CONTEXT_SHAPE,
   bundleExportContract: BUNDLE_EXPORT_CONTRACT,
   bannedApis: BANNED_APIS,
@@ -2305,6 +2337,33 @@ 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;
+
+/**
+ * sc-3727 — normalise a component `gradient` to `{ from, to, angle }`, or `null`.
+ *
+ * ONE validator for a value arriving by two routes — the theme token and the
+ * author's never-coerced per-instance `props.style` — so `set_theme` and the
+ * renderer cannot disagree about the same value (CLAUDE.md §3). Both stops are
+ * required: a one-stop gradient would paint a fill the author never chose. The
+ * hex grammar is also the injection guard — these stops are interpolated into
+ * CSS and into generated export source.
+ */
+function normaliseComponentGradient(raw) {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const from = typeof raw.from === "string" ? raw.from.trim() : "";
+  const to = typeof raw.to === "string" ? raw.to.trim() : "";
+  if (!GRADIENT_HEX_RE.test(from) || !GRADIENT_HEX_RE.test(to)) return null;
+  const { defaultAngle } = THEME_COMPONENT_GRADIENT;
+  // Read once — a second read of an accessor could return a different value and
+  // land NaN in a style.
+  const angle = raw.angle;
+  const deg = Number.isFinite(angle) ? Math.round(angle) : defaultAngle;
+  return { from, to, angle: ((deg % 360) + 360) % 360 };
+}
+
 export {
   CONTRACT,
   isHookAllowed,
@@ -2315,6 +2374,7 @@ export {
   readableTextColor,
   deriveAccentTints,
   gradientAngleToVector,
+  normaliseComponentGradient,
   widgetTranslationPrefix,
   widgetTranslationKey,
   sharedTranslationPrefix,

package/dist/host.d.ts

@@ -12,7 +12,17 @@ export function resolveProps<T = Record<string, unknown>>(
   props: unknown,
 ): T;
 
-export type ThemeComponentStyle = Record<string, string | number>;
+// sc-3727: a `gradient` token's value, the one non-scalar token type.
+export interface ThemeComponentGradient {
+  from: string;
+  to: string;
+  angle: number;
+}
+
+export type ThemeComponentStyle = Record<
+  string,
+  string | number | ThemeComponentGradient
+>;
 export type ThemeComponents = Record<string, ThemeComponentStyle>;
 
 /**

package/dist/index.d.ts

@@ -1432,6 +1432,22 @@ export function gradientAngleToVector(angle: number): {
   end: { x: number; y: number };
 };
 
+export interface ComponentGradient {
+  from: string;
+  to: string;
+  angle: number;
+}
+
+/**
+ * Normalise a component `gradient` style value to `{ from, to, angle }`, or null
+ * when it is unusable. Both stops are required; the angle wraps into 0-359.
+ * Shared by the theme-token coercion and the widget render path, so the same
+ * value cannot resolve two ways.
+ */
+export function normaliseComponentGradient(
+  raw: unknown,
+): ComponentGradient | null;
+
 // Linter
 export interface LintFinding {
   rule: string;

package/dist/index.js

@@ -88,5 +88,6 @@ export {
   readableTextColor,
   deriveAccentTints,
   gradientAngleToVector,
+  normaliseComponentGradient,
 } from "./contract.js";
 export { normalizeLucideIconName } from "./lucideIconName.js";

package/dist/index.native.js

@@ -86,5 +86,6 @@ export {
   readableTextColor,
   deriveAccentTints,
   gradientAngleToVector,
+  normaliseComponentGradient,
 } from "./contract.js";
 export { normalizeLucideIconName } from "./lucideIconName.js";

package/dist/theme-components.cjs

@@ -23,7 +23,7 @@
 // widget reads. The Mason build runner validates `set_theme` against the SAME
 // literal, so what a planner may emit and what a host applies cannot diverge.
 
-const { CONTRACT } = require("./contract.cjs");
+const { CONTRACT, normaliseComponentGradient } = require("./contract.cjs");
 
 // 3-, 6- and 8-digit hex, matching what the build runner persists — the host
 // must never drop a colour the runner already accepted.
@@ -47,6 +47,11 @@ function coerceToken(def, value) {
   if (def.type === "shadow") {
     return CONTRACT.themeComponentShadows.includes(value) ? value : undefined;
   }
+  // sc-3727: the gradient value has its own normaliser on the contract, shared
+  // with the widget render path so both routes agree (CLAUDE.md §3).
+  if (def.type === "gradient") {
+    return normaliseComponentGradient(value) || undefined;
+  }
   return undefined;
 }
 

package/dist/theme-components.js

@@ -15,7 +15,7 @@
 // widget reads. The Mason build runner validates `set_theme` against the SAME
 // literal, so what a planner may emit and what a host applies cannot diverge.
 
-import { CONTRACT } from "./contract.js";
+import { CONTRACT, normaliseComponentGradient } from "./contract.js";
 
 // 3-, 6- and 8-digit hex, matching what the build runner persists — the host
 // must never drop a colour the runner already accepted.
@@ -39,6 +39,11 @@ function coerceToken(def, value) {
   if (def.type === "shadow") {
     return CONTRACT.themeComponentShadows.includes(value) ? value : undefined;
   }
+  // sc-3727: the gradient value has its own normaliser on the contract, shared
+  // with the widget render path so both routes agree (CLAUDE.md §3).
+  if (def.type === "gradient") {
+    return normaliseComponentGradient(value) || undefined;
+  }
   return undefined;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.68.0",
+  "version": "0.69.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",