@colixsystems/widget-sdk 0.157.0 → 0.159.0

package/README.md

@@ -119,7 +119,7 @@ Behaviour: a bare date given to a `mode="datetime"` picker now shows local midni
 
 **The app header's row is arrangeable, and `./host` publishes the resolver both hosts read (sc-8023).** The row runs across the top of the content outside the side panel, and is drawn three times — as the phone header where the panel is a drawer, as the desktop strip, and as the full-width bar when one is switched on. Each surface hard-coded its own copy of it, so an author could colour the row but never move anything in it.
 
-- **`resolveTopStripeLayout(theme)`** reads `theme.sidebar.stripe` and returns the arrangement fully resolved: `slots` (already filtered and sequenced, so no host re-derives it), `order`, the box (`height`, `paddingX`, `contentOffsetY`), the resolved `backgroundColor` (joined in 0.155.0 by `tintColor` and `titleColor`), and `menuSide` — which edge the drawer must arrive from, since the brand grows and a burger ordered after it sits at the trailing edge. The web Player picks the drawer's side with it; the export makes it `drawerPosition`.
+- **`resolveTopStripeLayout(theme)`** reads `theme.sidebar.stripe` and returns the arrangement fully resolved: `slots` (already filtered and sequenced, so no host re-derives it), `order`, the box (`height`, `paddingX`, `contentOffsetY`, and `barHeight` — the height once the nudge is held, since pushing the contents down grows the bar rather than letting them fall out of it), the resolved `backgroundColor` (joined in 0.155.0 by `tintColor` and `titleColor`), and `menuSide` — which edge the drawer must arrive from, since the brand grows and a burger ordered after it sits at the trailing edge. The web Player picks the drawer's side with it; the export makes it `drawerPosition`.
 - **`TOP_STRIPE_SLOTS`** is the vocabulary (`back`, `menu`, `brand`, `notifications`) and **`TOP_STRIPE_ALWAYS_SHOWN_SLOTS`** the slots that move but never hide. The burger is the only member: it is drawn only where the panel is a drawer, and there it is the sole route into the menu, so hiding it would strand the visitor. It keeps its place in `order` regardless.
 - **`topStripeShowKey(slot)`** derives the `theme_config` key that shows or hides one slot, in one place, so a control, the write path and the resolver cannot spell it differently.
 - **The bounds travel with the resolver** — `MIN`/`MAX_TOP_STRIPE_HEIGHT_PX`, `MIN`/`MAX_TOP_STRIPE_PADDING_X_PX`, `MAX_TOP_STRIPE_OFFSET_Y_PX` — so a control offers exactly the range the resolver clamps to. `DEFAULT_TOP_STRIPE_HEIGHT_PX` / `DEFAULT_TOP_STRIPE_PADDING_X_PX` are what the DESKTOP row measures with nothing stored, published so a control can show the number an author is departing from; the resolver still answers `null`, because each surface keeps its own box until one is named.
