@colixsystems/widget-sdk 0.158.0 → 0.159.0

package/README.md

@@ -128,6 +128,12 @@ Additive — nothing in the existing `./host` surface changed, and the contract
 
 ### What's new in 0.151.0 (contract 1.118.0 — unchanged)
 
+**`resolveSidebarTokens` answers `activeInk` — the rail's active colour made readable as TEXT (sc-8655, REQ-NAV-LOCAL / REQ-THEME-14).** `activeColor` is authored as a SURFACE: the filled style paints it and forces a white label, so nothing in the system ever pressured it to be legible as ink. Every place that paints it as text inherited that — the accent style's active label, and now the entry a folded sidebar section hands its marking to — and the brand default reads 3.5:1 on the rail, below the 4.5:1 AA asks of normal text and worse than the unmarked rows around it.
+
+- `activeInk` is the same hue stepped toward the rail's own polarity (darker on a light rail, lighter on a dark one) only as far as AA needs, and is `activeColor` unchanged whenever that already reads. Derived, never authored: it moves with whatever colour the workspace sets, so there is no second control to keep in step.
+- **Additive.** `activeColor` still names the surface the filled style paints and the colour a non-text mark takes — a dot or an accent edge answers to 3:1, not 4.5:1, so those keep the author's actual colour. `CONTRACT` is untouched (`version` stays `1.122.0`): a host resolver, not a widget-facing surface.
+- Both hosts read it, so the Player, the exported drawer and the Design page's chrome preview cannot paint three different labels off one theme.
+
 **`resolveSidebarUnfold` joins the host navigation surface: where a page's local menu unfolds inside the app's own sidebar (sc-7696, REQ-NAV-LOCAL).** A page's local navigation could only be a bar, above or below its content. `local_nav` now also takes `SIDEBAR`, which takes no strip of the page: the saved menu unfolds in the rail and the drawer, under the global menu entry it belongs to.
 
 - `resolveSidebarUnfold({ entries, active, sections })` answers `{ under, items, standalone }` from host-neutral keys — page slugs on web, screen names in the export — so it is the ONE derivation both chromes read. Web calls it per render; the compiler asks it once per screen at build time, because the only runtime input is which screen is showing.

package/dist/host.d.ts

