@colixsystems/widget-sdk 0.167.0 → 0.168.0

package/README.md

@@ -93,7 +93,7 @@ Render an **assistant** message with `<RichText value={m.content} stripLegacyHtm
 A binding may now carry an opacity: `"theme:colors.primary/20"` is the primary brand colour at 20%.
 
 - **`parseThemeColorTokenRef(value)` / `formatThemeColorTokenRef(path, percent)`** publish the grammar beside the existing `isThemeColorTokenRef` predicate. The BARE form inherits whatever opacity the token itself carries — a workspace may author a translucent brand colour — so `/100` is a real value, not a redundant spelling: it is how "opaque, whatever the brand does" is said. One opacity has one spelling otherwise (no leading zeros, nothing above 100).
-- **`withHexAlpha(hex, percent)` / `hexAlphaPercent(hex)`** are the percent ↔ alpha-byte conversion the Studio's opacity control and both hosts' resolver share, so the 20% a panel reads back is the 20% a render paints.
+- **`withHexAlpha(hex, percent)` / `hexAlphaPercent(hex)`** are the percent ↔ alpha-byte conversion, so the 20% a panel reads back is the 20% a render paints. The Studio's `frontend/src/utils/color.js` keeps its own copy of this maths rather than importing it — that module is reached by a `node --test` suite, and the SDK is a Vite alias with no node resolution — and the two are pinned equal by the SDK's suite.
 - **An authored opacity replaces the token's.** With none authored the token is handed back verbatim, including a token that is itself translucent — reading the bare form as 100 would quietly paint a see-through brand colour solid.
 - **A token resolving to a non-hex colour stays opaque** — alpha cannot be applied without rewriting the author's notation — and the Studio disables the opacity control for that case rather than lying about it.
 - **Nothing changes for a widget author.** The host still hands your code an ordinary colour string; it is simply `#RRGGBBAA` when an opacity was authored.

package/dist/contract.cjs

