@colixsystems/widget-sdk 0.96.0 → 0.97.0

package/README.md

@@ -66,6 +66,11 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 `v0.91.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.97.0 (contract 1.69.0)
+
+**`CONTRACT.themeComponents` gains five scopes: `accent`, `destructive`, `muted`, `popover`, `ring` (sc-5392).** The vocabulary shipped with exactly `button`/`card`/`text` (sc-1497), so a shadcn/Tailwind app import's `--accent`, `--destructive`, `--muted`, `--popover` and `--ring` custom properties had no `themeConfig` home and were reported "no theme home" on every import. Each new scope binds to real `styleSchema` fields on the built-ins that already had a matching surface — `accent` (a highlight/tag surface: `background`/`borderColor`/`radius`) to the Label widget's own fields, `destructive` (a themed danger/delete action: `background`/`textColor`/`borderColor`) to a new "Danger" Button variant, `muted` (a subtle/secondary surface: `background`/`textColor`/`borderColor`/`radius`) to Form Input's and Form Builder's pre-existing input fields, `popover` (a dropdown/menu surface: `background`/`textColor`/`borderColor`) to the same two widgets' choice-field option list, and `ring` (the app-wide focus-visible outline: `color`/`width`) to a new emphasis border on Button. **This is HOST-ONLY plumbing, exactly like the three scopes before it** — `useTheme()`'s documented `components` slice is unchanged, no widget-authoring hook or `propertySchema` type moved, and no scope declares `universalFields`, so a third-party or AI-generated widget's contract is unaffected; the Developer guide and `DEFAULT_SYSTEM_PROMPT` need no update because neither ever documented this internal vocabulary. Fully additive: a theme with no `components` key, or one using only `button`/`card`/`text`, resolves exactly as before.
+- **`CONTRACT.version` → `1.69.0`** (additive: five new `themeComponents` scopes + their target-field bindings). No existing scope, token, or export changed shape.
+
 ### What's new in 0.96.0 (contract 1.68.0)
 
 **A manifest action can declare `manual`, and every action script gains a `request` global (sc-5366).** The backend Action model grew three ways of *reaching* a script to sit beside the ones that *fire* it: `manual` (nothing starts it — the workspace runs it on demand), `app` (a published app's button `onPress`) and `http_post` (an inbound webhook at `POST /api/v1/action-hooks/:actionId`, authenticated with one of the workspace's integration API keys). The same change retired the separate `appInvokable` boolean, so one column now answers "what starts this action?".

package/dist/contract.cjs

@@ -211,6 +211,34 @@ const CARD_UNIVERSAL_FIELDS = Object.freeze({
   gradient: "cardGradient",
 });
 
+// The Form widgets' text-entry surface, already read by both form widgets
+// (REQ-THEME-13, predating this scope) -- a genuine subtle/secondary surface
+// distinct from the card that hosts it.
+const MUTED_INPUT_FIELDS = Object.freeze({
+  background: "inputBackground",
+  textColor: "inputTextColor",
+  borderColor: "inputBorderColor",
+  radius: "inputRadius",
+});
+
+// The Form widgets' choice-field option list -- the closest thing this
+// catalog has to a menu/dropdown surface (singleChoice/multiChoice render an
+// inline list of options here).
+const POPOVER_FIELDS = Object.freeze({
+  background: "popoverBackground",
+  textColor: "popoverTextColor",
+  borderColor: "popoverBorderColor",
+});
+
+// The Button widget's danger-variant fields -- kept separate from its own
+// `background`/`textColor`/`borderColor` (the `button` scope's fields above)
+// so a themed destructive action never collides with the button's normal look.
+const DANGER_BUTTON_FIELDS = Object.freeze({
+  background: "dangerBackground",
+  textColor: "dangerTextColor",
+  borderColor: "dangerBorderColor",
+});
+
 const THEME_COMPONENTS = Object.freeze({
   button: Object.freeze({
     label: "Buttons",
@@ -277,6 +305,82 @@ const THEME_COMPONENTS = Object.freeze({
       "appstudio.data-value": TEXT_TYPOGRAPHY_FIELDS,
     }),
   }),
+  // sc-5392 -- a highlight/tag surface. Bound to Label's OWN background/
+  // borderColor/radius fields (REQ-THEME-13, predating this scope) rather
+  // than its `color` field, which the `text` scope already owns -- two
+  // scopes writing the same field on the same widget would race.
+  accent: Object.freeze({
+    label: "Accent",
+    tokens: Object.freeze({
+      background: Object.freeze({ type: "color", uiDefault: "colors.primarySoft" }),
+      borderColor: Object.freeze({ type: "color", uiDefault: "colors.primary" }),
+      radius: Object.freeze({ type: "size", min: 0, max: 48, uiDefault: "radii.pill" }),
+    }),
+    targets: Object.freeze({
+      "appstudio.label": Object.freeze({
+        background: "background",
+        borderColor: "borderColor",
+        radius: "radius",
+      }),
+    }),
+  }),
+  // sc-5392 -- the Button widget's danger/delete variant. Separate token set
+  // from `button` above so "make the buttons coral" never recolours Delete.
+  destructive: Object.freeze({
+    label: "Destructive",
+    tokens: Object.freeze({
+      background: Object.freeze({ type: "color", uiDefault: "colors.danger" }),
+      textColor: Object.freeze({ type: "color", uiDefault: "colors.onPrimary" }),
+      borderColor: Object.freeze({ type: "color", uiDefault: "colors.danger" }),
+    }),
+    targets: Object.freeze({
+      "appstudio.button": DANGER_BUTTON_FIELDS,
+    }),
+  }),
+  // sc-5392 -- a subtle/secondary surface, bound to the form widgets' own
+  // text-entry fields (already REQ-THEME-13 style fields, predating this
+  // scope) rather than to Text/Label/Data Value, whose `color` field the
+  // `text` scope already owns.
+  muted: Object.freeze({
+    label: "Muted",
+    tokens: Object.freeze({
+      background: Object.freeze({ type: "color", uiDefault: "colors.surfaceMuted" }),
+      textColor: Object.freeze({ type: "color", uiDefault: "colors.onSurfaceMuted" }),
+      borderColor: Object.freeze({ type: "color", uiDefault: "colors.border" }),
+      radius: Object.freeze({ type: "size", min: 0, max: 48, uiDefault: "radii.sm" }),
+    }),
+    targets: Object.freeze({
+      "appstudio.form-input": MUTED_INPUT_FIELDS,
+      "appstudio.form-builder": MUTED_INPUT_FIELDS,
+    }),
+  }),
+  // sc-5392 -- dropdown/menu surfaces. The form widgets' choice-field option
+  // list is the closest thing the built-in catalog has to a popover panel.
+  popover: Object.freeze({
+    label: "Popover",
+    tokens: Object.freeze({
+      background: Object.freeze({ type: "color", uiDefault: "colors.surface" }),
+      textColor: Object.freeze({ type: "color", uiDefault: "colors.onSurface" }),
+      borderColor: Object.freeze({ type: "color", uiDefault: "colors.border" }),
+    }),
+    targets: Object.freeze({
+      "appstudio.form-input": POPOVER_FIELDS,
+      "appstudio.form-builder": POPOVER_FIELDS,
+    }),
+  }),
+  // sc-5392 -- the app-wide focus-visible outline. A themed emphasis border
+  // on the Button widget, applied after its variant colours and beaten by the
+  // widget's own per-instance `borderColor` (REQ-THEME-13 stays final).
+  ring: Object.freeze({
+    label: "Focus ring",
+    tokens: Object.freeze({
+      color: Object.freeze({ type: "color", uiDefault: "colors.primary" }),
+      width: Object.freeze({ type: "size", min: 0, max: 8 }),
+    }),
+    targets: Object.freeze({
+      "appstudio.button": Object.freeze({ color: "ringColor", width: "ringWidth" }),
+    }),
+  }),
 });
 
 // sc-4505 — the value types a widget event payload field may declare. Narrower
@@ -2956,7 +3060,12 @@ const CONTRACT = deepFreeze({
   //    action script now sees a `request` global — `{ body }` on a run fired
   //    by the workspace-granted `http_post` webhook trigger, null otherwise.
   //    `app` and `http_post` stay operator-granted and are NOT declarable.
-  version: "1.68.0",
+  // 1.69.0: additive (sc-5392) — `themeComponents` gains five scopes:
+  //    `accent`, `destructive`, `muted`, `popover` and `ring`, so a
+  //    shadcn/Tailwind import's matching custom properties have a themeConfig
+  //    home instead of being reported lost. Host-only plumbing: no scope
+  //    declares `universalFields`, so a third-party manifest is unaffected.
+  version: "1.69.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -211,6 +211,34 @@ const CARD_UNIVERSAL_FIELDS = Object.freeze({
   gradient: "cardGradient",
 });
 
+// The Form widgets' text-entry surface, already read by both form widgets
+// (REQ-THEME-13, predating this scope) -- a genuine subtle/secondary surface
+// distinct from the card that hosts it.
+const MUTED_INPUT_FIELDS = Object.freeze({
+  background: "inputBackground",
+  textColor: "inputTextColor",
+  borderColor: "inputBorderColor",
+  radius: "inputRadius",
+});
+
+// The Form widgets' choice-field option list -- the closest thing this
+// catalog has to a menu/dropdown surface (singleChoice/multiChoice render an
+// inline list of options here).
+const POPOVER_FIELDS = Object.freeze({
+  background: "popoverBackground",
+  textColor: "popoverTextColor",
+  borderColor: "popoverBorderColor",
+});
+
+// The Button widget's danger-variant fields -- kept separate from its own
+// `background`/`textColor`/`borderColor` (the `button` scope's fields above)
+// so a themed destructive action never collides with the button's normal look.
+const DANGER_BUTTON_FIELDS = Object.freeze({
+  background: "dangerBackground",
+  textColor: "dangerTextColor",
+  borderColor: "dangerBorderColor",
+});
+
 const THEME_COMPONENTS = Object.freeze({
   button: Object.freeze({
     label: "Buttons",
@@ -277,6 +305,82 @@ const THEME_COMPONENTS = Object.freeze({
       "appstudio.data-value": TEXT_TYPOGRAPHY_FIELDS,
     }),
   }),
+  // sc-5392 -- a highlight/tag surface. Bound to Label's OWN background/
+  // borderColor/radius fields (REQ-THEME-13, predating this scope) rather
+  // than its `color` field, which the `text` scope already owns -- two
+  // scopes writing the same field on the same widget would race.
+  accent: Object.freeze({
+    label: "Accent",
+    tokens: Object.freeze({
+      background: Object.freeze({ type: "color", uiDefault: "colors.primarySoft" }),
+      borderColor: Object.freeze({ type: "color", uiDefault: "colors.primary" }),
+      radius: Object.freeze({ type: "size", min: 0, max: 48, uiDefault: "radii.pill" }),
+    }),
+    targets: Object.freeze({
+      "appstudio.label": Object.freeze({
+        background: "background",
+        borderColor: "borderColor",
+        radius: "radius",
+      }),
+    }),
+  }),
+  // sc-5392 -- the Button widget's danger/delete variant. Separate token set
+  // from `button` above so "make the buttons coral" never recolours Delete.
+  destructive: Object.freeze({
+    label: "Destructive",
+    tokens: Object.freeze({
+      background: Object.freeze({ type: "color", uiDefault: "colors.danger" }),
+      textColor: Object.freeze({ type: "color", uiDefault: "colors.onPrimary" }),
+      borderColor: Object.freeze({ type: "color", uiDefault: "colors.danger" }),
+    }),
+    targets: Object.freeze({
+      "appstudio.button": DANGER_BUTTON_FIELDS,
+    }),
+  }),
+  // sc-5392 -- a subtle/secondary surface, bound to the form widgets' own
+  // text-entry fields (already REQ-THEME-13 style fields, predating this
+  // scope) rather than to Text/Label/Data Value, whose `color` field the
+  // `text` scope already owns.
+  muted: Object.freeze({
+    label: "Muted",
+    tokens: Object.freeze({
+      background: Object.freeze({ type: "color", uiDefault: "colors.surfaceMuted" }),
+      textColor: Object.freeze({ type: "color", uiDefault: "colors.onSurfaceMuted" }),
+      borderColor: Object.freeze({ type: "color", uiDefault: "colors.border" }),
+      radius: Object.freeze({ type: "size", min: 0, max: 48, uiDefault: "radii.sm" }),
+    }),
+    targets: Object.freeze({
+      "appstudio.form-input": MUTED_INPUT_FIELDS,
+      "appstudio.form-builder": MUTED_INPUT_FIELDS,
+    }),
+  }),
+  // sc-5392 -- dropdown/menu surfaces. The form widgets' choice-field option
+  // list is the closest thing the built-in catalog has to a popover panel.
+  popover: Object.freeze({
+    label: "Popover",
+    tokens: Object.freeze({
+      background: Object.freeze({ type: "color", uiDefault: "colors.surface" }),
+      textColor: Object.freeze({ type: "color", uiDefault: "colors.onSurface" }),
+      borderColor: Object.freeze({ type: "color", uiDefault: "colors.border" }),
+    }),
+    targets: Object.freeze({
+      "appstudio.form-input": POPOVER_FIELDS,
+      "appstudio.form-builder": POPOVER_FIELDS,
+    }),
+  }),
+  // sc-5392 -- the app-wide focus-visible outline. A themed emphasis border
+  // on the Button widget, applied after its variant colours and beaten by the
+  // widget's own per-instance `borderColor` (REQ-THEME-13 stays final).
+  ring: Object.freeze({
+    label: "Focus ring",
+    tokens: Object.freeze({
+      color: Object.freeze({ type: "color", uiDefault: "colors.primary" }),
+      width: Object.freeze({ type: "size", min: 0, max: 8 }),
+    }),
+    targets: Object.freeze({
+      "appstudio.button": Object.freeze({ color: "ringColor", width: "ringWidth" }),
+    }),
+  }),
 });
 
 // sc-4505 — the value types a widget event payload field may declare. Narrower
@@ -2956,7 +3060,12 @@ const CONTRACT = deepFreeze({
   //    action script now sees a `request` global — `{ body }` on a run fired
   //    by the workspace-granted `http_post` webhook trigger, null otherwise.
   //    `app` and `http_post` stay operator-granted and are NOT declarable.
-  version: "1.68.0",
+  // 1.69.0: additive (sc-5392) — `themeComponents` gains five scopes:
+  //    `accent`, `destructive`, `muted`, `popover` and `ring`, so a
+  //    shadcn/Tailwind import's matching custom properties have a themeConfig
+  //    home instead of being reported lost. Host-only plumbing: no scope
+  //    declares `universalFields`, so a third-party manifest is unaffected.
+  version: "1.69.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/package.json

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