@@ -208,7 +208,14 @@ export function resolveFooterTokens(theme: unknown): FooterTokens;
 export interface SidebarTokens {
   backgroundColor: string;
   textColor: string;
+  /** The active colour as a SURFACE — what `filled` paints, what a non-text
+   *  mark (an accent edge, a folded section's dot) is drawn in. */
   activeColor: string;
+  /** sc-8655: the same colour as INK. `activeColor` is authored to sit under a
+   *  white label, so it can fall below AA as text on the rail; this is it
+   *  stepped toward the rail's own polarity until it clears 4.5:1, and equal to
+   *  `activeColor` whenever that already reads. Derived, never authored. */
+  activeInk: string;
   activeStyle: "filled" | "accent";
   borderColor: string | null;
   borderWidth: number | null;

package/dist/navigation.cjs

@@ -25,7 +25,7 @@
 // the SAME literal, so what a planner may persist and what a host draws cannot
 // diverge.
 
-const { CONTRACT, isHexColor } = require("./contract.cjs");
+const { CONTRACT, isHexColor, contrastRatio, mixHex, readableTextColor } = require("./contract.cjs");
 
 // Absent or unknown resolves here, so every app authored before menu types
 // existed renders and compiles byte-identically.
@@ -267,14 +267,46 @@ function brandPrimary(config) {
  * @returns {{ backgroundColor: string, textColor: string, activeColor: string,
  *   activeStyle: string, borderColor: string|null, borderWidth: number|null }}
  */
+// sc-8655: the sidebar's active colour is authored to sit UNDER a white label
+// (the filled style), so nothing ever pressured it to read as INK — the brand
+// default lands at 3.5:1 on the rail, below the 4.5:1 AA asks of normal text,
+// and worse than the inactive rows beside it. Every surface that paints the
+// active colour as TEXT reads the derived ink instead: the same hue, stepped
+// toward the rail's own polarity only as far as legibility needs.
+const AA_TEXT_CONTRAST = 4.5;
+const INK_STEP = 0.05;
+const INK_MAX_SHIFT = 0.7;
+
+function readableInk(color, background) {
+  if (!isHexColor(color) || !isHexColor(background)) return color;
+  if (contrastRatio(color, background) >= AA_TEXT_CONTRAST) return color;
+  // Darken on a light rail, lighten on a dark one — the direction that keeps
+  // the hue rather than washing it toward grey.
+  const toward = readableTextColor(background, "#000000", "#ffffff");
+  let ink = color;
+  for (let t = INK_STEP; t <= INK_MAX_SHIFT + 1e-9; t += INK_STEP) {
+    ink = mixHex(color, toward, t);
+    if (contrastRatio(ink, background) >= AA_TEXT_CONTRAST) break;
+  }
+  // A colour that cannot reach AA within the shift keeps the closest it got:
+  // the most readable answer available beats reverting to the unreadable one.
+  return ink;
+}
+
 function resolveSidebarTokens(theme) {
   const config = isPlainObject(theme) ? theme : {};
   const sidebar = isPlainObject(config.sidebar) ? config.sidebar : {};
   const borderColor = hexOrNull(sidebar.borderColor);
+  const backgroundColor = hexOr(sidebar.backgroundColor, chromeSurface(config));
+  const activeColor = hexOr(sidebar.activeColor, brandPrimary(config));
   return {
-    backgroundColor: hexOr(sidebar.backgroundColor, chromeSurface(config)),
+    backgroundColor,
     textColor: hexOr(sidebar.textColor, DEFAULT_CHROME_TEXT),
-    activeColor: hexOr(sidebar.activeColor, brandPrimary(config)),
+    activeColor,
+    // sc-8655: `activeColor` where it is a SURFACE, `activeInk` where it is
+    // text on the rail. Both hosts read the second for an accent-marked label
+    // and for a folded section's entry.
+    activeInk: readableInk(activeColor, backgroundColor),
     activeStyle: sidebar.activeStyle === "accent" ? "accent" : "filled",
     // REQ-THEME-LOOK: the colour is the switch — no colour, no line.
     borderColor,

package/dist/navigation.js

@@ -16,7 +16,7 @@
 // the SAME literal, so what a planner may persist and what a host draws cannot
 // diverge.
 
-import { CONTRACT, isHexColor } from "./contract.js";
+import { CONTRACT, isHexColor, contrastRatio, mixHex, readableTextColor } from "./contract.js";
 
 // Absent or unknown resolves here, so every app authored before menu types
 // existed renders and compiles byte-identically.
@@ -258,14 +258,46 @@ function brandPrimary(config) {
  * @returns {{ backgroundColor: string, textColor: string, activeColor: string,
  *   activeStyle: string, borderColor: string|null, borderWidth: number|null }}
  */
+// sc-8655: the sidebar's active colour is authored to sit UNDER a white label
+// (the filled style), so nothing ever pressured it to read as INK — the brand
+// default lands at 3.5:1 on the rail, below the 4.5:1 AA asks of normal text,
+// and worse than the inactive rows beside it. Every surface that paints the
+// active colour as TEXT reads the derived ink instead: the same hue, stepped
+// toward the rail's own polarity only as far as legibility needs.
+const AA_TEXT_CONTRAST = 4.5;
+const INK_STEP = 0.05;
+const INK_MAX_SHIFT = 0.7;
+
+function readableInk(color, background) {
+  if (!isHexColor(color) || !isHexColor(background)) return color;
+  if (contrastRatio(color, background) >= AA_TEXT_CONTRAST) return color;
+  // Darken on a light rail, lighten on a dark one — the direction that keeps
+  // the hue rather than washing it toward grey.
+  const toward = readableTextColor(background, "#000000", "#ffffff");
+  let ink = color;
+  for (let t = INK_STEP; t <= INK_MAX_SHIFT + 1e-9; t += INK_STEP) {
+    ink = mixHex(color, toward, t);
+    if (contrastRatio(ink, background) >= AA_TEXT_CONTRAST) break;
+  }
+  // A colour that cannot reach AA within the shift keeps the closest it got:
+  // the most readable answer available beats reverting to the unreadable one.
+  return ink;
+}
+
 export function resolveSidebarTokens(theme) {
   const config = isPlainObject(theme) ? theme : {};
   const sidebar = isPlainObject(config.sidebar) ? config.sidebar : {};
   const borderColor = hexOrNull(sidebar.borderColor);
+  const backgroundColor = hexOr(sidebar.backgroundColor, chromeSurface(config));
+  const activeColor = hexOr(sidebar.activeColor, brandPrimary(config));
   return {
-    backgroundColor: hexOr(sidebar.backgroundColor, chromeSurface(config)),
+    backgroundColor,
     textColor: hexOr(sidebar.textColor, DEFAULT_CHROME_TEXT),
-    activeColor: hexOr(sidebar.activeColor, brandPrimary(config)),
+    activeColor,
+    // sc-8655: `activeColor` where it is a SURFACE, `activeInk` where it is
+    // text on the rail. Both hosts read the second for an accent-marked label
+    // and for a folded section's entry.
+    activeInk: readableInk(activeColor, backgroundColor),
     activeStyle: sidebar.activeStyle === "accent" ? "accent" : "filled",
     // REQ-THEME-LOOK: the colour is the switch — no colour, no line.
     borderColor,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.158.0",
+  "version": "0.159.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",