@teamblind-chorus/ui 1.0.0

package/agents/components/list/radio.spec.json

@@ -0,0 +1,186 @@
+{
+  "$schema": "../../spec.schema.json",
+  "name": "List",
+  "family": "list",
+  "subcomponent": "radio",
+  "description": "Single-select picker List variant. Each row carries a leading 24px (`sys.icon.lg`) radio indicator; clicking any row commits its value via `onChange(value)`. Exactly one row is selected at a time (or zero before the user picks). Use inside picker sheets, settings rows, sort-by menus. A major category that opens a second screen can set `nav: true` to add a trailing drill-in chevron alongside the radio indicator — the row commits its value via `onChange` and routes to the sub-screen via the row's `onClick`.",
+  "element": "ul",
+  "props": {
+    "embedded": {
+      "type": "boolean",
+      "default": false,
+      "description": "Composition mode flag. When `true` (or when the List is a direct child of `.chorus-carousel` / `.chorus-feed`), enters **embedded mode**: zeroes its own `background` + `padding` so chrome defers to the host. Pass explicitly inside `<Carousel>` / `<Feed>` for the contract to be visible in JSX; the DOM-ancestry safety net in styles.css also activates the mode when omitted. See `compositionModes` in `list.family.json`."
+    },
+    "items": {
+      "type": "node",
+      "required": true,
+      "description": "Array of row descriptors."
+    },
+    "value": {
+      "type": "string",
+      "optional": true,
+      "description": "Selected value. Controlled."
+    },
+    "onChange": {
+      "type": "function",
+      "optional": true,
+      "description": "Commits the next value when a row is selected."
+    }
+  },
+  "slots": {
+    "container": {
+      "required": true,
+      "description": "Outer scroll surface. Vertical stack with a transparent fill (inherits parent container tone); rows separated by a 1px outlineVariant divider, not a gap."
+    },
+    "row": {
+      "required": true,
+      "description": "Single list item. Whole row is the interactive target."
+    },
+    "leading": {
+      "required": true,
+      "description": "24px (`sys.icon.lg`) radio indicator — `RadioIcon` at rest, `RadioFillIcon` when selected. Decorative — keyboard focus and click target both sit on the row.",
+      "accepts": [
+        "icon"
+      ]
+    },
+    "label": {
+      "required": true,
+      "description": "Primary row text. 16px / Regular / onSurface. Single line; truncates with ellipsis.",
+      "accepts": [
+        "text"
+      ]
+    },
+    "supportingText": {
+      "required": false,
+      "description": "Secondary line under label. 14px / Regular / onSurfaceVariant, sits directly under the label with no extra gap.",
+      "accepts": [
+        "text"
+      ]
+    },
+    "navChevron": {
+      "required": false,
+      "description": "Auto-rendered 16px right-pointing chevron at the trailing edge, painted when the row sets `nav: true` — marks a major category that opens a second screen, shown alongside the leading radio indicator. `onSurfaceVariant` tone, decorative (`aria-hidden`); never a separate hit target — the whole row is the click target."
+    }
+  },
+  "rowProps": {
+    "value": {
+      "type": "string",
+      "required": true
+    },
+    "label": {
+      "type": "string",
+      "required": true
+    },
+    "supportingText": {
+      "type": "string",
+      "optional": true
+    },
+    "nav": {
+      "type": "boolean",
+      "default": false,
+      "description": "Drill-in case for a major category — when `true`, the row auto-renders a trailing right-pointing chevron alongside the radio indicator, signalling the option opens a second screen."
+    },
+    "onClick": {
+      "type": "function",
+      "optional": true,
+      "description": "Fires on row click in addition to `onChange`. On a `nav: true` row, wire it to route to the category's second screen."
+    },
+    "disabled": {
+      "type": "boolean",
+      "default": false
+    },
+    "strong": {
+      "type": "boolean",
+      "default": false,
+      "description": "Per-row label-emphasis opt-in (family-wide contract — see [list.md § Cross-sub contract](./list.md)). When `true`, the row's label weight promotes from `body.md` Regular (400) to `label.lg` Semibold (600) at the same 16px size and 1.5 line-height — geometry stays identical, only the glyph stroke thickens. Use sparingly to mark one primary row inside a denser scan; a stack where every row is `strong` defeats the marker."
+    },
+    "forcedState": {
+      "type": "literal",
+      "values": [
+        "hovered",
+        "pressed",
+        "focused"
+      ],
+      "optional": true,
+      "description": "Docs-only — pins the row to a single visual state via `data-force-state`. Not for production use."
+    }
+  },
+  "sizing": {
+    "rowPaddingBlock": "ref.space.100",
+    "rowPaddingInline": "ref.space.200",
+    "rowMinHeight": "ref.space.600",
+    "leadingTextGap": "sys.layout.inline.md",
+    "leadingTextGapNote": "8px (`sys.layout.inline.md`) between the leading radio indicator (an icon leading) and the text group — the icon-leading rung of the family's role-based row spacing.",
+    "trailingActionGap": "sys.layout.inline.md",
+    "trailingActionGapNote": "Fixed 8px between the text group and a trailing nav chevron (the major-category `nav: true` case) — the family-wide trailing gap.",
+    "dividerWidth": "sys.borderWidth.hairline",
+    "dividerColor": "sys.color.outlineVariant",
+    "labelTypo": "sys.typo.body.md",
+    "labelColor": "sys.color.onSurface",
+    "supportingTypo": "sys.typo.body.sm",
+    "supportingColor": "sys.color.onSurfaceVariant",
+    "supportingOffset": "0",
+    "leadingRadioSize": "24 × 24",
+    "leadingRadioColorRest": "sys.color.outline",
+    "leadingRadioColorSelected": "sys.color.primary",
+    "navChevronSize": "16 × 16",
+    "navChevronColor": "sys.color.onSurfaceVariant"
+  },
+  "states": {
+    "default": {
+      "overlay": null
+    },
+    "hovered": {
+      "overlay": {
+        "color": "label",
+        "opacity": "sys.state.hover"
+      }
+    },
+    "pressed": {
+      "overlay": {
+        "color": "label",
+        "opacity": "sys.state.pressed"
+      }
+    },
+    "selected": {
+      "leading": "Filled primary indicator; row foreground stays at onSurface. No fill change on the row itself."
+    },
+    "disabled": {
+      "containerOpacity": "sys.state.disabled",
+      "containerOpacityScope": "Dims the row content only — the inter-row divider and the focus overlay keep full opacity, so a disabled row never fades the hairline rule between it and the next row.",
+      "pointerEvents": "none",
+      "note": "Radio indicator dims with the row."
+    }
+  },
+  "focusIndicator": {
+    "description": "Keyboard-focus visual — an accessibility indicator, not a lifecycle state. The ring sits on the row, not on the leading indicator — the row is the keyboard target.",
+    "composition": "inward",
+    "compositionReason": "Rows tile the column flush with only a hairline `outlineVariant` divider between them; an outward ring would overlap the divider and the neighbouring row.",
+    "overlay": {
+      "color": "label",
+      "opacity": "sys.state.focus"
+    },
+    "ring": {
+      "outerWidth": "sys.borderWidth.thin",
+      "outerColor": "sys.color.focus",
+      "outerLayerPosition": "depth 0..2px from the row edge (the outer stroke)",
+      "insetWidth": "sys.borderWidth.hairline",
+      "insetColor": "sys.color.focusInset",
+      "insetLayerPosition": "depth 2..3px from the row edge (the counter-ring just inside the outer stroke)",
+      "implementation": "inset box-shadow on the row's `::before` overlay (the `::after` carries the inter-row divider). Constrained strictly inside the row's footprint and never exceeds it."
+    },
+    "trigger": ":focus-visible (keyboard / programmatic focus, never plain mouse click)"
+  },
+  "behavior": {
+    "keyboardNavigation": "Arrow up/down moves focus between rows. Space and Enter commit the focused row's value. Home and End jump to first / last.",
+    "selectionModel": "Single-select only; selecting a row implicitly deselects the previously selected. Controlled — pass `value` and `onChange`; uncontrolled use defaults to no selection.",
+    "rowClickTarget": "Whole row is clickable. The leading indicator is never a separate hit target.",
+    "navDrillIn": "A row with `nav: true` renders the trailing chevron and routes to the category's second screen via the row's `onClick`, while the click still commits the row's value through `onChange`. The chevron is decorative — the whole row is the single click target, not the chevron alone.",
+    "truncationNotWrap": "Both label and supportingText truncate; the row never grows to fit long text."
+  },
+  "forbidden": [
+    "radio glyph as a separate hit area — the entire row is the click target",
+    "multi-select painted as radio — radio variant is single-select; use checkbox or chip/filter for multi-select",
+    "selected state painted with sys.color.primaryContainer fill — radio selected paints the inner dot, not the row fill"
+  ]
+}

