@colixsystems/widget-sdk 0.107.0 → 0.108.0

package/README.md

@@ -17,7 +17,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 
 | Group | Hook (signature) | Returns | Reads / scope |
 | ----- | ---------------- | ------- | ------------- |
-| **CORE** | `useTheme()` | `{ colors, elevation, spacing, spacingScale, radii, typography, components, widgetStyles }` | `ctx.workspace.theme` — no scope. `elevation` is the shared depth scale (`none / sm / md / lg / xl`) you spread into a style; `colors` includes the accent's quiet tiers (`primarySoft` / `onPrimarySoft` / `primaryStrong`). `components` is HOST-OWNED (the theme's per-component style tokens); the host has already folded it into your `props.style`, so read `useWidgetStyle()` and ignore this slice. |
+| **CORE** | `useTheme()` | `{ colors, elevation, spacing, spacingScale, radii, typography, components, widgetStyles }` | `ctx.workspace.theme` — no scope. `elevation` is the shared depth scale (`none / sm / md / lg / xl`) you spread into a style; `colors` includes the accent's quiet tiers (`primarySoft` / `onPrimarySoft` / `primaryStrong`) and `loader`, the spinner colour for your own loading state. `components` is HOST-OWNED (the theme's per-component style tokens); the host has already folded it into your `props.style`, so read `useWidgetStyle()` and ignore this slice. |
 | **CORE** | `useWorkspaceCurrency()` | `{ currency, formatMoney }` | `ctx.workspace.currency` — no scope. The currency this workspace charges its app users in, resolved at RENDER time. Render every price as `formatMoney(minorUnits)` and never write a currency symbol or code into a widget: the owner can change it after the widget ships, and a baked label then contradicts the charge. |
 | **CORE** | `useWidgetStyle()` | `{ [styleField]: value }` | `ctx.props.style` — no scope. The author-set per-widget style values declared in `manifest.styleSchema`; apply each onto whatever element you choose. |
 | **CORE** | `useUser()` | `{ id, email, displayName, roles, groupIds }` | `ctx.user` (host-built context, **camelCase** — not a wire payload; `id` null when anonymous) — no scope |
@@ -68,7 +68,20 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.107.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**.
+`v0.108.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.108.0 (contract 1.82.0)
+
+**`themeTokens.colors` gains `loader` — the surface's spinner colour (sc-6095).** A widget that drew its own loading state had no token for it, so it reached for a literal grey. On a dark theme that grey vanished into the background and the widget looked frozen rather than busy — the same bug the host's own loading holds had.
+
+`loader` tracks `onSurfaceMuted`, which means it rides the existing REQ-THEME-SURFACE derivation: it flips light on a dark page background, and it re-derives for a container that paints its own dark fill, exactly like the text colours around it. So reading it is enough — there is nothing to branch on:
+
+```js
+const t = useTheme();
+if (loading) return <ActivityIndicator color={t.colors.loader} />;
+```
+
+The workspace's *Design → Loading Indicator* panel can override it app-wide; unset, it stays derived. Additive — the full `colors` shape is now `{ primary, onPrimary, primarySoft, onPrimarySoft, primaryStrong, secondary, onSecondary, surface, onSurface, surfaceMuted, onSurfaceMuted, border, loader, danger, success, warning, info }`.
 
 ### What's new in 0.107.0 (contract 1.81.0)
 
@@ -388,7 +401,7 @@ Additive — one new hook, one new optional device capability, one new error cla
 
 - **The workspace theme now reaches the elements an app is built from.** Three things that used to be unreachable are now themeable: an element inside YOUR widget, the structural card container a page is made of, and any style field whose name the platform does not know. For a widget author the practical change is that **your `styleSchema` is the contract**: every field you declare becomes a knob the workspace owner can set once for the whole app, so declare the fields that describe your widget's appearance and give them clear `label`s and `ui.group`s — those labels are what the owner reads.
 - **A field name you invented is as reachable as a canonical one.** A theme may carry values keyed by your widget's manifest id and then by your own field names, so `panelFill` is adjustable app-wide exactly like `cardBackground`. Separately, the unambiguous card names (`cardBackground`, `cardBorderColor`, `cardRadius`, `cardPadding`, `cardGradient`) bind by NAME to any widget that declares them, so naming a genuine card surface canonically opts it into the workspace's Cards controls for free.
-- **`useTheme().colors` describes the surface your widget SITS ON, not the page.** A layout container that paints its own background re-derives the surface roles for everything inside it, so reading `colors.onSurface` for your text is readable whether your widget lands on the page, in a dark hero, or in a light card nested inside that hero. Nothing to opt into.
+- **`useTheme().colors` describes the surface your widget SITS ON, not the page.** A layout container that paints its own background re-derives the surface roles for everything inside it, so reading `colors.onSurface` for your text is readable whether your widget lands on the page, in a dark hero, or in a light card nested inside that hero. `colors.loader` is that same surface's spinner colour — paint your loading state with it rather than a literal grey. Nothing to opt into.
 - **Precedence, unchanged in spirit.** Contract default → workspace palette → component scope → per-widget-type value → the app author's per-instance `props.style`. Most specific wins, and the Properties Panel is still the final word. Your widget reads `props.style` exactly as before and never learns which layer supplied a value.
 - **A colour may carry OPACITY.** `isHexColor` accepts the 8-digit `#RRGGBBAA` form alongside 3 and 6 digits, so a theme colour with an alpha reaches `useTheme()` with its transparency intact. It used to be rejected and the host dropped the key outright, which is why a translucent page background never reached the dark-surface derivation and every panel fell back to white.
 - **The colour maths ignores alpha, on purpose.** `hexChannels` reads the R/G/B pair and skips any alpha, so contrast, readable text and the derived accent tints reason about the opaque colour. None of them can composite without knowing the backdrop, which a token table does not have — so transparency lives in the VALUE your widget renders, not in the decision about whether that colour reads as light or dark.

