@colixsystems/widget-sdk 0.109.0 → 0.111.0

package/README.md

@@ -69,7 +69,32 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.108.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.111.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.111.0 (contract 1.85.0)
+
+**Each side can be spaced on its own — the `spacing` property type (sc-6447).** Padding and margin were single numbers, so every inset applied to all four sides at once: a hero with generous top padding and none at the bottom, or a card held off only its left neighbour, had no expression. `cornerRadius` already offered each corner (0.104.0); padding and margin were the last four-valued members of the box model that did not.
+
+Declare `{ type: "spacing", label: "Padding", validation: { min: 0, max: 64 } }` in your `propertySchema` or `styleSchema`. The Studio renders a slider with a typeable number that sets all four sides, plus a disclosure for setting each one. The authored value is `number | { top, right, bottom, left }` — the scalar form is unchanged, so every value stored before is still valid.
+
+```js
+import { normaliseSpacing, spacingStyle } from "@colixsystems/widget-sdk";
+
+const padding = normaliseSpacing(props.style?.padding, 0, 64);
+return <View style={[styles.card, spacingStyle(padding, "padding")]} />;
+```
+
+`normaliseSpacing(value, fallback, max)` returns all four sides resolved and clamped; `spacingStyle(spacing, property, format)` emits the `padding`/`margin` shorthand when the sides agree and the four long-hand props when they differ (pass `` n => `${n}px` `` for the DOM). `mapSpacing` pushes each side through your own scaling, `isUniformSpacing` and `isZeroSpacing` round out the set. `CONTRACT.version` → `1.85.0`. Additive: every value accepted before is accepted now.
+
+### What's new in 0.110.0 (contract 1.84.0)
+
+**`resolveSidebarTokens` and `resolveTopBarTokens` — the rail's and the app bar's tokens, resolved once for both hosts (sc-6289).** The footer strip got a shared resolver in 1.71.0; the two chrome parts beside it did not, so their defaults lived inline in the web Player and again in the compiler — and had drifted. An unset `sidebar.backgroundColor` painted the app background in the Expo export where the Player painted it white, so a dark app shipped a dark drawer beside a white rail; an unset `topBar.textColor` painted the app name slate in the export where the Player has always used the brand colour.
+
+Both resolvers now own their defaults, which are what the web Player renders, so the export follows the appearance the author approved in the Studio rather than the other way round. Unlike `resolveFooterTokens`, the colours are never `null` — a default that lives in the resolver cannot drift, and one that lived in each host already had. `borderColor` stays nullable: the colour is the divider's switch.
+
+The top bar resolves **two** text colours. An unthemed bar paints its icons slate and its app name in the brand colour, and React Navigation's single `headerTintColor` cannot say both — so `tintColor` and `titleColor` are separate, and an authored `topBar.textColor` drives both. `show` is deliberately not among them: it depends on the menu type rather than the theme, and REQ-THEME-14 makes it a no-op on native.
+
+Host-integration surface only — nothing a widget imports changed. `CONTRACT.version` → `1.84.0`.
 
 ### What's new in 0.108.0 (contract 1.82.0)
 

package/dist/contract.cjs

