@colixsystems/widget-sdk 0.70.0 → 0.71.0

package/README.md

@@ -54,7 +54,19 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.70.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.71.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.71.0
+
+**A theme can set leading, tracking and case for text app-wide (sc-3857).** The `text` scope of `themeConfig.components` gains three tokens beside `color` and `fontSize`:
+
+- **`lineHeight`** — leading as a MULTIPLE of the font size (0.8–3), so one app-wide value stays right at every size. Tight leading (1.0–1.15) is what makes a 32px+ headline read as a headline rather than as oversized body text.
+- **`letterSpacing`** — tracking in pixels (−2 to 20). Wide positive tracking is what makes a small uppercase kicker read as a kicker.
+- **`textTransform`** — `none` | `uppercase` | `capitalize`, published as `CONTRACT.themeComponentTextTransforms`.
+
+Two new token value types back them: **`decimal`** (a clamped, 2-decimal number — `size` rounds, so it cannot carry a 1.05 multiplier) and **`textTransform`**. Each token binds to the identically named per-instance style field the target widgets read, so the author rule is unchanged: read `props.style` / `useWidgetStyle()`, and a per-instance value still wins over the app-wide token.
+
+`CONTRACT.version` → `1.48.0`. Additive: no existing export changed signature, and a theme with none of the new tokens renders exactly as before.
 
 ### What's new in 0.70.0
 

package/dist/contract.cjs