@@ -4539,10 +4539,10 @@ const CONTRACT = deepFreeze({
   //    field bound, so "our brand colour at 20%" forced the author back to a
   //    frozen hex, which then stopped following a rebrand — the exact thing
   //    binding exists to prevent. `parseThemeColorTokenRef` /
-  //    `formatThemeColorTokenRef` publish the grammar and
+  //    `formatThemeColorTokenRef` publish the grammar, and
   //    `withHexAlpha` / `hexAlphaPercent` the percent-to-byte conversion the
-  //    Studio's control and both hosts' resolver share, so 20% authored is 20%
-  //    painted. The BARE form inherits the token's own opacity (a brand colour
+  //    Studio's control and both hosts' resolver answer alike, so 20% authored
+  //    is 20% painted. The BARE form inherits the token's own opacity (a brand colour
   //    may be authored translucent), which makes `/100` a real value rather
   //    than a redundant spelling: it is how "opaque, whatever the brand does"
   //    is said. Additive: an unsuffixed binding parses and resolves exactly as

package/dist/contract.js

@@ -4535,10 +4535,10 @@ const CONTRACT = deepFreeze({
   //    field bound, so "our brand colour at 20%" forced the author back to a
   //    frozen hex, which then stopped following a rebrand — the exact thing
   //    binding exists to prevent. `parseThemeColorTokenRef` /
-  //    `formatThemeColorTokenRef` publish the grammar and
+  //    `formatThemeColorTokenRef` publish the grammar, and
   //    `withHexAlpha` / `hexAlphaPercent` the percent-to-byte conversion the
-  //    Studio's control and both hosts' resolver share, so 20% authored is 20%
-  //    painted. The BARE form inherits the token's own opacity (a brand colour
+  //    Studio's control and both hosts' resolver answer alike, so 20% authored
+  //    is 20% painted. The BARE form inherits the token's own opacity (a brand colour
   //    may be authored translucent), which makes `/100` a real value rather
   //    than a redundant spelling: it is how "opaque, whatever the brand does"
   //    is said. Additive: an unsuffixed binding parses and resolves exactly as

package/dist/host.js

@@ -74,6 +74,9 @@ export {
 // SIDEBAR local menu hangs in the rail and the drawer. The compiler asks it
 // once per screen at build time and the Player once per render, so the two
 // chromes derive the same tree from the same code.
+// REQ-NAV-LOCAL (sc-8901): `resolveLocalNavModel` answers WHICH model a page
+// wears in one device view, so the same menu can be a bottom bar on a phone and
+// unfold in the rail on a desktop.
 export {
   normaliseNavigation,
   menuItemCap,
@@ -94,6 +97,8 @@ export {
   DEFAULT_TOP_STRIPE_HEIGHT_PX,
   DEFAULT_TOP_STRIPE_PADDING_X_PX,
   resolveSidebarUnfold,
+  resolveLocalNavModel,
+  drawsLocalNavAnywhere,
 } from "./navigation.js";
 
 // sc-5717: the codec behind `useWidgetRoute()` — how a widget's own internal

package/dist/navigation.cjs

@@ -675,6 +675,64 @@ function resolveSidebarUnfold(input) {
   return { under: section.key, items: marked, standalone: true };
 }
 
+/**
+ * REQ-NAV-LOCAL (sc-8901) — which local-navigation model a page wears in ONE
+ * device view, so the same saved menu can be a bottom bar on a phone and unfold
+ * in the rail on a desktop.
+ *
+ * `local_nav` is the MOBILE value and the base of the cascade: a page authored
+ * before the wider views existed leaves both of them unset and therefore
+ * renders identically at every width. The cascade is REQ-LAY-07's — the one the
+ * layout grid and every responsive widget prop already use — because a page's
+ * chrome and its content must not disagree about what a tablet is.
+ *
+ * The vocabulary stays the API's: any non-empty string is a model and the
+ * host's own switch decides what it can draw, so a kind a newer backend allows
+ * cascades correctly here instead of being flattened to `NONE` on the way.
+ *
+ * @param {object|null|undefined} page — a page row carrying `local_nav` and,
+ *   optionally, `local_nav_tablet` / `local_nav_desktop`.
+ * @param {"mobile"|"tablet"|"desktop"} view — the device view being drawn.
+ * @returns {string} the model for that view; `NONE` when the page sets none.
+ */
+function resolveLocalNavModel(page, view) {
+  const at = (key) => {
+    const value = isPlainObject(page) ? page[key] : null;
+    return typeof value === "string" && value ? value : null;
+  };
+  const mobile = at("local_nav") || "NONE";
+  if (view === "desktop") {
+    return at("local_nav_desktop") || at("local_nav_tablet") || mobile;
+  }
+  if (view === "tablet") return at("local_nav_tablet") || mobile;
+  return mobile;
+}
+
+// sc-8901: the three device views a local bar can differ across — REQ-LAY-07's
+// own list, so a page's chrome and its content classify a width alike. Ordered
+// narrowest first, which is also the cascade's direction.
+const LOCAL_NAV_VIEWS = ["mobile", "tablet", "desktop"];
+
+/**
+ * REQ-NAV-LOCAL (sc-8901) — does this page draw a local bar in ANY device view?
+ *
+ * The saved-menu reference is shared by all three views, so it is required — and
+ * resolved onto the wire — as soon as one of them draws. Asking
+ * `local_nav !== "NONE"` alone would miss a page that carries a bar only on the
+ * wider views.
+ *
+ * Beside the cascade it is derived from, so the API rule, the export's screen
+ * bake and Copy Workspace cannot disagree about which pages have a bar.
+ *
+ * @param {object|null|undefined} page — a page row.
+ * @returns {boolean}
+ */
+function drawsLocalNavAnywhere(page) {
+  return LOCAL_NAV_VIEWS.some(
+    (view) => resolveLocalNavModel(page, view) !== "NONE",
+  );
+}
+
 // REQ-THEME-LOOK: the divider's width in px, bounded HERE so both hosts inherit
 // one range. The export clamped it on its way into the StyleSheet
 // (`coerceBorderWidth(...) ?? 1`) where the Player passed any finite number
@@ -711,4 +769,4 @@ function borderWidthOr(...values) {
   return BORDER_WIDTH_MIN;
 }
 
-module.exports = { normaliseNavigation, menuItemCap, resolveFooterTokens, resolveSidebarTokens, resolveTopStripeLayout, resolveTopBarTokens, topStripeShowKey, TOP_STRIPE_ALWAYS_SHOWN_SLOTS, TOP_STRIPE_SLOTS, MIN_TOP_STRIPE_HEIGHT_PX, MAX_TOP_STRIPE_HEIGHT_PX, MIN_TOP_STRIPE_PADDING_X_PX, MAX_TOP_STRIPE_PADDING_X_PX, MAX_TOP_STRIPE_OFFSET_Y_PX, DEFAULT_TOP_STRIPE_HEIGHT_PX, DEFAULT_TOP_STRIPE_PADDING_X_PX, resolveSidebarUnfold };
+module.exports = { normaliseNavigation, menuItemCap, resolveFooterTokens, resolveSidebarTokens, resolveTopStripeLayout, resolveTopBarTokens, topStripeShowKey, TOP_STRIPE_ALWAYS_SHOWN_SLOTS, TOP_STRIPE_SLOTS, MIN_TOP_STRIPE_HEIGHT_PX, MAX_TOP_STRIPE_HEIGHT_PX, MIN_TOP_STRIPE_PADDING_X_PX, MAX_TOP_STRIPE_PADDING_X_PX, MAX_TOP_STRIPE_OFFSET_Y_PX, DEFAULT_TOP_STRIPE_HEIGHT_PX, DEFAULT_TOP_STRIPE_PADDING_X_PX, resolveSidebarUnfold, resolveLocalNavModel, drawsLocalNavAnywhere };

package/dist/navigation.js

@@ -666,6 +666,64 @@ export function resolveSidebarUnfold(input) {
   return { under: section.key, items: marked, standalone: true };
 }
 
+/**
+ * REQ-NAV-LOCAL (sc-8901) — which local-navigation model a page wears in ONE
+ * device view, so the same saved menu can be a bottom bar on a phone and unfold
+ * in the rail on a desktop.
+ *
+ * `local_nav` is the MOBILE value and the base of the cascade: a page authored
+ * before the wider views existed leaves both of them unset and therefore
+ * renders identically at every width. The cascade is REQ-LAY-07's — the one the
+ * layout grid and every responsive widget prop already use — because a page's
+ * chrome and its content must not disagree about what a tablet is.
+ *
+ * The vocabulary stays the API's: any non-empty string is a model and the
+ * host's own switch decides what it can draw, so a kind a newer backend allows
+ * cascades correctly here instead of being flattened to `NONE` on the way.
+ *
+ * @param {object|null|undefined} page — a page row carrying `local_nav` and,
+ *   optionally, `local_nav_tablet` / `local_nav_desktop`.
+ * @param {"mobile"|"tablet"|"desktop"} view — the device view being drawn.
+ * @returns {string} the model for that view; `NONE` when the page sets none.
+ */
+export function resolveLocalNavModel(page, view) {
+  const at = (key) => {
+    const value = isPlainObject(page) ? page[key] : null;
+    return typeof value === "string" && value ? value : null;
+  };
+  const mobile = at("local_nav") || "NONE";
+  if (view === "desktop") {
+    return at("local_nav_desktop") || at("local_nav_tablet") || mobile;
+  }
+  if (view === "tablet") return at("local_nav_tablet") || mobile;
+  return mobile;
+}
+
+// sc-8901: the three device views a local bar can differ across — REQ-LAY-07's
+// own list, so a page's chrome and its content classify a width alike. Ordered
+// narrowest first, which is also the cascade's direction.
+const LOCAL_NAV_VIEWS = ["mobile", "tablet", "desktop"];
+
+/**
+ * REQ-NAV-LOCAL (sc-8901) — does this page draw a local bar in ANY device view?
+ *
+ * The saved-menu reference is shared by all three views, so it is required — and
+ * resolved onto the wire — as soon as one of them draws. Asking
+ * `local_nav !== "NONE"` alone would miss a page that carries a bar only on the
+ * wider views.
+ *
+ * Beside the cascade it is derived from, so the API rule, the export's screen
+ * bake and Copy Workspace cannot disagree about which pages have a bar.
+ *
+ * @param {object|null|undefined} page — a page row.
+ * @returns {boolean}
+ */
+export function drawsLocalNavAnywhere(page) {
+  return LOCAL_NAV_VIEWS.some(
+    (view) => resolveLocalNavModel(page, view) !== "NONE",
+  );
+}
+
 // REQ-THEME-LOOK: the divider's width in px, bounded HERE so both hosts inherit
 // one range. The export clamped it on its way into the StyleSheet
 // (`coerceBorderWidth(...) ?? 1`) where the Player passed any finite number

package/package.json

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