@colixsystems/widget-sdk 0.183.0 → 0.185.0

package/README.md

@@ -74,7 +74,19 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.183.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.185.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.185.0 (contract 1.146.0)
+
+**`<Card>` reads a style array, so a card given `flex: 1` in one actually shares its row.** `style` was read only as a plain object. A widget writing ordinary React Native, `style={[{ flex: 1, minWidth: 0 }, align && { alignItems: align }]}`, lost every key in the array: each card sized to its content and a row of figures ran out of its grid cell into the widget beside it once the numbers arrived. `<Card>` now flattens `style` the way both hosts do (nested arrays are walked in order, falsy entries are skipped, a later entry wins) before it reads the layout keys and the `card*` fields, so an array and the equivalent object draw the same card on the web Player and in the native app. `<Button>` and `<ListRow>` read their `style` through the same flatten; they already handled arrays, so nothing changes for them.
+
+**`<Stat>` stays inside a narrow tile.** Its icon, figure and delta sat on one line that could not shrink, so in a tile a third of a desktop column wide the delta ("Busiest day: Sat") ran past the card into the next one. The line now wraps: whatever does not fit moves underneath. A tile with room is unchanged.
+
+An installed widget is not rebuilt or republished for this. The web Player hands every widget bundle the host's own SDK at runtime, so the fix reaches it with the Studio release. A native app installs the published SDK release when it is next built.
+
+### What's new in 0.184.0 (contract 1.145.0)
+
+**A page's top navigation bar can put its tabs on the left, in the centre or on the right.** The tab row always started at the left edge, which looks wrong under a centred or right-aligned brand. `resolveTopBarTokens` now returns **`tabAlignment`** (`"left"` | `"center"` | `"right"`), read from `theme_config.topBar.tabAlignment`; anything else, including unset, resolves to `"left"`, so an app that never chose is unchanged. It also returns **`tabRowWidth`** (`"full"` | `"content"`, default `"full"`): the column the tabs sit in. `content` gives the tabs the page content's width and inset, so they line up with it, while the bar's own surface still spans the full width. Both hosts place the tabs with flexible spacers either side rather than by centring the row, so a row with more tabs than fit still scrolls sideways from its first tab instead of cutting it off. Host-integration surface only — no author-facing hook, prop, primitive, or manifest field changed.
 
 ### What's new in 0.183.0 (contract 1.144.0)
 

package/dist/button-view.js

@@ -8,6 +8,7 @@ import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
 import { lucideGlyph } from "./icon.js";
 import { applyThemeComponentStyle } from "./theme-components.js";
 import { cornerRadiusOverlay, shadowStyle, gradientProps } from "./card-style.js";
