@colixsystems/widget-sdk 0.292.0 → 0.293.0

package/README.md

@@ -90,7 +90,11 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.292.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.293.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.293.0 (contract 1.240.0)
+
+**Status colours follow the app's look.** `theme.colors.success`, `danger`, `warning` and `info` used to be the same four colours in every app, so a warm editorial palette showed a saturated green "Completed" chip and a bright blue "Booked" one. Each tone now keeps its hue family (green, red, amber, blue) but takes the app's accent saturation and lightness, stepped until it reads as text on the surface — and a dark palette derives its own lighter set. `<Badge>`, `<Banner>`, `<Progress>`, `<Stat>` deltas and toasts pick this up with no change on your side, and a badge's soft fill and label stay WCAG AA. A colour the workspace sets in the Alerts section of Design still wins. The derivation is `deriveStatusColors(primary, surface, onSurface)`, a host-side helper like `deriveAccentTints`; the four default literals are that derivation on the default palette, so an untouched theme renders as before.
 
 ### What's new in 0.292.0 (contract 1.239.0)
 

package/dist/contract.cjs

@@ -87,10 +87,13 @@ const DEFAULT_THEME_TOKENS = Object.freeze({
     // background — so a dark theme gets a visible spinner with no new maths.
     loader: "#475569",
     border: "#e2e8f0",
-    danger: "#dc2626",
-    success: "#059669",
-    warning: "#d97706",
-    info: "#0284c7",
+    // The four status tones are re-derived per tenant by `deriveStatusColors`
+    // (their hue families on the accent's saturation and lightness); these
+    // literals are that derivation applied to the default palette.
+    danger: "#e90b0b",
+    success: "#067e56",
+    warning: "#9b6507",
+    info: "#0877af",
   }),
   elevation: ELEVATION,
   interaction: INTERACTION,
@@ -6808,13 +6811,17 @@ const CONTRACT = deepFreeze({
   //    PaymentError codes.
   // 1.237.0: widening — `manifest.translations` may declare up to 500 keys
   //    (was 200).
+  // 1.239.0: additive — `deriveStatusColors`; the four status tokens follow the
+  //    palette, and their default literals are that derivation on the default.
   // 1.238.0: additive (sc-15659) — `useConnector(connectorRef)` + the
   //    `connectors` host client + the `connectorRef` propertySchema type + the
   //    `connectors.call:*` scope. A widget calls a REST connector's listed operations.
+  // 1.240.0: additive — `deriveStatusColors`; the four status tokens follow the
+  //    palette, and their default literals are that derivation on the default.
   // 1.239.0: additive (sc-15658) — an app-triggered run must finish within 250 ms
   //    of the press; `useAction` errors carry the new code ACTION_TIMEOUT
   //    (504), whose outcome is unknown.
-  version: "1.239.0",
+  version: "1.240.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -7051,6 +7058,70 @@ function deriveAccentTints(primary, surface, onSurface) {
   };
 }
 
+// The hue family each status tone keeps whatever the palette.
+const STATUS_HUES = Object.freeze({ success: 160, danger: 0, warning: 38, info: 200 });
+// Below this saturation a tone loses its hue, so a grey accent still reads as a colour.
+const STATUS_MIN_SATURATION = 0.35;
+// The lightness band a tone starts in, so a near-black or pastel accent keeps a visible hue.
+const STATUS_LIGHTNESS = Object.freeze({ min: 0.28, max: 0.62 });
+const STATUS_LIGHTNESS_STEP = 0.02;
+
+/** `[hue 0-360, saturation 0-1, lightness 0-1]` of a hex colour. */
+function hexToHsl(hex) {
+  const [r, g, b] = hexChannels(hex).map((v) => v / 255);
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  const l = (max + min) / 2;
+  if (max === min) return [0, 0, l];
+  const d = max - min;
+  const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+  let h;
+  if (max === r) h = (g - b) / d + (g < b ? 6 : 0);
+  else if (max === g) h = (b - r) / d + 2;
+  else h = (r - g) / d + 4;
+  return [h * 60, s, l];
+}
+
+function hslToHex(h, s, l) {
+  const k = (n) => (n + h / 30) % 12;
+  const a = s * Math.min(l, 1 - l);
+  const f = (n) => l - a * Math.max(-1, Math.min(k(n) - 3, 9 - k(n), 1));
+  const hex = (v) => Math.round(v * 255).toString(16).padStart(2, "0");
+  return `#${hex(f(0))}${hex(f(8))}${hex(f(4))}`;
+}
+
+/**
+ * Derive the four status colours from a resolved palette. Each tone keeps its
+ * hue family (green, red, amber, blue) and takes the accent's saturation and
+ * lightness, then is stepped toward `onSurface` until it clears WCAG AA against
+ * the surface, so a status mark reads as text on every look, light or dark.
+ * Returns `{ success, danger, warning, info }`, or `null` when the inputs
+ * aren't usable hex, letting the caller keep the default tokens.
+ */
+function deriveStatusColors(primary, surface, onSurface) {
+  if (!isHexColor(primary) || !isHexColor(surface) || !isHexColor(onSurface)) {
+    return null;
+  }
+  const [, accentS, accentL] = hexToHsl(primary);
+  const targetL = hexToHsl(onSurface)[2];
+  const s = Math.max(accentS, STATUS_MIN_SATURATION);
+  const out = {};
+  for (const [tone, hue] of Object.entries(STATUS_HUES)) {
+    let l = Math.min(STATUS_LIGHTNESS.max, Math.max(STATUS_LIGHTNESS.min, accentL));
+    let color = hslToHex(hue, s, l);
+    const step = targetL < l ? -STATUS_LIGHTNESS_STEP : STATUS_LIGHTNESS_STEP;
+    while (
+      contrastRatio(color, surface) < ACCENT_TEXT_MIN_CONTRAST &&
+      Math.abs(targetL - l) > STATUS_LIGHTNESS_STEP
+    ) {
+      l += step;
+      color = hslToHex(hue, s, l);
+    }
+    out[tone] = color;
+  }
+  return out;
+}
+
 // 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 });
