@colixsystems/widget-sdk 0.142.1 → 0.144.0

package/README.md

@@ -32,6 +32,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **CORE** | `useContainerWidth()` | `[width, onLayout]` | No context slice, no scope. Measures the width the widget's OWN box has, so it can lay itself out for the space it is in rather than for the screen. Spread the handler onto your outermost primitive. Use it for any widget with a wide form and a narrow one (a table, a toolbar, a row of tiles) — never switch on the device or window width, because a widget in a one-of-three grid cell on desktop has phone-width room and a widget filling a phone page does not. Width is 0 until the first layout: render the WIDE form then. One implementation covers web (react-native-web) and the native export. |
 | **CORE** | `isNarrowWidth(width)` | `boolean` | No context slice, no scope. True when a MEASURED width is below `NARROW_WIDTH_PX` (480) — the one threshold every widget switches at, so a page reflows together rather than raggedly. An unmeasured width (0) is NOT narrow, so nothing flashes through the narrow form on first paint. |
 | **CORE** | `useSectionEmpty(isEmpty)` | `void` | `ctx.section.reportEmpty` — no scope. Declares that the widget has NO content to show, so the host drops its layout slot instead of reserving space (and its parent's `gap`) for it. Returning `null` is not enough: the host wraps every widget in an entrance element, so a widget rendering nothing still leaves an empty box the parent stack gaps around. For a CONDITIONALLY ABSENT section (a per-record child collection with no rows for this record), never to suppress a genuine empty state. Stays mounted while collapsed, so passing `false` brings it back. Authoring surfaces never collapse. No-op on a host that doesn't implement it. |
+| **CORE** | `useScreenTitle(title)` | `void` | `ctx.screen.reportTitle` — no scope. Names the screen the widget is on, so the host paints that name in the app header beside the back control instead of the app brand. The page's own name is the default; only the widget knows the screen is really "Order #1423" rather than "Orders". The MOST RECENT call wins — with several widgets on one screen the last to report owns the title, and on unmount (or an empty title) the host falls back to the most recent surviving report and finally to the page name. Only a screen showing the back control paints a title; a root page keeps the brand. No-op on a host that doesn't implement it. |
 | **CORE** | `useRefresh(handler)` | `void` | `ctx.refresh.subscribe` — no scope. Subscribes the handler to the page-level refresh tick (pull-to-refresh on mobile). Handler may return a Promise — the host waits for `allSettled` before clearing the spinner. The three datastore hooks auto-subscribe their own `refetch`; widgets only call this directly to re-run non-datastore work. No-op on a host that doesn't implement refresh. |
 | **CORE** | `useClipboard()` | `{ copy, paste, hasContent }` | platform clipboard (web `navigator.clipboard` / native `expo-clipboard`); rejects with `ClipboardError` — no scope |
 | **CORE** | `useToast()` | `{ showToast }` | `ctx.toast.showToast` — wired by the Player and the Expo export; an authoring preview omits it and the call is a no-op — no scope |
@@ -70,7 +71,28 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.142.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.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**.
+
+### What's new in 0.144.0 (contract 1.112.0)
+
+**The global mobile quick bar is retired — `quickBarMaxItems` and `quickBarCap` leave the contract (sc-7753, REQ-NAV-STRUCTURE / REQ-NAV-LOCAL).** The quick bar was a second global menu bolted to the sidebar: its own per-page flag, its own five-item cap, its own strip on the app's bottom edge. Since sc-7695 a page can carry a bottom navigation bar of its own drawing a saved menu, which is the same strip with an author-chosen list behind it — so the global one was a duplicate shape.
+
+- `CONTRACT.themeMenuTypes.sidebar` is now `{ name, summary, maxItems }`. `menuItemCap` is unchanged; `quickBarCap` is **removed** — a page's bottom bar draws the menu the author composed, so there is no global number to state.
+- `resolveFooterTokens` stays exactly as it is. It was never the quick bar's alone: it is the BOTTOM EDGE's token set, and the page's own bottom bar reads it, so a workspace's bottom-edge colours survive the retirement untouched.
+- The sc-7753 backfill turns each workspace's quick-bar pages into a saved menu and points the pages that drew the strip at it BEFORE this ships, so no destination is lost.
+- Host-integration surface only; no author-facing hook, prop or manifest field changed. `CONTRACT.version` → `1.112.0`.
+**A widget can name the screen it is on — `useScreenTitle(title)` + the optional `ctx.screen` slice (sc-7955).** The app header now shows the PAGE title beside the back control on a sub-page, instead of repeating the app brand on every screen. The page's own name is the default, but a page is often about one record, and only the widget has it:
+
+```js
+const { data: order } = useDatastoreRecord(tableId, recordId);
+useScreenTitle(order ? `Order #${order.reference}` : null);
+```
+
+- The header reads "Order #1423" rather than "Orders" as soon as the record lands; before it does, the blank title leaves the page name standing (only a non-empty string registers).
+- `reportTitle` returns a release function, so the title reverts cleanly when the widget unmounts or its title empties.
+- **The most recent call wins.** With two title-setting widgets on one screen the last to report owns the header; when it goes, the host falls back to the most recent surviving report, then to the page name.
+- Only a screen that shows the back control paints a title — a root/menu page keeps the app brand or logo untouched.
+- Optional slice: on the Studio canvas and the Agent Mode edit preview there is no app header, so the hook is a no-op rather than an error.
 
 ### What's new in 0.142.1
 
@@ -99,8 +121,8 @@ if (triggeredBy && triggeredBy.type === "app_user") {
 
 **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.
+- `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). *(`quickBarCap` was removed in 0.142.0.)*
+- 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. *(That strip was itself retired in 0.142.0.)*
 - 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

