@colixsystems/widget-sdk 0.70.0 → 0.72.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
 
@@ -420,7 +432,7 @@ A runtime schema resolver so widgets can render by column type.
 The tenant's **Theme Settings** now flow all the way into `useTheme()`.
 
 - **`themeTokens.colors` gains `secondary` + `onSecondary`.** `useTheme().colors.secondary` reflects the tenant's *Secondary Color* picker (with `onSecondary` as its readable contrast color), alongside the existing `primary` / `onPrimary`. Built-in widgets like Button use it for their secondary variant; third-party widgets can use it for a branded second accent. The full `colors` shape is now `{ primary, onPrimary, secondary, onSecondary, surface, onSurface, surfaceMuted, onSurfaceMuted, border, danger, success, warning, info }`.
-- **`colors.primary` / `colors.secondary` / `typography.fontFamily` are tenant-resolved.** The host maps the Studio Theme Settings blob (Primary Color, Secondary Color, Global Font) onto the default tokens before handing them to `useTheme()`, on both the live Player and the exported app — so a widget that reads tokens re-themes automatically. (Custom Google fonts render in the Player today; the exported app falls back to the system face for non-system fonts until font bundling lands.)
+- **`colors.primary` / `colors.secondary` / `typography.fontFamily` / `typography.headingFontFamily` are tenant-resolved.** The host maps the Studio Theme Settings blob (Primary Color, Secondary Color, Global Font, Heading Font) onto the default tokens before handing them to `useTheme()`, on both the live Player and the exported app — so a widget that reads tokens re-themes automatically. Both families are loaded by the Player and bundled into the exported app, so they render the same on web and native.
 - **`CONTRACT.version` → `1.6.0`** (additive: two new `themeTokens.colors` keys). No existing export changed signature.
 
 ### What's new in 0.15.0
@@ -550,7 +562,7 @@ A widget that works but looks unfinished is only half done. `useTheme()` is the
 
 - **Pull spacing and corners from tokens.** Use `theme.spacing` (`xs / sm / md / lg / xl`) for a consistent padding and gap rhythm, and `theme.radii` (`sm / md / lg / pill`) for corners — `radii.lg` for cards and hero surfaces, `radii.md` for controls nested inside one. Don't hardcode raw pixel values.
 - **Build a hierarchy.** A clear title (large, bold, `colors.onSurface`), body text, and muted captions in `colors.onSurfaceMuted` — three weights, not one flat size. Reserve full-strength `colors.primary` (with `colors.onPrimary` for text on it) for the single most important action or metric.
-- **Set the theme font on every `Text`.** React Native `Text` does not inherit `fontFamily` from a parent, so a text element that omits it falls back to the system font and ignores the workspace's configured font. Put `theme.typography.fontFamily` on every text style (a shared `StyleSheet` built from `theme` keeps it in one place) and size text with `theme.typography.sizes`.
+- **Set the theme font on every `Text`.** React Native `Text` does not inherit `fontFamily` from a parent, so a text element that omits it falls back to the system font and ignores the workspace's configured font. Put `theme.typography.fontFamily` on every text style (a shared `StyleSheet` built from `theme` keeps it in one place) and size text with `theme.typography.sizes`. Use `theme.typography.headingFontFamily` instead on your widget's HEADING-tier text — titles and display numbers — so a workspace that pairs a display face with a body face gets that pairing inside your widget too. It defaults to `fontFamily`, so an unpaired workspace looks identical.
 - **Contain and elevate.** Wrap a logical unit in a surface: `colors.surface` + padding + `radii.lg` + `...theme.elevation.sm`. Give it the elevation **or** a `colors.border` hairline, not both — and prefer the elevation, because a hairline-only card reads as a wireframe. `theme.elevation` is a token table you spread into a style (`...theme.elevation.md`), covering `none / sm / md / lg / xl`; never hand-write `shadowOpacity` / `shadowRadius` / `boxShadow`. Use the status roles (`danger / success / warning / info`) for state.
 - **Tint the supporting cast.** `colors.primarySoft` is a tint of the workspace accent over the surface and `colors.onPrimarySoft` is guaranteed readable on it (WCAG AA, on light and dark themes alike). Use the pair for chips, secondary buttons, progress tracks, icon badges and selected rows. One saturated accent moment surrounded by several pale echoes of the same hue is what reads as designed — a row of grey-outlined buttons reads as a form. Never hand-mix a tint with `rgba(...)` or a translucent overlay.
 - **Spend one gradient.** `<Gradient colors={[theme.colors.primary, theme.colors.primaryStrong]} angle={160} style={…}>` is a `View` that paints a gradient behind its children, so it replaces the `View` you'd otherwise give a flat `backgroundColor`. `angle` is CSS degrees (0 = to top, 90 = to right, default 180); text on it uses `colors.onPrimary`. Exactly **one** per widget — on the focal element — and never behind body text. Both hosts render it identically (web paints CSS, native uses `expo-linear-gradient`), so there is no per-platform branching to write; don't import `expo-linear-gradient` yourself and don't write a `backgroundImage` string.