@@ -7248,6 +7319,7 @@ module.exports = {
   contrastRatio,
   readableTextColor,
   deriveAccentTints,
+  deriveStatusColors,
   deriveSurfaceTokens,
   inkForBackdrop,
   INK_CONTRAST,

package/dist/contract.js

@@ -83,10 +83,13 @@ const DEFAULT_THEME_TOKENS = Object.freeze({
     // background — so a dark theme gets a visible spinner with no new maths.
     loader: "#475569",
     border: "#e2e8f0",
-    danger: "#dc2626",
-    success: "#059669",
-    warning: "#d97706",
-    info: "#0284c7",
+    // The four status tones are re-derived per tenant by `deriveStatusColors`
+    // (their hue families on the accent's saturation and lightness); these
+    // literals are that derivation applied to the default palette.
+    danger: "#e90b0b",
+    success: "#067e56",
+    warning: "#9b6507",
+    info: "#0877af",
   }),
   elevation: ELEVATION,
   interaction: INTERACTION,
@@ -6804,13 +6807,17 @@ const CONTRACT = deepFreeze({
   //    PaymentError codes.
   // 1.237.0: widening — `manifest.translations` may declare up to 500 keys
   //    (was 200).
+  // 1.239.0: additive — `deriveStatusColors`; the four status tokens follow the
+  //    palette, and their default literals are that derivation on the default.
   // 1.238.0: additive (sc-15659) — `useConnector(connectorRef)` + the
   //    `connectors` host client + the `connectorRef` propertySchema type + the
   //    `connectors.call:*` scope. A widget calls a REST connector's listed operations.
+  // 1.240.0: additive — `deriveStatusColors`; the four status tokens follow the
+  //    palette, and their default literals are that derivation on the default.
   // 1.239.0: additive (sc-15658) — an app-triggered run must finish within 250 ms
   //    of the press; `useAction` errors carry the new code ACTION_TIMEOUT
   //    (504), whose outcome is unknown.
-  version: "1.239.0",
+  version: "1.240.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -7047,6 +7054,70 @@ function deriveAccentTints(primary, surface, onSurface) {
   };
 }
 
+// The hue family each status tone keeps whatever the palette.
+const STATUS_HUES = Object.freeze({ success: 160, danger: 0, warning: 38, info: 200 });
+// Below this saturation a tone loses its hue, so a grey accent still reads as a colour.
+const STATUS_MIN_SATURATION = 0.35;
+// The lightness band a tone starts in, so a near-black or pastel accent keeps a visible hue.
+const STATUS_LIGHTNESS = Object.freeze({ min: 0.28, max: 0.62 });
+const STATUS_LIGHTNESS_STEP = 0.02;
+
+/** `[hue 0-360, saturation 0-1, lightness 0-1]` of a hex colour. */
+function hexToHsl(hex) {
+  const [r, g, b] = hexChannels(hex).map((v) => v / 255);
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  const l = (max + min) / 2;
+  if (max === min) return [0, 0, l];
+  const d = max - min;
+  const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+  let h;
+  if (max === r) h = (g - b) / d + (g < b ? 6 : 0);
+  else if (max === g) h = (b - r) / d + 2;
+  else h = (r - g) / d + 4;
+  return [h * 60, s, l];
+}
+
+function hslToHex(h, s, l) {
+  const k = (n) => (n + h / 30) % 12;
+  const a = s * Math.min(l, 1 - l);
+  const f = (n) => l - a * Math.max(-1, Math.min(k(n) - 3, 9 - k(n), 1));
+  const hex = (v) => Math.round(v * 255).toString(16).padStart(2, "0");
+  return `#${hex(f(0))}${hex(f(8))}${hex(f(4))}`;
+}
+
+/**
+ * Derive the four status colours from a resolved palette. Each tone keeps its
+ * hue family (green, red, amber, blue) and takes the accent's saturation and
+ * lightness, then is stepped toward `onSurface` until it clears WCAG AA against
+ * the surface, so a status mark reads as text on every look, light or dark.
+ * Returns `{ success, danger, warning, info }`, or `null` when the inputs
+ * aren't usable hex, letting the caller keep the default tokens.
+ */
+function deriveStatusColors(primary, surface, onSurface) {
+  if (!isHexColor(primary) || !isHexColor(surface) || !isHexColor(onSurface)) {
+    return null;
+  }
+  const [, accentS, accentL] = hexToHsl(primary);
+  const targetL = hexToHsl(onSurface)[2];
+  const s = Math.max(accentS, STATUS_MIN_SATURATION);
+  const out = {};
+  for (const [tone, hue] of Object.entries(STATUS_HUES)) {
+    let l = Math.min(STATUS_LIGHTNESS.max, Math.max(STATUS_LIGHTNESS.min, accentL));
+    let color = hslToHex(hue, s, l);
+    const step = targetL < l ? -STATUS_LIGHTNESS_STEP : STATUS_LIGHTNESS_STEP;
+    while (
+      contrastRatio(color, surface) < ACCENT_TEXT_MIN_CONTRAST &&
+      Math.abs(targetL - l) > STATUS_LIGHTNESS_STEP
+    ) {
+      l += step;
+      color = hslToHex(hue, s, l);
+    }
+    out[tone] = color;
+  }
+  return out;
+}
+
 // 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 });
@@ -7244,6 +7315,7 @@ export {
   contrastRatio,
   readableTextColor,
   deriveAccentTints,
+  deriveStatusColors,
   deriveSurfaceTokens,
   inkForBackdrop,
   INK_CONTRAST,

package/dist/index.d.ts

@@ -6067,6 +6067,23 @@ export function deriveAccentTints(
   primaryStrong: string;
 } | null;
 
+/**
+ * Derive the four status colours from a resolved palette: each keeps its hue
+ * family and takes the accent's saturation and lightness, stepped toward
+ * `onSurface` until it clears WCAG AA against the surface. `null` when the
+ * inputs aren't hex.
+ */
+export function deriveStatusColors(
+  primary: string,
+  surface: string,
+  onSurface: string,
+): {
+  success: string;
+  danger: string;
+  warning: string;
+  info: string;
+} | null;
+
 /**
  * Map a CSS gradient angle (0 = to top, 90 = to right) to the `{ start, end }`
  * unit vectors expo-linear-gradient expects.

package/dist/index.js

@@ -215,6 +215,7 @@ export {
   contrastRatio,
   readableTextColor,
   deriveAccentTints,
+  deriveStatusColors,
   gradientAngleToVector,
   normaliseComponentGradient,
   componentGradientColors,

package/dist/index.native.js

@@ -208,6 +208,7 @@ export {
   contrastRatio,
   readableTextColor,
   deriveAccentTints,
+  deriveStatusColors,
   gradientAngleToVector,
   normaliseComponentGradient,
   componentGradientColors,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.292.0",
+  "version": "0.293.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

@@ -83,10 +83,13 @@ const DEFAULT_THEME_TOKENS = Object.freeze({
     // background — so a dark theme gets a visible spinner with no new maths.
     loader: "#475569",
     border: "#e2e8f0",
-    danger: "#dc2626",
-    success: "#059669",
-    warning: "#d97706",
-    info: "#0284c7",
+    // The four status tones are re-derived per tenant by `deriveStatusColors`
+    // (their hue families on the accent's saturation and lightness); these
+    // literals are that derivation applied to the default palette.
+    danger: "#e90b0b",
+    success: "#067e56",
+    warning: "#9b6507",
+    info: "#0877af",
   }),
   elevation: ELEVATION,
   interaction: INTERACTION,
@@ -6804,13 +6807,17 @@ const CONTRACT = deepFreeze({
   //    PaymentError codes.
   // 1.237.0: widening — `manifest.translations` may declare up to 500 keys
   //    (was 200).
+  // 1.239.0: additive — `deriveStatusColors`; the four status tokens follow the
+  //    palette, and their default literals are that derivation on the default.
   // 1.238.0: additive (sc-15659) — `useConnector(connectorRef)` + the
   //    `connectors` host client + the `connectorRef` propertySchema type + the
   //    `connectors.call:*` scope. A widget calls a REST connector's listed operations.
+  // 1.240.0: additive — `deriveStatusColors`; the four status tokens follow the
+  //    palette, and their default literals are that derivation on the default.
   // 1.239.0: additive (sc-15658) — an app-triggered run must finish within 250 ms
   //    of the press; `useAction` errors carry the new code ACTION_TIMEOUT
   //    (504), whose outcome is unknown.
-  version: "1.239.0",
+  version: "1.240.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -7047,6 +7054,70 @@ function deriveAccentTints(primary, surface, onSurface) {
   };
 }
 
+// The hue family each status tone keeps whatever the palette.
+const STATUS_HUES = Object.freeze({ success: 160, danger: 0, warning: 38, info: 200 });
+// Below this saturation a tone loses its hue, so a grey accent still reads as a colour.
+const STATUS_MIN_SATURATION = 0.35;
+// The lightness band a tone starts in, so a near-black or pastel accent keeps a visible hue.
+const STATUS_LIGHTNESS = Object.freeze({ min: 0.28, max: 0.62 });
+const STATUS_LIGHTNESS_STEP = 0.02;
+
+/** `[hue 0-360, saturation 0-1, lightness 0-1]` of a hex colour. */
+function hexToHsl(hex) {
+  const [r, g, b] = hexChannels(hex).map((v) => v / 255);
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  const l = (max + min) / 2;
+  if (max === min) return [0, 0, l];
+  const d = max - min;
+  const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+  let h;
+  if (max === r) h = (g - b) / d + (g < b ? 6 : 0);
+  else if (max === g) h = (b - r) / d + 2;
+  else h = (r - g) / d + 4;
+  return [h * 60, s, l];
+}
+
+function hslToHex(h, s, l) {
+  const k = (n) => (n + h / 30) % 12;
+  const a = s * Math.min(l, 1 - l);
+  const f = (n) => l - a * Math.max(-1, Math.min(k(n) - 3, 9 - k(n), 1));
+  const hex = (v) => Math.round(v * 255).toString(16).padStart(2, "0");
+  return `#${hex(f(0))}${hex(f(8))}${hex(f(4))}`;
+}
+
+/**
+ * Derive the four status colours from a resolved palette. Each tone keeps its
+ * hue family (green, red, amber, blue) and takes the accent's saturation and
+ * lightness, then is stepped toward `onSurface` until it clears WCAG AA against
+ * the surface, so a status mark reads as text on every look, light or dark.
+ * Returns `{ success, danger, warning, info }`, or `null` when the inputs
+ * aren't usable hex, letting the caller keep the default tokens.
+ */
+function deriveStatusColors(primary, surface, onSurface) {
+  if (!isHexColor(primary) || !isHexColor(surface) || !isHexColor(onSurface)) {
+    return null;
+  }
+  const [, accentS, accentL] = hexToHsl(primary);
+  const targetL = hexToHsl(onSurface)[2];
+  const s = Math.max(accentS, STATUS_MIN_SATURATION);
+  const out = {};
+  for (const [tone, hue] of Object.entries(STATUS_HUES)) {
+    let l = Math.min(STATUS_LIGHTNESS.max, Math.max(STATUS_LIGHTNESS.min, accentL));
+    let color = hslToHex(hue, s, l);
+    const step = targetL < l ? -STATUS_LIGHTNESS_STEP : STATUS_LIGHTNESS_STEP;
+    while (
+      contrastRatio(color, surface) < ACCENT_TEXT_MIN_CONTRAST &&
+      Math.abs(targetL - l) > STATUS_LIGHTNESS_STEP
+    ) {
+      l += step;
+      color = hslToHex(hue, s, l);
+    }
+    out[tone] = color;
+  }
+  return out;
+}
+
 // 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 });
@@ -7244,6 +7315,7 @@ export {
   contrastRatio,
   readableTextColor,
   deriveAccentTints,
+  deriveStatusColors,
   deriveSurfaceTokens,
   inkForBackdrop,
   INK_CONTRAST,