@@ -3362,7 +3362,31 @@ const CONTRACT = deepFreeze({
   //    additionally requires an `inheritAcl` RELATION column, which is what
   //    makes the stream a strict subset of what `list()` already returns.
   //    Backed by datastore-client 0.15.0. Omitting `scope` is unchanged.
-  version: "1.83.0",
+  // 1.84.0: additive (sc-6289) -- `resolveSidebarTokens` and
+  //    `resolveTopBarTokens` (host exports), the rail's and the app bar's
+  //    tokens beside the footer's. Their defaults used to be written separately
+  //    in each host and had drifted: an unset rail took the app background in
+  //    the export where the Player painted it white, and an unset header
+  //    painted the app name slate where the Player used the brand colour. The
+  //    resolvers own the defaults, so a host cannot keep its own. The top bar
+  //    resolves `tintColor` and `titleColor` separately because the web bar has
+  //    always painted its icons slate and its name in the brand colour, which
+  //    one `headerTintColor` cannot express; an authored `topBar.textColor`
+  //    drives both. `show` is deliberately absent -- it depends on the menu
+  //    type, not the theme, and is a no-op on native.
+  //
+  // 1.85.0: additive (sc-6447) — the `spacing` property type: a padding or
+  //    margin value is `number | { top, right, bottom, left }`, resolved by
+  //    `normaliseSpacing` and emitted by `spacingStyle(resolved, "padding" |
+  //    "margin")`. Padding and margin were the last four-valued members of the
+  //    box model an author could only set on all sides at once, while
+  //    `cornerRadius` (1.79.0) already offered each corner — so the same
+  //    master-plus-disclosure control now backs all three. The scalar form is
+  //    unchanged and still emits the shorthand, so an existing style renders
+  //    byte-identically. `mapSpacing` pushes each side through the responsive
+  //    and theme scaling the scalar already got; `isZeroSpacing` lets each box
+  //    property keep its own zero policy.
+  version: "1.85.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -3362,7 +3362,31 @@ const CONTRACT = deepFreeze({
   //    additionally requires an `inheritAcl` RELATION column, which is what
   //    makes the stream a strict subset of what `list()` already returns.
   //    Backed by datastore-client 0.15.0. Omitting `scope` is unchanged.
-  version: "1.83.0",
+  // 1.84.0: additive (sc-6289) -- `resolveSidebarTokens` and
+  //    `resolveTopBarTokens` (host exports), the rail's and the app bar's
+  //    tokens beside the footer's. Their defaults used to be written separately
+  //    in each host and had drifted: an unset rail took the app background in
+  //    the export where the Player painted it white, and an unset header
+  //    painted the app name slate where the Player used the brand colour. The
+  //    resolvers own the defaults, so a host cannot keep its own. The top bar
+  //    resolves `tintColor` and `titleColor` separately because the web bar has
+  //    always painted its icons slate and its name in the brand colour, which
+  //    one `headerTintColor` cannot express; an authored `topBar.textColor`
+  //    drives both. `show` is deliberately absent -- it depends on the menu
+  //    type, not the theme, and is a no-op on native.
+  //
+  // 1.85.0: additive (sc-6447) — the `spacing` property type: a padding or
+  //    margin value is `number | { top, right, bottom, left }`, resolved by
+  //    `normaliseSpacing` and emitted by `spacingStyle(resolved, "padding" |
+  //    "margin")`. Padding and margin were the last four-valued members of the
+  //    box model an author could only set on all sides at once, while
+  //    `cornerRadius` (1.79.0) already offered each corner — so the same
+  //    master-plus-disclosure control now backs all three. The scalar form is
+  //    unchanged and still emits the shorthand, so an existing style renders
+  //    byte-identically. `mapSpacing` pushes each side through the responsive
+  //    and theme scaling the scalar already got; `isZeroSpacing` lets each box
+  //    property keep its own zero policy.
+  version: "1.85.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/host.d.ts

@@ -194,6 +194,43 @@ export interface FooterTokens {
  */
 export function resolveFooterTokens(theme: unknown): FooterTokens;
 
+/** The sidebar rail's resolved tokens. Unlike the footer's, the colours are
+ *  never `null`: the default lives here so the two hosts cannot each keep a
+ *  different one. `borderColor` is still nullable — no colour, no divider. */
+export interface SidebarTokens {
+  backgroundColor: string;
+  textColor: string;
+  activeColor: string;
+  activeStyle: "filled" | "accent";
+  borderColor: string | null;
+  borderWidth: number | null;
+}
+
+/**
+ * Resolves the sidebar rail's tokens from a whole `theme_config`. Every default
+ * is what the web Player renders, so the export follows the Player rather than
+ * the other way round.
+ */
+export function resolveSidebarTokens(theme: unknown): SidebarTokens;
+
+/** The top app bar's resolved tokens. `tintColor` and `titleColor` are separate
+ *  because an unthemed bar paints its icons slate and its app name in the brand
+ *  colour; an authored `topBar.textColor` drives both. */
+export interface TopBarTokens {
+  backgroundColor: string;
+  tintColor: string;
+  titleColor: string;
+  borderColor: string | null;
+  borderWidth: number | null;
+}
+
+/**
+ * Resolves the top app bar's tokens from a whole `theme_config`. `show` is not
+ * among them: it depends on the menu type, not the theme, and is a no-op on
+ * native.
+ */
+export function resolveTopBarTokens(theme: unknown): TopBarTokens;
+
 /** A value a widget may persist: a scalar, or a flat array of them. */
 export type WidgetRouteScalar = string | number | boolean;
 export type WidgetRouteValue = WidgetRouteScalar | WidgetRouteScalar[];

package/dist/host.js

@@ -50,11 +50,16 @@ export {
 // the sidebar's so an untouched workspace keeps the appearance it has. It
 // exists because the strip IS the menu under `bottom-tabs`, where the sidebar
 // panel is hidden and those tokens can no longer be set at all.
+// 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,
 } from "./navigation.js";
 
 // sc-5717: the codec behind `useWidgetRoute()` — how a widget's own internal

package/dist/index.js

@@ -13,6 +13,14 @@ export {
   cornerRadiusStyle,
   hasCornerRadius,
 } from "./corner-radius.js";
+export {
+  SPACING_KEYS,
+  normaliseSpacing,
+  isUniformSpacing,
+  isZeroSpacing,
+  mapSpacing,
+  spacingStyle,
+} from "./spacing.js";
 export {
   WidgetContextProvider,
   DatastoreError,

package/dist/index.native.js

@@ -13,6 +13,14 @@ export {
   cornerRadiusStyle,
   hasCornerRadius,
 } from "./corner-radius.js";
+export {
+  SPACING_KEYS,
+  normaliseSpacing,
+  isUniformSpacing,
+  isZeroSpacing,
+  mapSpacing,
+  spacingStyle,
+} from "./spacing.js";
 export {
   WidgetContextProvider,
   DatastoreError,

package/dist/navigation.cjs

@@ -25,7 +25,7 @@
 // the SAME literal, so what a planner may persist and what a host draws cannot
 // diverge.
 
-const { CONTRACT } = require("./contract.cjs");
+const { CONTRACT, isHexColor } = require("./contract.cjs");
 
 // Absent or unknown resolves here, so every app authored before menu types
 // existed renders and compiles byte-identically.
@@ -114,6 +114,98 @@ function resolveFooterTokens(theme) {
   };
 }
 
+// REQ-THEME-14 — the rail's and the app bar's tokens, resolved once for both
+// hosts.
+//
+// These return FULLY resolved values where `resolveFooterTokens` above returns
+// raw-or-null, and the difference is deliberate. The footer's two hosts happen
+// to agree on their separately-written defaults; the rail's and the bar's did
+// not. An unset `sidebar.backgroundColor` painted #ffffff on web and the app
+// background in the export, and an unset `topBar.textColor` painted the brand
+// primary on web and slate-700 in the export. A default that lives in the
+// resolver cannot drift; one that lives in each host already had. The footer
+// wants this same shape next — the same fix, not yet applied.
+//
+// Every default is what the WEB Player renders today, so the Player does not
+// move and the export converges onto it. That is the direction the footer was
+// converged in too (compiler.service's footerBg defaults to the web's #ffffff).
+
+const DEFAULT_PRIMARY_COLOR = "#3b82f6";
+// The web rail's and app bar's `bg-white`.
+const DEFAULT_CHROME_SURFACE = "#ffffff";
+// The web nav item's `text-slate-600`.
+const DEFAULT_CHROME_TEXT = "#475569";
+// The web mobile header's icon colour, `text-slate-700`.
+const DEFAULT_TOP_BAR_TINT = "#334155";
+
+// The contract's own guard, which already admits the 8-digit form a look uses
+// to float a translucent rail (#RRGGBBAA).
+function hexOrNull(value) {
+  return isHexColor(value) ? value : null;
+}
+
+function hexOr(value, fallback) {
+  return hexOrNull(value) || fallback;
+}
+
+function brandPrimary(config) {
+  return hexOr(config.primaryColor, DEFAULT_PRIMARY_COLOR);
+}
+
+/**
+ * The sidebar rail's surface, labels, active item and opt-in divider.
+ *
+ * @param {unknown} theme — the whole `theme_config`; `primaryColor` is read
+ *   because an unset active colour resolves to the brand.
+ * @returns {{ backgroundColor: string, textColor: string, activeColor: string,
+ *   activeStyle: string, borderColor: string|null, borderWidth: number|null }}
+ */
+function resolveSidebarTokens(theme) {
+  const config = isPlainObject(theme) ? theme : {};
+  const sidebar = isPlainObject(config.sidebar) ? config.sidebar : {};
+  const borderColor = hexOrNull(sidebar.borderColor);
+  return {
+    backgroundColor: hexOr(sidebar.backgroundColor, DEFAULT_CHROME_SURFACE),
+    textColor: hexOr(sidebar.textColor, DEFAULT_CHROME_TEXT),
+    activeColor: hexOr(sidebar.activeColor, brandPrimary(config)),
+    activeStyle: sidebar.activeStyle === "accent" ? "accent" : "filled",
+    // REQ-THEME-LOOK: the colour is the switch — no colour, no line.
+    borderColor,
+    borderWidth: borderColor ? borderWidthOr(sidebar.borderWidth) : null,
+  };
+}
+
+/**
+ * The top app bar's surface, its two text colours and its opt-in divider.
+ *
+ * `tintColor` and `titleColor` are SEPARATE because the web bar has always
+ * painted them differently when the author names nothing: the hamburger and
+ * icons take slate, the app name takes the brand. React Navigation's single
+ * `headerTintColor` could not express that, which is why the export used to
+ * paint the name slate. One token, two resolved fields, both hosts agree.
+ *
+ * `show` is deliberately absent: it depends on the menu TYPE, not the theme,
+ * and REQ-THEME-14 makes it a no-op on native — so it is not a shared token.
+ *
+ * @param {unknown} theme — the whole `theme_config`.
+ * @returns {{ backgroundColor: string, tintColor: string, titleColor: string,
+ *   borderColor: string|null, borderWidth: number|null }}
+ */
+function resolveTopBarTokens(theme) {
+  const config = isPlainObject(theme) ? theme : {};
+  const topBar = isPlainObject(config.topBar) ? config.topBar : {};
+  const borderColor = hexOrNull(topBar.borderColor);
+  // An explicit colour drives BOTH slots; only the unset case splits.
+  const authored = hexOrNull(topBar.textColor);
+  return {
+    backgroundColor: hexOr(topBar.backgroundColor, DEFAULT_CHROME_SURFACE),
+    tintColor: authored || DEFAULT_TOP_BAR_TINT,
+    titleColor: authored || brandPrimary(config),
+    borderColor,
+    borderWidth: borderColor ? borderWidthOr(topBar.borderWidth) : null,
+  };
+}
+
 function borderWidthOr(...values) {
   for (const value of values) {
     if (typeof value === "number" && Number.isFinite(value)) return value;
@@ -121,4 +213,4 @@ function borderWidthOr(...values) {
   return 1;
 }
 
-module.exports = { normaliseNavigation, menuItemCap, quickBarCap, resolveFooterTokens };
+module.exports = { normaliseNavigation, menuItemCap, quickBarCap, resolveFooterTokens, resolveSidebarTokens, resolveTopBarTokens };

package/dist/navigation.js

@@ -16,7 +16,7 @@
 // the SAME literal, so what a planner may persist and what a host draws cannot
 // diverge.
 
-import { CONTRACT } from "./contract.js";
+import { CONTRACT, isHexColor } from "./contract.js";
 
 // Absent or unknown resolves here, so every app authored before menu types
 // existed renders and compiles byte-identically.
@@ -105,6 +105,98 @@ export function resolveFooterTokens(theme) {
   };
 }
 
+// REQ-THEME-14 — the rail's and the app bar's tokens, resolved once for both
+// hosts.
+//
+// These return FULLY resolved values where `resolveFooterTokens` above returns
+// raw-or-null, and the difference is deliberate. The footer's two hosts happen
+// to agree on their separately-written defaults; the rail's and the bar's did
+// not. An unset `sidebar.backgroundColor` painted #ffffff on web and the app
+// background in the export, and an unset `topBar.textColor` painted the brand
+// primary on web and slate-700 in the export. A default that lives in the
+// resolver cannot drift; one that lives in each host already had. The footer
+// wants this same shape next — the same fix, not yet applied.
+//
+// Every default is what the WEB Player renders today, so the Player does not
+// move and the export converges onto it. That is the direction the footer was
+// converged in too (compiler.service's footerBg defaults to the web's #ffffff).
+
+const DEFAULT_PRIMARY_COLOR = "#3b82f6";
+// The web rail's and app bar's `bg-white`.
+const DEFAULT_CHROME_SURFACE = "#ffffff";
+// The web nav item's `text-slate-600`.
+const DEFAULT_CHROME_TEXT = "#475569";
+// The web mobile header's icon colour, `text-slate-700`.
+const DEFAULT_TOP_BAR_TINT = "#334155";
+
+// The contract's own guard, which already admits the 8-digit form a look uses
+// to float a translucent rail (#RRGGBBAA).
+function hexOrNull(value) {
+  return isHexColor(value) ? value : null;
+}
+
+function hexOr(value, fallback) {
+  return hexOrNull(value) || fallback;
+}
+
+function brandPrimary(config) {
+  return hexOr(config.primaryColor, DEFAULT_PRIMARY_COLOR);
+}
+
+/**
+ * The sidebar rail's surface, labels, active item and opt-in divider.
+ *
+ * @param {unknown} theme — the whole `theme_config`; `primaryColor` is read
+ *   because an unset active colour resolves to the brand.
+ * @returns {{ backgroundColor: string, textColor: string, activeColor: string,
+ *   activeStyle: string, borderColor: string|null, borderWidth: number|null }}
+ */
+export function resolveSidebarTokens(theme) {
+  const config = isPlainObject(theme) ? theme : {};
+  const sidebar = isPlainObject(config.sidebar) ? config.sidebar : {};
+  const borderColor = hexOrNull(sidebar.borderColor);
+  return {
+    backgroundColor: hexOr(sidebar.backgroundColor, DEFAULT_CHROME_SURFACE),
+    textColor: hexOr(sidebar.textColor, DEFAULT_CHROME_TEXT),
+    activeColor: hexOr(sidebar.activeColor, brandPrimary(config)),
+    activeStyle: sidebar.activeStyle === "accent" ? "accent" : "filled",
+    // REQ-THEME-LOOK: the colour is the switch — no colour, no line.
+    borderColor,
+    borderWidth: borderColor ? borderWidthOr(sidebar.borderWidth) : null,
+  };
+}
+
+/**
+ * The top app bar's surface, its two text colours and its opt-in divider.
+ *
+ * `tintColor` and `titleColor` are SEPARATE because the web bar has always
+ * painted them differently when the author names nothing: the hamburger and
+ * icons take slate, the app name takes the brand. React Navigation's single
+ * `headerTintColor` could not express that, which is why the export used to
+ * paint the name slate. One token, two resolved fields, both hosts agree.
+ *
+ * `show` is deliberately absent: it depends on the menu TYPE, not the theme,
+ * and REQ-THEME-14 makes it a no-op on native — so it is not a shared token.
+ *
+ * @param {unknown} theme — the whole `theme_config`.
+ * @returns {{ backgroundColor: string, tintColor: string, titleColor: string,
+ *   borderColor: string|null, borderWidth: number|null }}
+ */
+export function resolveTopBarTokens(theme) {
+  const config = isPlainObject(theme) ? theme : {};
+  const topBar = isPlainObject(config.topBar) ? config.topBar : {};
+  const borderColor = hexOrNull(topBar.borderColor);
+  // An explicit colour drives BOTH slots; only the unset case splits.
+  const authored = hexOrNull(topBar.textColor);
+  return {
+    backgroundColor: hexOr(topBar.backgroundColor, DEFAULT_CHROME_SURFACE),
+    tintColor: authored || DEFAULT_TOP_BAR_TINT,
+    titleColor: authored || brandPrimary(config),
+    borderColor,
+    borderWidth: borderColor ? borderWidthOr(topBar.borderWidth) : null,
+  };
+}
+
 function borderWidthOr(...values) {
   for (const value of values) {
     if (typeof value === "number" && Number.isFinite(value)) return value;

package/dist/property-schema.js

@@ -2,6 +2,7 @@
 // Drives the schema-driven Properties Panel and validates persisted page JSON.
 
 import { CORNER_RADIUS_KEYS } from "./corner-radius.js";
+import { SPACING_KEYS } from "./spacing.js";
 
 const VALID_TYPES = new Set([
   "string", "number", "boolean",
@@ -57,6 +58,13 @@ const VALID_TYPES = new Set([
   // which both hosts spell identically. Plain numbers, so tenant-copy needs
   // no remap.
   "cornerRadius",
+  // REQ-LAY-17 (sc-6447): `spacing` is a padding/margin picker. Its value is
+  // `number | { top, right, bottom, left }` — a scalar spaces all four sides,
+  // the object spaces each independently. The Studio renders a slider +
+  // typeable number with a per-side disclosure; a widget turns the value into
+  // style props with `spacingStyle(normaliseSpacing(v), "padding")`, which both
+  // hosts spell identically. Plain numbers, so tenant-copy needs no remap.
+  "spacing",
   "expression", "eventBinding",
   "object", "array",
 ]);
@@ -192,6 +200,36 @@ function coerceLeaf(def, value, path, errors) {
       }
       return value;
     }
+    case "spacing": {
+      // REQ-LAY-17: a scalar spaces all four sides; an object spaces each.
+      // Every side is optional so a half-set object stays valid while the
+      // author is still adjusting — an unset side falls back to the scalar.
+      const { min = 0, max } = def.validation || {};
+      const checkSide = (n, at) => {
+        if (typeof n !== "number" || Number.isNaN(n)) {
+          errors.push(`${at}: expected number`);
+          return;
+        }
+        if (n < min) errors.push(`${at}: must be >= ${min}`);
+        if (max !== undefined && n > max) errors.push(`${at}: must be <= ${max}`);
+      };
+      if (typeof value === "number") {
+        checkSide(value, path);
+        return value;
+      }
+      if (!isPlainObject(value)) {
+        errors.push(`${path}: expected number or per-side object`);
+        return value;
+      }
+      for (const [k, n] of Object.entries(value)) {
+        if (!SPACING_KEYS.includes(k)) {
+          errors.push(`${path}.${k}: unknown side`);
+        } else if (n !== undefined && n !== null) {
+          checkSide(n, `${path}.${k}`);
+        }
+      }
+      return value;
+    }
     case "select":
       if (Array.isArray(def.enum) && !def.enum.some((e) => e.value === value)) {
         errors.push(`${path}: value not in enum`);

package/dist/spacing.js

@@ -0,0 +1,118 @@
+// REQ-LAY-17 (sc-6447): the per-side spacing vocabulary. ONE normaliser and ONE
+// style emitter for the web Player, the Builder canvas, the exported Expo app,
+// and any custom widget declaring a `padding`/`margin` field — so the four can
+// never disagree about what a spacing value means.
+//
+// The authored value is `number | { top, right, bottom, left }`. The scalar form
+// is what every existing style holds, so it stays first-class rather than being
+// migrated away: widening the shape beats adding a second key beside it
+// (CLAUDE.md §3). This mirrors `corner-radius.js` deliberately — padding/margin
+// and cornerRadius are the four-valued members of one box model, and an author
+// meets the same affordance in both.
+//
+// Both hosts spell the long-hand props identically (`paddingTop` / `marginTop`
+// &co in React inline style AND in React Native), which is why one emitter
+// serves both.
+
+export const SPACING_KEYS = Object.freeze(["top", "right", "bottom", "left"]);
+
+// The CSS/RN suffix per side. `padding` + "Top" and `margin` + "Top" are both
+// valid on web and native, so the property name is the caller's to choose.
+const LONGHAND_SUFFIX = Object.freeze({
+  top: "Top",
+  right: "Right",
+  bottom: "Bottom",
+  left: "Left",
+});
+
+function clampSide(value, fallback, max) {
+  // Unset (undefined/null/"") falls back; an explicit 0 is honoured — that
+  // distinction is what makes "no padding on just this side" expressible.
+  if (value === undefined || value === null || value === "") return fallback;
+  const n = Number(value);
+  if (!Number.isFinite(n)) return fallback;
+  // Truncates, where `corner-radius.js` rounds: padding and margin have always
+  // truncated (`clampInt` / `clampMargin`), and changing that would shift every
+  // existing fractional value by a pixel.
+  return Math.min(Math.max(Math.trunc(n), 0), max);
+}
+
+/**
+ * Resolve an authored spacing to its four sides.
+ *
+ * @param {number|object|null|undefined} value the authored `number | {sides}`
+ * @param {number} [fallback] the value each unset side takes
+ * @param {number} [max] the upper clamp, matching the field's declared max
+ * @returns {{top:number, right:number, bottom:number, left:number}}
+ */
+export function normaliseSpacing(value, fallback = 0, max = 64) {
+  const base = clampSide(
+    typeof value === "number" || typeof value === "string" ? value : undefined,
+    clampSide(fallback, 0, max),
+    max,
+  );
+  const sides = value && typeof value === "object" ? value : null;
+  const out = {};
+  for (const key of SPACING_KEYS) {
+    out[key] = clampSide(sides ? sides[key] : undefined, base, max);
+  }
+  return out;
+}
+
+/** True when all four sides resolve to the same number. */
+export function isUniformSpacing(spacing) {
+  if (!spacing) return true;
+  const { top } = spacing;
+  return SPACING_KEYS.every((key) => spacing[key] === top);
+}
+
+/** True when every side resolves to 0 — i.e. the value asks for no spacing. */
+export function isZeroSpacing(spacing) {
+  return !spacing || SPACING_KEYS.every((key) => !spacing[key]);
+}
+
+/**
+ * Map every side through `fn`, keeping the resolved shape. Used to push each
+ * side through the responsive/theme scaling the scalar form already got, so a
+ * per-side value scales down on a phone exactly like a uniform one.
+ *
+ * @param {object|null} spacing output of {@link normaliseSpacing}
+ * @param {(n: number) => number} fn
+ * @returns {object|null}
+ */
+export function mapSpacing(spacing, fn) {
+  if (!spacing) return null;
+  const out = {};
+  for (const key of SPACING_KEYS) {
+    const next = Number(fn(spacing[key]));
+    out[key] = Number.isFinite(next) ? next : spacing[key];
+  }
+  return out;
+}
+
+/**
+ * The style props for a resolved spacing, in the spelling BOTH hosts accept.
+ * A uniform value emits the shorthand so an untouched style is byte-identical
+ * to what the scalar form produced; only a genuinely mixed value pays for the
+ * four long-hand props.
+ *
+ * This emitter is MECHANICAL — it always emits, including an all-zero value.
+ * The zero policy differs per box property (a container's `padding: 0` has
+ * always been written, while a zero `margin` has always emitted nothing), so it
+ * belongs with each caller via {@link isZeroSpacing}, not baked in here.
+ *
+ * @param {object|null} spacing output of {@link normaliseSpacing}
+ * @param {"padding"|"margin"} [property] which box property to spell
+ * @param {(n: number) => any} [format] wraps each number — the DOM needs "12px"
+ * @returns {object|null}
+ */
+export function spacingStyle(spacing, property = "padding", format) {
+  if (!spacing) return null;
+  const wrap = format || ((n) => n);
+  if (isUniformSpacing(spacing)) return { [property]: wrap(spacing.top) };
+  const out = {};
+  for (const key of SPACING_KEYS) {
+    out[`${property}${LONGHAND_SUFFIX[key]}`] = wrap(spacing[key]);
+  }
+  return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.109.0",
+  "version": "0.111.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",