package/dist/contract.cjs

@@ -76,6 +76,10 @@ const DEFAULT_THEME_TOKENS = Object.freeze({
   typography: Object.freeze({
     fontFamily:
       'ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
+    // The display face for heading-tier text. Defaults to `fontFamily` — an app
+    // that never pairs renders on one typeface exactly as before.
+    headingFontFamily:
+      'ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
     sizes: Object.freeze({ xs: 12, sm: 14, md: 16, lg: 20, xl: 24, xxl: 32 }),
   }),
   // REQ-THEME-15: the tenant's per-component style tokens, folded in by the
@@ -107,6 +111,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 +141,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 +212,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 +2239,26 @@ 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.
+  //
+  // 1.49.0: additive (REQ-THEME-12) — `themeTokens.typography` gains
+  //    `headingFontFamily`, the display face for heading-tier text, and the
+  //    per-instance text vocabulary gains `fontRole` (`body` | `heading`) so an
+  //    author or Mason marks which text is a heading. `headingFontFamily`
+  //    defaults to the resolved `fontFamily`, and `fontRole` defaults to
+  //    `body`, so an app that sets neither renders on one typeface exactly as
+  //    before. Genuine headings — rich-text h1-h3 and container titles — take
+  //    the heading face without the field.
+  version: "1.49.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -2228,6 +2271,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

@@ -76,6 +76,10 @@ const DEFAULT_THEME_TOKENS = Object.freeze({
   typography: Object.freeze({
     fontFamily:
       'ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
+    // The display face for heading-tier text. Defaults to `fontFamily` — an app
+    // that never pairs renders on one typeface exactly as before.
+    headingFontFamily:
+      'ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
     sizes: Object.freeze({ xs: 12, sm: 14, md: 16, lg: 20, xl: 24, xxl: 32 }),
   }),
   // REQ-THEME-15: the tenant's per-component style tokens, folded in by the
@@ -107,6 +111,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 +141,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 +212,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 +2239,26 @@ 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.
+  //
+  // 1.49.0: additive (REQ-THEME-12) — `themeTokens.typography` gains
+  //    `headingFontFamily`, the display face for heading-tier text, and the
+  //    per-instance text vocabulary gains `fontRole` (`body` | `heading`) so an
+  //    author or Mason marks which text is a heading. `headingFontFamily`
+  //    defaults to the resolved `fontFamily`, and `fontRole` defaults to
+  //    `body`, so an app that sets neither renders on one typeface exactly as
+  //    before. Genuine headings — rich-text h1-h3 and container titles — take
+  //    the heading face without the field.
+  version: "1.49.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -2228,6 +2271,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/index.d.ts

@@ -306,6 +306,8 @@ export interface ThemeTokens {
   radii: { sm: number; md: number; lg: number; pill: number };
   typography: {
     fontFamily: string;
+    /** The display face for heading-tier text. Defaults to `fontFamily`. */
+    headingFontFamily: string;
     sizes: { xs: number; sm: number; md: number; lg: number; xl: number };
   };
 }

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.72.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",