@colixsystems/widget-sdk 0.170.0 → 0.172.0

package/README.md

@@ -73,7 +73,56 @@ 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.172.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.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 +1918,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

@@ -2345,7 +2345,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 +2363,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:
@@ -4613,7 +4655,13 @@ 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.
+  version: "1.133.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -2345,7 +2345,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 +2363,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:
@@ -4609,7 +4651,13 @@ 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.
+  version: "1.133.0",
   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() !== "";
+}

package/dist/detail-parts-view.js

@@ -0,0 +1,392 @@
+// The ONE implementation behind the `<Badge>`, `<Avatar>`, `<Progress>`,
+// `<Stat>` and `<Divider>` SDK components and the stock widgets of the same
+// names. The bindings (`detail-parts.js` / `detail-parts.native.js`) differ
+// only in where the primitives come from, so the hosts cannot drift.
+//
+// Meaning is never carried by colour alone: a badge always prints its label, a
+// progress its percent (unless the caller hides it), a stat's delta its sign.
+
+import React from "react";
+import { useHostTheme } from "./hooks.js";
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import { lucideGlyph, Icon } from "./icon.js";
+import { initialsFor } from "./initials.js";
+import {
+  avatarPixelSize,
+  badgeTint,
+  clampPercent,
+  dividerSpacing,
+  dividerThickness,
+  hasStatValue,
+  progressColor,
+  statDeltaColor,
+  statFontSize,
+} from "./detail-parts-tokens.js";
+
+const RING_SIZE_PX = 72;
+const RING_STROKE_PX = 8;
+const h = React.createElement;
+
+// Outside a widget host (a test, a preview) the defaults still paint.
+function useDetailTheme() {
+  return useHostTheme() || DEFAULT_THEME_TOKENS;
+}
+
+function glyph(name, size, color) {
+  const Glyph = lucideGlyph(name);
+  return Glyph ? h(Glyph, { size, color }) : null;
+}
+
+// A count badge may be a number; an empty one still shows it is a badge.
+function badgeText(label) {
+  if (typeof label === "number" && Number.isFinite(label)) return String(label);
+  return typeof label === "string" && label !== "" ? label : "Badge";
+}
+
+function captionText(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+/**
+ * Bind the detail parts to one platform's primitives.
+ *
+ * @param {{View: any, Text: any, Image: any, Svg: any, Circle: any}} rn
+ */
+export function makeDetailParts(rn) {
+  const { View, Text, Image, Svg, Circle } = rn;
+
+  function Badge({ label, tone = "neutral", icon, style, testID }) {
+    const { colors, spacing, radii, typography } = useDetailTheme();
+    const tint = badgeTint(colors, tone);
+    const text = badgeText(label);
+    const pill = {
+      // A pill hugs its label instead of stretching across a column.
+      alignSelf: "flex-start",
+      flexDirection: "row",
+      alignItems: "center",
+      gap: spacing.xs,
+      borderRadius: radii.pill,
+      paddingVertical: spacing.xs,
+      paddingHorizontal: spacing.sm,
+      backgroundColor: tint.backgroundColor,
+    };
+    const labelStyle = {
+      color: tint.color,
+      fontSize: typography.sizes.xs,
+      fontWeight: "600",
+      fontFamily: typography.fontFamily,
+    };
+    return h(
+      View,
+      { style: [pill, style], testID },
+      glyph(icon, typography.sizes.xs, tint.color),
+      h(Text, { style: labelStyle }, text),
+    );
+  }
+  Badge.displayName = "Badge";
+
+  function Avatar({ name, url, size = "md", shape = "circle", accessibilityLabel, style, testID }) {
+    const { colors, radii, typography } = useDetailTheme();
+    const px = avatarPixelSize(size);
+    const box = {
+      alignSelf: "flex-start",
+      width: px,
+      height: px,
+      borderRadius: shape === "rounded" ? radii.md : px / 2,
+      backgroundColor: colors.surfaceMuted,
+    };
+    const source = typeof url === "string" ? url.trim() : "";
+    const label = accessibilityLabel || captionText(name) || "Avatar";
+    if (source) {
+      return h(Image, {
+        source: { uri: source },
+        accessibilityLabel: label,
+        resizeMode: "cover",
+        style: [box, style],
+        testID,
+      });
+    }
+    const initials = initialsFor(name);
+    const fallback = { alignItems: "center", justifyContent: "center" };
+    const content = initials
+      ? h(
+          Text,
+          {
+            style: {
+              color: colors.onSurfaceMuted,
+              fontWeight: "600",
+              fontFamily: typography.fontFamily,
+              fontSize: Math.round(px * 0.4),
+            },
+          },
+          initials,
+        )
+      : h(Icon, { name: "user", size: Math.round(px * 0.55), color: colors.onSurfaceMuted });
+    return h(View, { style: [box, fallback, style], accessibilityLabel: label, testID }, content);
+  }
+  Avatar.displayName = "Avatar";
+
+  function ProgressRing({ percent, fill, showValue, caption, theme }) {
+    const { colors, spacing, typography } = theme;
+    const radius = (RING_SIZE_PX - RING_STROKE_PX) / 2;
+    const circumference = 2 * Math.PI * radius;
+    const centre = RING_SIZE_PX / 2;
+    const ring = { cx: centre, cy: centre, r: radius, strokeWidth: RING_STROKE_PX, fill: "none" };
+    return h(
+      View,
+      { style: { alignItems: "center" } },
+      h(
+        View,
+        { style: { width: RING_SIZE_PX, height: RING_SIZE_PX } },
+        h(
+          Svg,
+          { width: RING_SIZE_PX, height: RING_SIZE_PX },
+          h(Circle, { ...ring, stroke: colors.surfaceMuted }),
+          h(Circle, {
+            ...ring,
+            stroke: fill,
+            strokeLinecap: "round",
+            strokeDasharray: `${circumference} ${circumference}`,
+            strokeDashoffset: circumference * (1 - percent / 100),
+            rotation: -90,
+            originX: centre,
+            originY: centre,
+          }),
+        ),
+        showValue
+          ? h(
+              View,
+              {
+                style: {
+                  position: "absolute",
+                  top: 0,
+                  left: 0,
+                  right: 0,
+                  bottom: 0,
+                  alignItems: "center",
+                  justifyContent: "center",
+                },
+              },
+              h(
+                Text,
+                {
+                  style: {
+                    fontSize: typography.sizes.md,
+                    fontWeight: "700",
+                    color: colors.onSurface,
+                    fontFamily: typography.fontFamily,
+                  },
+                },
+                `${Math.round(percent)}%`,
+              ),
+            )
+          : null,
+      ),
+      caption
+        ? h(
+            Text,
+            {
+              style: {
+                marginTop: spacing.xs,
+                fontSize: typography.sizes.sm,
+                color: colors.onSurfaceMuted,
+                fontFamily: typography.fontFamily,
+              },
+            },
+            caption,
+          )
+        : null,
+    );
+  }
+
+  function ProgressBar({ percent, fill, showValue, caption, theme }) {
+    const { colors, spacing, radii, typography } = theme;
+    const small = { fontSize: typography.sizes.sm, fontFamily: typography.fontFamily };
+    const header =
+      caption || showValue
+        ? h(
+            View,
+            {
+              style: {
+                flexDirection: "row",
+                alignItems: "center",
+                justifyContent: "flex-end",
+                marginBottom: spacing.xs,
+              },
+            },
+            caption
+              ? h(Text, { style: { ...small, flex: 1, color: colors.onSurfaceMuted } }, caption)
+              : null,
+            showValue
+              ? h(
+                  Text,
+                  {
+                    style: {
+                      ...small,
+                      marginLeft: spacing.xs,
+                      fontWeight: "600",
+                      color: colors.onSurface,
+                    },
+                  },
+                  `${Math.round(percent)}%`,
+                )
+              : null,
+          )
+        : null;
+    const track = {
+      width: "100%",
+      height: spacing.sm,
+      borderRadius: radii.pill,
+      backgroundColor: colors.surfaceMuted,
+      overflow: "hidden",
+    };
+    return h(
+      View,
+      { style: { width: "100%" } },
+      header,
+      h(
+        View,
+        { style: track },
+        h(View, {
+          style: {
+            height: "100%",
+            borderRadius: radii.pill,
+            width: `${percent}%`,
+            backgroundColor: fill,
+          },
+        }),
+      ),
+    );
+  }
+
+  function Progress({ value = 0, variant = "bar", label, showValue = true, tone = "primary", style, testID }) {
+    const theme = useDetailTheme();
+    const percent = clampPercent(value);
+    const parts = {
+      percent,
+      fill: progressColor(theme.colors, tone),
+      showValue: showValue !== false,
+      caption: captionText(label),
+      theme,
+    };
+    return h(
+      View,
+      {
+        style: [{ width: "100%" }, style],
+        // The aria props, not accessibilityValue: react-native-web drops that one.
+        role: "progressbar",
+        "aria-valuemin": 0,
+        "aria-valuemax": 100,
+        "aria-valuenow": Math.round(percent),
+        testID,
+      },
+      variant === "ring" ? h(ProgressRing, parts) : h(ProgressBar, parts),
+    );
+  }
+  Progress.displayName = "Progress";
+
+  function Stat({
+    value,
+    label,
+    icon,
+    delta,
+    deltaTone = "neutral",
+    emptyValue = "—",
+    color,
+    fontSize,
+    style,
+    testID,
+  }) {
+    const { colors, spacing, typography } = useDetailTheme();
+    const empty = !hasStatValue(value);
+    const shown = empty ? (typeof emptyValue === "string" ? emptyValue : "") : String(value);
+    const size = statFontSize(fontSize, typography);
+    const valueColor = empty ? colors.onSurfaceMuted : color || colors.onSurface;
+    const deltaText = captionText(delta);
+    const caption = typeof label === "string" ? label : "";
+    return h(
+      View,
+      { style: [{ alignItems: "flex-start" }, style], testID },
+      h(
+        View,
+        { style: { flexDirection: "row", alignItems: "center", gap: spacing.xs } },
+        glyph(icon, Math.max(12, Math.round(size * 0.75)), valueColor),
+        h(
+          Text,
+          {
+            style: {
+              fontWeight: "700",
+              fontFamily: typography.headingFontFamily,
+              fontSize: size,
+              color: valueColor,
+            },
+          },
+          shown,
+        ),
+        deltaText
+          ? h(
+              Text,
+              {
+                style: {
+                  fontSize: typography.sizes.sm,
+                  fontWeight: "600",
+                  fontFamily: typography.fontFamily,
+                  color: statDeltaColor(colors, deltaTone),
+                },
+              },
+              deltaText,
+            )
+          : null,
+      ),
+      caption
+        ? h(
+            Text,
+            {
+              style: {
+                marginTop: spacing.xs,
+                fontSize: typography.sizes.sm,
+                color: colors.onSurfaceMuted,
+                fontFamily: typography.fontFamily,
+              },
+            },
+            caption,
+          )
+        : null,
+    );
+  }
+  Stat.displayName = "Stat";
+
+  function Divider({ label, thickness = 1, spacing = "md", color, style, testID }) {
+    const theme = useDetailTheme();
+    const caption = captionText(label);
+    const rule = {
+      height: dividerThickness(thickness),
+      backgroundColor: color || theme.colors.border,
+    };
+    const root = { width: "100%", paddingVertical: theme.spacing[dividerSpacing(spacing)] };
+    const body = caption
+      ? h(
+          View,
+          { style: { flexDirection: "row", alignItems: "center" } },
+          h(View, { style: [{ flex: 1 }, rule] }),
+          h(
+            Text,
+            {
+              style: {
+                marginHorizontal: theme.spacing.sm,
+                fontSize: theme.typography.sizes.sm,
+                color: theme.colors.onSurfaceMuted,
+                fontFamily: theme.typography.fontFamily,
+              },
+            },
+            caption,
+          ),
+          h(View, { style: [{ flex: 1 }, rule] }),
+        )
+      : h(View, { style: [{ width: "100%" }, rule] });
+    return h(View, { style: [root, style], testID }, body);
+  }
+  Divider.displayName = "Divider";
+
+  return { Badge, Avatar, Progress, Stat, Divider };
+}

package/dist/detail-parts.js

@@ -0,0 +1,15 @@
+// `<Badge>`, `<Avatar>`, `<Progress>`, `<Stat>`, `<Divider>` (web). Binds
+// ./detail-parts-view.js to react-native-web; see ./primitives.js for why not
+// the bare specifier.
+
+import * as ReactNative from "react-native-web";
+import Svg, { Circle } from "react-native-svg";
+import { makeDetailParts } from "./detail-parts-view.js";
+
+export const { Badge, Avatar, Progress, Stat, Divider } = makeDetailParts({
+  View: ReactNative.View,
+  Text: ReactNative.Text,
+  Image: ReactNative.Image,
+  Svg,
+  Circle,
+});

package/dist/detail-parts.native.js

@@ -0,0 +1,15 @@
+// `<Badge>`, `<Avatar>`, `<Progress>`, `<Stat>`, `<Divider>` (native). Binds
+// ./detail-parts-view.js to React Native; only the imports differ from
+// ./detail-parts.js.
+
+import { View, Text, Image } from "react-native";
+import Svg, { Circle } from "react-native-svg";
+import { makeDetailParts } from "./detail-parts-view.js";
+
+export const { Badge, Avatar, Progress, Stat, Divider } = makeDetailParts({
+  View,
+  Text,
+  Image,
+  Svg,
+  Circle,
+});

package/dist/index.d.ts

@@ -2601,7 +2601,48 @@ export const ListRow: (props: ListRowTokens & {
   accessibilityLabel?: string;
   style?: any;
   testID?: string;
-  /** Replaces the title block, e.g. for a multi-column row. */
+  /**
+   * Replaces the title block, e.g. for a multi-column row. A single `View`
+   * child spans the row between `leading` and `trailing`; anything else
+   * (several cells, say) sits in the row as given.
+   */
+  children?: ReactNode;
+}) => any;
+
+/**
+ * A table's column labels. Shares `<ListRow>`'s horizontal padding, gap and
+ * side edges (from the same Theme Settings > Lists values), so a label given
+ * the same flex as its row cell sits exactly over that column. Pass it the
+ * same overrides as the `<List>`. Make it the rows' `ScrollView`'s first,
+ * sticky child so it shares their width beside a scrollbar.
+ *
+ * @example
+ *   <ScrollView stickyHeaderIndices={[0]}>
+ *     <ListHeader style={{ backgroundColor: theme.colors.surface }}>
+ *       <Text style={[overline, { flex: 2, minWidth: 0 }]}>Name</Text>
+ *       <Text style={[overline, { flex: 1, minWidth: 0 }]}>Status</Text>
+ *     </ListHeader>
+ *     <List>
+ *       {rows.map((r) => (
+ *         <ListRow key={r.id} onPress={() => open(r)}>
+ *           <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>
+ *   </ScrollView>
+ */
+export const ListHeader: (props: Pick<ListRowTokens, "rowPadding" | "gap" | "dividerColor" | "dividerWidth"> & {
+  /** A spacer as wide as the rows' `leading`, so the columns still line up. */
+  leading?: ReactNode;
+  /** A spacer (or label) as wide as the rows' `trailing`. */
+  trailing?: ReactNode;
+  /** The divider under the labels. Defaults to true. */
+  divider?: boolean;
+  accessibilityLabel?: string;
+  style?: any;
+  testID?: string;
+  /** The column labels, shaped exactly like the rows' `children`. */
   children?: ReactNode;
 }) => any;
 
@@ -2616,6 +2657,82 @@ export const EmptyState: (props: {
   children?: ReactNode;
 }) => any;
 
+/**
+ * Themed status pill: a record's state (Active, Paid, Overdue) beside the
+ * thing it describes. The label always renders; the tone only tints it.
+ *
+ * @example
+ *   <Badge label={row.status} tone="success" />
+ */
+export const Badge: (props: {
+  label?: string | number;
+  tone?: "neutral" | "info" | "success" | "warning" | "danger";
+  /** A lucide icon name shown before the label. */
+  icon?: string;
+  style?: any;
+  testID?: string;
+}) => any;
+
+/** Themed picture of a person, falling back to initials, then a glyph. */
+export const Avatar: (props: {
+  /** Drives the initials and the accessibility label. */
+  name?: string;
+  /** An absolute image URL. */
+  url?: string;
+  /** A size token, or a number of px (clamped to 16-160). */
+  size?: "sm" | "md" | "lg" | "xl" | number;
+  shape?: "circle" | "rounded";
+  accessibilityLabel?: string;
+  style?: any;
+  testID?: string;
+}) => any;
+
+/** Themed completion bar or ring for real progress toward a known goal. */
+export const Progress: (props: {
+  /** Percent complete; clamped to 0-100. */
+  value?: number;
+  variant?: "bar" | "ring";
+  label?: string;
+  /** Render the percent as text. Default true. */
+  showValue?: boolean;
+  tone?: "primary" | "success" | "warning" | "danger";
+  style?: any;
+  testID?: string;
+}) => any;
+
+/** Themed headline figure. Displays a value you computed; it fetches nothing. */
+export const Stat: (props: {
+  /** The figure. Empty (null, blank, NaN) prints `emptyValue` instead. */
+  value?: string | number | null;
+  label?: string;
+  /** A lucide icon name beside the figure. */
+  icon?: string;
+  delta?: string;
+  deltaTone?: "neutral" | "positive" | "negative";
+  /** Printed when `value` is empty. Default "—". */
+  emptyValue?: string;
+  color?: string;
+  /** The figure's size in px (12-96); defaults to the theme's xxl. */
+  fontSize?: number;
+  style?: any;
+  testID?: string;
+}) => any;
+
+/** Themed rule splitting two groups inside one surface; optionally captioned. */
+export const Divider: (props: {
+  label?: string;
+  /** Line thickness in px, 1-8. */
+  thickness?: number;
+  spacing?: "sm" | "md" | "lg";
+  /** Defaults to the theme's border colour. */
+  color?: string;
+  style?: any;
+  testID?: string;
+}) => any;
+
+/** A person's initials: "Ada Lovelace" → "AL"; "" when the name has no letters. */
+export function initialsFor(name: unknown): string;
+
 /**
  * Themed card surface. With no props it takes the app's card look (Theme
  * Settings > Cards). Props override one card; `style` takes the `card*` style

package/dist/index.js

@@ -196,7 +196,10 @@ export {
 } from "./emoji-reactions.js";
 export { insertAtCaret, pushRecentEmoji } from "./emoji-picker-tokens.js";
 // Themed list building blocks; rows follow the theme's `list` scope.
-export { List, ListRow, EmptyState } from "./list.js";
+export { List, ListRow, ListHeader, EmptyState } from "./list.js";
+// Themed detail parts; the stock Badge/Avatar/Progress/Stat/Divider wrap these.
+export { Badge, Avatar, Progress, Stat, Divider } from "./detail-parts.js";
+export { initialsFor } from "./initials.js";
 // The one card surface: the theme's `card` scope, a gradient fill, margin.
 export { Card } from "./card.js";
 export {

package/dist/index.native.js

@@ -189,7 +189,10 @@ export {
 } from "./emoji-reactions.js";
 export { insertAtCaret, pushRecentEmoji } from "./emoji-picker-tokens.js";
 // Themed list building blocks; rows follow the theme's `list` scope.
-export { List, ListRow, EmptyState } from "./list.native.js";
+export { List, ListRow, ListHeader, EmptyState } from "./list.native.js";
+// Themed detail parts; the stock Badge/Avatar/Progress/Stat/Divider wrap these.
+export { Badge, Avatar, Progress, Stat, Divider } from "./detail-parts.native.js";
+export { initialsFor } from "./initials.js";
 // The one card surface: the theme's `card` scope, a gradient fill, margin.
 export { Card } from "./card.native.js";
 export {

package/dist/initials.js

@@ -0,0 +1,17 @@
+// The ONE initials rule, for `<Avatar>` and every built-in that falls back to a
+// person's initials. Two rules would print different letters for one person.
+//
+// Returns "" when the name yields no letters, so each caller keeps its own
+// fallback (a "?", a person glyph).
+
+/** "Ada Lovelace" → "AL", "Ada" → "A", "  " → "". */
+export function initialsFor(name) {
+  const parts =
+    typeof name === "string" ? name.trim().split(/\s+/).filter(Boolean) : [];
+  if (parts.length === 0) return "";
+  // Array.from, not slice: a multi-byte first character must not be halved.
+  const first = Array.from(parts[0])[0];
+  if (parts.length === 1) return first.toUpperCase();
+  const last = Array.from(parts[parts.length - 1])[0];
+  return (first + last).toUpperCase();
+}

package/dist/list-tokens.js

@@ -9,6 +9,9 @@ import { normaliseThemeComponents } from "./theme-components.js";
 // A row with no themed height still meets the 44px touch-target floor.
 export const LIST_ROW_MIN_HEIGHT = 44;
 
+// The accent bar a selected row carries on its leading edge.
+export const LIST_SELECTED_BAR_WIDTH = 3;
+
 // The per-row overrides a widget may pass, named as the theme tokens are.
 export const LIST_TOKEN_NAMES = Object.freeze([
   "rowPadding",
@@ -66,3 +69,31 @@ export function resolveListTokens(theme, overrides) {
     pressedBackground: mixHex(colors.onSurface, background || colors.surface, 0.94),
   };
 }
+
+/** The width of a row's side edges: a tile's outline, none on a flush band. */
+export function listSideEdgeWidth(tokens) {
+  return tokens.separated ? tokens.dividerWidth : 0;
+}
+
+/**
+ * The horizontal geometry `<ListRow>` and `<ListHeader>` share: the direction,
+ * the gap between leading, body and trailing, and the inset. Both draw from
+ * this one function, so a header cell sits over its row cell by construction.
+ *
+ * @param {ReturnType<typeof resolveListTokens>} tokens
+ * @param {{ md: number }} spacing — the theme's spacing scale.
+ * @param {boolean} [selected] — the row carries the accent bar.
+ */
+export function listRowFrame(tokens, spacing, selected = false) {
+  const frame = {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: spacing.md,
+    paddingHorizontal: tokens.rowPadding,
+  };
+  if (!selected) return frame;
+  // The bar replaces the side edge and takes its width out of the inset,
+  // so a row's cells do not move when it is selected.
+  const inset = tokens.rowPadding + listSideEdgeWidth(tokens) - LIST_SELECTED_BAR_WIDTH;
+  return { ...frame, paddingLeft: Math.max(0, inset) };
+}

package/dist/list-view.js

@@ -1,5 +1,5 @@
-// The ONE implementation behind the `<List>`, `<ListRow>` and `<EmptyState>`
-// SDK primitives. The platform bindings (`list.js` / `list.native.js`) differ
+// The ONE implementation behind the `<List>`, `<ListRow>`, `<ListHeader>` and
+// `<EmptyState>` SDK primitives. The platform bindings (`list.js` / `list.native.js`) differ
 // only in where the primitives come from, so the hosts cannot drift.
 //
 // Every widget drawing a list of records used to hand-roll its rows, so two
@@ -10,7 +10,13 @@ import React from "react";
 import { useHostTheme } from "./hooks.js";
 import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
 import { Icon } from "./icon.js";
-import { resolveListTokens, LIST_TOKEN_NAMES } from "./list-tokens.js";
+import {
+  resolveListTokens,
+  listRowFrame,
+  listSideEdgeWidth,
+  LIST_TOKEN_NAMES,
+  LIST_SELECTED_BAR_WIDTH,
+} from "./list-tokens.js";
 import { textRoleStyle } from "./text-roles.js";
 
 // Outside a widget host (a test, a preview) the defaults still paint a row.
@@ -26,15 +32,49 @@ function listOverrides(props) {
   return out;
 }
 
+function soleElement(children) {
+  const parts = React.Children.toArray(children);
+  return parts.length === 1 && React.isValidElement(parts[0]) ? parts[0] : null;
+}
+
+const HORIZONTAL_PADDING = [
+  "padding",
+  "paddingHorizontal",
+  "paddingLeft",
+  "paddingStart",
+  "paddingInline",
+  "paddingInlineStart",
+];
+
 /**
  * Bind the shared list components to one platform's primitives.
  *
- * @param {{View: any, Text: any, Pressable: any}} rn
+ * @param {{View: any, Text: any, Pressable: any, StyleSheet: any}} rn
  */
 export function makeList(rn) {
-  const { View, Text, Pressable } = rn;
+  const { View, Text, Pressable, StyleSheet } = rn;
   const ListContext = React.createContext(null);
 
+  function useRowTokens(props) {
+    const theme = useListTheme();
+    const inherited = React.useContext(ListContext);
+    return [theme, resolveListTokens(theme, { ...inherited, ...listOverrides(props) })];
+  }
+
+  // A lone row View spans the row, as the title block does. Anything
+  // else (cells, a component rendering cells) stays in the row as before.
+  function customBody(children) {
+    const only = soleElement(children);
+    return only && only.type === View
+      ? React.createElement(View, { style: { flex: 1, minWidth: 0 } }, only)
+      : children;
+  }
+
+  function setsOwnInset(style) {
+    const flat = StyleSheet.flatten(style) || {};
+    return HORIZONTAL_PADDING.some((key) => flat[key] !== undefined);
+  }
+
   function List(props) {
     const { children, style, testID } = props;
     const theme = useListTheme();
@@ -72,12 +112,7 @@ export function makeList(rn) {
       testID,
       children,
     } = props;
-    const theme = useListTheme();
-    const inherited = React.useContext(ListContext);
-    const tokens = resolveListTokens(theme, {
-      ...inherited,
-      ...listOverrides(props),
-    });
+    const [theme, tokens] = useRowTokens(props);
     const { colors, spacing, typography } = theme;
 
     const pressable = typeof onPress === "function";
@@ -90,10 +125,8 @@ export function makeList(rn) {
         ? { borderBottomWidth: tokens.dividerWidth, borderColor: tokens.dividerColor }
         : null;
     const rowStyle = {
-      flexDirection: "row",
-      alignItems: "center",
-      gap: spacing.md,
-      paddingHorizontal: tokens.rowPadding,
+      // An inset the widget sets itself is left exactly as it asked.
+      ...listRowFrame(tokens, spacing, selected && !setsOwnInset(style)),
       paddingVertical: tokens.rowPadding,
       // A dense look may shrink a static row, never a tap target.
       minHeight: pressable ? Math.max(tokens.rowMinHeight, 44) : tokens.rowMinHeight,
@@ -104,7 +137,7 @@ export function makeList(rn) {
       ...(selected
         ? {
             backgroundColor: tokens.selectedBackground,
-            borderLeftWidth: 3,
+            borderLeftWidth: LIST_SELECTED_BAR_WIDTH,
             borderLeftColor: tokens.selectedAccent,
           }
         : null),
@@ -112,7 +145,7 @@ export function makeList(rn) {
 
     const body =
       children !== undefined
-        ? children
+        ? customBody(children)
         : React.createElement(
             View,
             { style: { flex: 1, gap: 2 } },
@@ -174,6 +207,39 @@ export function makeList(rn) {
   }
   ListRow.displayName = "ListRow";
 
+  // A table's column labels: a ListRow's frame and body slot with none of its
+  // row chrome, so each label sits over its column.
+  function ListHeader(props) {
+    const { leading, trailing, divider = true, accessibilityLabel, style, testID, children } = props;
+    const [theme, tokens] = useRowTokens(props);
+    const { spacing } = theme;
+    // Transparent side edges stand in for a tile's outline.
+    const side = listSideEdgeWidth(tokens);
+    const headerStyle = {
+      ...listRowFrame(tokens, spacing),
+      paddingVertical: Math.min(tokens.rowPadding, spacing.sm),
+      ...(side > 0
+        ? { borderLeftWidth: side, borderRightWidth: side, borderColor: "transparent" }
+        : null),
+      ...(divider && tokens.dividerWidth > 0
+        ? { borderBottomWidth: tokens.dividerWidth, borderBottomColor: tokens.dividerColor }
+        : null),
+    };
+    return React.createElement(
+      View,
+      {
+        style: [headerStyle, style],
+        testID,
+        accessibilityLabel,
+        accessible: accessibilityLabel ? true : undefined,
+      },
+      leading || null,
+      customBody(children),
+      trailing || null,
+    );
+  }
+  ListHeader.displayName = "ListHeader";
+
   function EmptyState({ icon = "inbox", title, message, children, style, testID }) {
     const { colors, spacing, radii, typography } = useListTheme();
     return React.createElement(
@@ -211,5 +277,5 @@ export function makeList(rn) {
   }
   EmptyState.displayName = "EmptyState";
 
-  return { List, ListRow, EmptyState };
+  return { List, ListRow, ListHeader, EmptyState };
 }

package/dist/list.js

@@ -1,7 +1,7 @@
-// `<List>`, `<ListRow>`, `<EmptyState>` (web). Binds ./list-view.js to
-// react-native-web; see ./primitives.js for why not the bare specifier.
+// `<List>`, `<ListRow>`, `<ListHeader>`, `<EmptyState>` (web). Binds
+// ./list-view.js to react-native-web; see ./primitives.js for why not the bare specifier.
 
 import * as ReactNative from "react-native-web";
 import { makeList } from "./list-view.js";
 
-export const { List, ListRow, EmptyState } = makeList(ReactNative);
+export const { List, ListRow, ListHeader, EmptyState } = makeList(ReactNative);

package/dist/list.native.js

@@ -1,7 +1,7 @@
-// `<List>`, `<ListRow>`, `<EmptyState>` (native). Binds ./list-view.js to
-// React Native's own primitives; only the import differs from ./list.js.
+// `<List>`, `<ListRow>`, `<ListHeader>`, `<EmptyState>` (native). Binds
+// ./list-view.js to React Native's own primitives; only the import differs from ./list.js.
 
-import { View, Text, Pressable } from "react-native";
+import { View, Text, Pressable, StyleSheet } from "react-native";
 import { makeList } from "./list-view.js";
 
-export const { List, ListRow, EmptyState } = makeList({ View, Text, Pressable });
+export const { List, ListRow, ListHeader, EmptyState } = makeList({ View, Text, Pressable, StyleSheet });

package/dist/webbundle.js

@@ -90,12 +90,15 @@ function cssInjectPlugin() {
  *   packer passes the frontend's `node_modules` (where the vetted web packages
  *   are installed per the adding-vetted-packages skill) so the bundle resolves
  *   them no matter the invoking CWD.
+ * @param {boolean} [opts.minify]  minify the output for production serving.
+ *   Off by default so the dev server's bundle stays readable.
  * @returns {Promise<string>} the bundled ESM source.
  */
 export async function bundleWebEntry({
   entryPath,
   external = hostExternalSpecifiers(),
   nodePaths = [],
+  minify = false,
 }) {
   const esbuild = await loadEsbuild();
   const result = await esbuild.build({
@@ -138,6 +141,7 @@ export async function bundleWebEntry({
     // adds extra roots so a packer invoked from the repo root still resolves the
     // vetted web packages installed under frontend/node_modules.
     nodePaths,
+    minify,
     logLevel: "silent",
   });
   const out = result.outputFiles?.[0];

package/package.json

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

package/src/webbundle.js

@@ -90,12 +90,15 @@ function cssInjectPlugin() {
  *   packer passes the frontend's `node_modules` (where the vetted web packages
  *   are installed per the adding-vetted-packages skill) so the bundle resolves
  *   them no matter the invoking CWD.
+ * @param {boolean} [opts.minify]  minify the output for production serving.
+ *   Off by default so the dev server's bundle stays readable.
  * @returns {Promise<string>} the bundled ESM source.
  */
 export async function bundleWebEntry({
   entryPath,
   external = hostExternalSpecifiers(),
   nodePaths = [],
+  minify = false,
 }) {
   const esbuild = await loadEsbuild();
   const result = await esbuild.build({
@@ -138,6 +141,7 @@ export async function bundleWebEntry({
     // adds extra roots so a packer invoked from the repo root still resolves the
     // vetted web packages installed under frontend/node_modules.
     nodePaths,
+    minify,
     logLevel: "silent",
   });
   const out = result.outputFiles?.[0];