@colixsystems/widget-sdk 0.124.0 → 0.125.0

package/README.md

@@ -70,7 +70,19 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.124.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.125.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.125.0 (contract 1.97.0)
+
+**A `top-bar` app no longer chooses which row carries its menu — `CONTRACT.themeTopBarMenuStyles` is REMOVED and `normaliseNavigation` returns `menuType` alone (sc-7044).** 0.120.0 gave the shape two menu rows to pick between: `links`, the row of text links beside the brand it had always drawn, and `tabs`, a dedicated tab row beneath the bar. `links` turned out to be the site-mode header's own row — literally the same `header` nav variant, sitting in the Studio beside "Show a header on site-mode pages" and its "Menu links" toggle, so an author was offered three adjacent settings that render the same thing. The tab row is the one that reads as an app's global navigation, so it is now the only one.
+
+A host branches on `menuType` alone:
+
+- `CONTRACT.themeTopBarMenuStyles` is gone, and so is the `ThemeTopBarMenuStyle` type. `ResolvedNavigation` is `{ menuType }`.
+- `resolveTopBarTokens` is UNCHANGED — the whole `topBar` tab vocabulary (`tabStyle`, `contentSurface`, `tabIndicatorWidth`, `tabCornerRadius`, `tabPaddingX` / `tabPaddingY`, `tabBackgroundColor`, `tabActiveBackgroundColor`) now applies to every `top-bar` app rather than only to one that opted into tabs.
+- A stored `navigation.topBarMenuStyle` is **inert**, not migrated. Nothing reads it, so no backfill runs; a `top-bar` app that never chose `tabs` renders the tab row from this version on.
+
+**BREAKING, host-integration surface only** — a host that destructured `topBarMenuStyle` must stop. Nothing a widget author imports moved: no hook, primitive, manifest field or `propertySchema` type changed. `CONTRACT.version` → `1.97.0`.
 
 ### What's new in 0.124.0 (contract 1.96.0)
 

package/dist/contract.cjs

@@ -216,7 +216,7 @@ const THEME_MENU_TYPES = Object.freeze({
   "top-bar": Object.freeze({
     name: "Top bar",
     summary:
-      "A horizontal row of links in the app header, scrolling sideways when it runs out of room. No rail at any width.",
+      "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,
   }),
@@ -228,18 +228,6 @@ const THEME_MENU_TYPES = Object.freeze({
     quickBarMaxItems: null,
   }),
 });
