@colixsystems/widget-sdk 0.156.0 → 0.158.0

package/README.md

@@ -73,7 +73,15 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.156.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.157.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.157.0 (contract 1.122.0 — unchanged)
+
+**The app header's row has its own text colour (sc-8518).** `resolveTopStripeLayout(theme)` now returns **`tintColor`** and **`titleColor`** beside the resolved `backgroundColor`, each reading `theme.sidebar.stripe.textColor` and falling back through `resolveTopBarTokens` when it is unset — exactly as the surface already falls back. One authored colour drives both, as the bar's own does; unset they part, the icons taking slate and the app name the brand.
+
+Before this the row's ink lived on `topBar.textColor`, which also paints the tab row every top navigation bar draws — so recolouring the app header moved every one of those tab rows with it. What the two colours reach is what `slots` describes: the phone header, the desktop strip, the full-width bar, and the export's screen header. The drawer's own account rows, the sign-in control, the notification bell and the site-mode sheet are not that row and keep reading the bar.
+
+Additive — nothing in the existing `./host` surface changed, an unset value resolves to what it resolved to before, and the contract is untouched.
 
 ### What's new in 0.156.0 (contract 1.122.0)
 
@@ -111,7 +119,7 @@ Behaviour: a bare date given to a `mode="datetime"` picker now shows local midni
 
 **The app header's row is arrangeable, and `./host` publishes the resolver both hosts read (sc-8023).** The row runs across the top of the content outside the side panel, and is drawn three times — as the phone header where the panel is a drawer, as the desktop strip, and as the full-width bar when one is switched on. Each surface hard-coded its own copy of it, so an author could colour the row but never move anything in it.
 
-- **`resolveTopStripeLayout(theme)`** reads `theme.sidebar.stripe` and returns the arrangement fully resolved: `slots` (already filtered and sequenced, so no host re-derives it), `order`, the box (`height`, `paddingX`, `contentOffsetY`), the resolved `backgroundColor`, and `menuSide` — which edge the drawer must arrive from, since the brand grows and a burger ordered after it sits at the trailing edge. The web Player picks the drawer's side with it; the export makes it `drawerPosition`.
+- **`resolveTopStripeLayout(theme)`** reads `theme.sidebar.stripe` and returns the arrangement fully resolved: `slots` (already filtered and sequenced, so no host re-derives it), `order`, the box (`height`, `paddingX`, `contentOffsetY`, and `barHeight` — the height once the nudge is held, since pushing the contents down grows the bar rather than letting them fall out of it), the resolved `backgroundColor` (joined in 0.155.0 by `tintColor` and `titleColor`), and `menuSide` — which edge the drawer must arrive from, since the brand grows and a burger ordered after it sits at the trailing edge. The web Player picks the drawer's side with it; the export makes it `drawerPosition`.
 - **`TOP_STRIPE_SLOTS`** is the vocabulary (`back`, `menu`, `brand`, `notifications`) and **`TOP_STRIPE_ALWAYS_SHOWN_SLOTS`** the slots that move but never hide. The burger is the only member: it is drawn only where the panel is a drawer, and there it is the sole route into the menu, so hiding it would strand the visitor. It keeps its place in `order` regardless.
 - **`topStripeShowKey(slot)`** derives the `theme_config` key that shows or hides one slot, in one place, so a control, the write path and the resolver cannot spell it differently.
 - **The bounds travel with the resolver** — `MIN`/`MAX_TOP_STRIPE_HEIGHT_PX`, `MIN`/`MAX_TOP_STRIPE_PADDING_X_PX`, `MAX_TOP_STRIPE_OFFSET_Y_PX` — so a control offers exactly the range the resolver clamps to. `DEFAULT_TOP_STRIPE_HEIGHT_PX` / `DEFAULT_TOP_STRIPE_PADDING_X_PX` are what the DESKTOP row measures with nothing stored, published so a control can show the number an author is departing from; the resolver still answers `null`, because each surface keeps its own box until one is named.

