@colixsystems/widget-sdk 0.71.0 → 0.72.0

package/README.md

@@ -432,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
@@ -562,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
@@ -2245,7 +2249,16 @@ const CONTRACT = deepFreeze({
   //    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",
+  //
+  // 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,

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
@@ -2245,7 +2249,16 @@ const CONTRACT = deepFreeze({
   //    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",
+  //
+  // 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,

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.71.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",