@colixsystems/widget-sdk 0.109.0 → 0.110.0

package/README.md

@@ -69,7 +69,17 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`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**.
+`v0.110.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.110.0 (contract 1.84.0)
+
+**`resolveSidebarTokens` and `resolveTopBarTokens` — the rail's and the app bar's tokens, resolved once for both hosts (sc-6289).** The footer strip got a shared resolver in 1.71.0; the two chrome parts beside it did not, so their defaults lived inline in the web Player and again in the compiler — and had drifted. An unset `sidebar.backgroundColor` painted the app background in the Expo export where the Player painted it white, so a dark app shipped a dark drawer beside a white rail; an unset `topBar.textColor` painted the app name slate in the export where the Player has always used the brand colour.
+
+Both resolvers now own their defaults, which are what the web Player renders, so the export follows the appearance the author approved in the Studio rather than the other way round. Unlike `resolveFooterTokens`, the colours are never `null` — a default that lives in the resolver cannot drift, and one that lived in each host already had. `borderColor` stays nullable: the colour is the divider's switch.
+
+The top bar resolves **two** text colours. An unthemed bar paints its icons slate and its app name in the brand colour, and React Navigation's single `headerTintColor` cannot say both — so `tintColor` and `titleColor` are separate, and an authored `topBar.textColor` drives both. `show` is deliberately not among them: it depends on the menu type rather than the theme, and REQ-THEME-14 makes it a no-op on native.
+
+Host-integration surface only — nothing a widget imports changed. `CONTRACT.version` → `1.84.0`.
 
 ### What's new in 0.108.0 (contract 1.82.0)
 

package/dist/contract.cjs