package/dist/host.d.ts

@@ -332,8 +332,12 @@ export interface TopStripeLayout {
    *  bar's 64px, the phone header's content-sized row. */
   height: number | null;
   paddingX: number | null;
-  /** How far the row is pushed down, 0-60px. */
+  /** How far the row's contents are pushed down, 0-60px. */
   contentOffsetY: number;
+  /** The bar's total height once the nudge is held — its box plus
+   *  `contentOffsetY`, so contents never fall out of the bottom. Null only
+   *  while both are unset, where each surface keeps its own box. */
+  barHeight: number | null;
   /** Every slot in the author's sequence, hidden ones included. */
   order: TopStripeSlot[];
   /** What the bar actually SHOWS, already filtered and sequenced. A surface

package/dist/navigation.cjs

@@ -403,15 +403,18 @@ function topStripeOrder(value) {
  * bar left holding nothing is not drawn at all.
  *
  * @param {unknown} theme — the whole `theme_config`.
- * @returns {{ backgroundColor: string, height: number|null,
- *   paddingX: number|null, contentOffsetY: number, order: string[],
- *   slots: string[], menuSide: "start"|"end" }}
+ * @returns {{ backgroundColor: string, tintColor: string, titleColor: string,
+ *   height: number|null, paddingX: number|null, contentOffsetY: number,
+ *   barHeight: number|null,
+ *   order: string[], slots: string[], menuSide: "start"|"end" }}
  */
 function resolveTopStripeLayout(theme) {
   const config = isPlainObject(theme) ? theme : {};
   const sidebar = isPlainObject(config.sidebar) ? config.sidebar : {};
   const stripe = isPlainObject(sidebar.stripe) ? sidebar.stripe : {};
   const order = topStripeOrder(stripe.order);
+  // Resolved once: the row's colours all fall back through the app-header bar.
+  const barTokens = resolveTopBarTokens(theme);
   const shown = (slot) => {
     if (TOP_STRIPE_ALWAYS_SHOWN_SLOTS.includes(slot)) return true;
     const value = stripe[topStripeShowKey(slot)];
@@ -420,39 +423,69 @@ function resolveTopStripeLayout(theme) {
       : TOP_STRIPE_SLOT_SHOWN_BY_DEFAULT[slot];
   };
   const slots = order.filter(shown);
+  // Unset defers to each surface's own box — the desktop bar's fixed 64px, the
+  // phone header's content-sized row.
+  const height = topStripeClampedOr(
+    stripe.height,
+    MIN_TOP_STRIPE_HEIGHT_PX,
+    MAX_TOP_STRIPE_HEIGHT_PX,
+    null,
+  );
+  const contentOffsetY = topStripeClampedOr(
+    stripe.contentOffsetY,
+    0,
+    MAX_TOP_STRIPE_OFFSET_Y_PX,
+    0,
+  );
   return {
     // There is no alignment to resolve: the brand slot GROWS, so the row has no
     // free space for `justify-content` to distribute and every value looked
     // identical. The row spreads because the brand takes the slack.
-    // Unset defers to each surface's own box — the desktop bar's fixed 64px,
-    // the phone header's content-sized row.
-    height: topStripeClampedOr(
-      stripe.height,
-      MIN_TOP_STRIPE_HEIGHT_PX,
-      MAX_TOP_STRIPE_HEIGHT_PX,
-      null,
-    ),
+    height,
     paddingX: topStripeClampedOr(
       stripe.paddingX,
       MIN_TOP_STRIPE_PADDING_X_PX,
       MAX_TOP_STRIPE_PADDING_X_PX,
       null,
     ),
-    contentOffsetY: topStripeClampedOr(
-      stripe.contentOffsetY,
-      0,
-      MAX_TOP_STRIPE_OFFSET_Y_PX,
-      0,
-    ),
+    contentOffsetY,
+    // sc-8552: the bar GROWS by the nudge rather than letting its contents fall
+    // out of the bottom — the box the author sized, plus what they pushed into
+    // it. For a surface that must state a height (the desktop bar, the native
+    // header); the phone row is content-sized and grows on its padding alone.
+    barHeight:
+      height === null && contentOffsetY === 0
+        ? null
+        : (height ?? DEFAULT_TOP_STRIPE_HEIGHT_PX) + contentOffsetY,
     // sc-8023: the stripe's OWN surface, inheriting the app-header colour when
     // unset — so an untouched app is unmoved, and an author who dresses a
     // page's top navigation bar no longer repaints the stripe above the panel by
     // accident. Fully resolved here, not raw-or-null, for the reason sc-8033
     // resolved the footer's: a default that lives in each host drifts.
-    backgroundColor: hexOr(
-      stripe.backgroundColor,
-      resolveTopBarTokens(theme).backgroundColor,
-    ),
+    backgroundColor: hexOr(stripe.backgroundColor, barTokens.backgroundColor),
+    // sc-8518: the row's OWN text, the half sc-8023 left on the bar. An author
+    // recolouring the app header used to move every top navigation bar's tab
+    // labels with it, because both read `topBar.textColor` — and had to open a
+    // panel named after the other part to do it.
+    //
+    // One authored colour drives BOTH slots, exactly as the bar's own does:
+    // unset they part (icons take slate, the app name takes the brand), and
+    // naming one is a decision about the whole row. Unset inherits the bar,
+    // so an app that never opens this field is unmoved.
+    //
+    // The row is what `slots` above describes — the desktop bar, the phone
+    // header, and native's screen header. The drawer's own account rows, the
+    // sign-in control and the site-mode sheet are NOT this row and keep
+    // reading the bar; so does the SITE header, which is shown instead of this
+    // row rather than beside it.
+    //
+    // The notification bell is the one member of `slots` this does not reach.
+    // It keeps its own resting colour on both hosts — web reads the authored
+    // `topBar.textColor` and the export tints it not at all — and moving it
+    // here would widen that difference rather than close it. Whoever closes it
+    // should move both hosts at once.
+    tintColor: hexOr(stripe.textColor, barTokens.tintColor),
+    titleColor: hexOr(stripe.textColor, barTokens.titleColor),
     order,
     slots,
     // sc-8023: which edge the panel the burger opens should come in from. The

package/dist/navigation.js

@@ -394,15 +394,18 @@ function topStripeOrder(value) {
  * bar left holding nothing is not drawn at all.
  *
  * @param {unknown} theme — the whole `theme_config`.
- * @returns {{ backgroundColor: string, height: number|null,
- *   paddingX: number|null, contentOffsetY: number, order: string[],
- *   slots: string[], menuSide: "start"|"end" }}
+ * @returns {{ backgroundColor: string, tintColor: string, titleColor: string,
+ *   height: number|null, paddingX: number|null, contentOffsetY: number,
+ *   barHeight: number|null,
+ *   order: string[], slots: string[], menuSide: "start"|"end" }}
  */
 export function resolveTopStripeLayout(theme) {
   const config = isPlainObject(theme) ? theme : {};
   const sidebar = isPlainObject(config.sidebar) ? config.sidebar : {};
   const stripe = isPlainObject(sidebar.stripe) ? sidebar.stripe : {};
   const order = topStripeOrder(stripe.order);
+  // Resolved once: the row's colours all fall back through the app-header bar.
+  const barTokens = resolveTopBarTokens(theme);
   const shown = (slot) => {
     if (TOP_STRIPE_ALWAYS_SHOWN_SLOTS.includes(slot)) return true;
     const value = stripe[topStripeShowKey(slot)];
@@ -411,39 +414,69 @@ export function resolveTopStripeLayout(theme) {
       : TOP_STRIPE_SLOT_SHOWN_BY_DEFAULT[slot];
   };
   const slots = order.filter(shown);
+  // Unset defers to each surface's own box — the desktop bar's fixed 64px, the
+  // phone header's content-sized row.
+  const height = topStripeClampedOr(
+    stripe.height,
+    MIN_TOP_STRIPE_HEIGHT_PX,
+    MAX_TOP_STRIPE_HEIGHT_PX,
+    null,
+  );
+  const contentOffsetY = topStripeClampedOr(
+    stripe.contentOffsetY,
+    0,
+    MAX_TOP_STRIPE_OFFSET_Y_PX,
+    0,
+  );
   return {
     // There is no alignment to resolve: the brand slot GROWS, so the row has no
     // free space for `justify-content` to distribute and every value looked
     // identical. The row spreads because the brand takes the slack.
-    // Unset defers to each surface's own box — the desktop bar's fixed 64px,
-    // the phone header's content-sized row.
-    height: topStripeClampedOr(
-      stripe.height,
-      MIN_TOP_STRIPE_HEIGHT_PX,
-      MAX_TOP_STRIPE_HEIGHT_PX,
-      null,
-    ),
+    height,
     paddingX: topStripeClampedOr(
       stripe.paddingX,
       MIN_TOP_STRIPE_PADDING_X_PX,
       MAX_TOP_STRIPE_PADDING_X_PX,
       null,
     ),
-    contentOffsetY: topStripeClampedOr(
-      stripe.contentOffsetY,
-      0,
-      MAX_TOP_STRIPE_OFFSET_Y_PX,
-      0,
-    ),
+    contentOffsetY,
+    // sc-8552: the bar GROWS by the nudge rather than letting its contents fall
+    // out of the bottom — the box the author sized, plus what they pushed into
+    // it. For a surface that must state a height (the desktop bar, the native
+    // header); the phone row is content-sized and grows on its padding alone.
+    barHeight:
+      height === null && contentOffsetY === 0
+        ? null
+        : (height ?? DEFAULT_TOP_STRIPE_HEIGHT_PX) + contentOffsetY,
     // sc-8023: the stripe's OWN surface, inheriting the app-header colour when
     // unset — so an untouched app is unmoved, and an author who dresses a
     // page's top navigation bar no longer repaints the stripe above the panel by
     // accident. Fully resolved here, not raw-or-null, for the reason sc-8033
     // resolved the footer's: a default that lives in each host drifts.
-    backgroundColor: hexOr(
-      stripe.backgroundColor,
-      resolveTopBarTokens(theme).backgroundColor,
-    ),
+    backgroundColor: hexOr(stripe.backgroundColor, barTokens.backgroundColor),
+    // sc-8518: the row's OWN text, the half sc-8023 left on the bar. An author
+    // recolouring the app header used to move every top navigation bar's tab
+    // labels with it, because both read `topBar.textColor` — and had to open a
+    // panel named after the other part to do it.
+    //
+    // One authored colour drives BOTH slots, exactly as the bar's own does:
+    // unset they part (icons take slate, the app name takes the brand), and
+    // naming one is a decision about the whole row. Unset inherits the bar,
+    // so an app that never opens this field is unmoved.
+    //
+    // The row is what `slots` above describes — the desktop bar, the phone
+    // header, and native's screen header. The drawer's own account rows, the
+    // sign-in control and the site-mode sheet are NOT this row and keep
+    // reading the bar; so does the SITE header, which is shown instead of this
+    // row rather than beside it.
+    //
+    // The notification bell is the one member of `slots` this does not reach.
+    // It keeps its own resting colour on both hosts — web reads the authored
+    // `topBar.textColor` and the export tints it not at all — and moving it
+    // here would widen that difference rather than close it. Whoever closes it
+    // should move both hosts at once.
+    tintColor: hexOr(stripe.textColor, barTokens.tintColor),
+    titleColor: hexOr(stripe.textColor, barTokens.titleColor),
     order,
     slots,
     // sc-8023: which edge the panel the burger opens should come in from. The

package/package.json

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