package/dist/contract.cjs

@@ -64,6 +64,11 @@ const DEFAULT_THEME_TOKENS = Object.freeze({
     onSurface: "#111827",
     surfaceMuted: "#f8fafc",
     onSurfaceMuted: "#475569",
+    // sc-6095: the colour a loading spinner is painted with. A spinner is a
+    // muted foreground mark on the surface it sits on, so it tracks
+    // `onSurfaceMuted`, which deriveSurfaceTokens already flips for a dark
+    // background — so a dark theme gets a visible spinner with no new maths.
+    loader: "#475569",
     border: "#e2e8f0",
     danger: "#dc2626",
     success: "#059669",
@@ -457,12 +462,13 @@ 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, loader, danger, success, warning, info } — " +
         "REQ-THEME-SURFACE: the surface group (surface / surfaceMuted / onSurface / " +
-        "onSurfaceMuted / border) describes the surface your widget SITS ON, not the " +
+        "onSurfaceMuted / border / loader) 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.",
+        "there is nothing to opt into. `loader` is that surface's spinner colour " +
+        "(sc-6095) — paint your own loading state with it rather than a literal grey.",
       spacing: "{ xs, sm, md, lg, xl }",
       spacingScale:
         "number — the app-wide spacing multiplier (REQ-THEME-LOOK, default 1). " +
@@ -3326,7 +3332,16 @@ const CONTRACT = deepFreeze({
   //    through the already-vetted react-native-svg and carries no native
   //    module of its own, so it is host-shimmed on web and pinned in the
   //    export like date-fns. No existing entry changed shape.
-  version: "1.81.0",
+  //
+  // 1.82.0: additive (sc-6095) — `themeTokens.colors` gains `loader`, the
+  //    colour a loading spinner is painted with, and `deriveSurfaceTokens`
+  //    returns it alongside the surface/text/border set. A spinner is a muted
+  //    foreground mark on the surface it sits on, so it tracks `onSurfaceMuted`
+  //    and inherits that set's dark-background flip — which is what makes a
+  //    dark theme's spinner visible instead of grey-on-grey.
+  //    `useTheme().colors.loader` is the value a widget reads for its own
+  //    loading state; both hosts paint their chrome spinners from the same key.
+  version: "1.82.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -3511,7 +3526,7 @@ const DARK_SURFACE_TEXT = Object.freeze({
  * 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
+ * Returns all six 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.
  */
@@ -3528,6 +3543,7 @@ function deriveSurfaceTokens(backgroundColor) {
       surfaceMuted: base.surfaceMuted,
       onSurface: base.onSurface,
       onSurfaceMuted: base.onSurfaceMuted,
+      loader: base.loader,
       border: base.border,
     };
   }
@@ -3536,6 +3552,7 @@ function deriveSurfaceTokens(backgroundColor) {
     surfaceMuted: mixHex(backgroundColor, "#ffffff", SURFACE_LIFT.surfaceMuted),
     onSurface: DARK_SURFACE_TEXT.onSurface,
     onSurfaceMuted: DARK_SURFACE_TEXT.onSurfaceMuted,
+    loader: DARK_SURFACE_TEXT.onSurfaceMuted,
     border: mixHex(backgroundColor, "#ffffff", SURFACE_LIFT.border),
   };
 }

package/dist/contract.js

@@ -64,6 +64,11 @@ const DEFAULT_THEME_TOKENS = Object.freeze({
     onSurface: "#111827",
     surfaceMuted: "#f8fafc",
     onSurfaceMuted: "#475569",
+    // sc-6095: the colour a loading spinner is painted with. A spinner is a
+    // muted foreground mark on the surface it sits on, so it tracks
+    // `onSurfaceMuted`, which deriveSurfaceTokens already flips for a dark
+    // background — so a dark theme gets a visible spinner with no new maths.
+    loader: "#475569",
     border: "#e2e8f0",
     danger: "#dc2626",
     success: "#059669",
@@ -457,12 +462,13 @@ 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, loader, danger, success, warning, info } — " +
         "REQ-THEME-SURFACE: the surface group (surface / surfaceMuted / onSurface / " +
-        "onSurfaceMuted / border) describes the surface your widget SITS ON, not the " +
+        "onSurfaceMuted / border / loader) 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.",
+        "there is nothing to opt into. `loader` is that surface's spinner colour " +
+        "(sc-6095) — paint your own loading state with it rather than a literal grey.",
       spacing: "{ xs, sm, md, lg, xl }",
       spacingScale:
         "number — the app-wide spacing multiplier (REQ-THEME-LOOK, default 1). " +
@@ -3326,7 +3332,16 @@ const CONTRACT = deepFreeze({
   //    through the already-vetted react-native-svg and carries no native
   //    module of its own, so it is host-shimmed on web and pinned in the
   //    export like date-fns. No existing entry changed shape.
-  version: "1.81.0",
+  //
+  // 1.82.0: additive (sc-6095) — `themeTokens.colors` gains `loader`, the
+  //    colour a loading spinner is painted with, and `deriveSurfaceTokens`
+  //    returns it alongside the surface/text/border set. A spinner is a muted
+  //    foreground mark on the surface it sits on, so it tracks `onSurfaceMuted`
+  //    and inherits that set's dark-background flip — which is what makes a
+  //    dark theme's spinner visible instead of grey-on-grey.
+  //    `useTheme().colors.loader` is the value a widget reads for its own
+  //    loading state; both hosts paint their chrome spinners from the same key.
+  version: "1.82.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -3511,7 +3526,7 @@ const DARK_SURFACE_TEXT = Object.freeze({
  * 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
+ * Returns all six 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.
  */
@@ -3528,6 +3543,7 @@ function deriveSurfaceTokens(backgroundColor) {
       surfaceMuted: base.surfaceMuted,
       onSurface: base.onSurface,
       onSurfaceMuted: base.onSurfaceMuted,
+      loader: base.loader,
       border: base.border,
     };
   }
@@ -3536,6 +3552,7 @@ function deriveSurfaceTokens(backgroundColor) {
     surfaceMuted: mixHex(backgroundColor, "#ffffff", SURFACE_LIFT.surfaceMuted),
     onSurface: DARK_SURFACE_TEXT.onSurface,
     onSurfaceMuted: DARK_SURFACE_TEXT.onSurfaceMuted,
+    loader: DARK_SURFACE_TEXT.onSurfaceMuted,
     border: mixHex(backgroundColor, "#ffffff", SURFACE_LIFT.border),
   };
 }

package/package.json

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