@colixsystems/widget-sdk 0.144.0 → 0.145.0

package/README.md

@@ -71,7 +71,19 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.144.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.145.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.145.0 (contract 1.113.0)
+
+**The app's bottom navigation bar gets its own active-tab look — `resolveFooterTokens` gains three (sc-7951).** `theme_config.footer` already carried an `activeStyle`, but no Studio control ever wrote it, so the SIDEBAR's active-item style silently decided the bottom bar too: an author who accented the rail accented the tab bar, with no way to separate them. The bar was also under-authorable — `"filled"` *bundled* the active tab's surface with its label, pinning the surface to `activeColor` and the label to a hard-coded white, so no author could paint a surface of their own.
+
+- **`footer.activeStyle` is now the bar's**, reachable from the Design page's Bottom navigation bar panel. Unset it still falls back to `sidebar.activeStyle`, so every existing workspace renders exactly as before.
+- **`footer.tabActiveBackgroundColor`** — the active tab's surface. New, and it falls back to **nothing**: a vertical rail item has no tab surface, so unlike the colours this inherits from no one.
+- **`footer.tabLayout`** — `"inline"` (the row the bar has always drawn) or `"stacked"`, the glyph above its label. Also footer-only.
+
+`resolveFooterTokens` now returns the active tab **already decided** — `activeSurface` (hex or `null`) and `activeTint` — so neither host re-derives the back-compat pairing. `"filled"` with nothing named is still the active colour behind a white label; **naming a surface unbundles the two**, and the label goes back to `activeColor` so the author owns both halves. `activeColor` is resolved in the helper now rather than by each caller, so it is a `string` rather than raw-or-null — `FooterTokens.activeColor` narrows accordingly. The inherited colours are also hex-guarded on the way **out**, not only in: the export already refused a malformed stored value while the Player handed it to a style object.
+
+It also settles a divergence the bar carried: under `"accent"` the web Player drew a **left** border (the rail's rule on a horizontal tab) and the export drew no edge at all. Both now mark the edge **facing the page** — a bottom tab's top — reserved transparent at every tab's width so marking one cannot shift the row. A tab is also the same 6px-rounded chip on both hosts, where native used to be square.
 
 ### What's new in 0.144.0 (contract 1.112.0)
 

package/dist/contract.cjs

@@ -4041,7 +4041,20 @@ const CONTRACT = deepFreeze({
   //    belongs to a PAGE's own bottom navigation bar (`local_nav = BOTTOM_BAR`,
   //    REQ-NAV-LOCAL), chosen per page. `resolveFooterTokens` is unchanged —
   //    it is the bottom edge's token set and the surviving bar reads it.
-  version: "1.112.0",
+  // 1.113.0: additive (sc-7951) — `resolveFooterTokens` gains the bottom
+  //    bar's OWN three. `activeStyle` was on the wire but had no Studio
+  //    control, so the SIDEBAR's decided the strip too; `tabActiveBackgroundColor`
+  //    (the active tab's surface) and `tabLayout` (`inline` | `stacked`) are new
+  //    and fall back to nothing, because a vertical rail item has neither. The
+  //    resolver now also returns the active tab already DECIDED — `activeSurface`
+  //    and `activeTint` — so neither host re-derives the back-compat pairing
+  //    ("filled" with nothing named is the active colour behind a white label);
+  //    naming a surface unbundles the two. `activeColor` is resolved here now
+  //    rather than by each caller, so it is a string rather than raw-or-null,
+  //    and the inherited colours are hex-guarded on the way out as well as in.
+  //    Every colour still falls back to the sidebar's: an untouched workspace is
+  //    unchanged.
+  version: "1.113.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -4037,7 +4037,20 @@ const CONTRACT = deepFreeze({
   //    belongs to a PAGE's own bottom navigation bar (`local_nav = BOTTOM_BAR`,
   //    REQ-NAV-LOCAL), chosen per page. `resolveFooterTokens` is unchanged —
   //    it is the bottom edge's token set and the surviving bar reads it.
-  version: "1.112.0",
+  // 1.113.0: additive (sc-7951) — `resolveFooterTokens` gains the bottom
+  //    bar's OWN three. `activeStyle` was on the wire but had no Studio
+  //    control, so the SIDEBAR's decided the strip too; `tabActiveBackgroundColor`
+  //    (the active tab's surface) and `tabLayout` (`inline` | `stacked`) are new
+  //    and fall back to nothing, because a vertical rail item has neither. The
+  //    resolver now also returns the active tab already DECIDED — `activeSurface`
+  //    and `activeTint` — so neither host re-derives the back-compat pairing
+  //    ("filled" with nothing named is the active colour behind a white label);
+  //    naming a surface unbundles the two. `activeColor` is resolved here now
+  //    rather than by each caller, so it is a string rather than raw-or-null,
+  //    and the inherited colours are hex-guarded on the way out as well as in.
+  //    Every colour still falls back to the sidebar's: an untouched workspace is
+  //    unchanged.
+  version: "1.113.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/host.d.ts

@@ -179,16 +179,29 @@ export function menuItemCap(menuType: string): number | null;
 export interface FooterTokens {
   backgroundColor: string | null;
   textColor: string | null;
-  activeColor: string | null;
+  /** Never `null`: an unset value resolves to the brand primary here rather
+   *  than in each host, which is what lets the two active-tab fields below be
+   *  resolved here at all. */
+  activeColor: string;
   borderColor: string | null;
   borderWidth: number | null;
   activeStyle: "filled" | "accent";
+  /** Whether a tab's glyph sits beside its label or above it (sc-7951). */
+  tabLayout: "inline" | "stacked";
+  /** The active tab's surface, or `null` for none. Under "filled" with nothing
+   *  named this is the active colour — what both hosts shipped. */
+  activeSurface: string | null;
+  /** The active tab's label and glyph. White only under an unnamed "filled"
+   *  surface, which is the pairing both hosts hard-coded. */
+  activeTint: string;
 }
 
 /**
- * Resolves the footer strip's tokens from a whole `theme_config`. Every field
- * falls back to the sidebar's, so a workspace that never opens the Footer panel
- * renders exactly as it did before the block existed.
+ * Resolves the footer strip's tokens from a whole `theme_config`. Every colour
+ * falls back to the sidebar's, so a workspace that never opens the Bottom
+ * navigation bar panel renders exactly as it did before the block existed.
+ * `tabActiveBackgroundColor` and `tabLayout` are the strip's own and inherit
+ * from nothing — a vertical rail item has neither.
  */
 export function resolveFooterTokens(theme: unknown): FooterTokens;
 

package/dist/navigation.cjs

@@ -76,39 +76,69 @@ function menuItemCap(menuType) {
 //
 // sc-7753: the global quick bar these tokens were introduced for is retired;
 // the bar that reads them now is the page's own (`local_nav = BOTTOM_BAR`).
+//
+// sc-7951: three of the keys ARE that bar's own — the active-item style it
+// used to borrow from the rail for want of a control, the active tab's
+// surface, and whether the glyph sits beside the label or above it.
 function resolveFooterTokens(theme) {
   const config = isPlainObject(theme) ? theme : {};
   const footer = isPlainObject(config.footer) ? config.footer : {};
   const sidebar = isPlainObject(config.sidebar) ? config.sidebar : {};
-  const pick = (key) => footer[key] || sidebar[key] || null;
+  // Hex-guarded on the way out, not merely on the way in: `theme_config` is an
+  // opaque blob an operator can hand-edit, and the EXPORT already refused a
+  // malformed colour here while the Player passed it to a style object — so the
+  // guard is what stops the two hosts painting a stored junk value differently.
+  const pick = (key) => hexOrNull(footer[key]) || hexOrNull(sidebar[key]) || null;
   const borderColor = pick("borderColor");
+  // sc-7951: the rail's style is the FALLBACK now, not the only source. Unset
+  // still follows the rail, which is what keeps every shipped app where it is.
   const activeStyle = footer.activeStyle || sidebar.activeStyle;
+  const accent = activeStyle === "accent";
+  const activeColor = hexOr(pick("activeColor"), brandPrimary(config));
+  // Footer-only: a rail item is a full-width row with no tab surface to paint,
+  // so this inherits from nothing and unset means "no surface of its own".
+  const namedSurface = hexOrNull(footer.tabActiveBackgroundColor);
   return {
     backgroundColor: pick("backgroundColor"),
     textColor: pick("textColor"),
-    // Unlike the others this has no null state on either host: an unset active
-    // colour resolves to the brand primary, which the caller supplies.
-    activeColor: pick("activeColor"),
+    // Resolved here rather than by each caller, which is what lets the two
+    // active-tab fields below be resolved here too.
+    activeColor,
     // REQ-THEME-LOOK: the divider's COLOUR is its switch. Unset draws no line at
     // all — which the native strip did not honour before this, ruling a
     // hairline across a tinted bar that had asked for none.
     borderColor,
     borderWidth: borderColor ? borderWidthOr(footer.borderWidth, sidebar.borderWidth) : null,
-    activeStyle: activeStyle === "accent" ? "accent" : "filled",
+    activeStyle: accent ? "accent" : "filled",
+    // sc-7951: bottom tabs are the only strip tall enough to stack the two, so
+    // the choice is the footer's alone.
+    tabLayout: footer.tabLayout === "stacked" ? "stacked" : "inline",
+    // sc-7951: the active tab's two halves, resolved HERE so neither host
+    // re-derives the back-compat rule. "filled" with nothing named is what both
+    // hosts shipped — the active colour as the fill, the label forced white —
+    // and that pairing is the only reason a marked tab's label is not simply
+    // the active colour. Naming a surface unbundles them: the surface is the
+    // author's and the label goes back to the active colour.
+    activeSurface: namedSurface || (accent ? null : activeColor),
+    activeTint: accent || namedSurface ? activeColor : FILLED_TAB_LABEL,
   };
 }
 
 // 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
+// These return FULLY resolved values where `resolveFooterTokens` above still
+// returns raw-or-null for its SURFACE, LABEL and DIVIDER colours, and the
+// difference is deliberate. The footer's two hosts happen to agree on their
+// separately-written defaults for those three (`#ffffff` / `#475569` / no
+// line); the rail's and the bar's did not. sc-7951 resolved the footer's active
+// tab — `activeColor`, `activeSurface`, `activeTint` — because a rule that
+// pairs a surface with a label cannot live in two hosts; the three above are
+// what remains of the old shape. 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.
+// resolver cannot drift; one that lives in each host already had. The footer's
+// three remaining raw colours want this same shape next.
 //
 // 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
@@ -126,6 +156,9 @@ const DEFAULT_TOP_BAR_TINT = "#334155";
 // The page beneath the chrome — the web's `DEFAULT_APP_BACKGROUND_COLOR`
 // (frontend/src/utils/theme.js) and the compiler's, which are the same slate-50.
 const DEFAULT_APP_SURFACE = "#f8fafc";
+// The literal both hosts hard-coded behind an unnamed "filled" surface, before
+// resolveFooterTokens decided the pairing once (sc-7951).
+const FILLED_TAB_LABEL = "#ffffff";
 
 // A gradient shows only when BOTH stops are a flat hex — the rule both hosts'
 // page readers apply (`normaliseThemeGradient`, mirrored frontend/backend). A

package/dist/navigation.js

@@ -67,39 +67,69 @@ export function menuItemCap(menuType) {
 //
 // sc-7753: the global quick bar these tokens were introduced for is retired;
 // the bar that reads them now is the page's own (`local_nav = BOTTOM_BAR`).
+//
+// sc-7951: three of the keys ARE that bar's own — the active-item style it
+// used to borrow from the rail for want of a control, the active tab's
+// surface, and whether the glyph sits beside the label or above it.
 export function resolveFooterTokens(theme) {
   const config = isPlainObject(theme) ? theme : {};
   const footer = isPlainObject(config.footer) ? config.footer : {};
   const sidebar = isPlainObject(config.sidebar) ? config.sidebar : {};
-  const pick = (key) => footer[key] || sidebar[key] || null;
+  // Hex-guarded on the way out, not merely on the way in: `theme_config` is an
+  // opaque blob an operator can hand-edit, and the EXPORT already refused a
+  // malformed colour here while the Player passed it to a style object — so the
+  // guard is what stops the two hosts painting a stored junk value differently.
+  const pick = (key) => hexOrNull(footer[key]) || hexOrNull(sidebar[key]) || null;
   const borderColor = pick("borderColor");
+  // sc-7951: the rail's style is the FALLBACK now, not the only source. Unset
+  // still follows the rail, which is what keeps every shipped app where it is.
   const activeStyle = footer.activeStyle || sidebar.activeStyle;
+  const accent = activeStyle === "accent";
+  const activeColor = hexOr(pick("activeColor"), brandPrimary(config));
+  // Footer-only: a rail item is a full-width row with no tab surface to paint,
+  // so this inherits from nothing and unset means "no surface of its own".
+  const namedSurface = hexOrNull(footer.tabActiveBackgroundColor);
   return {
     backgroundColor: pick("backgroundColor"),
     textColor: pick("textColor"),
-    // Unlike the others this has no null state on either host: an unset active
-    // colour resolves to the brand primary, which the caller supplies.
-    activeColor: pick("activeColor"),
+    // Resolved here rather than by each caller, which is what lets the two
+    // active-tab fields below be resolved here too.
+    activeColor,
     // REQ-THEME-LOOK: the divider's COLOUR is its switch. Unset draws no line at
     // all — which the native strip did not honour before this, ruling a
     // hairline across a tinted bar that had asked for none.
     borderColor,
     borderWidth: borderColor ? borderWidthOr(footer.borderWidth, sidebar.borderWidth) : null,
-    activeStyle: activeStyle === "accent" ? "accent" : "filled",
+    activeStyle: accent ? "accent" : "filled",
+    // sc-7951: bottom tabs are the only strip tall enough to stack the two, so
+    // the choice is the footer's alone.
+    tabLayout: footer.tabLayout === "stacked" ? "stacked" : "inline",
+    // sc-7951: the active tab's two halves, resolved HERE so neither host
+    // re-derives the back-compat rule. "filled" with nothing named is what both
+    // hosts shipped — the active colour as the fill, the label forced white —
+    // and that pairing is the only reason a marked tab's label is not simply
+    // the active colour. Naming a surface unbundles them: the surface is the
+    // author's and the label goes back to the active colour.
+    activeSurface: namedSurface || (accent ? null : activeColor),
+    activeTint: accent || namedSurface ? activeColor : FILLED_TAB_LABEL,
   };
 }
 
 // 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
+// These return FULLY resolved values where `resolveFooterTokens` above still
+// returns raw-or-null for its SURFACE, LABEL and DIVIDER colours, and the
+// difference is deliberate. The footer's two hosts happen to agree on their
+// separately-written defaults for those three (`#ffffff` / `#475569` / no
+// line); the rail's and the bar's did not. sc-7951 resolved the footer's active
+// tab — `activeColor`, `activeSurface`, `activeTint` — because a rule that
+// pairs a surface with a label cannot live in two hosts; the three above are
+// what remains of the old shape. 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.
+// resolver cannot drift; one that lives in each host already had. The footer's
+// three remaining raw colours want this same shape next.
 //
 // 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
@@ -117,6 +147,9 @@ const DEFAULT_TOP_BAR_TINT = "#334155";
 // The page beneath the chrome — the web's `DEFAULT_APP_BACKGROUND_COLOR`
 // (frontend/src/utils/theme.js) and the compiler's, which are the same slate-50.
 const DEFAULT_APP_SURFACE = "#f8fafc";
+// The literal both hosts hard-coded behind an unnamed "filled" surface, before
+// resolveFooterTokens decided the pairing once (sc-7951).
+const FILLED_TAB_LABEL = "#ffffff";
 
 // A gradient shows only when BOTH stops are a flat hex — the rule both hosts'
 // page readers apply (`normaliseThemeGradient`, mirrored frontend/backend). A

package/package.json

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