@@ -107,6 +107,14 @@ const DEFAULT_THEME_TOKENS = Object.freeze({
 // cannot drift between what Mason may emit and what a host actually applies.
 const THEME_COMPONENT_SHADOWS = Object.freeze(["none", "sm", "md", "lg"]);
 
+// sc-3857 — the `textTransform` token's closed enum, matching the per-instance
+// Text/Label/Data Value style field and React Native's own vocabulary.
+const THEME_COMPONENT_TEXT_TRANSFORMS = Object.freeze([
+  "none",
+  "uppercase",
+  "capitalize",
+]);
+
 // sc-3727 — the `gradient` token's value shape: two hex stops plus a CSS-degree
 // angle, the same grammar as `themeConfig.backgroundGradient` minus the radial
 // variant (a component fill projects through `<Gradient>`, which is linear-only
@@ -129,6 +137,16 @@ const CARD_SURFACE_FIELDS = Object.freeze({
   gradient: "cardGradient",
 });
 
+// The text field names every text-bearing built-in reads
+// (frontend/src/components/widgets/_shared/textStyle.js TYPOGRAPHY_STYLE_FIELDS).
+const TEXT_TYPOGRAPHY_FIELDS = Object.freeze({
+  color: "color",
+  fontSize: "fontSize",
+  lineHeight: "lineHeight",
+  letterSpacing: "letterSpacing",
+  textTransform: "textTransform",
+});
+
 // A form widget's submit button — the `button` scope reaches it through the
 // form's own submit* fields, so "make the buttons coral" does not skip forms.
 const FORM_SUBMIT_FIELDS = Object.freeze({
@@ -190,14 +208,16 @@ const THEME_COMPONENTS = Object.freeze({
     tokens: Object.freeze({
       color: Object.freeze({ type: "color", uiDefault: "colors.onSurface" }),
       fontSize: Object.freeze({ type: "size", min: 8, max: 96, uiDefault: "typography.sizes.md" }),
+      // sc-3857 — leading as a MULTIPLE of the font size, so one app-wide value
+      // is right at every size; `size` cannot carry it because it rounds.
+      lineHeight: Object.freeze({ type: "decimal", min: 0.8, max: 3, step: 0.05 }),
+      letterSpacing: Object.freeze({ type: "decimal", min: -2, max: 20, step: 0.1 }),
+      textTransform: Object.freeze({ type: "textTransform" }),
     }),
     targets: Object.freeze({
-      "appstudio.text": Object.freeze({ color: "color", fontSize: "fontSize" }),
-      "appstudio.label": Object.freeze({ color: "color", fontSize: "fontSize" }),
-      "appstudio.data-value": Object.freeze({
-        color: "color",
-        fontSize: "fontSize",
-      }),
+      "appstudio.text": TEXT_TYPOGRAPHY_FIELDS,
+      "appstudio.label": TEXT_TYPOGRAPHY_FIELDS,
+      "appstudio.data-value": TEXT_TYPOGRAPHY_FIELDS,
     }),
   }),
 });
@@ -2215,7 +2235,17 @@ const CONTRACT = deepFreeze({
   //    null, which is how one button stays flat while the rest are gradiented.
   //    Additive: no export changed signature and a theme with no gradient token
   //    renders exactly as before.
-  version: "1.47.0",
+  // 1.48.0: additive (sc-3857) — leading, tracking and case on the `text` scope.
+  //    `lineHeight` (a MULTIPLE of the font size), `letterSpacing` (pixels) and
+  //    `textTransform` join the existing `color` / `fontSize` tokens and bind to
+  //    the identically named per-instance style fields Text, Label and Data Value
+  //    now read, so a theme can set app-wide typography and an author still
+  //    overrides it per instance. Two new token value types back them: `decimal`
+  //    (a clamped 2-decimal number — `size` rounds, so it cannot carry a 1.05
+  //    multiplier) and `textTransform`, whose closed enum is published as
+  //    `themeComponentTextTransforms`. Additive: no export changed signature and
+  //    a theme with none of the new tokens renders exactly as before.
+  version: "1.48.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -2228,6 +2258,7 @@ const CONTRACT = deepFreeze({
   themeTokens: DEFAULT_THEME_TOKENS,
   themeComponents: THEME_COMPONENTS,
   themeComponentShadows: THEME_COMPONENT_SHADOWS,
+  themeComponentTextTransforms: THEME_COMPONENT_TEXT_TRANSFORMS,
   themeComponentGradient: THEME_COMPONENT_GRADIENT,
   widgetContextShape: WIDGET_CONTEXT_SHAPE,
   bundleExportContract: BUNDLE_EXPORT_CONTRACT,

package/dist/contract.js

@@ -107,6 +107,14 @@ const DEFAULT_THEME_TOKENS = Object.freeze({
 // cannot drift between what Mason may emit and what a host actually applies.
 const THEME_COMPONENT_SHADOWS = Object.freeze(["none", "sm", "md", "lg"]);
 
+// sc-3857 — the `textTransform` token's closed enum, matching the per-instance
+// Text/Label/Data Value style field and React Native's own vocabulary.
+const THEME_COMPONENT_TEXT_TRANSFORMS = Object.freeze([
+  "none",
+  "uppercase",
+  "capitalize",
+]);
+
 // sc-3727 — the `gradient` token's value shape: two hex stops plus a CSS-degree
 // angle, the same grammar as `themeConfig.backgroundGradient` minus the radial
 // variant (a component fill projects through `<Gradient>`, which is linear-only
@@ -129,6 +137,16 @@ const CARD_SURFACE_FIELDS = Object.freeze({
   gradient: "cardGradient",
 });
 
+// The text field names every text-bearing built-in reads
+// (frontend/src/components/widgets/_shared/textStyle.js TYPOGRAPHY_STYLE_FIELDS).
+const TEXT_TYPOGRAPHY_FIELDS = Object.freeze({
+  color: "color",
+  fontSize: "fontSize",
+  lineHeight: "lineHeight",
+  letterSpacing: "letterSpacing",
+  textTransform: "textTransform",
+});
+
 // A form widget's submit button — the `button` scope reaches it through the
 // form's own submit* fields, so "make the buttons coral" does not skip forms.
 const FORM_SUBMIT_FIELDS = Object.freeze({
@@ -190,14 +208,16 @@ const THEME_COMPONENTS = Object.freeze({
     tokens: Object.freeze({
       color: Object.freeze({ type: "color", uiDefault: "colors.onSurface" }),
       fontSize: Object.freeze({ type: "size", min: 8, max: 96, uiDefault: "typography.sizes.md" }),
+      // sc-3857 — leading as a MULTIPLE of the font size, so one app-wide value
+      // is right at every size; `size` cannot carry it because it rounds.
+      lineHeight: Object.freeze({ type: "decimal", min: 0.8, max: 3, step: 0.05 }),
+      letterSpacing: Object.freeze({ type: "decimal", min: -2, max: 20, step: 0.1 }),
+      textTransform: Object.freeze({ type: "textTransform" }),
     }),
     targets: Object.freeze({
-      "appstudio.text": Object.freeze({ color: "color", fontSize: "fontSize" }),
-      "appstudio.label": Object.freeze({ color: "color", fontSize: "fontSize" }),
-      "appstudio.data-value": Object.freeze({
-        color: "color",
-        fontSize: "fontSize",
-      }),
+      "appstudio.text": TEXT_TYPOGRAPHY_FIELDS,
+      "appstudio.label": TEXT_TYPOGRAPHY_FIELDS,
+      "appstudio.data-value": TEXT_TYPOGRAPHY_FIELDS,
     }),
   }),
 });
@@ -2215,7 +2235,17 @@ const CONTRACT = deepFreeze({
   //    null, which is how one button stays flat while the rest are gradiented.
   //    Additive: no export changed signature and a theme with no gradient token
   //    renders exactly as before.
-  version: "1.47.0",
+  // 1.48.0: additive (sc-3857) — leading, tracking and case on the `text` scope.
+  //    `lineHeight` (a MULTIPLE of the font size), `letterSpacing` (pixels) and
+  //    `textTransform` join the existing `color` / `fontSize` tokens and bind to
+  //    the identically named per-instance style fields Text, Label and Data Value
+  //    now read, so a theme can set app-wide typography and an author still
+  //    overrides it per instance. Two new token value types back them: `decimal`
+  //    (a clamped 2-decimal number — `size` rounds, so it cannot carry a 1.05
+  //    multiplier) and `textTransform`, whose closed enum is published as
+  //    `themeComponentTextTransforms`. Additive: no export changed signature and
+  //    a theme with none of the new tokens renders exactly as before.
+  version: "1.48.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -2228,6 +2258,7 @@ const CONTRACT = deepFreeze({
   themeTokens: DEFAULT_THEME_TOKENS,
   themeComponents: THEME_COMPONENTS,
   themeComponentShadows: THEME_COMPONENT_SHADOWS,
+  themeComponentTextTransforms: THEME_COMPONENT_TEXT_TRANSFORMS,
   themeComponentGradient: THEME_COMPONENT_GRADIENT,
   widgetContextShape: WIDGET_CONTEXT_SHAPE,
   bundleExportContract: BUNDLE_EXPORT_CONTRACT,

package/dist/theme-components.cjs

@@ -44,9 +44,22 @@ function coerceToken(def, value) {
     if (!Number.isFinite(n)) return undefined;
     return Math.min(def.max, Math.max(def.min, Math.round(n)));
   }
+  // sc-3857: a leading multiplier / tracking value must survive the decimals
+  // `size` rounds away — 1.05 leading is the whole point of the token.
+  if (def.type === "decimal") {
+    const n = typeof value === "number" ? value : Number(value);
+    if (!Number.isFinite(n)) return undefined;
+    const clamped = Math.min(def.max, Math.max(def.min, n));
+    return Math.round(clamped * 100) / 100;
+  }
   if (def.type === "shadow") {
     return CONTRACT.themeComponentShadows.includes(value) ? value : undefined;
   }
+  if (def.type === "textTransform") {
+    return CONTRACT.themeComponentTextTransforms.includes(value)
+      ? value
+      : undefined;
+  }
   // sc-3727: the gradient value has its own normaliser on the contract, shared
   // with the widget render path so both routes agree (CLAUDE.md §3).
   if (def.type === "gradient") {

package/dist/theme-components.js

@@ -36,9 +36,22 @@ function coerceToken(def, value) {
     if (!Number.isFinite(n)) return undefined;
     return Math.min(def.max, Math.max(def.min, Math.round(n)));
   }
+  // sc-3857: a leading multiplier / tracking value must survive the decimals
+  // `size` rounds away — 1.05 leading is the whole point of the token.
+  if (def.type === "decimal") {
+    const n = typeof value === "number" ? value : Number(value);
+    if (!Number.isFinite(n)) return undefined;
+    const clamped = Math.min(def.max, Math.max(def.min, n));
+    return Math.round(clamped * 100) / 100;
+  }
   if (def.type === "shadow") {
     return CONTRACT.themeComponentShadows.includes(value) ? value : undefined;
   }
+  if (def.type === "textTransform") {
+    return CONTRACT.themeComponentTextTransforms.includes(value)
+      ? value
+      : undefined;
+  }
   // sc-3727: the gradient value has its own normaliser on the contract, shared
   // with the widget render path so both routes agree (CLAUDE.md §3).
   if (def.type === "gradient") {

package/package.json

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