@colixsystems/widget-sdk 0.170.0 → 0.173.1

package/README.md

@@ -25,7 +25,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **CORE** | `useRouteParams()` | `{ [paramKey]: value }` | `ctx.navigation.currentRoute.params` — no scope. The nav params the previous page passed via `goTo(pageId, params)`; the flat accessor for master→detail (read `recordId` on a detail page). Empty object when none. |
 | **CORE** | `usePageContext()` | `{ params, records }` | `ctx.pageContext` — no scope. The page's DECLARED parameters, resolved once by the host: `params` are coerced to their declared types, `records` holds the row already fetched for each `record` param (read it instead of fetching again). Both empty when the page declares none. |
 | **CORE** | `useWidgetRoute(initial)` | `[state, setState]` | `ctx.widgetRoute` — no scope. Where YOUR WIDGET is, persisted by the host so it survives a reload and travels in a shared link (the `w_<instanceId>` query key on web, the screen's route params natively): the folder a browser has opened, a wizard step, a selected tab, a list's sort and search. `useState` semantics over an object — writes MERGE, `null` clears a key back to its `initial`, and `initial` is read once. Values are scalars or flat arrays of scalars, size- and length-capped; anything else is not stored. NOT history (Back still leaves the page, on both platforms). Degrades to component state on the Studio canvas. |
-| **CORE** | `useWidgetEvent(name)` | `(payload?) => void` | `ctx.events.emit` — no scope. The hook IS the emitter: `const emitSlot = useWidgetEvent("slotChosen")`, then `emitSlot(payload)`. Never destructure the result — there is no `emit` member. |
+| **CORE** | `useWidgetEvent(name)` | `(payload?) => void` | `ctx.events.emit` — no scope. The hook IS the emitter: `const emitSlot = useWidgetEvent("slotChosen")`, then `emitSlot(payload)`. Never destructure the result — there is no `emit` member. A sibling's input reads the payload, and a page action the author binds to the event (Run action, Navigate) runs with it — fired from one control, only that control runs it. |
 | **CORE** | `useWidgetInput(inputName)` | the published payload, or `undefined` | `ctx.inputs` — no scope. Reads a value ANOTHER widget on the same page published with `useWidgetEvent`. Declare the input in `manifest.inputs`; the page author wires it to one sibling's declared event. The channel retains the last payload, so a widget that mounts later still reads it. `undefined` while unwired or before the first publish — always render a sensible default. Page-scoped and ephemeral: use `useRouteParams()` for state that must survive navigation, the datastore for state that must persist. |
 | **CORE** | `useChildRenderer()` | `{ renderNode(node) }` | `ctx.renderer` — no scope (prefer the `WidgetTree` component) |
 | **CORE** | `useFill()` | `boolean` | `ctx.fill` — no scope. `true` when the host sized this widget to fill its page-grid tile's reserved height (containers + media fill by default; the author can override per tile). Media-style widgets switch to a `flex: 1` / `height: "100%"` layout; others ignore it. Defaults `false`. |
@@ -73,7 +73,72 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.170.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.173.1` — 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.173.1 (contract 1.134.1)
+
+**An event your widget fires can run a page action, from the one control that fires it.** The author (or Mason) can bind Run action or Navigate to any event your manifest declares, and it runs when `useWidgetEvent` fires it. Fire the event from one control and only that control runs the action:
+
+```jsx
+// manifest: events: [{ name: "onBookPressed", payloadSchema: { classId: { type: "string" } } }]
+const emitBook = useWidgetEvent("onBookPressed");
+<Button title="Book" onPress={() => emitBook({ classId })} />
+```
+
+Never declare your own event as `onPress`: an `onPress` binding makes the whole widget one tap target, so a tap anywhere on it runs the action. Documentation only — both hosts already dispatched a named event's binding.
+
+### What's new in 0.173.0 (contract 1.134.0)
+
+**A `datastoreTemplate` RELATION may name any table in the template.** The installer now creates every table before any column, so `targetSuffix` may point at a table declared later in `tables`, and two tables may relate to each other both ways. A suffix no table in the template has is still rejected at publish. No change is needed to an existing template.
+
+### What's new in 0.172.0 (contract 1.133.0)
+
+**Tables whose rows use their full width, under a header that lines up: `ListHeader`, and a `ListRow` whose `View` child spans the row.** A `ListRow` given its own content used that content as-is, beside `leading` and `trailing` in a horizontal row. So a single row `View` of flex cells shrank to the width of its text and squeezed its cells into the left of the row, while a hand-built header above spread across the full width. A single `View` child now gets the same flexible slot the title block has, spanning the row between `leading` and `trailing`. Anything else (several cells, a component that renders cells, a lone `Text`) sits in the row exactly as before.
+
+`<ListHeader>` labels a table's columns. It takes the same horizontal padding, gap and side edges as `<ListRow>`, from the same Theme Settings > Lists values, so a label given the same `flex` as its row cell sits over that column however the theme changes. A header `View` with its own padding cannot do that.
+
+```jsx
+const label = textRoleStyle("overline", theme.typography, theme.colors);
+const body = textRoleStyle("body", theme.typography, theme.colors);
+<ScrollView style={{ flex: 1 }} stickyHeaderIndices={[0]}>
+  <ListHeader style={{ backgroundColor: theme.colors.surface }}>
+    <Text numberOfLines={1} style={[label, { flex: 2, minWidth: 0 }]}>Customer</Text>
+    <Text numberOfLines={1} style={[label, { flex: 1, minWidth: 0 }]}>Status</Text>
+  </ListHeader>
+  <List>
+    {orders.map((o) => (
+      <ListRow key={o.id} onPress={() => open(o)}>
+        <Text numberOfLines={1} style={[body, { flex: 2, minWidth: 0 }]}>{o.customer}</Text>
+        <Text numberOfLines={1} style={[body, { flex: 1, minWidth: 0 }]}>{o.status}</Text>
+      </ListRow>
+    ))}
+  </List>
+</ScrollView>
+```
+
+Give the header and the rows the same shape: the same cells, the same `flex` per column, and `minWidth: 0` on every cell. Pass the header the same list overrides you pass the `<List>` (`rowPadding`, `gap`, `dividerColor`, `dividerWidth`). Make it the first child of the rows' `ScrollView` with `stickyHeaderIndices={[0]}`: it stays in view, and it shares the rows' width beside a scrollbar, which a header outside the scroller does not. Give it the surface it sits on as its background so rows do not show through. When rows carry a `leading` or `trailing` node, pass the header a spacer of the same width in that slot. A selected row's accent bar now takes its width from the row's inset, so its cells stay under their labels too (unless the widget sets the row's padding through `style`, which is left exactly as it asked).
+
+Installed widgets pick up the row fix with no rebuild on the web: the Player hands every widget the host's own SDK. An exported app picks it up on its next export.
+
+### What's new in 0.171.0 (contract 1.132.0)
+
+**`Badge`, `Avatar`, `Progress`, `Stat` and `Divider` — the small parts a record row is made of.** A custom widget listing records had no themed status pill, avatar or progress bar, so it drew its own and never matched the built-ins. These are now SDK components, and the built-in Badge, Avatar, Progress, Stat and Divider widgets render through them:
+
+```jsx
+<ListRow
+  title={order.title}
+  leading={<Avatar name={order.owner.label} size="sm" />}
+  trailing={<Badge label={order.status} tone={order.status === "Overdue" ? "danger" : "success"} />}
+/>
+```
+
+- **`<Badge>`** is a record's state (Active, Paid, Overdue) beside the thing it describes. `tone` is `neutral` | `info` | `success` | `warning` | `danger`, tinted from the app's theme; the label always shows.
+- **`<Avatar>`** is a person: a picture, else the name's initials, else a person glyph. `size` is `sm` | `md` | `lg` | `xl` or a number of px.
+- **`<Progress>`** is real progress toward a goal, as a `bar` or a `ring`; the percent is clamped to 0-100 and printed.
+- **`<Stat>`** displays a headline figure you computed, with an optional caption, icon and delta. An empty value prints `emptyValue` (default "—"), never a fake 0.
+- **`<Divider>`** splits two groups inside one surface, optionally captioned. A `<List>` and a `<Card>` already draw their own edges.
+
+`initialsFor(name)` is exported too. Additive: the built-in widgets render as before.
 
 ### What's new in 0.170.0 (contract 1.131.0)
 
@@ -1869,7 +1934,8 @@ import { defineWidget, validateManifest, useDatastoreQuery, Text, View } from "@
 - `MarkdownInput` — the authoring half of `<RichText>` (sc-6970). `<MarkdownInput value={draft} onChange={setDraft} />` is a multi-line field, a toolbar whose buttons wrap the current SELECTION in markdown markers (bold, italic, code, H2, H3, bullets, numbered list, each toggling back off), and a live `<RichText>` preview of the result underneath — the way to let an app USER write formatted text, instead of a bare `TextInput` plus hand-rolled buttons that can only splice literal tags into the value. Props: `value`, `onChange(next)`, `placeholder`, `previewLabel` (default `Preview`), `showPreview` (default true), `renderImage` (passed through to the preview), `minHeight` (150) and `maxHeight` (280) so a long draft scrolls inside its box, `accessibilityLabel`, `style`, `testID`.
 - `parseMarkdown`, `markdownToPlainText`, `parseMarkdownImage`, `formatMarkdownImage`, `stripHtmlToMarkdown`, `MARKDOWN_IMAGE_SIZES` — the same grammar as pure helpers, for content you inspect rather than render: the block list, a marker-free projection (list previews, search, a11y labels), the one-line image form read and written, a legacy-HTML row normalised to markdown on read, and the closed size list (`small` | `medium` | `large` | `full`).
 - `isSafeMarkdownImageSrc`, `isHttpImageSrc`, `normaliseMarkdownImageSize`, `readMarkdownAlt` — the image half of that grammar, for a widget rendering images itself via `renderImage`. `isSafeMarkdownImageSrc` is the same allowlist the parser applies (an `http(s)` URL or a filestore id; a `javascript:` scheme is refused), so the widget and the parser cannot disagree about which src is renderable.
-- `List`, `ListRow`, `EmptyState` — the themed list building blocks. `<ListRow title subtitle leading trailing onPress selected divider>` draws one record row from the theme's `list` scope (padding, height, gap, radius, background, divider); `<List>` spaces its rows and hands overrides down; `<EmptyState icon title message>` is the "nothing here" panel. Never hand-roll a row from `View` + `Pressable`.
+- `List`, `ListRow`, `ListHeader`, `EmptyState` — the themed list building blocks. `<ListRow title subtitle leading trailing onPress selected divider>` draws one record row from the theme's `list` scope (padding, height, gap, radius, background, divider); `<List>` spaces its rows and hands overrides down; `<ListHeader>` labels a table's columns on the rows' own inset; `<EmptyState icon title message>` is the "nothing here" panel. Never hand-roll a row or a header row from `View` + `Pressable`.
+- `Badge`, `Avatar`, `Progress`, `Stat`, `Divider` — the themed status pill, person picture, completion bar or ring, headline figure and rule the built-in widgets of the same names render through. Reach for them inside a record row instead of hand-rolling a pill or a circle from `View`.
 - `Card`, `Button`, `TextField` — the themed card surface, button and text field the built-in widgets render through. With no props each takes the app's look from Theme Settings (Cards, Buttons, Muted); never hand-roll one from `View` / `Pressable` / a bare `TextInput`.
 - `Tabs` — the themed tab strip. `<Tabs items value onChange>` draws a segmented control, pills or an underline as the theme's `tabs` scope says; render the selected panel yourself. Never hand-roll tabs from `Pressable` chips.
 - `textRoleStyle(role, typography, colors)`, `TEXT_ROLES` — the style of a semantic text tier, shared with the built-in widgets.

package/dist/contract.cjs

@@ -1558,6 +1558,12 @@ const HOOKS = [
   {
     name: "useWidgetEvent",
     signature: "useWidgetEvent(eventName)",
+    description:
+      "Fires one of the events the manifest declares. The page wires it two " +
+      "ways: a sibling widget's input reads the payload, and an author-bound " +
+      "page action (Run action, Navigate) runs with it. Fire a named event " +
+      "from ONE control to have only that control run the action; an onPress " +
+      "binding instead makes the whole widget the tap target.",
     // sc-4753 — the hook IS the emitter, so its return is declared as a bare
     // callable. Naming an `emit` member here made every derived surface tell
     // authors to destructure a function, which yields undefined at run time.
@@ -2345,7 +2351,14 @@ const PRIMITIVES = [
   {
     name: "ListRow",
     description:
-      'Themed list row. `<ListRow title={item.name} subtitle={item.email} leading={<Icon name="user" size={20} />} trailing={<Text>…</Text>} onPress={() => open(item)} selected={item.id === selectedId} />`. THE way to draw one row of records: its padding, minimum height, divider, corner radius and background come from the theme\'s Lists settings, so every list in the app matches — never hand-roll a row from `View` + `Pressable`. Props: `title`, `subtitle` (rendered in the subtitle / caption text tiers), `leading` / `trailing` nodes, `children` (replaces the title block, for a multi-column row), `onPress` (makes it a button with a press state), `selected`, `disabled`, `divider` (default true; pass false on the last row), `accessibilityLabel`, `style`, `testID`, plus the same per-row overrides `<List>` takes. Declare `listRowPadding` / `listRowRadius` / … style fields and pass them through to let an author override one widget.',
+      'Themed list row. `<ListRow title={item.name} subtitle={item.email} leading={<Icon name="user" size={20} />} trailing={<Text>…</Text>} onPress={() => open(item)} selected={item.id === selectedId} />`. THE way to draw one row of records: its padding, minimum height, divider, corner radius and background come from the theme\'s Lists settings, so every list in the app matches — never hand-roll a row from `View` + `Pressable`. Props: `title`, `subtitle` (rendered in the subtitle / caption text tiers), `leading` / `trailing` nodes, `children` (replaces the title block: a single `View` child — your own row of cells — spans the full width between `leading` and `trailing`; anything else, such as several cells, sits in the row as given, which is the shape a table row takes under a `<ListHeader>`), `onPress` (makes it a button with a press state), `selected`, `disabled`, `divider` (default true; pass false on the last row), `accessibilityLabel`, `style`, `testID`, plus the same per-row overrides `<List>` takes. Declare `listRowPadding` / `listRowRadius` / … style fields and pass them through to let an author override one widget.',
+    rnComponent: null,
+    docsUrl: null,
+  },
+  {
+    name: "ListHeader",
+    description:
+      "Themed column header for a table of `<ListRow>`s. `<ListHeader><Text style={[overline, { flex: 2, minWidth: 0 }]}>Name</Text><Text style={[overline, { flex: 1, minWidth: 0 }]}>Status</Text></ListHeader>` above `<List>{rows.map((r) => <ListRow key={r.id}><Text numberOfLines={1} style={[body, { flex: 2, minWidth: 0 }]}>{r.name}</Text><Text numberOfLines={1} style={[body, { flex: 1, minWidth: 0 }]}>{r.status}</Text></ListRow>)}</List>`. THE way to label a table's columns: it takes the SAME horizontal padding, gap and side edges as `<ListRow>` from the theme's Lists settings, so a label given the same `flex` as its row cell sits exactly over that column — never hand-build a header `View` with its own padding, which cannot line up with the rows. Give the header and the rows the same shape (the same cells as children, each column the same `flex`, `minWidth: 0` on every cell). Props: `children` (the labels), `leading` / `trailing` (a spacer as wide as the rows' leading / trailing node, so the columns still line up), `divider` (default true), `accessibilityLabel`, `style`, `testID`, and the list overrides that shape it (`rowPadding`, `gap`, `dividerColor`, `dividerWidth`) — pass it the SAME overrides you pass the `<List>`. To keep it in view, make it the FIRST child of the rows' `ScrollView` with `stickyHeaderIndices={[0]}`, and give it the surface it sits on (`style={{ backgroundColor: theme.colors.surface }}`) so rows do not show through it: inside the scroller it shares the rows' width beside a scrollbar, which a header outside it cannot.",
     rnComponent: null,
     docsUrl: null,
   },
@@ -2356,6 +2369,41 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  {
+    name: "Badge",
+    description:
+      'Themed status pill. `<Badge label={row.status} tone={row.status === "Overdue" ? "danger" : "success"} />`. THE way to show a record\'s STATE (Active, Paid, Overdue, New) beside the thing it describes: in a `<ListRow>` trailing slot, next to a title, in a detail header. The label always renders, so the meaning never rides on colour alone. Keep it to one to three words; a name, amount, date or sentence is plain text, not a badge. Its fill and text colour come from the app\'s theme per tone, so never hand-roll a pill from `View` + radius + a hex. Props: `label` (string or number), `tone` ("neutral" | "info" | "success" | "warning" | "danger", default "neutral"), `icon` (optional lucide name before the label), `style`, `testID`. It hugs its label (`alignSelf: "flex-start"`); pass `style={{ alignSelf: "auto" }}` to let the parent place it.',
+    rnComponent: null,
+    docsUrl: null,
+  },
+  {
+    name: "Avatar",
+    description:
+      'Themed picture of a person. `<Avatar name={row.owner.label} url={photoUrl} size="sm" />`. THE way to show a PERSON: in a `<ListRow>` leading slot, a profile header, a list of members. It falls back from the picture to the name\'s initials to a person glyph, so the slot is never blank. Never use it for a place, product or topic. Props: `name` (the initials and the accessibility label come from it), `url` (an absolute image URL; resolve a file field to a URL first), `size` ("sm" 32 | "md" 40 | "lg" 56 | "xl" 80, or a number of px), `shape` ("circle" | "rounded"), `accessibilityLabel`, `style`, `testID`.',
+    rnComponent: null,
+    docsUrl: null,
+  },
+  {
+    name: "Progress",
+    description:
+      'Themed completion bar or ring. `<Progress value={(done / total) * 100} label="Sessions booked" />`. THE way to show real progress toward a known goal. `value` is clamped to 0-100, and the percent renders as text unless `showValue={false}`. Never decoration, a rating or a score. Props: `value`, `variant` ("bar" | "ring", default "bar"), `label`, `showValue` (default true), `tone` ("primary" | "success" | "warning" | "danger", default "primary"), `style`, `testID`.',
+    rnComponent: null,
+    docsUrl: null,
+  },
+  {
+    name: "Stat",
+    description:
+      'Themed headline figure. `<Stat value={openCount} label="Open orders" delta="+3 this week" deltaTone="positive" icon="package" />`. THE way to show one headline number in a summary tile; put peer tiles side by side in a row. It only DISPLAYS a figure, so compute it yourself (e.g. from `useDatastoreQuery` rows). An empty value (null, undefined, blank text, NaN) prints `emptyValue` (default "—") in the muted tier, never a fake 0. Props: `value` (string or number), `label`, `icon` (lucide name), `delta`, `deltaTone` ("neutral" | "positive" | "negative"), `emptyValue`, `color` and `fontSize` (12-96) for the figure, `style`, `testID`.',
+    rnComponent: null,
+    docsUrl: null,
+  },
+  {
+    name: "Divider",
+    description:
+      'Themed rule. `<Divider />`, or `<Divider label="or" />` for a captioned one. It splits two groups INSIDE one surface that nothing else separates: a card\'s summary from its details, or two alternatives. A `<List>` already draws its own row dividers and a `<Card>` its own edge, so never add one between rows or around a card. Props: `label` (optional caption centred in the rule), `thickness` (1-8 px), `spacing` ("sm" | "md" | "lg" breathing room), `color` (defaults to the theme border), `style`, `testID`.',
+    rnComponent: null,
+    docsUrl: null,
+  },
   {
     name: "Tabs",
     description:
@@ -2591,7 +2639,10 @@ const MANIFEST_SCHEMA = {
       "{ type, label? } — the SAME shape as propertySchema, NOT JSON Schema — " +
       "where type is one of string, number, boolean, object, array. The payload reaches " +
       "any sibling widget on the page whose inputs entry the page author wired " +
-      "to this event.",
+      "to this event. An event can also run a page action the author binds to " +
+      "it (Run action, Navigate): fired from one control with useWidgetEvent, " +
+      "only that control runs the action. Never declare it as onPress, which " +
+      "the host binds as a tap target over the whole widget.",
     default: [],
   },
   inputs: {
@@ -2610,7 +2661,7 @@ const MANIFEST_SCHEMA = {
     type: "object",
     required: false,
     description:
-      "Optional. Tables the widget needs, seeded into the workspace at install time. Authors wire them into the widget's `tableRef` properties via the Properties Panel — the SDK does not auto-bind. Limits: 8 tables, 24 columns per table. RELATION columns address siblings by `targetSuffix` (must be declared earlier in the array). Tables persist across uninstalls. A `tableRef` property may also carry `sharedTable: true`, declaring that the table is the APP'S OWN — the author picks an existing table and the widget seeds nothing for it. That is the correct shape for a widget that reads data it does not own (a chart, a metric, a manager view over another widget's table). `sharedTable` exempts the property from needing a seeded table at publish (`manifest.requiredTableRefsHaveTemplate`) WITHOUT making it optional: the author must still bind one, and the host still refuses to place the widget unbound. Use it instead of dropping `required` — a widget that silently renders an empty tile is the defect it looks like a fix for. sc-7530: a table may also declare `roleGrants` — group-scoped access named SYMBOLICALLY, because a group id belongs to the workspace that installs the widget and could never travel in the manifest. Declare the audiences once at template level as `roles: [{ key, label, description? }]` (key is lowercase kebab, max 8 roles), then per table `roleGrants: [{ role, canRead?, canWrite?, canDelete? }]`. The installing workspace binds each role to one of its own user groups (or has one created) during the install consent step, so a permission model where an admin group does everything and signed-in users only read survives the trip between workspaces. Use `publicGrant` for the two id-less audiences (everyone / any signed-in user) and `roleGrants` for anything that names a group. A role nobody binds simply writes no grant — it never fails the install. sc-7557: a column may declare `encrypted: true` — its values are stored AES-256-GCM encrypted at rest under a per-workspace subkey. The widget still reads and writes PLAINTEXT (the platform encrypts on write, decrypts for end users); studio users see `🔒` instead, and the column cannot be searched, filtered or sorted on. Sample `rows` you seed for it are encrypted the same way. Not valid on `RELATION` — its value is a foreign key the backend must resolve — and publishing one is rejected.",
+      "Optional. Tables the widget needs, seeded into the workspace at install time. Authors wire them into the widget's `tableRef` properties via the Properties Panel — the SDK does not auto-bind. Limits: 8 tables, 24 columns per table. RELATION columns address siblings by `targetSuffix` (any table in the same array, in any order; tables may relate to each other both ways). Tables persist across uninstalls. A `tableRef` property may also carry `sharedTable: true`, declaring that the table is the APP'S OWN — the author picks an existing table and the widget seeds nothing for it. That is the correct shape for a widget that reads data it does not own (a chart, a metric, a manager view over another widget's table). `sharedTable` exempts the property from needing a seeded table at publish (`manifest.requiredTableRefsHaveTemplate`) WITHOUT making it optional: the author must still bind one, and the host still refuses to place the widget unbound. Use it instead of dropping `required` — a widget that silently renders an empty tile is the defect it looks like a fix for. sc-7530: a table may also declare `roleGrants` — group-scoped access named SYMBOLICALLY, because a group id belongs to the workspace that installs the widget and could never travel in the manifest. Declare the audiences once at template level as `roles: [{ key, label, description? }]` (key is lowercase kebab, max 8 roles), then per table `roleGrants: [{ role, canRead?, canWrite?, canDelete? }]`. The installing workspace binds each role to one of its own user groups (or has one created) during the install consent step, so a permission model where an admin group does everything and signed-in users only read survives the trip between workspaces. Use `publicGrant` for the two id-less audiences (everyone / any signed-in user) and `roleGrants` for anything that names a group. A role nobody binds simply writes no grant — it never fails the install. sc-7557: a column may declare `encrypted: true` — its values are stored AES-256-GCM encrypted at rest under a per-workspace subkey. The widget still reads and writes PLAINTEXT (the platform encrypts on write, decrypts for end users); studio users see `🔒` instead, and the column cannot be searched, filtered or sorted on. Sample `rows` you seed for it are encrypted the same way. Not valid on `RELATION` — its value is a foreign key the backend must resolve — and publishing one is rejected.",
   },
   translations: {
     type: "object",
@@ -4613,7 +4664,14 @@ const CONTRACT = deepFreeze({
   //    parameters a Run action event sent (the binding's `params` merged over
   //    the emitting widget's payload), deep-frozen, null on every non-`app`
   //    trigger. Additive: a script that never reads it runs unchanged.
-  version: "1.131.0",
+  // 1.132.0: additive (sc-9086) — the `Badge`, `Avatar`, `Progress`, `Stat`
+  // and `Divider` primitives. The stock widgets of the same names render
+  // through them, so a custom widget's status pill matches a built-in's.
+  // 1.133.0: additive (sc-9002) — `ListHeader` (column labels on `ListRow`'s frame);
+  //    a `ListRow`'s lone `View` child spans the row; a selected row's bar
+  //    no longer shifts its content. Other rows render as before.
+  // 1.134.1: docs (sc-9122) — an emitted event can run a bound action.
+  version: "1.134.1",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -1558,6 +1558,12 @@ const HOOKS = [
   {
     name: "useWidgetEvent",
     signature: "useWidgetEvent(eventName)",
+    description:
+      "Fires one of the events the manifest declares. The page wires it two " +
+      "ways: a sibling widget's input reads the payload, and an author-bound " +
+      "page action (Run action, Navigate) runs with it. Fire a named event " +
+      "from ONE control to have only that control run the action; an onPress " +
+      "binding instead makes the whole widget the tap target.",
     // sc-4753 — the hook IS the emitter, so its return is declared as a bare
     // callable. Naming an `emit` member here made every derived surface tell
     // authors to destructure a function, which yields undefined at run time.
@@ -2345,7 +2351,14 @@ const PRIMITIVES = [
   {
     name: "ListRow",
     description:
-      'Themed list row. `<ListRow title={item.name} subtitle={item.email} leading={<Icon name="user" size={20} />} trailing={<Text>…</Text>} onPress={() => open(item)} selected={item.id === selectedId} />`. THE way to draw one row of records: its padding, minimum height, divider, corner radius and background come from the theme\'s Lists settings, so every list in the app matches — never hand-roll a row from `View` + `Pressable`. Props: `title`, `subtitle` (rendered in the subtitle / caption text tiers), `leading` / `trailing` nodes, `children` (replaces the title block, for a multi-column row), `onPress` (makes it a button with a press state), `selected`, `disabled`, `divider` (default true; pass false on the last row), `accessibilityLabel`, `style`, `testID`, plus the same per-row overrides `<List>` takes. Declare `listRowPadding` / `listRowRadius` / … style fields and pass them through to let an author override one widget.',
+      'Themed list row. `<ListRow title={item.name} subtitle={item.email} leading={<Icon name="user" size={20} />} trailing={<Text>…</Text>} onPress={() => open(item)} selected={item.id === selectedId} />`. THE way to draw one row of records: its padding, minimum height, divider, corner radius and background come from the theme\'s Lists settings, so every list in the app matches — never hand-roll a row from `View` + `Pressable`. Props: `title`, `subtitle` (rendered in the subtitle / caption text tiers), `leading` / `trailing` nodes, `children` (replaces the title block: a single `View` child — your own row of cells — spans the full width between `leading` and `trailing`; anything else, such as several cells, sits in the row as given, which is the shape a table row takes under a `<ListHeader>`), `onPress` (makes it a button with a press state), `selected`, `disabled`, `divider` (default true; pass false on the last row), `accessibilityLabel`, `style`, `testID`, plus the same per-row overrides `<List>` takes. Declare `listRowPadding` / `listRowRadius` / … style fields and pass them through to let an author override one widget.',
+    rnComponent: null,
+    docsUrl: null,
+  },
+  {
+    name: "ListHeader",
+    description:
+      "Themed column header for a table of `<ListRow>`s. `<ListHeader><Text style={[overline, { flex: 2, minWidth: 0 }]}>Name</Text><Text style={[overline, { flex: 1, minWidth: 0 }]}>Status</Text></ListHeader>` above `<List>{rows.map((r) => <ListRow key={r.id}><Text numberOfLines={1} style={[body, { flex: 2, minWidth: 0 }]}>{r.name}</Text><Text numberOfLines={1} style={[body, { flex: 1, minWidth: 0 }]}>{r.status}</Text></ListRow>)}</List>`. THE way to label a table's columns: it takes the SAME horizontal padding, gap and side edges as `<ListRow>` from the theme's Lists settings, so a label given the same `flex` as its row cell sits exactly over that column — never hand-build a header `View` with its own padding, which cannot line up with the rows. Give the header and the rows the same shape (the same cells as children, each column the same `flex`, `minWidth: 0` on every cell). Props: `children` (the labels), `leading` / `trailing` (a spacer as wide as the rows' leading / trailing node, so the columns still line up), `divider` (default true), `accessibilityLabel`, `style`, `testID`, and the list overrides that shape it (`rowPadding`, `gap`, `dividerColor`, `dividerWidth`) — pass it the SAME overrides you pass the `<List>`. To keep it in view, make it the FIRST child of the rows' `ScrollView` with `stickyHeaderIndices={[0]}`, and give it the surface it sits on (`style={{ backgroundColor: theme.colors.surface }}`) so rows do not show through it: inside the scroller it shares the rows' width beside a scrollbar, which a header outside it cannot.",
     rnComponent: null,
     docsUrl: null,
   },
@@ -2356,6 +2369,41 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  {
+    name: "Badge",
+    description:
+      'Themed status pill. `<Badge label={row.status} tone={row.status === "Overdue" ? "danger" : "success"} />`. THE way to show a record\'s STATE (Active, Paid, Overdue, New) beside the thing it describes: in a `<ListRow>` trailing slot, next to a title, in a detail header. The label always renders, so the meaning never rides on colour alone. Keep it to one to three words; a name, amount, date or sentence is plain text, not a badge. Its fill and text colour come from the app\'s theme per tone, so never hand-roll a pill from `View` + radius + a hex. Props: `label` (string or number), `tone` ("neutral" | "info" | "success" | "warning" | "danger", default "neutral"), `icon` (optional lucide name before the label), `style`, `testID`. It hugs its label (`alignSelf: "flex-start"`); pass `style={{ alignSelf: "auto" }}` to let the parent place it.',
+    rnComponent: null,
+    docsUrl: null,
+  },
+  {
+    name: "Avatar",
+    description:
+      'Themed picture of a person. `<Avatar name={row.owner.label} url={photoUrl} size="sm" />`. THE way to show a PERSON: in a `<ListRow>` leading slot, a profile header, a list of members. It falls back from the picture to the name\'s initials to a person glyph, so the slot is never blank. Never use it for a place, product or topic. Props: `name` (the initials and the accessibility label come from it), `url` (an absolute image URL; resolve a file field to a URL first), `size` ("sm" 32 | "md" 40 | "lg" 56 | "xl" 80, or a number of px), `shape` ("circle" | "rounded"), `accessibilityLabel`, `style`, `testID`.',
+    rnComponent: null,
+    docsUrl: null,
+  },
+  {
+    name: "Progress",
+    description:
+      'Themed completion bar or ring. `<Progress value={(done / total) * 100} label="Sessions booked" />`. THE way to show real progress toward a known goal. `value` is clamped to 0-100, and the percent renders as text unless `showValue={false}`. Never decoration, a rating or a score. Props: `value`, `variant` ("bar" | "ring", default "bar"), `label`, `showValue` (default true), `tone` ("primary" | "success" | "warning" | "danger", default "primary"), `style`, `testID`.',
+    rnComponent: null,
+    docsUrl: null,
+  },
+  {
+    name: "Stat",
+    description:
+      'Themed headline figure. `<Stat value={openCount} label="Open orders" delta="+3 this week" deltaTone="positive" icon="package" />`. THE way to show one headline number in a summary tile; put peer tiles side by side in a row. It only DISPLAYS a figure, so compute it yourself (e.g. from `useDatastoreQuery` rows). An empty value (null, undefined, blank text, NaN) prints `emptyValue` (default "—") in the muted tier, never a fake 0. Props: `value` (string or number), `label`, `icon` (lucide name), `delta`, `deltaTone` ("neutral" | "positive" | "negative"), `emptyValue`, `color` and `fontSize` (12-96) for the figure, `style`, `testID`.',
+    rnComponent: null,
+    docsUrl: null,
+  },
+  {
+    name: "Divider",
+    description:
+      'Themed rule. `<Divider />`, or `<Divider label="or" />` for a captioned one. It splits two groups INSIDE one surface that nothing else separates: a card\'s summary from its details, or two alternatives. A `<List>` already draws its own row dividers and a `<Card>` its own edge, so never add one between rows or around a card. Props: `label` (optional caption centred in the rule), `thickness` (1-8 px), `spacing` ("sm" | "md" | "lg" breathing room), `color` (defaults to the theme border), `style`, `testID`.',
+    rnComponent: null,
+    docsUrl: null,
+  },
   {
     name: "Tabs",
     description:
@@ -2587,7 +2635,10 @@ const MANIFEST_SCHEMA = {
       "{ type, label? } — the SAME shape as propertySchema, NOT JSON Schema — " +
       "where type is one of string, number, boolean, object, array. The payload reaches " +
       "any sibling widget on the page whose inputs entry the page author wired " +
-      "to this event.",
+      "to this event. An event can also run a page action the author binds to " +
+      "it (Run action, Navigate): fired from one control with useWidgetEvent, " +
+      "only that control runs the action. Never declare it as onPress, which " +
+      "the host binds as a tap target over the whole widget.",
     default: [],
   },
   inputs: {
@@ -2606,7 +2657,7 @@ const MANIFEST_SCHEMA = {
     type: "object",
     required: false,
     description:
-      "Optional. Tables the widget needs, seeded into the workspace at install time. Authors wire them into the widget's `tableRef` properties via the Properties Panel — the SDK does not auto-bind. Limits: 8 tables, 24 columns per table. RELATION columns address siblings by `targetSuffix` (must be declared earlier in the array). Tables persist across uninstalls. A `tableRef` property may also carry `sharedTable: true`, declaring that the table is the APP'S OWN — the author picks an existing table and the widget seeds nothing for it. That is the correct shape for a widget that reads data it does not own (a chart, a metric, a manager view over another widget's table). `sharedTable` exempts the property from needing a seeded table at publish (`manifest.requiredTableRefsHaveTemplate`) WITHOUT making it optional: the author must still bind one, and the host still refuses to place the widget unbound. Use it instead of dropping `required` — a widget that silently renders an empty tile is the defect it looks like a fix for. sc-7530: a table may also declare `roleGrants` — group-scoped access named SYMBOLICALLY, because a group id belongs to the workspace that installs the widget and could never travel in the manifest. Declare the audiences once at template level as `roles: [{ key, label, description? }]` (key is lowercase kebab, max 8 roles), then per table `roleGrants: [{ role, canRead?, canWrite?, canDelete? }]`. The installing workspace binds each role to one of its own user groups (or has one created) during the install consent step, so a permission model where an admin group does everything and signed-in users only read survives the trip between workspaces. Use `publicGrant` for the two id-less audiences (everyone / any signed-in user) and `roleGrants` for anything that names a group. A role nobody binds simply writes no grant — it never fails the install. sc-7557: a column may declare `encrypted: true` — its values are stored AES-256-GCM encrypted at rest under a per-workspace subkey. The widget still reads and writes PLAINTEXT (the platform encrypts on write, decrypts for end users); studio users see `🔒` instead, and the column cannot be searched, filtered or sorted on. Sample `rows` you seed for it are encrypted the same way. Not valid on `RELATION` — its value is a foreign key the backend must resolve — and publishing one is rejected.",
+      "Optional. Tables the widget needs, seeded into the workspace at install time. Authors wire them into the widget's `tableRef` properties via the Properties Panel — the SDK does not auto-bind. Limits: 8 tables, 24 columns per table. RELATION columns address siblings by `targetSuffix` (any table in the same array, in any order; tables may relate to each other both ways). Tables persist across uninstalls. A `tableRef` property may also carry `sharedTable: true`, declaring that the table is the APP'S OWN — the author picks an existing table and the widget seeds nothing for it. That is the correct shape for a widget that reads data it does not own (a chart, a metric, a manager view over another widget's table). `sharedTable` exempts the property from needing a seeded table at publish (`manifest.requiredTableRefsHaveTemplate`) WITHOUT making it optional: the author must still bind one, and the host still refuses to place the widget unbound. Use it instead of dropping `required` — a widget that silently renders an empty tile is the defect it looks like a fix for. sc-7530: a table may also declare `roleGrants` — group-scoped access named SYMBOLICALLY, because a group id belongs to the workspace that installs the widget and could never travel in the manifest. Declare the audiences once at template level as `roles: [{ key, label, description? }]` (key is lowercase kebab, max 8 roles), then per table `roleGrants: [{ role, canRead?, canWrite?, canDelete? }]`. The installing workspace binds each role to one of its own user groups (or has one created) during the install consent step, so a permission model where an admin group does everything and signed-in users only read survives the trip between workspaces. Use `publicGrant` for the two id-less audiences (everyone / any signed-in user) and `roleGrants` for anything that names a group. A role nobody binds simply writes no grant — it never fails the install. sc-7557: a column may declare `encrypted: true` — its values are stored AES-256-GCM encrypted at rest under a per-workspace subkey. The widget still reads and writes PLAINTEXT (the platform encrypts on write, decrypts for end users); studio users see `🔒` instead, and the column cannot be searched, filtered or sorted on. Sample `rows` you seed for it are encrypted the same way. Not valid on `RELATION` — its value is a foreign key the backend must resolve — and publishing one is rejected.",
   },
   translations: {
     type: "object",
@@ -4609,7 +4660,14 @@ const CONTRACT = deepFreeze({
   //    parameters a Run action event sent (the binding's `params` merged over
   //    the emitting widget's payload), deep-frozen, null on every non-`app`
   //    trigger. Additive: a script that never reads it runs unchanged.
-  version: "1.131.0",
+  // 1.132.0: additive (sc-9086) — the `Badge`, `Avatar`, `Progress`, `Stat`
+  // and `Divider` primitives. The stock widgets of the same names render
+  // through them, so a custom widget's status pill matches a built-in's.
+  // 1.133.0: additive (sc-9002) — `ListHeader` (column labels on `ListRow`'s frame);
+  //    a `ListRow`'s lone `View` child spans the row; a selected row's bar
+  //    no longer shifts its content. Other rows render as before.
+  // 1.134.1: docs (sc-9122) — an emitted event can run a bound action.
+  version: "1.134.1",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/detail-parts-tokens.js

@@ -0,0 +1,91 @@
+// The pure rules behind `<Badge>`, `<Avatar>`, `<Progress>`, `<Stat>` and
+// `<Divider>`: which theme colour a tone reads, and the clamps that keep a
+// bad prop from reaching a native style as NaN (a crash on the export).
+
+import { deriveAccentTints } from "./contract.js";
+
+export const BADGE_TONES = Object.freeze(["neutral", "info", "success", "warning", "danger"]);
+export const PROGRESS_TONES = Object.freeze(["primary", "success", "warning", "danger"]);
+export const STAT_DELTA_TONES = Object.freeze(["neutral", "positive", "negative"]);
+export const AVATAR_SIZES = Object.freeze({ sm: 32, md: 40, lg: 56, xl: 80 });
+export const DIVIDER_SPACINGS = Object.freeze(["sm", "md", "lg"]);
+
+const AVATAR_PX_BOUNDS = Object.freeze({ min: 16, max: 160 });
+const DIVIDER_THICKNESS_BOUNDS = Object.freeze({ min: 1, max: 8 });
+const STAT_FONT_SIZE_BOUNDS = Object.freeze({ min: 12, max: 96 });
+
+const DELTA_TONE_COLORS = Object.freeze({
+  neutral: "onSurfaceMuted",
+  positive: "success",
+  negative: "danger",
+});
+
+function clamp(n, { min, max }) {
+  return Math.min(max, Math.max(min, n));
+}
+
+/**
+ * The soft fill + readable text pair for a badge tone, derived from the theme's
+ * own colours. `neutral` (or an unknown tone) is the muted surface pair.
+ */
+export function badgeTint(colors, tone) {
+  const muted = { backgroundColor: colors.surfaceMuted, color: colors.onSurfaceMuted };
+  const accent = tone !== "neutral" && BADGE_TONES.includes(tone) ? colors[tone] : null;
+  if (!accent) return muted;
+  const tints = deriveAccentTints(accent, colors.surface, colors.onSurface);
+  return tints ? { backgroundColor: tints.primarySoft, color: tints.onPrimarySoft } : muted;
+}
+
+/** A 0-100 percent; anything unreadable is 0. */
+export function clampPercent(value) {
+  const n = Number(value);
+  return Number.isFinite(n) ? clamp(n, { min: 0, max: 100 }) : 0;
+}
+
+/** The fill colour a progress tone reads; an unknown tone is the primary. */
+export function progressColor(colors, tone) {
+  return colors[PROGRESS_TONES.includes(tone) ? tone : "primary"];
+}
+
+/**
+ * An avatar's edge in px: a size token, or a number clamped to a sane range.
+ * Object.hasOwn, because an inherited key ("constructor") is truthy.
+ */
+export function avatarPixelSize(size) {
+  if (typeof size === "number" && Number.isFinite(size)) {
+    return Math.round(clamp(size, AVATAR_PX_BOUNDS));
+  }
+  return Object.hasOwn(AVATAR_SIZES, size) ? AVATAR_SIZES[size] : AVATAR_SIZES.md;
+}
+
+/** A divider's line height in whole px, 1-8. */
+export function dividerThickness(value) {
+  const n = Number(value);
+  if (!Number.isFinite(n)) return DIVIDER_THICKNESS_BOUNDS.min;
+  return clamp(Math.round(n), DIVIDER_THICKNESS_BOUNDS);
+}
+
+/** The spacing token a divider's breathing room reads; unknown is "md". */
+export function dividerSpacing(spacing) {
+  return DIVIDER_SPACINGS.includes(spacing) ? spacing : "md";
+}
+
+/** A stat's value size: the caller's, when it is in range, else the theme's xxl. */
+export function statFontSize(fontSize, typography) {
+  const inRange =
+    typeof fontSize === "number" &&
+    fontSize >= STAT_FONT_SIZE_BOUNDS.min &&
+    fontSize <= STAT_FONT_SIZE_BOUNDS.max;
+  return inRange ? fontSize : typography.sizes.xxl;
+}
+
+/** The colour a stat's delta reads; an unknown tone is neutral. */
+export function statDeltaColor(colors, tone) {
+  return colors[DELTA_TONE_COLORS[STAT_DELTA_TONES.includes(tone) ? tone : "neutral"]];
+}
+
+/** A value worth printing: a finite number or non-blank text. */
+export function hasStatValue(value) {
+  if (typeof value === "number") return Number.isFinite(value);
+  return typeof value === "string" && value.trim() !== "";
+}