+import { flattenStyle } from "./flatten-style.js";
 import {
   buttonSurfaceOverlay,
   buttonSurfaceTextOverlay,
@@ -123,8 +124,8 @@ export function makeButton(rn) {
     const owned = ownedButtonPaint(
       resolvedVariant,
       f,
-      StyleSheet.flatten(style),
-      StyleSheet.flatten(labelStyle),
+      flattenStyle(style),
+      flattenStyle(labelStyle),
     );
     const { layers, ink } = containerLayers(resolvedVariant, f, colors, owned);
 

package/dist/card-style.js

@@ -8,6 +8,7 @@
 import { CONTRACT, isHexColor, mixHex, normaliseComponentGradient } from "./contract.js";
 import { normaliseCornerRadius, cornerRadiusStyle } from "./corner-radius.js";
 import { normaliseSpacing, spacingStyle, isZeroSpacing } from "./spacing.js";
+import { flattenStyle } from "./flatten-style.js";
 
 export const SHADOW_PRESETS = CONTRACT.themeTokens.elevation;
 
@@ -90,17 +91,19 @@ export const CARD_LAYOUT_STYLE_FIELDS = Object.freeze([
  * `<Card style={{ width: "100%" }}>` from being silently dropped; a card
  * declaring none yields null, so it emits no extra style object.
  *
+ * `style` may be an RN style array, read as the hosts flatten it.
+ *
  * An `undefined` value is skipped rather than copied: react-native-web's
  * styleq ignores it while React Native's flattenStyle assigns it, so copying
  * one would clear the theme's value on native alone.
  */
 export function cardLayoutStyle(style) {
-  if (!style || typeof style !== "object" || Array.isArray(style)) return null;
+  const flat = flattenStyle(style);
   const out = {};
   let any = false;
   for (const key of CARD_LAYOUT_STYLE_FIELDS) {
-    if (style[key] === undefined) continue;
-    out[key] = style[key];
+    if (flat[key] === undefined) continue;
+    out[key] = flat[key];
     any = true;
   }
   return any ? out : null;
@@ -131,12 +134,7 @@ export function cardBackdrop(styles, gradient) {
     const [from, to] = gradient.colors;
     return isOpaqueHex(from) && isOpaqueHex(to) ? mixHex(from, to, 0.5) : null;
   }
-  let fill = null;
-  for (const style of [styles].flat(Infinity)) {
-    if (style && typeof style === "object" && style.backgroundColor !== undefined) {
-      fill = style.backgroundColor;
-    }
-  }
+  const fill = flattenStyle(styles).backgroundColor;
   return isOpaqueHex(fill) ? fill : null;
 }
 

package/dist/card-view.js

@@ -17,6 +17,7 @@ import {
   cardBackdrop,
 } from "./card-style.js";
 import { normaliseThemeComponents } from "./theme-components.js";
+import { flattenStyle } from "./flatten-style.js";
 
 // A wrapped scroller stays transparent and fits inside the gradient.
 const SCROLLER_IN_GRADIENT = { backgroundColor: "transparent", flexShrink: 1 };
@@ -80,8 +81,9 @@ export function makeCard(rn) {
   const { View, Gradient } = rn;
 
   /**
-   * @param {object} [props.style] — `card*` fields, `shadow`, `margin`
-   *   (a widget's per-instance style, theme tokens already folded in). On a
+   * @param {object|Array} [props.style] — `card*` fields, `shadow`, `margin`
+   *   (a widget's per-instance style, theme tokens already folded in), as an
+   *   object or an RN style array, flattened as the hosts flatten it. On a
    *   card with no `baseStyle` it also carries the box's LAYOUT
    *   (`CARD_LAYOUT_STYLE_FIELDS`), so `style={{ width: "100%" }}` sizes the
    *   card rather than vanishing. Under `as` + a gradient the layout rides the
@@ -124,14 +126,15 @@ export function makeCard(rn) {
     // A built-in brings its own base and receives the theme through `style`;
     // anything else starts from the theme, so it matches without plumbing.
     const standalone = baseStyle === undefined;
+    const own = flattenStyle(style);
     const fields = {
       ...(standalone ? themedFields(theme) : null),
-      ...style,
+      ...own,
       ...explicit,
     };
     const base = standalone ? themedBase(theme) : baseStyle;
     // Last, so an author's own declaration beats the theme's surface.
-    const layout = standalone ? cardLayoutStyle(style) : null;
+    const layout = standalone ? cardLayoutStyle(own) : null;
 
     const overlay = withoutMargin ? cardSurfaceStyle(fields) : cardOverlay(fields);
     const gradient = cardGradientProps(fields);

package/dist/contract.cjs

@@ -2478,7 +2478,7 @@ const PRIMITIVES = [
   {
     name: "Stat",
     description:
-      'Themed headline figure. `<Stat value={openCount} label="Open orders" delta="+3 this week" deltaTone="positive" icon="package" />`. THE way to show one headline number in a summary tile; put peer tiles side by side in a row. It only DISPLAYS a figure: compute a count, sum or average over a table with `useDatastoreFigure` and pass its `text`. An empty value (null, undefined, blank text, NaN) prints `emptyValue` (default "—") in the muted tier, never a fake 0. Props: `value` (string or number), `label`, `icon` (lucide name), `delta`, `deltaTone` ("neutral" | "positive" | "negative"), `emptyValue`, `color` and `fontSize` (12-96) for the figure, `style`, `testID`.',
+      'Themed headline figure. `<Stat value={openCount} label="Open orders" delta="+3 this week" deltaTone="positive" icon="package" />`. THE way to show one headline number in a summary tile; put peer tiles side by side in a row. It only DISPLAYS a figure: compute a count, sum or average over a table with `useDatastoreFigure` and pass its `text`. An empty value (null, undefined, blank text, NaN) prints `emptyValue` (default "—") in the muted tier, never a fake 0. Props: `value` (string or number), `label`, `icon` (lucide name), `delta`, `deltaTone` ("neutral" | "positive" | "negative"), `emptyValue`, `color` and `fontSize` (12-96) for the figure, `style`, `testID`. In a tile too narrow for the icon, figure and delta on one line, they wrap onto the next line rather than run past the tile.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -2499,7 +2499,7 @@ const PRIMITIVES = [
   {
     name: "Card",
     description:
-      'Themed card surface. `<Card>…</Card>` — THE way to draw a card, panel or tile: with no props it takes the app\'s card look (Theme Settings > Cards: background, border, corner radius, padding, shadow, gradient) so it matches every built-in card. Override one card with `background`, `borderColor`, `radius`, `padding` (a number or `{ top, right, bottom, left }`), `shadow` ("none" | "sm" | "md" | "lg") or `gradient` (`{ from, to, angle }`), or pass `style={props.style}` when your widget declares the `cardBackground` / `cardBorderColor` / `cardRadius` / `cardPadding` / `cardGradient` / `shadow` / `margin` style fields, so an author can restyle it. A card that brings no `baseStyle` also takes the box\'s LAYOUT from `style` — width, height, the flex properties, `alignSelf`, `gap`, position — so `style={{ width: \'100%\', maxWidth: 480, alignSelf: \'center\' }}` sizes the card and still keeps the app\'s card look; put anything else about the container on `containerStyle`. A gradient paints on both hosts. `as` renders the card as another container (e.g. `Pressable`, `ScrollView`) and every other prop lands on it. Never hand-roll a card from `View` + border + radius.',
+      'Themed card surface. `<Card>…</Card>` — THE way to draw a card, panel or tile: with no props it takes the app\'s card look (Theme Settings > Cards: background, border, corner radius, padding, shadow, gradient) so it matches every built-in card. Override one card with `background`, `borderColor`, `radius`, `padding` (a number or `{ top, right, bottom, left }`), `shadow` ("none" | "sm" | "md" | "lg") or `gradient` (`{ from, to, angle }`), or pass `style={props.style}` when your widget declares the `cardBackground` / `cardBorderColor` / `cardRadius` / `cardPadding` / `cardGradient` / `shadow` / `margin` style fields, so an author can restyle it. A card that brings no `baseStyle` also takes the box\'s LAYOUT from `style` — width, height, the flex properties, `alignSelf`, `gap`, position — so `style={{ width: \'100%\', maxWidth: 480, alignSelf: \'center\' }}` sizes the card and still keeps the app\'s card look; put anything else about the container on `containerStyle`. `style` may be an object or a React Native style array (`style={[{ flex: 1, minWidth: 0 }, align && { alignItems: align }]}`), read as the host flattens it: nested arrays and falsy entries are fine and a later entry wins. A gradient paints on both hosts. `as` renders the card as another container (e.g. `Pressable`, `ScrollView`) and every other prop lands on it. Never hand-roll a card from `View` + border + radius.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -4803,7 +4803,17 @@ const CONTRACT = deepFreeze({
   //    `send_invitation`; `false` stores the invite unsent. Invite rows gain
   //    `sent_at` and the `not_sent` status, and `useInvites().resend` is its
   //    first send. Omitting the flag emails at once, as before.
-  version: "1.144.0",
+  // 1.145.0: additive (sc-10123) — `resolveTopBarTokens` returns
+  //    `tabAlignment` ("left" | "center" | "right"), where a local top bar's
+  //    tabs sit across the row, and `tabRowWidth` ("full" | "content"), the
+  //    column they sit in. Unset resolves to "left" / "full", as before.
+  // 1.146.0: fix (sc-10179) — `<Card style>` reads an RN style ARRAY as the
+  //    host flattens it. It read only a plain object, so
+  //    `style={[{ flex: 1, minWidth: 0 }, …]}` lost every key and the cards
+  //    sized to their content. `<Button>` / `<ListRow>` read their `style`
+  //    through the same flatten; their behaviour is unchanged. `<Stat>`'s
+  //    icon, figure and delta wrap in a tile too narrow to hold them.
+  version: "1.146.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -2478,7 +2478,7 @@ const PRIMITIVES = [
   {
     name: "Stat",
     description:
-      'Themed headline figure. `<Stat value={openCount} label="Open orders" delta="+3 this week" deltaTone="positive" icon="package" />`. THE way to show one headline number in a summary tile; put peer tiles side by side in a row. It only DISPLAYS a figure: compute a count, sum or average over a table with `useDatastoreFigure` and pass its `text`. An empty value (null, undefined, blank text, NaN) prints `emptyValue` (default "—") in the muted tier, never a fake 0. Props: `value` (string or number), `label`, `icon` (lucide name), `delta`, `deltaTone` ("neutral" | "positive" | "negative"), `emptyValue`, `color` and `fontSize` (12-96) for the figure, `style`, `testID`.',
+      'Themed headline figure. `<Stat value={openCount} label="Open orders" delta="+3 this week" deltaTone="positive" icon="package" />`. THE way to show one headline number in a summary tile; put peer tiles side by side in a row. It only DISPLAYS a figure: compute a count, sum or average over a table with `useDatastoreFigure` and pass its `text`. An empty value (null, undefined, blank text, NaN) prints `emptyValue` (default "—") in the muted tier, never a fake 0. Props: `value` (string or number), `label`, `icon` (lucide name), `delta`, `deltaTone` ("neutral" | "positive" | "negative"), `emptyValue`, `color` and `fontSize` (12-96) for the figure, `style`, `testID`. In a tile too narrow for the icon, figure and delta on one line, they wrap onto the next line rather than run past the tile.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -2499,7 +2499,7 @@ const PRIMITIVES = [
   {
     name: "Card",
     description:
-      'Themed card surface. `<Card>…</Card>` — THE way to draw a card, panel or tile: with no props it takes the app\'s card look (Theme Settings > Cards: background, border, corner radius, padding, shadow, gradient) so it matches every built-in card. Override one card with `background`, `borderColor`, `radius`, `padding` (a number or `{ top, right, bottom, left }`), `shadow` ("none" | "sm" | "md" | "lg") or `gradient` (`{ from, to, angle }`), or pass `style={props.style}` when your widget declares the `cardBackground` / `cardBorderColor` / `cardRadius` / `cardPadding` / `cardGradient` / `shadow` / `margin` style fields, so an author can restyle it. A card that brings no `baseStyle` also takes the box\'s LAYOUT from `style` — width, height, the flex properties, `alignSelf`, `gap`, position — so `style={{ width: \'100%\', maxWidth: 480, alignSelf: \'center\' }}` sizes the card and still keeps the app\'s card look; put anything else about the container on `containerStyle`. A gradient paints on both hosts. `as` renders the card as another container (e.g. `Pressable`, `ScrollView`) and every other prop lands on it. Never hand-roll a card from `View` + border + radius.',
+      'Themed card surface. `<Card>…</Card>` — THE way to draw a card, panel or tile: with no props it takes the app\'s card look (Theme Settings > Cards: background, border, corner radius, padding, shadow, gradient) so it matches every built-in card. Override one card with `background`, `borderColor`, `radius`, `padding` (a number or `{ top, right, bottom, left }`), `shadow` ("none" | "sm" | "md" | "lg") or `gradient` (`{ from, to, angle }`), or pass `style={props.style}` when your widget declares the `cardBackground` / `cardBorderColor` / `cardRadius` / `cardPadding` / `cardGradient` / `shadow` / `margin` style fields, so an author can restyle it. A card that brings no `baseStyle` also takes the box\'s LAYOUT from `style` — width, height, the flex properties, `alignSelf`, `gap`, position — so `style={{ width: \'100%\', maxWidth: 480, alignSelf: \'center\' }}` sizes the card and still keeps the app\'s card look; put anything else about the container on `containerStyle`. `style` may be an object or a React Native style array (`style={[{ flex: 1, minWidth: 0 }, align && { alignItems: align }]}`), read as the host flattens it: nested arrays and falsy entries are fine and a later entry wins. A gradient paints on both hosts. `as` renders the card as another container (e.g. `Pressable`, `ScrollView`) and every other prop lands on it. Never hand-roll a card from `View` + border + radius.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -4799,7 +4799,17 @@ const CONTRACT = deepFreeze({
   //    `send_invitation`; `false` stores the invite unsent. Invite rows gain
   //    `sent_at` and the `not_sent` status, and `useInvites().resend` is its
   //    first send. Omitting the flag emails at once, as before.
-  version: "1.144.0",
+  // 1.145.0: additive (sc-10123) — `resolveTopBarTokens` returns
+  //    `tabAlignment` ("left" | "center" | "right"), where a local top bar's
+  //    tabs sit across the row, and `tabRowWidth` ("full" | "content"), the
+  //    column they sit in. Unset resolves to "left" / "full", as before.
+  // 1.146.0: fix (sc-10179) — `<Card style>` reads an RN style ARRAY as the
+  //    host flattens it. It read only a plain object, so
+  //    `style={[{ flex: 1, minWidth: 0 }, …]}` lost every key and the cards
+  //    sized to their content. `<Button>` / `<ListRow>` read their `style`
+  //    through the same flatten; their behaviour is unchanged. `<Stat>`'s
+  //    icon, figure and delta wrap in a tile too narrow to hold them.
+  version: "1.146.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/detail-parts-view.js

@@ -309,7 +309,8 @@ export function makeDetailParts(rn) {
       { style: [{ alignItems: "flex-start" }, style], testID },
       h(
         View,
-        { style: { flexDirection: "row", alignItems: "center", gap: spacing.xs } },
+        // Wraps in a narrow tile rather than running past its edge.
+        { style: { flexDirection: "row", flexWrap: "wrap", alignItems: "center", gap: spacing.xs } },
         glyph(icon, Math.max(12, Math.round(size * 0.75)), valueColor),
         h(
           Text,

package/dist/flatten-style.js

@@ -0,0 +1,23 @@
+// The ONE way the SDK reads keys out of a caller's `style`. Platform-free, so
+// the component views and the card resolvers share it on both hosts.
+
+/**
+ * A React Native style as one plain object, resolved exactly as both hosts'
+ * `StyleSheet.flatten` resolve it: nested arrays are walked in order, falsy
+ * and non-object entries are skipped, and a later entry's key wins — an
+ * explicit `undefined` included, as React Native assigns it.
+ *
+ * A component that applies only SOME of `style`'s keys must read them through
+ * this: `style={[{ flex: 1 }, cond && { alignItems }]}` is ordinary RN, and
+ * reading the array as if it were the object loses every key in it.
+ *
+ * @param {object|Array|null|undefined|false} style
+ * @returns {object} a new object; empty when the style declares nothing.
+ */
+export function flattenStyle(style) {
+  const out = {};
+  for (const entry of [style].flat(Infinity)) {
+    if (entry && typeof entry === "object") Object.assign(out, entry);
+  }
+  return out;
+}

package/dist/host.d.ts

@@ -291,6 +291,11 @@ export interface TopBarTokens {
    *  bar's surface behind an indicator; `attached` cuts the bar away under the
    *  current tab so the page shows through it. */
   tabStyle: "underline" | "attached";
+  /** Where the row's tabs sit across its width; `left` unless authored. */
+  tabAlignment: "left" | "center" | "right";
+  /** The column the tabs sit in: the whole bar, or the page content's. The
+   *  bar's surface spans the full width either way. */
+  tabRowWidth: "full" | "content";
   /** 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. */

package/dist/index.d.ts

@@ -2861,8 +2861,9 @@ export const Card: (props: {
    * sizes the card; anything else about the container goes on
    * `containerStyle`. Read for the `card*` fields alone when `baseStyle` is
    * given — the contract the built-in widgets pass their whole style bag on.
+   * An RN style array is read as the host flattens it.
    */
-  style?: Record<string, any>;
+  style?: Record<string, any> | ReadonlyArray<any>;
   /** The caller's own base style; a card given none starts from the theme. */
   baseStyle?: any;
   as?: any;

package/dist/list-view.js

@@ -18,6 +18,7 @@ import {
   LIST_SELECTED_BAR_WIDTH,
 } from "./list-tokens.js";
 import { textRoleStyle } from "./text-roles.js";
+import { flattenStyle } from "./flatten-style.js";
 
 // Outside a widget host (a test, a preview) the defaults still paint a row.
 function useListTheme() {
@@ -49,10 +50,10 @@ const HORIZONTAL_PADDING = [
 /**
  * Bind the shared list components to one platform's primitives.
  *
- * @param {{View: any, Text: any, Pressable: any, StyleSheet: any}} rn
+ * @param {{View: any, Text: any, Pressable: any}} rn
  */
 export function makeList(rn) {
-  const { View, Text, Pressable, StyleSheet } = rn;
+  const { View, Text, Pressable } = rn;
   const ListContext = React.createContext(null);
 
   function useRowTokens(props) {
@@ -71,7 +72,7 @@ export function makeList(rn) {
   }
 
   function setsOwnInset(style) {
-    const flat = StyleSheet.flatten(style) || {};
+    const flat = flattenStyle(style);
     return HORIZONTAL_PADDING.some((key) => flat[key] !== undefined);
   }
 

package/dist/list.native.js

@@ -1,7 +1,7 @@
 // `<List>`, `<ListRow>`, `<ListHeader>`, `<EmptyState>` (native). Binds
 // ./list-view.js to React Native's own primitives; only the import differs from ./list.js.
 
-import { View, Text, Pressable, StyleSheet } from "react-native";
+import { View, Text, Pressable } from "react-native";
 import { makeList } from "./list-view.js";
 
-export const { List, ListRow, ListHeader, EmptyState } = makeList({ View, Text, Pressable, StyleSheet });
+export const { List, ListRow, ListHeader, EmptyState } = makeList({ View, Text, Pressable });

package/dist/navigation.cjs

@@ -535,6 +535,9 @@ function resolveTopStripeLayout(theme) {
   };
 }
 
+const TAB_ALIGNMENTS = ["left", "center", "right"];
+const TAB_ROW_WIDTHS = ["full", "content"];
+
 function resolveTopBarTokens(theme) {
   const config = isPlainObject(theme) ? theme : {};
   const topBar = isPlainObject(config.topBar) ? config.topBar : {};
@@ -566,6 +569,18 @@ 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",
+    // sc-10123: where the row's tabs sit across its width. Both hosts place
+    // them with flexible spacers rather than centring the row, so a row that
+    // overflows still scrolls from its first tab instead of clipping it.
+    tabAlignment: TAB_ALIGNMENTS.includes(topBar.tabAlignment)
+      ? topBar.tabAlignment
+      : "left",
+    // sc-10123: the column the tabs sit in. `full` spans the bar; `content`
+    // shares the page content's width and inset, so the tabs line up with it.
+    // The bar's surface always spans.
+    tabRowWidth: TAB_ROW_WIDTHS.includes(topBar.tabRowWidth)
+      ? topBar.tabRowWidth
+      : "full",
     // 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

package/dist/navigation.js

@@ -526,6 +526,9 @@ export function resolveTopStripeLayout(theme) {
   };
 }
 
+const TAB_ALIGNMENTS = ["left", "center", "right"];
+const TAB_ROW_WIDTHS = ["full", "content"];
+
 export function resolveTopBarTokens(theme) {
   const config = isPlainObject(theme) ? theme : {};
   const topBar = isPlainObject(config.topBar) ? config.topBar : {};
@@ -557,6 +560,18 @@ 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",
+    // sc-10123: where the row's tabs sit across its width. Both hosts place
+    // them with flexible spacers rather than centring the row, so a row that
+    // overflows still scrolls from its first tab instead of clipping it.
+    tabAlignment: TAB_ALIGNMENTS.includes(topBar.tabAlignment)
+      ? topBar.tabAlignment
+      : "left",
+    // sc-10123: the column the tabs sit in. `full` spans the bar; `content`
+    // shares the page content's width and inset, so the tabs line up with it.
+    // The bar's surface always spans.
+    tabRowWidth: TAB_ROW_WIDTHS.includes(topBar.tabRowWidth)
+      ? topBar.tabRowWidth
+      : "full",
     // 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

package/package.json

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