@colixsystems/widget-sdk 0.71.0 → 0.73.0

package/README.md

@@ -54,7 +54,7 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`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**.
+`v0.73.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
 
@@ -170,6 +170,10 @@ useEffect(() => {
 
 **New linter rule `react-not-imported` — widget source must be self-contained (sc-2353).** The automatic JSX runtime binds `jsx`/`jsxs` from `react/jsx-runtime` but never `React` itself, so source that reaches for the bare `React` global (`React.createElement` / `React.Fragment` / `React.memo` / `React.useMemo`) without importing it bundles cleanly, then throws `ReferenceError: React is not defined` the moment a non-initial code path hits the reference. The platform does **not** inject a `React` binding — earlier behaviour that auto-injected one left source that broke as soon as it was downloaded and re-uploaded through a path that doesn't inject. The linter now flags a bare-`React` reference with no `import React from "react"` (or `import * as React`) as an error, so the failure becomes a publish/upload finding (and an AI-agent repair-loop finding) instead of a broken shipped widget. Plain JSX, which needs no React import, is never flagged; a `React` mention inside a comment or string is masked. Author fix: add `import React from "react";` (`react` is already vetted), or prefer a JSX fragment `<>…</>` plus the SDK hooks/primitives over reaching for `React` directly. `CONTRACT` is unchanged (no new field).
 
+### What's new in 0.73.0
+
+**`secrets` is now listed in `CONTRACT.actionScriptGlobals`.** The action runner has always exposed a frozen `secrets` object to server-action scripts — the tenant's stored key/value configuration, read as `secrets["STRIPE_API_KEY"]` (REQ-ACTION-SECRET) — but the contract never listed it, so the Developer guide and the AI widget agent's prompt, both of which derive their globals list from this array, never told an author it existed. That omission is why generated scripts inline a plaintext credential instead of reading one. **Never put an API key, token, or password in `scriptSource`** — a manifest is distributed with the widget, so a literal credential is published with it. Name the key, read it from `secrets`, and fail loudly when it is missing; the workspace operator supplies the value in the Studio. `CONTRACT.version` → `1.50.0`. Documentation-only against the runtime — the global was already there — but additive to the published contract, so it moves the minor.
+
 ### What's new in 0.54.0
 
 **Generate & save PDFs from a widget (sc-2314).** New `usePdfExport({ spaceType, folderId? })` hook. `exportToPdf(html, { fileName?, folderId? })` renders the HTML to a PDF **server-side** (the platform's headless-Chromium pipeline) and saves it into the end-user's Filestore via `ctx.filestore.files.exportPdf`, resolving to the created file row (`application/pdf`). It reuses the filestore owner_id resolution + per-folder write gate and the existing `files.write:*` scope. Because the rendering is server-side, the capability behaves identically on the web Player and the native Expo export — no browser-only PDF library is added to the vetted set. Pairs with `@colixsystems/filestore-client@0.6.0`'s new `files.exportPdf(...)`. `CONTRACT.version` → `1.38.0`. Additive — no existing hook, primitive, manifest field, or token changed shape.
@@ -432,7 +436,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,11 +566,12 @@ 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.
-- **Compose forms — pair fields into rows, don't stack one per row.** Put short, related fields side by side (first + last name, city + postal code, expiry + CVC): a row of `{ flexDirection: 'row', flexWrap: 'wrap', gap: theme.spacing.md }` with each field cell `{ flexGrow: 1, flexBasis: 160 }` splits the width on a wide card and wraps to stacked on a narrow phone — the native-safe way to go multi-column (widgets have no breakpoint hook, so never hard-code fixed columns). Keep wide fields (email, address, notes) full-width, cap it at two–three per row, group a long form into labelled sections, and label every input above it (not placeholder-only).
+- **Size to your container — measure it, don't stretch into it.** The same widget sits in a full-width desktop section (~1400px), a half-width grid cell (~700px) and a phone (~360px), so layout built only from `flex: 1` stretches to fill whatever it is handed — a month calendar ends up with 200px day cells and swallows the page. Measure your own width with `onLayout={(e) => setWidth(e.nativeEvent.layout.width)}` on the root `View` (a React Native primitive, so it behaves identically on both hosts), render nothing size-dependent while `width === 0`, and compute every threshold from the measured value: a widget gets no declared breakpoint prop, but it can always measure. **Cap a repeating cell** rather than giving a grid `flex: 1` — `const cell = Math.max(32, Math.min(Math.floor((usable - gap * (columns - 1)) / columns), 64));`, with a calendar day cell topping out at 56–72px on `aspectRatio: 1`, and the grid given its exact computed width plus `alignSelf: 'center'` when the cap leaves slack. **Split two co-equal surfaces above ~720px measured width** (`flexDirection: width >= 720 ? 'row' : 'column'`, each half `{ flex: 1, minWidth: 0 }`) — a picker beside the form it feeds on a wide canvas, stacked in reading order below it. Never hardcode a width, never put `flex: 1` / `height: '100%'` on a content widget's root, and don't read the screen with `Dimensions` — the screen is not the widget.
+- **Compose forms — pair fields into rows, don't stack one per row.** Put short, related fields side by side (first + last name, city + postal code, expiry + CVC): a row of `{ flexDirection: 'row', flexWrap: 'wrap', gap: theme.spacing.md }` with each field cell `{ flexGrow: 1, flexBasis: 160 }` splits the width on a wide card and wraps to stacked on a narrow phone — the right recipe for field pairs because it needs no measurement (a fixed-width column overflows a phone; when a layout needs a real column count instead of wrapping, measure your width as above). Keep wide fields (email, address, notes) full-width, cap it at two–three per row, group a long form into labelled sections, and label every input above it (not placeholder-only).
 - **Respond to touch.** Give every `Pressable` a pressed state via the function-style `style={({ pressed }) => [base, pressed && { opacity: 0.7 }]}`.
 - **Drag and drop — show what is being dragged.** A drag where the item stays put reads as broken. Three things change the moment a drag starts: the **drag proxy** (the item lifts and follows the finger — `...theme.elevation.lg`, `{ scale: 1.03 }`, `opacity: 0.9`; for a tall or full-width item drag a compact `primarySoft` pill with its icon + one line of label instead), the **source placeholder** (the vacated slot keeps its height as a quiet `colors.surfaceMuted` block so the list doesn't collapse), and the **drop target** (one slot at a time highlighted with `primarySoft` or a 2px `colors.primary` border). Always animate the release — settle into the new slot, or `Animated.spring(pan, { toValue: { x: 0, y: 0 }, useNativeDriver: false })` back to the origin on cancel. Build it with `Animated` + `PanResponder` from `react-native` (the only mechanism that behaves identically on both hosts) — never HTML5 drag events (`draggable` / `onDragStart` / `dataTransfer` are web-only, and `document` / `window` are banned) — and start the drag from a `GripVertical` grip handle whenever the row is also tappable or sits in a `ScrollView`.
 - **Use icons for clarity.** Pair a `lucide-react-native` icon with its label at a consistent size, coloured from the theme. The label never repeats the icon as a character — with a `Plus` icon the button says "Add item", never "+ Add item" (that renders a doubled plus).

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
@@ -1116,6 +1120,7 @@ const ACTION_TRIGGER_TYPES = [
 // linter does NOT scan action scripts.
 const ACTION_SCRIPT_GLOBALS = [
   "datastore",
+  "secrets",
   "fetch",
   "connectors",
   "console",
@@ -2245,7 +2250,23 @@ 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.
+  // 1.50.0: additive — `secrets` joins `actionScriptGlobals`. The action
+  //    runner has always frozen the tenant's resolved key/value config onto
+  //    the sandbox as `secrets` (REQ-ACTION-SECRET), but the contract never
+  //    listed it, so the Developer guide and the agent prompt — both derived
+  //    from this list — never told an author it existed. That omission is why
+  //    a generated script inlines a plaintext credential instead of reading
+  //    `secrets["KEY"]`. No runtime change; the global was already there.
+  version: "1.50.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
@@ -1116,6 +1120,7 @@ const ACTION_TRIGGER_TYPES = [
 // linter does NOT scan action scripts.
 const ACTION_SCRIPT_GLOBALS = [
   "datastore",
+  "secrets",
   "fetch",
   "connectors",
   "console",
@@ -2245,7 +2250,23 @@ 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.
+  // 1.50.0: additive — `secrets` joins `actionScriptGlobals`. The action
+  //    runner has always frozen the tenant's resolved key/value config onto
+  //    the sandbox as `secrets` (REQ-ACTION-SECRET), but the contract never
+  //    listed it, so the Developer guide and the agent prompt — both derived
+  //    from this list — never told an author it existed. That omission is why
+  //    a generated script inlines a plaintext credential instead of reading
+  //    `secrets["KEY"]`. No runtime change; the global was already there.
+  version: "1.50.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.73.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",