@@ -3362,7 +3362,19 @@ const CONTRACT = deepFreeze({
   //    additionally requires an `inheritAcl` RELATION column, which is what
   //    makes the stream a strict subset of what `list()` already returns.
   //    Backed by datastore-client 0.15.0. Omitting `scope` is unchanged.
-  version: "1.83.0",
+  // 1.84.0: additive (sc-6289) -- `resolveSidebarTokens` and
+  //    `resolveTopBarTokens` (host exports), the rail's and the app bar's
+  //    tokens beside the footer's. Their defaults used to be written separately
+  //    in each host and had drifted: an unset rail took the app background in
+  //    the export where the Player painted it white, and an unset header
+  //    painted the app name slate where the Player used the brand colour. The
+  //    resolvers own the defaults, so a host cannot keep its own. The top bar
+  //    resolves `tintColor` and `titleColor` separately because the web bar has
+  //    always painted its icons slate and its name in the brand colour, which
+  //    one `headerTintColor` cannot express; an authored `topBar.textColor`
+  //    drives both. `show` is deliberately absent -- it depends on the menu
+  //    type, not the theme, and is a no-op on native.
+  version: "1.84.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -3362,7 +3362,19 @@ const CONTRACT = deepFreeze({
   //    additionally requires an `inheritAcl` RELATION column, which is what
   //    makes the stream a strict subset of what `list()` already returns.
   //    Backed by datastore-client 0.15.0. Omitting `scope` is unchanged.
-  version: "1.83.0",
+  // 1.84.0: additive (sc-6289) -- `resolveSidebarTokens` and
+  //    `resolveTopBarTokens` (host exports), the rail's and the app bar's
+  //    tokens beside the footer's. Their defaults used to be written separately
+  //    in each host and had drifted: an unset rail took the app background in
+  //    the export where the Player painted it white, and an unset header
+  //    painted the app name slate where the Player used the brand colour. The
+  //    resolvers own the defaults, so a host cannot keep its own. The top bar
+  //    resolves `tintColor` and `titleColor` separately because the web bar has
+  //    always painted its icons slate and its name in the brand colour, which
+  //    one `headerTintColor` cannot express; an authored `topBar.textColor`
+  //    drives both. `show` is deliberately absent -- it depends on the menu
+  //    type, not the theme, and is a no-op on native.
+  version: "1.84.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/host.d.ts

@@ -194,6 +194,43 @@ export interface FooterTokens {
  */
 export function resolveFooterTokens(theme: unknown): FooterTokens;
 
+/** The sidebar rail's resolved tokens. Unlike the footer's, the colours are
+ *  never `null`: the default lives here so the two hosts cannot each keep a
+ *  different one. `borderColor` is still nullable — no colour, no divider. */
+export interface SidebarTokens {
+  backgroundColor: string;
+  textColor: string;
+  activeColor: string;
+  activeStyle: "filled" | "accent";
+  borderColor: string | null;
+  borderWidth: number | null;
+}
+
+/**
+ * Resolves the sidebar rail's tokens from a whole `theme_config`. Every default
+ * is what the web Player renders, so the export follows the Player rather than
+ * the other way round.
+ */
+export function resolveSidebarTokens(theme: unknown): SidebarTokens;
+
+/** The top app bar's resolved tokens. `tintColor` and `titleColor` are separate
+ *  because an unthemed bar paints its icons slate and its app name in the brand
+ *  colour; an authored `topBar.textColor` drives both. */
+export interface TopBarTokens {
+  backgroundColor: string;
+  tintColor: string;
+  titleColor: string;
+  borderColor: string | null;
+  borderWidth: number | null;
+}
+
+/**
+ * Resolves the top app bar's tokens from a whole `theme_config`. `show` is not
+ * among them: it depends on the menu type, not the theme, and is a no-op on
+ * native.
+ */
+export function resolveTopBarTokens(theme: unknown): TopBarTokens;
+
 /** A value a widget may persist: a scalar, or a flat array of them. */
 export type WidgetRouteScalar = string | number | boolean;
 export type WidgetRouteValue = WidgetRouteScalar | WidgetRouteScalar[];

package/dist/host.js

@@ -50,11 +50,16 @@ export {
 // the sidebar's so an untouched workspace keeps the appearance it has. It
 // exists because the strip IS the menu under `bottom-tabs`, where the sidebar
 // panel is hidden and those tokens can no longer be set at all.
+// REQ-THEME-14: `resolveSidebarTokens` and `resolveTopBarTokens` are the same
+// idea for the rail and the app bar, whose defaults used to live inline in each
+// host and had already drifted apart.
 export {
   normaliseNavigation,
   menuItemCap,
   quickBarCap,
   resolveFooterTokens,
+  resolveSidebarTokens,
+  resolveTopBarTokens,
 } from "./navigation.js";
 
 // sc-5717: the codec behind `useWidgetRoute()` — how a widget's own internal

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 } = require("./contract.cjs");
+const { CONTRACT, isHexColor } = require("./contract.cjs");
 
 // Absent or unknown resolves here, so every app authored before menu types
 // existed renders and compiles byte-identically.
@@ -114,6 +114,98 @@ function resolveFooterTokens(theme) {
   };
 }
 
+// REQ-THEME-14 — the rail's and the app bar's tokens, resolved once for both
+// hosts.
+//
+// These return FULLY resolved values where `resolveFooterTokens` above returns
+// raw-or-null, and the difference is deliberate. The footer's two hosts happen
+// to agree on their separately-written defaults; the rail's and the bar's did
+// not. An unset `sidebar.backgroundColor` painted #ffffff on web and the app
+// background in the export, and an unset `topBar.textColor` painted the brand
+// primary on web and slate-700 in the export. A default that lives in the
+// resolver cannot drift; one that lives in each host already had. The footer
+// wants this same shape next — the same fix, not yet applied.
+//
+// Every default is what the WEB Player renders today, so the Player does not
+// move and the export converges onto it. That is the direction the footer was
+// converged in too (compiler.service's footerBg defaults to the web's #ffffff).
+
+const DEFAULT_PRIMARY_COLOR = "#3b82f6";
+// The web rail's and app bar's `bg-white`.
+const DEFAULT_CHROME_SURFACE = "#ffffff";
+// The web nav item's `text-slate-600`.
+const DEFAULT_CHROME_TEXT = "#475569";
+// The web mobile header's icon colour, `text-slate-700`.
+const DEFAULT_TOP_BAR_TINT = "#334155";
+
+// The contract's own guard, which already admits the 8-digit form a look uses
+// to float a translucent rail (#RRGGBBAA).
+function hexOrNull(value) {
+  return isHexColor(value) ? value : null;
+}
+
+function hexOr(value, fallback) {
+  return hexOrNull(value) || fallback;
+}
+
+function brandPrimary(config) {
+  return hexOr(config.primaryColor, DEFAULT_PRIMARY_COLOR);
+}
+
+/**
+ * The sidebar rail's surface, labels, active item and opt-in divider.
+ *
+ * @param {unknown} theme — the whole `theme_config`; `primaryColor` is read
+ *   because an unset active colour resolves to the brand.
+ * @returns {{ backgroundColor: string, textColor: string, activeColor: string,
+ *   activeStyle: string, borderColor: string|null, borderWidth: number|null }}
+ */
+function resolveSidebarTokens(theme) {
+  const config = isPlainObject(theme) ? theme : {};
+  const sidebar = isPlainObject(config.sidebar) ? config.sidebar : {};
+  const borderColor = hexOrNull(sidebar.borderColor);
+  return {
+    backgroundColor: hexOr(sidebar.backgroundColor, DEFAULT_CHROME_SURFACE),
+    textColor: hexOr(sidebar.textColor, DEFAULT_CHROME_TEXT),
+    activeColor: hexOr(sidebar.activeColor, brandPrimary(config)),
+    activeStyle: sidebar.activeStyle === "accent" ? "accent" : "filled",
+    // REQ-THEME-LOOK: the colour is the switch — no colour, no line.
+    borderColor,
+    borderWidth: borderColor ? borderWidthOr(sidebar.borderWidth) : null,
+  };
+}
+
+/**
+ * The top app bar's surface, its two text colours and its opt-in divider.
+ *
+ * `tintColor` and `titleColor` are SEPARATE because the web bar has always
+ * painted them differently when the author names nothing: the hamburger and
+ * icons take slate, the app name takes the brand. React Navigation's single
+ * `headerTintColor` could not express that, which is why the export used to
+ * paint the name slate. One token, two resolved fields, both hosts agree.
+ *
+ * `show` is deliberately absent: it depends on the menu TYPE, not the theme,
+ * and REQ-THEME-14 makes it a no-op on native — so it is not a shared token.
+ *
+ * @param {unknown} theme — the whole `theme_config`.
+ * @returns {{ backgroundColor: string, tintColor: string, titleColor: string,
+ *   borderColor: string|null, borderWidth: number|null }}
+ */
+function resolveTopBarTokens(theme) {
+  const config = isPlainObject(theme) ? theme : {};
+  const topBar = isPlainObject(config.topBar) ? config.topBar : {};
+  const borderColor = hexOrNull(topBar.borderColor);
+  // An explicit colour drives BOTH slots; only the unset case splits.
+  const authored = hexOrNull(topBar.textColor);
+  return {
+    backgroundColor: hexOr(topBar.backgroundColor, DEFAULT_CHROME_SURFACE),
+    tintColor: authored || DEFAULT_TOP_BAR_TINT,
+    titleColor: authored || brandPrimary(config),
+    borderColor,
+    borderWidth: borderColor ? borderWidthOr(topBar.borderWidth) : null,
+  };
+}
+
 function borderWidthOr(...values) {
   for (const value of values) {
     if (typeof value === "number" && Number.isFinite(value)) return value;
@@ -121,4 +213,4 @@ function borderWidthOr(...values) {
   return 1;
 }
 
-module.exports = { normaliseNavigation, menuItemCap, quickBarCap, resolveFooterTokens };
+module.exports = { normaliseNavigation, menuItemCap, quickBarCap, resolveFooterTokens, resolveSidebarTokens, resolveTopBarTokens };

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 } from "./contract.js";
+import { CONTRACT, isHexColor } from "./contract.js";
 
 // Absent or unknown resolves here, so every app authored before menu types
 // existed renders and compiles byte-identically.
@@ -105,6 +105,98 @@ export function resolveFooterTokens(theme) {
   };
 }
 
+// REQ-THEME-14 — the rail's and the app bar's tokens, resolved once for both
+// hosts.
+//
+// These return FULLY resolved values where `resolveFooterTokens` above returns
+// raw-or-null, and the difference is deliberate. The footer's two hosts happen
+// to agree on their separately-written defaults; the rail's and the bar's did
+// not. An unset `sidebar.backgroundColor` painted #ffffff on web and the app
+// background in the export, and an unset `topBar.textColor` painted the brand
+// primary on web and slate-700 in the export. A default that lives in the
+// resolver cannot drift; one that lives in each host already had. The footer
+// wants this same shape next — the same fix, not yet applied.
+//
+// Every default is what the WEB Player renders today, so the Player does not
+// move and the export converges onto it. That is the direction the footer was
+// converged in too (compiler.service's footerBg defaults to the web's #ffffff).
+
+const DEFAULT_PRIMARY_COLOR = "#3b82f6";
+// The web rail's and app bar's `bg-white`.
+const DEFAULT_CHROME_SURFACE = "#ffffff";
+// The web nav item's `text-slate-600`.
+const DEFAULT_CHROME_TEXT = "#475569";
+// The web mobile header's icon colour, `text-slate-700`.
+const DEFAULT_TOP_BAR_TINT = "#334155";
+
+// The contract's own guard, which already admits the 8-digit form a look uses
+// to float a translucent rail (#RRGGBBAA).
+function hexOrNull(value) {
+  return isHexColor(value) ? value : null;
+}
+
+function hexOr(value, fallback) {
+  return hexOrNull(value) || fallback;
+}
+
+function brandPrimary(config) {
+  return hexOr(config.primaryColor, DEFAULT_PRIMARY_COLOR);
+}
+
+/**
+ * The sidebar rail's surface, labels, active item and opt-in divider.
+ *
+ * @param {unknown} theme — the whole `theme_config`; `primaryColor` is read
+ *   because an unset active colour resolves to the brand.
+ * @returns {{ backgroundColor: string, textColor: string, activeColor: string,
+ *   activeStyle: string, borderColor: string|null, borderWidth: number|null }}
+ */
+export function resolveSidebarTokens(theme) {
+  const config = isPlainObject(theme) ? theme : {};
+  const sidebar = isPlainObject(config.sidebar) ? config.sidebar : {};
+  const borderColor = hexOrNull(sidebar.borderColor);
+  return {
+    backgroundColor: hexOr(sidebar.backgroundColor, DEFAULT_CHROME_SURFACE),
+    textColor: hexOr(sidebar.textColor, DEFAULT_CHROME_TEXT),
+    activeColor: hexOr(sidebar.activeColor, brandPrimary(config)),
+    activeStyle: sidebar.activeStyle === "accent" ? "accent" : "filled",
+    // REQ-THEME-LOOK: the colour is the switch — no colour, no line.
+    borderColor,
+    borderWidth: borderColor ? borderWidthOr(sidebar.borderWidth) : null,
+  };
+}
+
+/**
+ * The top app bar's surface, its two text colours and its opt-in divider.
+ *
+ * `tintColor` and `titleColor` are SEPARATE because the web bar has always
+ * painted them differently when the author names nothing: the hamburger and
+ * icons take slate, the app name takes the brand. React Navigation's single
+ * `headerTintColor` could not express that, which is why the export used to
+ * paint the name slate. One token, two resolved fields, both hosts agree.
+ *
+ * `show` is deliberately absent: it depends on the menu TYPE, not the theme,
+ * and REQ-THEME-14 makes it a no-op on native — so it is not a shared token.
+ *
+ * @param {unknown} theme — the whole `theme_config`.
+ * @returns {{ backgroundColor: string, tintColor: string, titleColor: string,
+ *   borderColor: string|null, borderWidth: number|null }}
+ */
+export function resolveTopBarTokens(theme) {
+  const config = isPlainObject(theme) ? theme : {};
+  const topBar = isPlainObject(config.topBar) ? config.topBar : {};
+  const borderColor = hexOrNull(topBar.borderColor);
+  // An explicit colour drives BOTH slots; only the unset case splits.
+  const authored = hexOrNull(topBar.textColor);
+  return {
+    backgroundColor: hexOr(topBar.backgroundColor, DEFAULT_CHROME_SURFACE),
+    tintColor: authored || DEFAULT_TOP_BAR_TINT,
+    titleColor: authored || brandPrimary(config),
+    borderColor,
+    borderWidth: borderColor ? borderWidthOr(topBar.borderWidth) : null,
+  };
+}
+
 function borderWidthOr(...values) {
   for (const value of values) {
     if (typeof value === "number" && Number.isFinite(value)) return value;

package/package.json

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