@colixsystems/widget-sdk 0.140.0 → 0.141.0

package/README.md

@@ -70,7 +70,15 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.140.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.141.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.141.0 (contract 1.109.0)
+
+**The app's global navigation is the sidebar alone — `top-bar` and `bottom-tabs` leave `CONTRACT.themeMenuTypes` (sc-7352, REQ-NAV-STRUCTURE).** A top bar is now a PAGE's local bar drawing a saved menu (REQ-NAV-LOCAL, sc-7103): the same tab row the `top-bar` shape used to draw, themed by the same `topBar` tokens (`resolveTopBarTokens` is unchanged), worn by one page under the sidebar. Two "top bars" competing for one word and one token set was the reason.
+
+- `normaliseNavigation` resolves a stored `top-bar` or `bottom-tabs` to `sidebar`, so a host never has to guard the value. `menuItemCap` / `quickBarCap` keep their signatures (`quickBarCap("sidebar")` is still 5).
+- The global menu never lived in the shape (it is the pages' `show_in_menu` flags), so a workspace that stored a retired shape already draws the sidebar with the same menu. The sc-7352 backfill deletes the stored key BEFORE the shapes disappear; a bottom-tabs app's phone strip becomes the sidebar's quick bar.
+- Host-integration surface only; no author-facing hook, prop or manifest field changed. `CONTRACT.version` → `1.109.0`.
 
 ### What's new in 0.140.0 (contract 1.108.0)
 

package/dist/contract.cjs

@@ -217,36 +217,20 @@ const THEME_WIDGET_STYLES = Object.freeze({
 // PlayerChrome and the compiler's navigator -- so a type cannot be offered to an
 // author without every host actually drawing it.
 //
-// `maxItems` caps how many menu pages the chrome draws at once, and its meaning
-// differs per type deliberately. The sidebar's mobile quick bar is a SECONDARY
-// curated bar, so its own cap may drop a page -- the rail still lists every one.
-// A bottom-tabs strip IS the menu, so its cap must never drop one: the surplus
-// moves behind a "More" sheet instead.
+// REQ-NAV-STRUCTURE (sc-7352): the app's GLOBAL navigation has exactly one
+// shape, the sidebar. A top bar is a PAGE's local bar drawing a saved menu
+// (REQ-NAV-LOCAL), themed by the `topBar` tokens, never an app-wide menu shape.
+// `maxItems` is the menu cap (none for a rail); `quickBarMaxItems` caps the
+// SECONDARY mobile quick bar, which may drop a page because the rail and the
+// drawer still list every one.
 const THEME_MENU_TYPES = Object.freeze({
   sidebar: Object.freeze({
     name: "Sidebar",
     summary:
       "A persistent left rail on desktop; a hamburger drawer plus the optional bottom quick bar on mobile.",
     maxItems: null,
-    // The SECONDARY mobile quick bar's cap. It may drop a page past it, because
-    // the rail and the drawer still list every one -- the opposite of
-    // `bottom-tabs`' `maxItems`, where the strip IS the menu.
     quickBarMaxItems: 5,
   }),
-  "top-bar": Object.freeze({
-    name: "Top bar",
-    summary:
-      "A tab row beneath the app header at every width -- icon and label per page, scrolling sideways when it runs out of room. No rail at any width.",
-    maxItems: null,
-    quickBarMaxItems: null,
-  }),
-  "bottom-tabs": Object.freeze({
-    name: "Bottom tabs",
-    summary:
-      "A sticky bottom strip at every width -- the phone-native shape. Pages past the cap move behind a More sheet.",
-    maxItems: 4,
-    quickBarMaxItems: null,
-  }),
 });
 const THEME_SPACING_SCALE = Object.freeze({
   min: 0.5,
@@ -3976,7 +3960,17 @@ const CONTRACT = deepFreeze({
   //    a stored hex is untouched and still renders byte-identically, and an
   //    unresolvable binding falls back to the field's `themeDefault` rather
   //    than painting blank.
-  version: "1.108.0",
+  // 1.109.0: BREAKING on the pre-1.0 channel (sc-7352) — `themeMenuTypes`
+  //    loses `top-bar` and `bottom-tabs`: the app's global navigation is the
+  //    sidebar alone, and a top bar is a page's LOCAL bar drawing a saved menu
+  //    (REQ-NAV-LOCAL), themed by the same `topBar` tokens. A stored
+  //    `navigation.menuType` of a retired shape resolves to `sidebar` through
+  //    `normaliseNavigation`, so no host has to guard the value; the global
+  //    menu never lived in the shape, so such apps already draw the sidebar,
+  //    and the sc-7352 backfill deletes the stored key (a bottom-tabs app's
+  //    strip becomes the sidebar's quick bar) BEFORE this ships.
+  //    `menuItemCap` / `quickBarCap` keep their signatures.
+  version: "1.109.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -217,36 +217,20 @@ const THEME_WIDGET_STYLES = Object.freeze({
 // PlayerChrome and the compiler's navigator -- so a type cannot be offered to an
 // author without every host actually drawing it.
 //
-// `maxItems` caps how many menu pages the chrome draws at once, and its meaning
-// differs per type deliberately. The sidebar's mobile quick bar is a SECONDARY
-// curated bar, so its own cap may drop a page -- the rail still lists every one.
-// A bottom-tabs strip IS the menu, so its cap must never drop one: the surplus
-// moves behind a "More" sheet instead.
+// REQ-NAV-STRUCTURE (sc-7352): the app's GLOBAL navigation has exactly one
+// shape, the sidebar. A top bar is a PAGE's local bar drawing a saved menu
+// (REQ-NAV-LOCAL), themed by the `topBar` tokens, never an app-wide menu shape.
+// `maxItems` is the menu cap (none for a rail); `quickBarMaxItems` caps the
+// SECONDARY mobile quick bar, which may drop a page because the rail and the
+// drawer still list every one.
 const THEME_MENU_TYPES = Object.freeze({
   sidebar: Object.freeze({
     name: "Sidebar",
     summary:
       "A persistent left rail on desktop; a hamburger drawer plus the optional bottom quick bar on mobile.",
     maxItems: null,
-    // The SECONDARY mobile quick bar's cap. It may drop a page past it, because
-    // the rail and the drawer still list every one -- the opposite of
-    // `bottom-tabs`' `maxItems`, where the strip IS the menu.
     quickBarMaxItems: 5,
   }),
-  "top-bar": Object.freeze({
-    name: "Top bar",
-    summary:
-      "A tab row beneath the app header at every width -- icon and label per page, scrolling sideways when it runs out of room. No rail at any width.",
-    maxItems: null,
-    quickBarMaxItems: null,
-  }),
-  "bottom-tabs": Object.freeze({
-    name: "Bottom tabs",
-    summary:
-      "A sticky bottom strip at every width -- the phone-native shape. Pages past the cap move behind a More sheet.",
-    maxItems: 4,
-    quickBarMaxItems: null,
-  }),
 });
 const THEME_SPACING_SCALE = Object.freeze({
   min: 0.5,
@@ -3976,7 +3960,17 @@ const CONTRACT = deepFreeze({
   //    a stored hex is untouched and still renders byte-identically, and an
   //    unresolvable binding falls back to the field's `themeDefault` rather
   //    than painting blank.
-  version: "1.108.0",
+  // 1.109.0: BREAKING on the pre-1.0 channel (sc-7352) — `themeMenuTypes`
+  //    loses `top-bar` and `bottom-tabs`: the app's global navigation is the
+  //    sidebar alone, and a top bar is a page's LOCAL bar drawing a saved menu
+  //    (REQ-NAV-LOCAL), themed by the same `topBar` tokens. A stored
+  //    `navigation.menuType` of a retired shape resolves to `sidebar` through
+  //    `normaliseNavigation`, so no host has to guard the value; the global
+  //    menu never lived in the shape, so such apps already draw the sidebar,
+  //    and the sc-7352 backfill deletes the stored key (a bottom-tabs app's
+  //    strip becomes the sidebar's quick bar) BEFORE this ships.
+  //    `menuItemCap` / `quickBarCap` keep their signatures.
+  version: "1.109.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/host.d.ts

@@ -150,10 +150,11 @@ export function createToastController(
 ): ToastController;
 
 // REQ-NAV-STRUCTURE — the navigation SHAPE a host draws its chrome in. The
-// vocabulary is closed by `CONTRACT.themeMenuTypes`; these are the resolvers
-// both hosts switch on.
+// vocabulary is closed by `CONTRACT.themeMenuTypes`; since sc-7352 it holds
+// the sidebar alone (a top bar is a page's local bar, REQ-NAV-LOCAL), and any
+// stored value outside it resolves to `sidebar`.
 
-export type ThemeMenuType = "sidebar" | "top-bar" | "bottom-tabs";
+export type ThemeMenuType = "sidebar";
 
 export interface ResolvedNavigation {
   menuType: ThemeMenuType;
@@ -168,8 +169,7 @@ export function normaliseNavigation(navigation: unknown): ResolvedNavigation;
 
 /**
  * How many menu pages this shape may draw at once, or `null` for no cap. The
- * cap's meaning differs per type: the sidebar's quick bar may drop a page past
- * it, a bottom-tabs strip must move its surplus behind a More sheet.
+ * sidebar has none — its rail and drawer list every menu page.
  */
 export function menuItemCap(menuType: string): number | null;
 
@@ -232,16 +232,14 @@ export interface TopBarTokens {
    *  label plus its indicator. Falls back to the RAIL's `activeColor` and then
    *  to the brand, so an app states its navigation colour once. */
   activeColor: string;
-  /** How a `tabs` menu row marks its current page. `underline` keeps the tab in
-   *  the bar's surface behind an indicator; `attached` makes it a folder tab
-   *  that takes `contentSurface` and sits over the row's divider. Meaningless
-   *  under the `links` style, which draws no tabs. */
+  /** How a local bar marks its current page. `underline` keeps the tab in the
+   *  bar's surface behind an indicator; `attached` cuts the bar away under the
+   *  current tab so the page shows through it. */
   tabStyle: "underline" | "attached";
-  /** The surface an `attached` tab AND its content panel share — always
-   *  opaque, because a translucent tab would show the bar through the page it
-   *  is part of. Honours `tabActiveBackgroundColor`, so moving the tab moves
-   *  the page with it. */
-  contentSurface: string;
+  /** Under `attached`, the colour the PANEL behind the row paints — the
+   *  authored `tabActiveBackgroundColor`, alpha kept — or null for the page's
+   *  own wash. The current tab paints nothing itself. */
+  contentSurface: string | null;
   /** A tab's own surface, authored or null. Null paints none and the bar shows
    *  through. */
   tabBackgroundColor: string | null;

package/dist/host.js

@@ -52,15 +52,14 @@ export {
   TOAST_DEFAULTS,
 } from "./toast-host.js";
 
-// REQ-NAV-STRUCTURE: the navigation-shape resolver both hosts draw their chrome
-// from. `normaliseNavigation` turns a stored `theme_config.navigation` block into
-// the resolved `{ menuType }` the chrome switches on; `menuItemCap` states how
-// many menu pages that shape may draw at once. One implementation, so a menu
-// type cannot mean one thing in the Player and another in the Expo export.
-// `resolveFooterTokens` is the footer strip's own token set, falling back to
-// 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-NAV-STRUCTURE: the navigation resolver both hosts draw their chrome from.
+// `normaliseNavigation` turns a stored `theme_config.navigation` block into the
+// resolved `{ menuType }` — always `sidebar` since sc-7352 retired the other
+// shapes, so a stored value never needs guarding; `menuItemCap` / `quickBarCap`
+// state the caps. One implementation, so the chrome cannot mean one thing in
+// the Player and another in the Expo export. `resolveFooterTokens` is the quick
+// bar's own token set, falling back to the sidebar's so an untouched workspace
+// keeps the appearance it has.
 // 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.

package/dist/navigation.cjs

@@ -59,10 +59,8 @@ function normaliseNavigation(navigation) {
 }
 
 /**
- * How many MENU pages the chrome may draw at once, or `null` for no cap.
- *
- * Where the chrome IS the menu (`bottom-tabs`) this cap must never drop a page:
- * the surplus moves behind a More sheet. Contrast `quickBarCap` below.
+ * How many MENU pages the chrome may draw at once, or `null` for no cap. The
+ * sidebar has none. Contrast `quickBarCap` below.
  *
  * @param {string} menuType — a resolved menu type.
  * @returns {number|null}
@@ -90,13 +88,17 @@ function quickBarCap(menuType) {
 }
 
 // The strip's surface was hard-coded white on BOTH hosts and its items read the
-// sidebar's tokens — which is fine while it is the sidebar's secondary quick bar
-// and fatal once it IS the menu (`bottom-tabs` hides the sidebar panel, so those
-// tokens have nowhere to be set). `footer` gives it tokens of its own.
+// sidebar's tokens. `footer` gives the quick bar tokens of its own.
+//
+// Every colour falls back to the sidebar's, so a workspace that never opens the
+// panel keeps exactly the appearance it has today; only an explicit `footer`
+// value moves anything.
 //
-// Every field falls back to the sidebar's, so a workspace that never opens the
-// Footer panel keeps exactly the appearance it has today; only an explicit
-// `footer` value moves anything.
+// sc-7695: this block is the BOTTOM EDGE's, not the quick bar's alone. A page's
+// own bottom bar (REQ-NAV-LOCAL) is the same strip worn by one page and reads
+// exactly these values — the Design panel that edits them is named for that
+// bar, since the quick bar is on its way out (sc-7753) and the look outlives
+// it. No key is the bar's alone: two strips, one look.
 function resolveFooterTokens(theme) {
   const config = isPlainObject(theme) ? theme : {};
   const footer = isPlainObject(config.footer) ? config.footer : {};
@@ -176,11 +178,6 @@ function pageColor(config, alphaRule) {
   );
 }
 
-// An `attached` tab: opaque, or the bar shows through the page it joins.
-function pageSurface(config) {
-  return pageColor(config, opaqueOr);
-}
-
 // sc-6596: what an UNSET rail or bar is painted. Read at full strength — an
 // alpha on the bottom layer would mean nothing to chrome above it.
 function chromeSurface(config) {
@@ -223,12 +220,6 @@ function tabIndicatorOr(value) {
   return Math.min(Math.max(Math.round(value), 0), TAB_INDICATOR_MAX);
 }
 
-function opaqueOr(value) {
-  return isHexColor(value) && value.length !== 9 && value.length !== 5
-    ? value
-    : null;
-}
-
 // A gradient stop as the page readers admit one: flat hex, never alpha.
 function flatHexOrNull(value) {
   return isHexColor(value) && value.length !== 9 ? value : null;
@@ -330,18 +321,15 @@ function resolveTopBarTokens(theme) {
     // surface and meets the page beneath it, so the two read as one plane. Meaningless on a shape that draws no tab row — a host
     // reads it only where it has tabs to draw.
     tabStyle: topBar.tabStyle === "attached" ? "attached" : "underline",
-    // The surface an `attached` tab AND its content panel share. One value for
-    // both, so the join cannot come apart: whatever the current tab is painted,
-    // the page beneath it is painted too. An authored active surface therefore
-    // moves both. Resolved HERE rather than by each host, because a tab that
-    // fails to match the page it is joined to reads as a mismatched box instead
-    // of a tab, and two hosts computing it separately is exactly how that
-    // drifts. Opaque by construction: a translucent tab would show the bar
-    // through the page it claims to be part of.
-    contentSurface: hexOr(
-      opaqueOr(topBar.tabActiveBackgroundColor),
-      pageSurface(config),
-    ),
+    // The surface the PANEL behind an `attached` row paints — the authored
+    // active colour, alpha and all, or nothing. Under `attached` the current
+    // tab itself paints NOTHING: it is a hole in the bar, and what shows
+    // through it is this panel, or the page's own wash when this is null. So
+    // the tab is exactly as see-through as the page, a gradient stays one
+    // gradient, and a translucent page never doubles up under a tab (sc-7352 —
+    // painting the tab a copy of the page could never do any of that). One
+    // value, resolved HERE, so both hosts paint the panel the same colour.
+    contentSurface: hexOrNull(topBar.tabActiveBackgroundColor),
     // REQ-NAV-STRUCTURE: the underline that marks the current tab, in px. Zero
     // turns it OFF and leaves the tab marked by its label colour alone, which
     // is a real choice rather than an unstyled state — so unlike the chrome
@@ -360,9 +348,9 @@ function resolveTopBarTokens(theme) {
     // and the bar shows through it, which is what the row did before the keys
     // existed — so an app that never set them is unchanged.
     tabBackgroundColor: hexOrNull(topBar.tabBackgroundColor),
-    // Only meaningful where the style draws no panel: under `attached` the
-    // active surface IS `contentSurface` above. Null under `underline` leaves
-    // the current tab unpainted, marked by its indicator alone.
+    // Under `underline` the current tab's own surface, or null for none. Under
+    // `attached` the tab paints nothing and this colour is the PANEL's — see
+    // `contentSurface` above.
     tabActiveBackgroundColor: hexOrNull(topBar.tabActiveBackgroundColor),
   };
 }

package/dist/navigation.js

@@ -50,10 +50,8 @@ export function normaliseNavigation(navigation) {
 }
 
 /**
- * How many MENU pages the chrome may draw at once, or `null` for no cap.
- *
- * Where the chrome IS the menu (`bottom-tabs`) this cap must never drop a page:
- * the surplus moves behind a More sheet. Contrast `quickBarCap` below.
+ * How many MENU pages the chrome may draw at once, or `null` for no cap. The
+ * sidebar has none. Contrast `quickBarCap` below.
  *
  * @param {string} menuType — a resolved menu type.
  * @returns {number|null}
@@ -81,13 +79,17 @@ export function quickBarCap(menuType) {
 }
 
 // The strip's surface was hard-coded white on BOTH hosts and its items read the
-// sidebar's tokens — which is fine while it is the sidebar's secondary quick bar
-// and fatal once it IS the menu (`bottom-tabs` hides the sidebar panel, so those
-// tokens have nowhere to be set). `footer` gives it tokens of its own.
+// sidebar's tokens. `footer` gives the quick bar tokens of its own.
+//
+// Every colour falls back to the sidebar's, so a workspace that never opens the
+// panel keeps exactly the appearance it has today; only an explicit `footer`
+// value moves anything.
 //
-// Every field falls back to the sidebar's, so a workspace that never opens the
-// Footer panel keeps exactly the appearance it has today; only an explicit
-// `footer` value moves anything.
+// sc-7695: this block is the BOTTOM EDGE's, not the quick bar's alone. A page's
+// own bottom bar (REQ-NAV-LOCAL) is the same strip worn by one page and reads
+// exactly these values — the Design panel that edits them is named for that
+// bar, since the quick bar is on its way out (sc-7753) and the look outlives
+// it. No key is the bar's alone: two strips, one look.
 export function resolveFooterTokens(theme) {
   const config = isPlainObject(theme) ? theme : {};
   const footer = isPlainObject(config.footer) ? config.footer : {};
@@ -167,11 +169,6 @@ function pageColor(config, alphaRule) {
   );
 }
 
-// An `attached` tab: opaque, or the bar shows through the page it joins.
-function pageSurface(config) {
-  return pageColor(config, opaqueOr);
-}
-
 // sc-6596: what an UNSET rail or bar is painted. Read at full strength — an
 // alpha on the bottom layer would mean nothing to chrome above it.
 function chromeSurface(config) {
@@ -214,12 +211,6 @@ function tabIndicatorOr(value) {
   return Math.min(Math.max(Math.round(value), 0), TAB_INDICATOR_MAX);
 }
 
-function opaqueOr(value) {
-  return isHexColor(value) && value.length !== 9 && value.length !== 5
-    ? value
-    : null;
-}
-
 // A gradient stop as the page readers admit one: flat hex, never alpha.
 function flatHexOrNull(value) {
   return isHexColor(value) && value.length !== 9 ? value : null;
@@ -321,18 +312,15 @@ export function resolveTopBarTokens(theme) {
     // surface and meets the page beneath it, so the two read as one plane. Meaningless on a shape that draws no tab row — a host
     // reads it only where it has tabs to draw.
     tabStyle: topBar.tabStyle === "attached" ? "attached" : "underline",
-    // The surface an `attached` tab AND its content panel share. One value for
-    // both, so the join cannot come apart: whatever the current tab is painted,
-    // the page beneath it is painted too. An authored active surface therefore
-    // moves both. Resolved HERE rather than by each host, because a tab that
-    // fails to match the page it is joined to reads as a mismatched box instead
-    // of a tab, and two hosts computing it separately is exactly how that
-    // drifts. Opaque by construction: a translucent tab would show the bar
-    // through the page it claims to be part of.
-    contentSurface: hexOr(
-      opaqueOr(topBar.tabActiveBackgroundColor),
-      pageSurface(config),
-    ),
+    // The surface the PANEL behind an `attached` row paints — the authored
+    // active colour, alpha and all, or nothing. Under `attached` the current
+    // tab itself paints NOTHING: it is a hole in the bar, and what shows
+    // through it is this panel, or the page's own wash when this is null. So
+    // the tab is exactly as see-through as the page, a gradient stays one
+    // gradient, and a translucent page never doubles up under a tab (sc-7352 —
+    // painting the tab a copy of the page could never do any of that). One
+    // value, resolved HERE, so both hosts paint the panel the same colour.
+    contentSurface: hexOrNull(topBar.tabActiveBackgroundColor),
     // REQ-NAV-STRUCTURE: the underline that marks the current tab, in px. Zero
     // turns it OFF and leaves the tab marked by its label colour alone, which
     // is a real choice rather than an unstyled state — so unlike the chrome
@@ -351,9 +339,9 @@ export function resolveTopBarTokens(theme) {
     // and the bar shows through it, which is what the row did before the keys
     // existed — so an app that never set them is unchanged.
     tabBackgroundColor: hexOrNull(topBar.tabBackgroundColor),
-    // Only meaningful where the style draws no panel: under `attached` the
-    // active surface IS `contentSurface` above. Null under `underline` leaves
-    // the current tab unpainted, marked by its indicator alone.
+    // Under `underline` the current tab's own surface, or null for none. Under
+    // `attached` the tab paints nothing and this colour is the PANEL's — see
+    // `contentSurface` above.
     tabActiveBackgroundColor: hexOrNull(topBar.tabActiveBackgroundColor),
   };
 }

package/package.json

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