package/agents/components/list/standard.md

@@ -0,0 +1,262 @@
+# Standard
+
+The default [List](./list.md) sub — display or navigation rows over the shared List anatomy. The whole row is the click target; there is no selection model. A row is text-only by default, opting into a **leading image** (40px [Thumbnail](../thumbnail/thumbnail.md) via `thumbnail`) or a **leading icon** (`sys.icon.lg` glyph via `icon`). Geometry, typography, divider, state overlays, and inward focus ring delegate to the [family-wide rules](./list.md).
+
+**Layout inset.** `full-bleed` — sits as a direct child of the page shell. Each row pays its own `16px inline / 8px block` padding via `layout.container.*`; do **not** wrap the list in another `padding-inline` / `px-*` / `style={{ padding: … }}` div. Inside a bounded surface (Card / Dialog / BottomSheet / Sheet), apply the negative-margin opt-out — see [`AGENTS.md` § Composition rules](../../../AGENTS.md#composition-rules).
+
+A row opts into an inline `count` Badge to the right of the label (4px / `sys.layout.inline.sm` — the unread / status-count case below). For the richer directory shape — a selectable avatar at the 32 / 48 / 56 rung with a stacked `secondary` identity line + optional description — reach for [list/entry](./entry.md), the canonical home for entity-row directory cases. Standard's leading image is single-density at the 40 rung; its own inline `count` covers the plain label + count case without the avatar-directory anatomy.
+
+## Default
+
+A plain text list — five menu rows with optional supporting text.
+
+```preview
+list/standard
+---
+import { List } from '@teamblind-chorus/ui';
+
+<List
+  items={[
+    { value: 'profile',  label: 'Profile',         supportingText: 'Name, photo, bio' },
+    { value: 'notif',    label: 'Notifications',   supportingText: 'Email, push, in-app' },
+    { value: 'privacy',  label: 'Privacy',         supportingText: 'Who can see your activity' },
+    { value: 'language', label: 'Language' },
+    { value: 'about',    label: 'About' },
+  ]}
+/>
+```
+
+## Use cases
+
+### With trailing action
+
+A Text Button in the row's `trailingIcon` slot turns a display row into row + action — the row label stays informational (no `onClick` on the row), the trailing button is the only commit target. Reach for it on settings rows that pair a value with a small "change / edit / view" action.
+
+```preview
+list/standard-with-trailing-action
+---
+import { Button, List } from '@teamblind-chorus/ui';
+
+<List
+  aria-label="Notification channels"
+  items={[
+    {
+      value: 'email',
+      label: 'Email',
+      supportingText: 'work@example.com',
+      trailingIcon: (
+        <Button variant="text" size="small" appearance="accent" onClick={() => {}}>
+          Edit
+        </Button>
+      ),
+    },
+    {
+      value: 'sms',
+      label: 'SMS',
+      supportingText: '+1 (415) ***-2487',
+      trailingIcon: (
+        <Button variant="text" size="small" appearance="accent" onClick={() => {}}>
+          Edit
+        </Button>
+      ),
+    },
+  ]}
+/>
+```
+
+### With an inline count
+
+Pass a `count` on a row and a Badge renders to the right of the label on the same line, separated by `4px` (`sys.layout.inline.sm`) — the unread / status-count case. The label shrinks first so a long label truncates against the count, which stays pinned at its intrinsic width. Unlike `trailingIcon`, the count tiles tight to the label inside the text group, so it **composes with the drill-in chevron**: a `nav: true` row carries the count by the label *and* keeps its trailing chevron — one row with both an icon and a badge.
+
+```preview
+list/standard-count
+---
+import { List, Badge } from '@teamblind-chorus/ui';
+
+<List
+  items={[
+    { value: 'profile',  label: 'Profile',       supportingText: 'Display name, avatar, bio', nav: true },
+    { value: 'channels', label: 'My channels',   supportingText: '12 joined · 3 muted', nav: true },
+    { value: 'notif',    label: 'Notifications', count: <Badge>3</Badge>, nav: true },
+    { value: 'privacy',  label: 'Privacy', nav: true },
+    { value: 'account',  label: 'Account', nav: true },
+  ]}
+/>
+```
+
+### Drill-in rows
+
+Set `nav: true` on a row to auto-render a trailing right-pointing chevron — the drill-in affordance signalling the row routes to another surface. The whole row is the click target; the chevron is decorative. This is the canonical settings / menu navigation shape (it replaces the former `nav` variant). A per-item `trailingIcon` overrides the chevron for that row.
+
+```preview
+list/standard-nav
+---
+import { List } from '@teamblind-chorus/ui';
+
+<List
+  items={[
+    { value: 'profile',  label: 'Profile',         supportingText: 'Display name, avatar, bio', nav: true },
+    { value: 'channels', label: 'My channels',     supportingText: '12 joined · 3 muted',        nav: true },
+    { value: 'notif',    label: 'Notifications', nav: true },
+    { value: 'privacy',  label: 'Privacy',       nav: true },
+    { value: 'account',  label: 'Account',       nav: true },
+  ]}
+/>
+```
+
+### With a leading icon
+
+Pass an `icon` on a row and a 24px (`sys.icon.lg`) glyph renders at the leading edge in `onSurfaceVariant`, `8px` (`sys.layout.inline.md`) from the text group — the category-mark shape for settings / menu rows, lighter than a 40px leading image (and mutually exclusive with `thumbnail`). The glyph is decorative (the label carries the meaning) and the slot enforces the 24 rung regardless of the glyph's own `size`. Every other slot stays optional, so the icon composes with `supportingText`, an inline `count`, and the drill-in chevron.
+
+```preview
+list/standard-icon-leading
+---
+import { List, Badge } from '@teamblind-chorus/ui';
+import { ProfileIcon, BellIcon, BookmarkIcon, PulseIcon } from '@teamblind-chorus/ui/icons';
+
+<List
+  items={[
+    { value: 'profile',  label: 'Profile',       supportingText: 'Display name, avatar, bio', icon: <ProfileIcon />, nav: true },
+    { value: 'notif',    label: 'Notifications', icon: <BellIcon />, count: <Badge>3</Badge>, nav: true },
+    { value: 'saved',    label: 'Saved',         icon: <BookmarkIcon />, nav: true },
+    { value: 'activity', label: 'Activity',      icon: <PulseIcon />, nav: true },
+  ]}
+/>
+```
+
+### Leading image
+
+Pass a `thumbnail` on a row and a 40px [Thumbnail](../thumbnail/thumbnail.md) renders at the leading edge, vertically centred against the label column. `thumbnail` props (`src`, `alt`, `updateDot`, `logoBadge`) forward verbatim. The gap to the text group steps up to `12px` (`sys.layout.inline.lg`) so the avatar and the label column read as two distinct blocks. This is the channel / source / author row shape — same click semantics as a text row, no selection model.
+
+```preview
+list/standard-image
+---
+import { List } from '@teamblind-chorus/ui';
+
+<List
+  items={[
+    { value: 'design-weekly', label: 'Design Weekly', supportingText: 'Updated 2h ago', thumbnail: { alt: 'Design Weekly' } },
+    { value: 'frontend',      label: 'Frontend Friday', supportingText: 'Updated 1d ago', thumbnail: { alt: 'Frontend Friday' } },
+    { value: 'changelog',     label: 'Changelog',       supportingText: 'Updated 3d ago', thumbnail: { alt: 'Changelog' } },
+  ]}
+/>
+```
+
+### Leading image — with trailing action
+
+A Text Button in the row's `trailingIcon` slot — the canonical "directory row + small commit" composition. Reach for it on follow / join / invite rows where the leading Thumbnail anchors the entity and the trailing button is the only commit. Row body stays informational.
+
+```preview
+list/standard-image-with-trailing-action
+---
+import { Button, List } from '@teamblind-chorus/ui';
+
+<List
+  aria-label="Suggested channels"
+  items={[
+    {
+      value: 'product',
+      label: 'Product Design',
+      supportingText: '1,204 colleagues following',
+      thumbnail: { alt: 'Product Design' },
+      trailingIcon: (
+        <Button variant="text" size="small" appearance="accent" onClick={() => {}}>
+          Follow
+        </Button>
+      ),
+    },
+    {
+      value: 'frontend',
+      label: 'Frontend',
+      supportingText: '892 colleagues following',
+      thumbnail: { alt: 'Frontend' },
+      trailingIcon: (
+        <Button variant="text" size="small" appearance="accent" onClick={() => {}}>
+          Follow
+        </Button>
+      ),
+    },
+  ]}
+/>
+```
+
+### Leading image — drill-in rows
+
+Set `nav: true` on a leading-image row for an avatar-anchored row that routes to another surface (channel → channel detail, person → profile). The whole row is the click target; the chevron is decorative. A per-item `trailingIcon` overrides the chevron.
+
+```preview
+list/standard-image-nav
+---
+import { List } from '@teamblind-chorus/ui';
+
+<List
+  items={[
+    { value: 'design-weekly', label: 'Design Weekly',   supportingText: '2.3k members', thumbnail: { alt: 'Design Weekly' }, nav: true },
+    { value: 'frontend',      label: 'Frontend Friday', supportingText: '1.1k members', thumbnail: { alt: 'Frontend Friday' }, nav: true },
+    { value: 'changelog',     label: 'Changelog',       supportingText: '840 members',  thumbnail: { alt: 'Changelog' }, nav: true },
+  ]}
+/>
+```
+
+### Leading image — without divider
+
+`divider: false` on a row suppresses its bottom hairline rule — useful when a visual group ends mid-stack and the divider would visually fence off the next group from its label. The row's footprint and inline padding stay unchanged.
+
+```preview
+list/standard-image-without-divider
+---
+import { List } from '@teamblind-chorus/ui';
+
+<List
+  items={[
+    { value: 'design-weekly', label: 'Design Weekly', supportingText: 'Updated 2h ago', thumbnail: { alt: 'Design Weekly' } },
+    { value: 'frontend',      label: 'Frontend Friday', supportingText: 'Updated 1d ago', thumbnail: { alt: 'Frontend Friday' }, divider: false },
+    { value: 'changelog',     label: 'Changelog',       supportingText: 'Updated 3d ago', thumbnail: { alt: 'Changelog' } },
+  ]}
+/>
+```
+
+## Slots
+
+- **container** — outer vertical stack (delegates to family).
+- **row** — single list item; whole row is the click target.
+- **leading** *(optional)* — one of two mutually exclusive types, omitted when the row passes neither (the label then starts at the row's inline edge):
+  - *image type* — a [Thumbnail](../thumbnail/thumbnail.md) at the 40 rung, vertically centred, painted when the row passes `thumbnail`. `thumbnail` props (`src`, `alt`, `updateDot`, `logoBadge`) forward verbatim. Gap to the text group is `12px` (`sys.layout.inline.lg`).
+  - *icon type* — a 24px (`sys.icon.lg`) decorative glyph in `onSurfaceVariant`, vertically centred, painted when the row passes `icon`. Gap to the text group is `8px` (`sys.layout.inline.md`); the slot enforces the 24 rung regardless of the glyph's own `size`.
+- **label** — primary row text. 16px / Regular / `onSurface`. Truncates first against an inline `count`.
+- **count** *(optional, per-row)* — inline node to the right of the label on the same line, separated by `4px` (`sys.layout.inline.sm`). Canonical fill: a numeric [Badge](../badge/badge.md). Tiles tight to the label inside the text group (distinct from `trailingIcon` at the trailing edge); composes with the nav chevron on the same row.
+- **supportingText** *(optional)* — secondary line under label. Sits directly under the label with no extra gap.
+- **trailingIcon** *(optional, per-row)* — consumer-supplied node at the trailing edge. Each row decides independently. Canonical fills: a 16px icon (e.g. an external-link mark), or `<Button variant="text" appearance="accent">` (Follow / Invite) on leading-image rows. A status badge does **not** go here — it tiles next to the label via `count`. Its own hit target: a tap on this slot stops propagating before it reaches the row's `onClick`. Overrides the nav chevron on the same row.
+- **navChevron** *(optional, per-row)* — auto-rendered 16px right-pointing chevron, painted when the row sets `nav: true`. `onSurfaceVariant`, decorative; never a separate hit target.
+- **divider** *(optional, per-row)* — pass `divider: false` to suppress the row's bottom hairline. Use when a visual group ends mid-stack and the divider would visually fence off the next group from its label.
+
+## States
+
+No `selected` state — selection belongs to the [Radio sub](./radio.md).
+
+## Focus indicator
+
+Inward 3-layer ring inside the row's bounds — see the family-wide [Focus indicator](./list.md#cross-sub-contract). The preview pins **My channels** to its focused state via `forcedState: 'focused'` for static inspection.
+
+```preview
+list/focus-indicator
+---
+import { List } from '@teamblind-chorus/ui';
+
+<List
+  items={[
+    { value: 'profile',  label: 'Profile',         supportingText: 'Display name, avatar, bio', nav: true },
+    { value: 'channels', label: 'My channels',     supportingText: '12 joined · 3 muted', nav: true, forcedState: 'focused' },
+    { value: 'notif',    label: 'Notifications', nav: true },
+    { value: 'privacy',  label: 'Privacy', nav: true },
+    { value: 'account',  label: 'Account', nav: true },
+  ]}
+/>
+```
+
+## Behavior
+
+- **Keyboard navigation.** Arrow ↑ / ↓ moves focus between rows; Home / End jump to first / last.
+- **Row click target.** The whole row is clickable when `onClick` is bound to the item. The leading thumbnail is never a separate hit target.
+- **Trailing slot is its own hit target.** Clicks inside `trailingIcon` stop propagating before they reach the row — wire a favorite / mute / pin toggle there without it committing the row's primary action.
+</content>