@colixsystems/widget-sdk 0.148.0 → 0.149.0

package/README.md

@@ -1626,7 +1626,20 @@ 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`. 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.
+- **Style text by its ROLE, not by inventing a size and weight.** `theme.typography.roles` carries the workspace's type scale as six semantic tiers — `display`, `title`, `subtitle`, `body`, `caption`, `overline` — each already resolved to a `fontSize`, `fontWeight`, `fontStyle`, `lineHeight` (a MULTIPLE of the size), `letterSpacing`, `textTransform` and a `colorToken`. Pick the tier the text IS, rather than choosing `fontSize: 16, fontWeight: "600"` yourself: your widget's section title is `title`, each card or row title is `subtitle`, running text is `body`, timestamps and helper text are `caption`, a small kicker or column label is `overline`, and a headline stat is `display`. This is what stops one widget rendering a subtitle bold while the widget beside it renders one italic, and it lets the workspace re-tune every subtitle in the app from Theme Settings in one edit. **Two tokens need converting rather than copying** — `lineHeight` is a multiple (React Native wants absolute pixels, so the raw `1.15` gives you a one-pixel line box) and `colorToken` names a colour rather than being one:
+
+  ```js
+  const r = theme.typography.roles.subtitle;
+  const titleStyle = {
+    fontSize: r.fontSize,
+    fontWeight: r.fontWeight,
+    letterSpacing: r.letterSpacing,
+    textTransform: r.textTransform,
+    lineHeight: Math.round(r.fontSize * r.lineHeight),
+    color: r.color || theme.colors[r.colorToken],
+  };
+  ```
+- **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). A role already names its face for you — `display` and `title` take `theme.typography.headingFontFamily`, the rest take `fontFamily` — so a workspace that pairs a display face with a body face gets that pairing inside your widget without you naming a family. `headingFontFamily` 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

@@ -108,6 +108,58 @@ const DEFAULT_THEME_TOKENS = Object.freeze({
     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-ROLE (sc-8058): the app's type scale as six SEMANTIC roles.
+    // Typography carried two faces and a size scale and nothing else, so a
+    // widget needing a "subtitle" had nothing to reach for and each invented
+    // its own literal — bold in Notifications, italic in User Management,
+    // unweighted in Files. A role names the TIER; the theme owns its look.
+    //
+    // Which FACE a role takes lives in `_shared/textStyle.js` ROLE_FACES —
+    // structural, not themeable, so it resolves without theme data. `colorToken` is
+    // the SURFACE token the role is painted with, resolved per render against
+    // the surface-aware theme (REQ-THEME-DARK / REQ-THEME-SURFACE) rather than
+    // frozen as a hex — a theme may override it with an explicit `color`.
+    roles: Object.freeze({
+      display: Object.freeze({
+        fontSize: 32,
+        fontWeight: "700",
+        lineHeight: 1.05,
+        letterSpacing: -0.5,
+        colorToken: "onSurface",
+      }),
+      title: Object.freeze({
+        fontSize: 24,
+        fontWeight: "700",
+        lineHeight: 1.15,
+        letterSpacing: -0.2,
+        colorToken: "onSurface",
+      }),
+      subtitle: Object.freeze({
+        fontSize: 16,
+        fontWeight: "600",
+        lineHeight: 1.3,
+        colorToken: "onSurface",
+      }),
+      body: Object.freeze({
+        fontSize: 16,
+        fontWeight: "400",
+        lineHeight: 1.5,
+        colorToken: "onSurface",
+      }),
+      caption: Object.freeze({
+        fontSize: 12,
+        fontWeight: "400",
+        lineHeight: 1.4,
+        colorToken: "onSurfaceMuted",
+      }),
+      overline: Object.freeze({
+        fontSize: 12,
+        fontWeight: "600",
+        lineHeight: 1.4,
+        letterSpacing: 1.5,
+        colorToken: "onSurfaceMuted",
+      }),
+    }),
   }),
   // REQ-THEME-15: the tenant's per-component style tokens, folded in by the
   // host so ONE channel carries them to the Player and the export. Empty by
@@ -172,6 +224,44 @@ const THEME_COMPONENT_TEXT_TRANSFORMS = Object.freeze([
   "capitalize",
 ]);
 
+// REQ-THEME-ROLE (sc-8058) -- the THEME side of the six semantic text tiers, in
+// the order the widgets' own TEXT_ROLES lists them. `themeTokens.typography.roles`
+// carries the seeded values; this names what a TENANT may override, so the Studio
+// control, the Mason `set_theme` coercion and the docs read ONE vocabulary --
+// exactly as `themeComponents` already is for the per-component tokens.
+const THEME_TEXT_ROLES = Object.freeze([
+  "display",
+  "title",
+  "subtitle",
+  "body",
+  "caption",
+  "overline",
+]);
+
+// Mirrors the backend's SITE_HEADER_FONT_WEIGHTS so one theme speaks one weight
+// vocabulary. Strings, because that is what both hosts' `fontWeight` takes.
+const THEME_TEXT_ROLE_FONT_WEIGHTS = Object.freeze([
+  "100", "200", "300", "400", "500", "600", "700", "800", "900",
+]);
+
+const THEME_TEXT_ROLE_FONT_STYLES = Object.freeze(["normal", "italic"]);
+
+// The per-role token vocabulary, declared like a `themeComponents` scope's
+// `tokens`: each field's value type and bounds stated ONCE, so the Studio
+// control, the set_theme coercion and the host validator cannot disagree.
+// `lineHeight` is a MULTIPLE of `fontSize` (REQ-THEME-13's grammar), so one
+// value is right at every size; `color` overrides the role's surface-aware
+// `colorToken`, which is why no role seeds a literal colour.
+const THEME_TEXT_ROLE_FIELDS = Object.freeze({
+  fontSize: Object.freeze({ type: "size", min: 8, max: 96 }),
+  fontWeight: Object.freeze({ type: "enum", values: THEME_TEXT_ROLE_FONT_WEIGHTS }),
+  fontStyle: Object.freeze({ type: "enum", values: THEME_TEXT_ROLE_FONT_STYLES }),
+  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" }),
+  color: Object.freeze({ type: "color" }),
+});
+
 // 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
@@ -4140,7 +4230,20 @@ const CONTRACT = deepFreeze({
   //    where the rail's and the header's keep sc-7965's 1-8 clamp. A backfill
   //    (`20270123000000_sc8033_footer_tokens_uncouple`) materialised what each
   //    workspace was inheriting, so no shipped app moved.
-  version: "1.116.0",
+  // 1.117.0: additive (sc-8058) -- the six SEMANTIC text roles.
+  //    `themeTokens.typography.roles` seeds display / title / subtitle / body /
+  //    caption / overline, and `themeTextRoles` + `themeTextRoleFields` publish
+  //    the tier names and the per-role token vocabulary (each field's type and
+  //    bounds) a TENANT may override -- the single source the Studio control,
+  //    the Mason `set_theme` coercion and the docs read, exactly as
+  //    `themeComponents` already is. Typography carried two faces and a size
+  //    scale and nothing else, so every widget drawing a "subtitle" invented its
+  //    own literal and no theme edit could move them together. Which FACE a role
+  //    takes is deliberately absent -- that is structural (`ROLE_FACES` in the
+  //    hosts' shared textStyle module), not a theme token. Additive: no export
+  //    changed signature, and a theme carrying no `roles` renders on the seeded
+  //    defaults exactly as before.
+  version: "1.117.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -4156,6 +4259,8 @@ const CONTRACT = deepFreeze({
   themeComponentShadows: THEME_COMPONENT_SHADOWS,
   themeComponentTextTransforms: THEME_COMPONENT_TEXT_TRANSFORMS,
   themeComponentGradient: THEME_COMPONENT_GRADIENT,
+  themeTextRoles: THEME_TEXT_ROLES,
+  themeTextRoleFields: THEME_TEXT_ROLE_FIELDS,
   themeSpacingScale: THEME_SPACING_SCALE,
   themeMenuTypes: THEME_MENU_TYPES,
   themeWidgetStyles: THEME_WIDGET_STYLES,

package/dist/contract.js

@@ -108,6 +108,58 @@ const DEFAULT_THEME_TOKENS = Object.freeze({
     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-ROLE (sc-8058): the app's type scale as six SEMANTIC roles.
+    // Typography carried two faces and a size scale and nothing else, so a
+    // widget needing a "subtitle" had nothing to reach for and each invented
+    // its own literal — bold in Notifications, italic in User Management,
+    // unweighted in Files. A role names the TIER; the theme owns its look.
+    //
+    // Which FACE a role takes lives in `_shared/textStyle.js` ROLE_FACES —
+    // structural, not themeable, so it resolves without theme data. `colorToken` is
+    // the SURFACE token the role is painted with, resolved per render against
+    // the surface-aware theme (REQ-THEME-DARK / REQ-THEME-SURFACE) rather than
+    // frozen as a hex — a theme may override it with an explicit `color`.
+    roles: Object.freeze({
+      display: Object.freeze({
+        fontSize: 32,
+        fontWeight: "700",
+        lineHeight: 1.05,
+        letterSpacing: -0.5,
+        colorToken: "onSurface",
+      }),
+      title: Object.freeze({
+        fontSize: 24,
+        fontWeight: "700",
+        lineHeight: 1.15,
+        letterSpacing: -0.2,
+        colorToken: "onSurface",
+      }),
+      subtitle: Object.freeze({
+        fontSize: 16,
+        fontWeight: "600",
+        lineHeight: 1.3,
+        colorToken: "onSurface",
+      }),
+      body: Object.freeze({
+        fontSize: 16,
+        fontWeight: "400",
+        lineHeight: 1.5,
+        colorToken: "onSurface",
+      }),
+      caption: Object.freeze({
+        fontSize: 12,
+        fontWeight: "400",
+        lineHeight: 1.4,
+        colorToken: "onSurfaceMuted",
+      }),
+      overline: Object.freeze({
+        fontSize: 12,
+        fontWeight: "600",
+        lineHeight: 1.4,
+        letterSpacing: 1.5,
+        colorToken: "onSurfaceMuted",
+      }),
+    }),
   }),
   // REQ-THEME-15: the tenant's per-component style tokens, folded in by the
   // host so ONE channel carries them to the Player and the export. Empty by
@@ -172,6 +224,44 @@ const THEME_COMPONENT_TEXT_TRANSFORMS = Object.freeze([
   "capitalize",
 ]);
 
+// REQ-THEME-ROLE (sc-8058) -- the THEME side of the six semantic text tiers, in
+// the order the widgets' own TEXT_ROLES lists them. `themeTokens.typography.roles`
+// carries the seeded values; this names what a TENANT may override, so the Studio
+// control, the Mason `set_theme` coercion and the docs read ONE vocabulary --
+// exactly as `themeComponents` already is for the per-component tokens.
+const THEME_TEXT_ROLES = Object.freeze([
+  "display",
+  "title",
+  "subtitle",
+  "body",
+  "caption",
+  "overline",
+]);
+
+// Mirrors the backend's SITE_HEADER_FONT_WEIGHTS so one theme speaks one weight
+// vocabulary. Strings, because that is what both hosts' `fontWeight` takes.
+const THEME_TEXT_ROLE_FONT_WEIGHTS = Object.freeze([
+  "100", "200", "300", "400", "500", "600", "700", "800", "900",
+]);
+
+const THEME_TEXT_ROLE_FONT_STYLES = Object.freeze(["normal", "italic"]);
+
+// The per-role token vocabulary, declared like a `themeComponents` scope's
+// `tokens`: each field's value type and bounds stated ONCE, so the Studio
+// control, the set_theme coercion and the host validator cannot disagree.
+// `lineHeight` is a MULTIPLE of `fontSize` (REQ-THEME-13's grammar), so one
+// value is right at every size; `color` overrides the role's surface-aware
+// `colorToken`, which is why no role seeds a literal colour.
+const THEME_TEXT_ROLE_FIELDS = Object.freeze({
+  fontSize: Object.freeze({ type: "size", min: 8, max: 96 }),
+  fontWeight: Object.freeze({ type: "enum", values: THEME_TEXT_ROLE_FONT_WEIGHTS }),
+  fontStyle: Object.freeze({ type: "enum", values: THEME_TEXT_ROLE_FONT_STYLES }),
+  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" }),
+  color: Object.freeze({ type: "color" }),
+});
+
 // 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
@@ -4136,7 +4226,20 @@ const CONTRACT = deepFreeze({
   //    where the rail's and the header's keep sc-7965's 1-8 clamp. A backfill
   //    (`20270123000000_sc8033_footer_tokens_uncouple`) materialised what each
   //    workspace was inheriting, so no shipped app moved.
-  version: "1.116.0",
+  // 1.117.0: additive (sc-8058) -- the six SEMANTIC text roles.
+  //    `themeTokens.typography.roles` seeds display / title / subtitle / body /
+  //    caption / overline, and `themeTextRoles` + `themeTextRoleFields` publish
+  //    the tier names and the per-role token vocabulary (each field's type and
+  //    bounds) a TENANT may override -- the single source the Studio control,
+  //    the Mason `set_theme` coercion and the docs read, exactly as
+  //    `themeComponents` already is. Typography carried two faces and a size
+  //    scale and nothing else, so every widget drawing a "subtitle" invented its
+  //    own literal and no theme edit could move them together. Which FACE a role
+  //    takes is deliberately absent -- that is structural (`ROLE_FACES` in the
+  //    hosts' shared textStyle module), not a theme token. Additive: no export
+  //    changed signature, and a theme carrying no `roles` renders on the seeded
+  //    defaults exactly as before.
+  version: "1.117.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -4152,6 +4255,8 @@ const CONTRACT = deepFreeze({
   themeComponentShadows: THEME_COMPONENT_SHADOWS,
   themeComponentTextTransforms: THEME_COMPONENT_TEXT_TRANSFORMS,
   themeComponentGradient: THEME_COMPONENT_GRADIENT,
+  themeTextRoles: THEME_TEXT_ROLES,
+  themeTextRoleFields: THEME_TEXT_ROLE_FIELDS,
   themeSpacingScale: THEME_SPACING_SCALE,
   themeMenuTypes: THEME_MENU_TYPES,
   themeWidgetStyles: THEME_WIDGET_STYLES,

package/dist/theme-background.cjs

@@ -75,7 +75,7 @@ function normaliseImageUrl(raw) {
 
 // A single tint laid over the image. Alpha lives in the 8-digit hex, so the
 // author controls opacity with the colour itself rather than a second field —
-// the same way `siteHeader.backgroundColor` already floats a header.
+// the same way `siteHeader.backgroundColor` already tints a header.
 function normaliseOverlay(raw) {
   return hexOrNull(raw);
 }

package/dist/theme-background.js

@@ -67,7 +67,7 @@ function normaliseImageUrl(raw) {
 
 // A single tint laid over the image. Alpha lives in the 8-digit hex, so the
 // author controls opacity with the colour itself rather than a second field —
-// the same way `siteHeader.backgroundColor` already floats a header.
+// the same way `siteHeader.backgroundColor` already tints a header.
 function normaliseOverlay(raw) {
   return hexOrNull(raw);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.148.0",
+  "version": "0.149.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",