@@ -220,16 +220,13 @@ const THEME_WIDGET_STYLES = Object.freeze({
 // 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.
+// `maxItems` is the menu cap (none for a rail).
 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.",
+      "A persistent left rail on desktop; a hamburger drawer on mobile.",
     maxItems: null,
-    quickBarMaxItems: 5,
   }),
 });
 const THEME_SPACING_SCALE = Object.freeze({
@@ -718,6 +715,26 @@ const HOOKS = [
     requiredContextSlice: ["section.reportEmpty"],
     scopes: null,
   },
+  {
+    name: "useScreenTitle",
+    signature: "useScreenTitle(title)",
+    description:
+      "Name the screen this widget is on, so the host paints that name in the " +
+      "app header beside the back control. The page's own name is the default; " +
+      "only the widget knows when the screen is really \"Order #1423\" rather " +
+      "than \"Orders\". The MOST RECENT call wins: with several widgets on one " +
+      "screen the last to report owns the title, and when that widget unmounts " +
+      "(or passes an empty title) the host falls back to the most recent " +
+      "surviving report and finally to the page name. Only a screen that shows " +
+      "the back control paints a title — a root page keeps the app brand, so a " +
+      "title reported there is held but not shown. Safe on a host that does not " +
+      "implement it (Studio canvas, Agent Mode edit preview) — a no-op there.",
+    returnShape: {
+      "(returns)": "void",
+    },
+    requiredContextSlice: ["screen.reportTitle"],
+    scopes: null,
+  },
   {
     name: "useNavigation",
     signature: "useNavigation()",
@@ -2321,6 +2338,22 @@ const WIDGET_CONTEXT_SHAPE = {
     required: false,
     fields: { subscribe: "function" },
   },
+  // sc-7955 — widget -> host screen-chrome signal. The widget owns the knowledge
+  // (it has the record), the host owns the chrome (the header title slot).
+  // Optional so an AUTHORING host can omit it: with no slice the hook is a
+  // no-op on the Studio canvas and the Agent Mode edit preview, neither of
+  // which paints an app header at all.
+  screen: {
+    description:
+      "Optional screen-chrome slot. { reportTitle(title) -> release }. " +
+      "Registers this widget's title for the screen it is on and returns a " +
+      "release function that withdraws it; the host paints the most recently " +
+      "registered title in the header beside the back control and falls back " +
+      "to the page name once every registration is released. Backs " +
+      "useScreenTitle().",
+    required: false,
+    fields: { reportTitle: "function" },
+  },
   // sc-4416 — widget -> host emptiness signal. The widget owns the knowledge
   // (it has the rows); the host owns the spacing (the slot and its gap).
   // Optional so an AUTHORING host can omit it on purpose: with no slice the
@@ -3983,6 +4016,14 @@ const CONTRACT = deepFreeze({
   //    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.
+  // 1.111.0: additive (sc-7955) -- `screen` joins `widgetContextShape` and
+  //    `useScreenTitle(title)` joins `hooks`: a widget names the screen it is
+  //    on, and the host paints that name in the header beside the back control
+  //    instead of the app brand. `reportTitle` returns a release function; the
+  //    MOST RECENT registration wins and the host falls back to the most recent
+  //    surviving one, then to the page name. The slice is OPTIONAL, so an
+  //    authoring host (Studio canvas, Agent Mode edit preview) omits it and the
+  //    hook is a no-op there rather than an error.
   // 1.110.0: additive (sc-7885) — `triggeredBy` joins `actionScriptGlobals`:
   //    WHO initiated this run, as `{ type, id, name, email, role }`, or `null`
   //    on `schedule` / `record_*` where nothing did. `type` is `"app_user"` (an
@@ -3992,7 +4033,15 @@ const CONTRACT = deepFreeze({
   //    integration identity; this describes the caller, it does not grant
   //    anything. The same commit adds `properties` to this list, which the
   //    action-sdk copy had carried since 1.50.0 while this one had not.
-  version: "1.110.0",
+  // 1.112.0: BREAKING on the pre-1.0 channel (sc-7753) — `themeMenuTypes`
+  //    loses `quickBarMaxItems` and the `quickBarCap` host export goes with
+  //    it. The app's global mobile quick bar is retired: it was a SELECTION
+  //    over the global menu, and the rail and drawer list every menu page
+  //    regardless, so nothing was reachable only through it. The bottom edge
+  //    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",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -220,16 +220,13 @@ const THEME_WIDGET_STYLES = Object.freeze({
 // 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.
+// `maxItems` is the menu cap (none for a rail).
 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.",
+      "A persistent left rail on desktop; a hamburger drawer on mobile.",
     maxItems: null,
-    quickBarMaxItems: 5,
   }),
 });
 const THEME_SPACING_SCALE = Object.freeze({
@@ -718,6 +715,26 @@ const HOOKS = [
     requiredContextSlice: ["section.reportEmpty"],
     scopes: null,
   },
+  {
+    name: "useScreenTitle",
+    signature: "useScreenTitle(title)",
+    description:
+      "Name the screen this widget is on, so the host paints that name in the " +
+      "app header beside the back control. The page's own name is the default; " +
+      "only the widget knows when the screen is really \"Order #1423\" rather " +
+      "than \"Orders\". The MOST RECENT call wins: with several widgets on one " +
+      "screen the last to report owns the title, and when that widget unmounts " +
+      "(or passes an empty title) the host falls back to the most recent " +
+      "surviving report and finally to the page name. Only a screen that shows " +
+      "the back control paints a title — a root page keeps the app brand, so a " +
+      "title reported there is held but not shown. Safe on a host that does not " +
+      "implement it (Studio canvas, Agent Mode edit preview) — a no-op there.",
+    returnShape: {
+      "(returns)": "void",
+    },
+    requiredContextSlice: ["screen.reportTitle"],
+    scopes: null,
+  },
   {
     name: "useNavigation",
     signature: "useNavigation()",
@@ -2317,6 +2334,22 @@ const WIDGET_CONTEXT_SHAPE = {
     required: false,
     fields: { subscribe: "function" },
   },
+  // sc-7955 — widget -> host screen-chrome signal. The widget owns the knowledge
+  // (it has the record), the host owns the chrome (the header title slot).
+  // Optional so an AUTHORING host can omit it: with no slice the hook is a
+  // no-op on the Studio canvas and the Agent Mode edit preview, neither of
+  // which paints an app header at all.
+  screen: {
+    description:
+      "Optional screen-chrome slot. { reportTitle(title) -> release }. " +
+      "Registers this widget's title for the screen it is on and returns a " +
+      "release function that withdraws it; the host paints the most recently " +
+      "registered title in the header beside the back control and falls back " +
+      "to the page name once every registration is released. Backs " +
+      "useScreenTitle().",
+    required: false,
+    fields: { reportTitle: "function" },
+  },
   // sc-4416 — widget -> host emptiness signal. The widget owns the knowledge
   // (it has the rows); the host owns the spacing (the slot and its gap).
   // Optional so an AUTHORING host can omit it on purpose: with no slice the
@@ -3979,6 +4012,14 @@ const CONTRACT = deepFreeze({
   //    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.
+  // 1.111.0: additive (sc-7955) -- `screen` joins `widgetContextShape` and
+  //    `useScreenTitle(title)` joins `hooks`: a widget names the screen it is
+  //    on, and the host paints that name in the header beside the back control
+  //    instead of the app brand. `reportTitle` returns a release function; the
+  //    MOST RECENT registration wins and the host falls back to the most recent
+  //    surviving one, then to the page name. The slice is OPTIONAL, so an
+  //    authoring host (Studio canvas, Agent Mode edit preview) omits it and the
+  //    hook is a no-op there rather than an error.
   // 1.110.0: additive (sc-7885) — `triggeredBy` joins `actionScriptGlobals`:
   //    WHO initiated this run, as `{ type, id, name, email, role }`, or `null`
   //    on `schedule` / `record_*` where nothing did. `type` is `"app_user"` (an
@@ -3988,7 +4029,15 @@ const CONTRACT = deepFreeze({
   //    integration identity; this describes the caller, it does not grant
   //    anything. The same commit adds `properties` to this list, which the
   //    action-sdk copy had carried since 1.50.0 while this one had not.
-  version: "1.110.0",
+  // 1.112.0: BREAKING on the pre-1.0 channel (sc-7753) — `themeMenuTypes`
+  //    loses `quickBarMaxItems` and the `quickBarCap` host export goes with
+  //    it. The app's global mobile quick bar is retired: it was a SELECTION
+  //    over the global menu, and the rail and drawer list every menu page
+  //    regardless, so nothing was reachable only through it. The bottom edge
+  //    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",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -386,6 +386,36 @@ export function useSectionEmpty(isEmpty) {
   }, [empty]);
 }
 
+/**
+ * sc-7955 — name the screen this widget is on, so the host paints that name in
+ * the header beside the back control. The page name is the default; only the
+ * widget knows when the screen is really "Order #1423" rather than "Orders".
+ *
+ * The MOST RECENT call wins: with several widgets on one screen the last to
+ * report owns the title, and when that widget unmounts (or passes an empty
+ * title) the host falls back to the most recent surviving report, then to the
+ * page name. Pass a blank or non-string title to bow out without unmounting
+ * (only a non-empty string registers, so a numeric id registers nothing).
+ *
+ * Keep it short — roughly 25 characters. The slot is one line and truncates
+ * with an ellipsis, sharing the row with back and the bell/identity cluster.
+ *
+ * Only a screen that shows the back control paints a title — a root page keeps
+ * the app brand, so a title reported there is held but not shown.
+ *
+ * Safe to call on a host that does not implement it: the hook is a no-op on the
+ * Studio canvas and the Agent Mode edit preview, which paint no app header.
+ */
+export function useScreenTitle(title) {
+  const ctx = useWidgetContextOrThrow("useScreenTitle");
+  const report = ctx.screen && ctx.screen.reportTitle;
+  const text = typeof title === "string" ? title.trim() : "";
+  useEffect(() => {
+    if (typeof report !== "function" || !text) return undefined;
+    return report(text);
+  }, [report, text]);
+}
+
 /**
  * sc-4399 — measure the width the widget's own box actually has, so it can lay
  * itself out for the space it is in rather than for the screen. A widget in a

package/dist/host.d.ts

@@ -173,15 +173,9 @@ export function normaliseNavigation(navigation: unknown): ResolvedNavigation;
  */
 export function menuItemCap(menuType: string): number | null;
 
-/**
- * How many pages the SECONDARY mobile quick bar draws, or `null` where the shape
- * draws none (only `sidebar` has one). Unlike `menuItemCap` this cap MAY drop a
- * page: the rail and drawer still list every menu page.
- */
-export function quickBarCap(menuType: string): number | null;
-
-/** The footer strip's resolved tokens. A `null` colour means the host keeps its
- *  own default; a `null` `borderColor` means no divider is drawn at all. */
+/** The app's bottom edge — a page's own bottom navigation bar. A `null` colour
+ *  means the host keeps its own default; a `null` `borderColor` means no
+ *  divider is drawn at all. */
 export interface FooterTokens {
   backgroundColor: string | null;
   textColor: string | null;

package/dist/host.js

@@ -55,18 +55,17 @@ export {
 // 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.
+// shapes, so a stored value never needs guarding; `menuItemCap` states the cap.
+// One implementation, so the chrome cannot mean one thing in the Player and
+// another in the Expo export. `resolveFooterTokens` is the BOTTOM EDGE's token
+// set — a page's own bottom navigation bar (REQ-NAV-LOCAL) — 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.
 export {
   normaliseNavigation,
   menuItemCap,
-  quickBarCap,
   resolveFooterTokens,
   resolveSidebarTokens,
   resolveTopBarTokens,

package/dist/index.d.ts

@@ -1473,6 +1473,8 @@ export function useRefresh(
  * collapse. Safe on a host that does not implement it — a no-op there.
  */
 export function useSectionEmpty(isEmpty: boolean): void;
+/** sc-7955 — name this screen for the header title slot; most recent call wins. */
+export function useScreenTitle(title: string | null | undefined): void;
 
 /** The layout event a react-native primitive passes to `onLayout`. */
 export interface WidgetLayoutEvent {

package/dist/index.js

@@ -75,6 +75,7 @@ export {
   useChildRenderer,
   useRefresh,
   useSectionEmpty,
+  useScreenTitle,
   useContainerWidth,
   useGeolocation,
   GeolocationError,

package/dist/index.native.js

@@ -75,6 +75,7 @@ export {
   useChildRenderer,
   useRefresh,
   useSectionEmpty,
+  useScreenTitle,
   useContainerWidth,
   useGeolocation,
   GeolocationError,

package/dist/navigation.cjs

@@ -60,7 +60,7 @@ function normaliseNavigation(navigation) {
 
 /**
  * How many MENU pages the chrome may draw at once, or `null` for no cap. The
- * sidebar has none. Contrast `quickBarCap` below.
+ * sidebar has none.
  *
  * @param {string} menuType — a resolved menu type.
  * @returns {number|null}
@@ -70,35 +70,12 @@ function menuItemCap(menuType) {
   return entry ? entry.maxItems : null;
 }
 
-/**
- * How many pages the SECONDARY mobile quick bar draws, or `null` where that
- * shape draws none. Only the `sidebar` shape has one.
- *
- * This cap MAY drop a page, and that is the difference from `menuItemCap`: the
- * rail and the drawer still list every menu page, so the bar is a shortcut
- * rather than the menu. It lived as a constant on one host and a literal on the
- * other before this, which is exactly how the two would have drifted.
- *
- * @param {string} menuType — a resolved menu type.
- * @returns {number|null}
- */
-function quickBarCap(menuType) {
-  const entry = CONTRACT.themeMenuTypes[menuType];
-  return entry ? entry.quickBarMaxItems : null;
-}
-
-// The strip's surface was hard-coded white on BOTH hosts and its items read the
-// 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.
+// REQ-NAV-LOCAL: the app's BOTTOM EDGE — the tokens a page's own bottom
+// navigation bar is drawn from. Every colour falls back to the sidebar's, so a
+// workspace that never opens the panel keeps the appearance it has.
 //
-// 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.
+// 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`).
 function resolveFooterTokens(theme) {
   const config = isPlainObject(theme) ? theme : {};
   const footer = isPlainObject(config.footer) ? config.footer : {};
@@ -113,8 +90,8 @@ function resolveFooterTokens(theme) {
     // colour resolves to the brand primary, which the caller supplies.
     activeColor: pick("activeColor"),
     // REQ-THEME-LOOK: the divider's COLOUR is its switch. Unset draws no line at
-    // all — which the native quick bar did not honour before this, ruling a
-    // hairline across a tinted strip that had asked for none.
+    // 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",
@@ -362,4 +339,4 @@ function borderWidthOr(...values) {
   return 1;
 }
 
-module.exports = { normaliseNavigation, menuItemCap, quickBarCap, resolveFooterTokens, resolveSidebarTokens, resolveTopBarTokens };
+module.exports = { normaliseNavigation, menuItemCap, resolveFooterTokens, resolveSidebarTokens, resolveTopBarTokens };

package/dist/navigation.js

@@ -51,7 +51,7 @@ export function normaliseNavigation(navigation) {
 
 /**
  * How many MENU pages the chrome may draw at once, or `null` for no cap. The
- * sidebar has none. Contrast `quickBarCap` below.
+ * sidebar has none.
  *
  * @param {string} menuType — a resolved menu type.
  * @returns {number|null}
@@ -61,35 +61,12 @@ export function menuItemCap(menuType) {
   return entry ? entry.maxItems : null;
 }
 
-/**
- * How many pages the SECONDARY mobile quick bar draws, or `null` where that
- * shape draws none. Only the `sidebar` shape has one.
- *
- * This cap MAY drop a page, and that is the difference from `menuItemCap`: the
- * rail and the drawer still list every menu page, so the bar is a shortcut
- * rather than the menu. It lived as a constant on one host and a literal on the
- * other before this, which is exactly how the two would have drifted.
- *
- * @param {string} menuType — a resolved menu type.
- * @returns {number|null}
- */
-export function quickBarCap(menuType) {
-  const entry = CONTRACT.themeMenuTypes[menuType];
-  return entry ? entry.quickBarMaxItems : null;
-}
-
-// The strip's surface was hard-coded white on BOTH hosts and its items read the
-// 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.
+// REQ-NAV-LOCAL: the app's BOTTOM EDGE — the tokens a page's own bottom
+// navigation bar is drawn from. Every colour falls back to the sidebar's, so a
+// workspace that never opens the panel keeps the appearance it has.
 //
-// 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.
+// 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`).
 export function resolveFooterTokens(theme) {
   const config = isPlainObject(theme) ? theme : {};
   const footer = isPlainObject(config.footer) ? config.footer : {};
@@ -104,8 +81,8 @@ export function resolveFooterTokens(theme) {
     // colour resolves to the brand primary, which the caller supplies.
     activeColor: pick("activeColor"),
     // REQ-THEME-LOOK: the divider's COLOUR is its switch. Unset draws no line at
-    // all — which the native quick bar did not honour before this, ruling a
-    // hairline across a tinted strip that had asked for none.
+    // 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",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.142.1",
+  "version": "0.144.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",
@@ -49,7 +49,7 @@
   ],
   "scripts": {
     "build": "node scripts/build.js",
-    "test": "node --test src/__tests__/contract.test.js src/__tests__/theme-token-refs.test.js src/__tests__/vetted-imports-audit.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-invites.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-filestore-file.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-payments.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-section-empty.test.js src/__tests__/hooks-widget-event.test.js src/__tests__/hooks-widget-input.test.js src/__tests__/hooks-identification.test.js src/__tests__/hooks-subscription.test.js src/__tests__/hooks-volatile-query-key.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/linter-translation-api.test.js src/__tests__/linter-page-url.test.js src/__tests__/linter-image-height.test.js src/__tests__/linter-flex-basis-percent.test.js src/__tests__/linter-hardcoded-design.test.js src/__tests__/linter-editability.test.js src/__tests__/linter-measured-padding.test.js src/__tests__/linter-payment-error.test.js src/__tests__/linter-platform.test.js src/__tests__/linter-react-import.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/lucideIconName.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/hooks-translate.test.js src/__tests__/devserver.test.js src/__tests__/flatten-entry.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js src/__tests__/property-schema-resolve.test.js src/__tests__/corner-radius.test.js src/__tests__/theme-components-parity.test.js src/__tests__/navigation-parity.test.js src/__tests__/theme-depth-tokens.test.js src/__tests__/interaction-lift.test.js src/__tests__/toast-host.test.js src/__tests__/overlay-tokens.test.js src/__tests__/hooks-domain-error-mapping.test.js src/__tests__/linter-datastore-error.test.js src/__tests__/linter-write-gating.test.js src/__tests__/hooks-speech-to-text.test.js src/__tests__/hooks-camera.test.js src/__tests__/hooks-barcode.test.js src/__tests__/hooks-image-editor.test.js src/__tests__/hooks-bound-columns.test.js src/__tests__/hooks-stable-query.test.js src/__tests__/hooks-can-write.test.js src/__tests__/widget-route.test.js src/__tests__/linter-html-in-content.test.js src/__tests__/markdown.test.js src/__tests__/markdown-edit.test.js src/__tests__/richtext-tokens.test.js src/__tests__/style-group.test.js"
+    "test": "node --test src/__tests__/contract.test.js src/__tests__/theme-token-refs.test.js src/__tests__/vetted-imports-audit.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-invites.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-filestore-file.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-payments.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-section-empty.test.js src/__tests__/hooks-screen-title.test.js src/__tests__/hooks-widget-event.test.js src/__tests__/hooks-widget-input.test.js src/__tests__/hooks-identification.test.js src/__tests__/hooks-subscription.test.js src/__tests__/hooks-volatile-query-key.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/linter-translation-api.test.js src/__tests__/linter-page-url.test.js src/__tests__/linter-image-height.test.js src/__tests__/linter-flex-basis-percent.test.js src/__tests__/linter-hardcoded-design.test.js src/__tests__/linter-editability.test.js src/__tests__/linter-measured-padding.test.js src/__tests__/linter-payment-error.test.js src/__tests__/linter-platform.test.js src/__tests__/linter-react-import.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/lucideIconName.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/hooks-translate.test.js src/__tests__/devserver.test.js src/__tests__/flatten-entry.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js src/__tests__/property-schema-resolve.test.js src/__tests__/corner-radius.test.js src/__tests__/theme-components-parity.test.js src/__tests__/navigation-parity.test.js src/__tests__/theme-depth-tokens.test.js src/__tests__/interaction-lift.test.js src/__tests__/toast-host.test.js src/__tests__/overlay-tokens.test.js src/__tests__/hooks-domain-error-mapping.test.js src/__tests__/linter-datastore-error.test.js src/__tests__/linter-write-gating.test.js src/__tests__/hooks-speech-to-text.test.js src/__tests__/hooks-camera.test.js src/__tests__/hooks-barcode.test.js src/__tests__/hooks-image-editor.test.js src/__tests__/hooks-bound-columns.test.js src/__tests__/hooks-stable-query.test.js src/__tests__/hooks-can-write.test.js src/__tests__/widget-route.test.js src/__tests__/linter-html-in-content.test.js src/__tests__/markdown.test.js src/__tests__/markdown-edit.test.js src/__tests__/richtext-tokens.test.js src/__tests__/style-group.test.js"
   },
   "engines": {
     "node": ">=18"