-const THEME_TOP_BAR_MENU_STYLES = Object.freeze({
-  links: Object.freeze({
-    name: "Links",
-    summary:
-      "Text links beside the brand, dropping to their own row only when a phone leaves them no space.",
-  }),
-  tabs: Object.freeze({
-    name: "Tabs",
-    summary:
-      "A dedicated tab row under the bar at every width -- icon and label per page, marked by the brand, scrolling sideways when it runs out of room.",
-  }),
-});
 const THEME_SPACING_SCALE = Object.freeze({
   min: 0.5,
   max: 2,
@@ -3671,7 +3659,15 @@ const CONTRACT = deepFreeze({
   //    privacy remains the record ACL's job. Existing `literal` and
   //    `relativeDate` conditions are untouched -- minor bump on the pre-1.0
   //    channel.
-  version: "1.96.0",
+  // 1.97.0: BREAKING (sc-7044) -- `themeTopBarMenuStyles` is REMOVED and
+  //    `normaliseNavigation` no longer returns `topBarMenuStyle`. A `top-bar`
+  //    app has ONE menu shape: the tab row beneath the bar. The `links` style
+  //    drew the menu on the same row-of-text-links the site-mode header draws,
+  //    so the Studio offered three adjacent settings that an author could not
+  //    tell apart. A host now branches on `menuType` alone; a stored
+  //    `navigation.topBarMenuStyle` is inert rather than migrated, so a
+  //    `top-bar` app that never chose `tabs` moves to the tab row.
+  version: "1.97.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -3688,7 +3684,6 @@ const CONTRACT = deepFreeze({
   themeComponentGradient: THEME_COMPONENT_GRADIENT,
   themeSpacingScale: THEME_SPACING_SCALE,
   themeMenuTypes: THEME_MENU_TYPES,
-  themeTopBarMenuStyles: THEME_TOP_BAR_MENU_STYLES,
   themeWidgetStyles: THEME_WIDGET_STYLES,
   widgetContextShape: WIDGET_CONTEXT_SHAPE,
   bundleExportContract: BUNDLE_EXPORT_CONTRACT,

package/dist/contract.js

@@ -216,7 +216,7 @@ const THEME_MENU_TYPES = Object.freeze({
   "top-bar": Object.freeze({
     name: "Top bar",
     summary:
-      "A horizontal row of links in the app header, scrolling sideways when it runs out of room. No rail at any width.",
+      "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,
   }),
@@ -228,18 +228,6 @@ const THEME_MENU_TYPES = Object.freeze({
     quickBarMaxItems: null,
   }),
 });
-const THEME_TOP_BAR_MENU_STYLES = Object.freeze({
-  links: Object.freeze({
-    name: "Links",
-    summary:
-      "Text links beside the brand, dropping to their own row only when a phone leaves them no space.",
-  }),
-  tabs: Object.freeze({
-    name: "Tabs",
-    summary:
-      "A dedicated tab row under the bar at every width -- icon and label per page, marked by the brand, scrolling sideways when it runs out of room.",
-  }),
-});
 const THEME_SPACING_SCALE = Object.freeze({
   min: 0.5,
   max: 2,
@@ -3671,7 +3659,15 @@ const CONTRACT = deepFreeze({
   //    privacy remains the record ACL's job. Existing `literal` and
   //    `relativeDate` conditions are untouched -- minor bump on the pre-1.0
   //    channel.
-  version: "1.96.0",
+  // 1.97.0: BREAKING (sc-7044) -- `themeTopBarMenuStyles` is REMOVED and
+  //    `normaliseNavigation` no longer returns `topBarMenuStyle`. A `top-bar`
+  //    app has ONE menu shape: the tab row beneath the bar. The `links` style
+  //    drew the menu on the same row-of-text-links the site-mode header draws,
+  //    so the Studio offered three adjacent settings that an author could not
+  //    tell apart. A host now branches on `menuType` alone; a stored
+  //    `navigation.topBarMenuStyle` is inert rather than migrated, so a
+  //    `top-bar` app that never chose `tabs` moves to the tab row.
+  version: "1.97.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -3688,7 +3684,6 @@ const CONTRACT = deepFreeze({
   themeComponentGradient: THEME_COMPONENT_GRADIENT,
   themeSpacingScale: THEME_SPACING_SCALE,
   themeMenuTypes: THEME_MENU_TYPES,
-  themeTopBarMenuStyles: THEME_TOP_BAR_MENU_STYLES,
   themeWidgetStyles: THEME_WIDGET_STYLES,
   widgetContextShape: WIDGET_CONTEXT_SHAPE,
   bundleExportContract: BUNDLE_EXPORT_CONTRACT,

package/dist/host.d.ts

@@ -155,14 +155,8 @@ export function createToastController(
 
 export type ThemeMenuType = "sidebar" | "top-bar" | "bottom-tabs";
 
-// How a `top-bar` app draws its menu — closed by
-// `CONTRACT.themeTopBarMenuStyles`. Meaningless on the other two shapes, where
-// the resolver always reports "links".
-export type ThemeTopBarMenuStyle = "links" | "tabs";
-
 export interface ResolvedNavigation {
   menuType: ThemeMenuType;
-  topBarMenuStyle: ThemeTopBarMenuStyle;
 }
 
 /**

package/dist/navigation.cjs

@@ -30,9 +30,6 @@ const { CONTRACT, isHexColor } = require("./contract.cjs");
 // Absent or unknown resolves here, so every app authored before menu types
 // existed renders and compiles byte-identically.
 const DEFAULT_MENU_TYPE = "sidebar";
-// Today's row of text links, so an app that never made the choice draws exactly
-// what it drew before it existed.
-const DEFAULT_TOP_BAR_MENU_STYLE = "links";
 
 function isPlainObject(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -45,8 +42,7 @@ function isPlainObject(value) {
  * yields the default sidebar rather than something a host has to guard against.
  *
  * @param {unknown} navigation — the raw `theme_config.navigation` value.
- * @returns {{ menuType: string, topBarMenuStyle: string }} the resolved
- *   navigation structure.
+ * @returns {{ menuType: string }} the resolved navigation structure.
  */
 function normaliseNavigation(navigation) {
   const block = isPlainObject(navigation) ? navigation : {};
@@ -55,16 +51,11 @@ function normaliseNavigation(navigation) {
     typeof raw === "string" && Object.hasOwn(CONTRACT.themeMenuTypes, raw)
       ? raw
       : DEFAULT_MENU_TYPE;
-  const rawStyle = block.topBarMenuStyle;
-  // Resolved to `links` for every shape but `top-bar`, so a host reading it can
-  // never act on a value the app's own chrome has no row to draw.
-  const topBarMenuStyle =
-    menuType === "top-bar" &&
-    typeof rawStyle === "string" &&
-    Object.hasOwn(CONTRACT.themeTopBarMenuStyles, rawStyle)
-      ? rawStyle
-      : DEFAULT_TOP_BAR_MENU_STYLE;
-  return { menuType, topBarMenuStyle };
+  // sc-7044: the SHAPE is the whole answer. A `top-bar` app used to also choose
+  // which row carried its menu, and the `links` option drew the site header's
+  // own row of text links — a second way to say the same thing. The tab row is
+  // the only shape now, so a stored `topBarMenuStyle` is read by nobody.
+  return { menuType };
 }
 
 /**
@@ -339,8 +330,8 @@ function resolveTopBarTokens(theme) {
     // `underline` keeps the tab in the bar's surface and marks it with an
     // indicator. `attached` makes it a real folder tab: it takes the CONTENT's
     // surface and sits over the row's divider, so the tab and the page beneath
-    // read as one plane. Meaningless under the `links` style, which draws no
-    // tabs — a host reads it only where it has tabs to draw.
+    // 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,
@@ -369,8 +360,8 @@ function resolveTopBarTokens(theme) {
     tabPaddingX: tabSpaceOr(topBar.tabPaddingX, DEFAULT_TAB_PADDING_X),
     tabPaddingY: tabSpaceOr(topBar.tabPaddingY, DEFAULT_TAB_PADDING_Y),
     // A tab's own surface, authored or nothing. Null means the tab paints none
-    // and the bar shows through it, which is what both styles did before the
-    // keys existed — so an app that never set them is unchanged.
+    // 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

package/dist/navigation.js

@@ -21,9 +21,6 @@ import { CONTRACT, isHexColor } from "./contract.js";
 // Absent or unknown resolves here, so every app authored before menu types
 // existed renders and compiles byte-identically.
 const DEFAULT_MENU_TYPE = "sidebar";
-// Today's row of text links, so an app that never made the choice draws exactly
-// what it drew before it existed.
-const DEFAULT_TOP_BAR_MENU_STYLE = "links";
 
 function isPlainObject(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -36,8 +33,7 @@ function isPlainObject(value) {
  * yields the default sidebar rather than something a host has to guard against.
  *
  * @param {unknown} navigation — the raw `theme_config.navigation` value.
- * @returns {{ menuType: string, topBarMenuStyle: string }} the resolved
- *   navigation structure.
+ * @returns {{ menuType: string }} the resolved navigation structure.
  */
 export function normaliseNavigation(navigation) {
   const block = isPlainObject(navigation) ? navigation : {};
@@ -46,16 +42,11 @@ export function normaliseNavigation(navigation) {
     typeof raw === "string" && Object.hasOwn(CONTRACT.themeMenuTypes, raw)
       ? raw
       : DEFAULT_MENU_TYPE;
-  const rawStyle = block.topBarMenuStyle;
-  // Resolved to `links` for every shape but `top-bar`, so a host reading it can
-  // never act on a value the app's own chrome has no row to draw.
-  const topBarMenuStyle =
-    menuType === "top-bar" &&
-    typeof rawStyle === "string" &&
-    Object.hasOwn(CONTRACT.themeTopBarMenuStyles, rawStyle)
-      ? rawStyle
-      : DEFAULT_TOP_BAR_MENU_STYLE;
-  return { menuType, topBarMenuStyle };
+  // sc-7044: the SHAPE is the whole answer. A `top-bar` app used to also choose
+  // which row carried its menu, and the `links` option drew the site header's
+  // own row of text links — a second way to say the same thing. The tab row is
+  // the only shape now, so a stored `topBarMenuStyle` is read by nobody.
+  return { menuType };
 }
 
 /**
@@ -330,8 +321,8 @@ export function resolveTopBarTokens(theme) {
     // `underline` keeps the tab in the bar's surface and marks it with an
     // indicator. `attached` makes it a real folder tab: it takes the CONTENT's
     // surface and sits over the row's divider, so the tab and the page beneath
-    // read as one plane. Meaningless under the `links` style, which draws no
-    // tabs — a host reads it only where it has tabs to draw.
+    // 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,
@@ -360,8 +351,8 @@ export function resolveTopBarTokens(theme) {
     tabPaddingX: tabSpaceOr(topBar.tabPaddingX, DEFAULT_TAB_PADDING_X),
     tabPaddingY: tabSpaceOr(topBar.tabPaddingY, DEFAULT_TAB_PADDING_Y),
     // A tab's own surface, authored or nothing. Null means the tab paints none
-    // and the bar shows through it, which is what both styles did before the
-    // keys existed — so an app that never set them is unchanged.
+    // 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

package/package.json

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