@@ -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;
@@ -332,8 +339,12 @@ export interface TopStripeLayout {
    *  bar's 64px, the phone header's content-sized row. */
   height: number | null;
   paddingX: number | null;
-  /** How far the row is pushed down, 0-60px. */
+  /** How far the row's contents are pushed down, 0-60px. */
   contentOffsetY: number;
+  /** The bar's total height once the nudge is held — its box plus
+   *  `contentOffsetY`, so contents never fall out of the bottom. Null only
+   *  while both are unset, where each surface keeps its own box. */
+  barHeight: number | null;
   /** Every slot in the author's sequence, hidden ones included. */
   order: TopStripeSlot[];
   /** What the bar actually SHOWS, already filtered and sequenced. A surface

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,
@@ -405,6 +437,7 @@ function topStripeOrder(value) {
  * @param {unknown} theme — the whole `theme_config`.
  * @returns {{ backgroundColor: string, tintColor: string, titleColor: string,
  *   height: number|null, paddingX: number|null, contentOffsetY: number,
+ *   barHeight: number|null,
  *   order: string[], slots: string[], menuSide: "start"|"end" }}
  */
 function resolveTopStripeLayout(theme) {
@@ -422,30 +455,40 @@ function resolveTopStripeLayout(theme) {
       : TOP_STRIPE_SLOT_SHOWN_BY_DEFAULT[slot];
   };
   const slots = order.filter(shown);
+  // Unset defers to each surface's own box — the desktop bar's fixed 64px, the
+  // phone header's content-sized row.
+  const height = topStripeClampedOr(
+    stripe.height,
+    MIN_TOP_STRIPE_HEIGHT_PX,
+    MAX_TOP_STRIPE_HEIGHT_PX,
+    null,
+  );
+  const contentOffsetY = topStripeClampedOr(
+    stripe.contentOffsetY,
+    0,
+    MAX_TOP_STRIPE_OFFSET_Y_PX,
+    0,
+  );
   return {
     // There is no alignment to resolve: the brand slot GROWS, so the row has no
     // free space for `justify-content` to distribute and every value looked
     // identical. The row spreads because the brand takes the slack.
-    // Unset defers to each surface's own box — the desktop bar's fixed 64px,
-    // the phone header's content-sized row.
-    height: topStripeClampedOr(
-      stripe.height,
-      MIN_TOP_STRIPE_HEIGHT_PX,
-      MAX_TOP_STRIPE_HEIGHT_PX,
-      null,
-    ),
+    height,
     paddingX: topStripeClampedOr(
       stripe.paddingX,
       MIN_TOP_STRIPE_PADDING_X_PX,
       MAX_TOP_STRIPE_PADDING_X_PX,
       null,
     ),
-    contentOffsetY: topStripeClampedOr(
-      stripe.contentOffsetY,
-      0,
-      MAX_TOP_STRIPE_OFFSET_Y_PX,
-      0,
-    ),
+    contentOffsetY,
+    // sc-8552: the bar GROWS by the nudge rather than letting its contents fall
+    // out of the bottom — the box the author sized, plus what they pushed into
+    // it. For a surface that must state a height (the desktop bar, the native
+    // header); the phone row is content-sized and grows on its padding alone.
+    barHeight:
+      height === null && contentOffsetY === 0
+        ? null
+        : (height ?? DEFAULT_TOP_STRIPE_HEIGHT_PX) + contentOffsetY,
     // sc-8023: the stripe's OWN surface, inheriting the app-header colour when
     // unset — so an untouched app is unmoved, and an author who dresses a
     // page's top navigation bar no longer repaints the stripe above the panel by

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,
@@ -396,6 +428,7 @@ function topStripeOrder(value) {
  * @param {unknown} theme — the whole `theme_config`.
  * @returns {{ backgroundColor: string, tintColor: string, titleColor: string,
  *   height: number|null, paddingX: number|null, contentOffsetY: number,
+ *   barHeight: number|null,
  *   order: string[], slots: string[], menuSide: "start"|"end" }}
  */
 export function resolveTopStripeLayout(theme) {
@@ -413,30 +446,40 @@ export function resolveTopStripeLayout(theme) {
       : TOP_STRIPE_SLOT_SHOWN_BY_DEFAULT[slot];
   };
   const slots = order.filter(shown);
+  // Unset defers to each surface's own box — the desktop bar's fixed 64px, the
+  // phone header's content-sized row.
+  const height = topStripeClampedOr(
+    stripe.height,
+    MIN_TOP_STRIPE_HEIGHT_PX,
+    MAX_TOP_STRIPE_HEIGHT_PX,
+    null,
+  );
+  const contentOffsetY = topStripeClampedOr(
+    stripe.contentOffsetY,
+    0,
+    MAX_TOP_STRIPE_OFFSET_Y_PX,
+    0,
+  );
   return {
     // There is no alignment to resolve: the brand slot GROWS, so the row has no
     // free space for `justify-content` to distribute and every value looked
     // identical. The row spreads because the brand takes the slack.
-    // Unset defers to each surface's own box — the desktop bar's fixed 64px,
-    // the phone header's content-sized row.
-    height: topStripeClampedOr(
-      stripe.height,
-      MIN_TOP_STRIPE_HEIGHT_PX,
-      MAX_TOP_STRIPE_HEIGHT_PX,
-      null,
-    ),
+    height,
     paddingX: topStripeClampedOr(
       stripe.paddingX,
       MIN_TOP_STRIPE_PADDING_X_PX,
       MAX_TOP_STRIPE_PADDING_X_PX,
       null,
     ),
-    contentOffsetY: topStripeClampedOr(
-      stripe.contentOffsetY,
-      0,
-      MAX_TOP_STRIPE_OFFSET_Y_PX,
-      0,
-    ),
+    contentOffsetY,
+    // sc-8552: the bar GROWS by the nudge rather than letting its contents fall
+    // out of the bottom — the box the author sized, plus what they pushed into
+    // it. For a surface that must state a height (the desktop bar, the native
+    // header); the phone row is content-sized and grows on its padding alone.
+    barHeight:
+      height === null && contentOffsetY === 0
+        ? null
+        : (height ?? DEFAULT_TOP_STRIPE_HEIGHT_PX) + contentOffsetY,
     // sc-8023: the stripe's OWN surface, inheriting the app-header colour when
     // unset — so an untouched app is unmoved, and an author who dresses a
     // page's top navigation bar no longer repaints the stripe above the panel by

package/package.json

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