@colixsystems/widget-sdk 0.110.0 → 0.111.0

package/README.md

@@ -69,7 +69,22 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.110.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)
 

package/dist/contract.cjs

@@ -3374,7 +3374,19 @@ const CONTRACT = deepFreeze({
   //    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.
-  version: "1.84.0",
+  //
+  // 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

@@ -3374,7 +3374,19 @@ const CONTRACT = deepFreeze({
   //    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.
-  version: "1.84.0",
+  //
+  // 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/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/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.110.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",