@forwardreach/saas-ui 0.10.4 → 0.12.0

package/CHANGELOG.md

@@ -1,29 +1,249 @@
 # Changelog
 
+## 0.12.0
+
+### Minor Changes
+
+- **`SelectMenu`: a single choice whose popup this package draws.** A native
+  `<select>` styled down to a line of text has exactly one piece of chrome left —
+  the platform's own popup — and it is the one piece CSS cannot reach. This is
+  the component for that case. It is additive in API — no existing export
+  changes shape — and the one existing call site that renders differently is
+  named below.
+
+  - **Two trigger presentations.** `variant="control"` (the default) is `Select`'s
+    bounded field with a chevron, in the same `sm`/`md` scale, so swapping one for
+    the other returns the same field with a themed popup. `variant="inline"` draws
+    no box at rest: the trigger is the label's own text at the size of the line it
+    sits in, with the hover surface, the chevron, and a focus ring without an
+    offset arriving on hover, focus, and while open. The inline variant is why the
+    component exists, and shipping it is what keeps a consumer from forcing a 40px
+    bordered control down to a 20px line through `className` and child selectors.
+  - **The same options `Combobox` takes**, groups included: consecutive options
+    declaring one group collapse under one heading, an ungrouped option ends the
+    run above it, and the component never reorders. The option list, its keyboard
+    model, and its group semantics are `Combobox`'s own, extracted into an
+    internal module both components render — `Combobox`'s suite passes unedited
+    across the extraction.
+  - **A filter once the list is long enough**, at `SELECT_MENU_SEARCH_THRESHOLD`
+    options (eight) and not before; `searchable` forces it either way. With a
+    filter, focus stays in the field while the list is navigated; without one, the
+    listbox itself holds focus. Both run the listbox pattern through
+    `aria-activedescendant`.
+  - **`emptyLabel`** offers clearing the value as a row that reports `""`.
+    **`placeholder`** is what the trigger shows when no option matches `value` — a
+    field holding nothing, or one holding a value the list no longer offers, which
+    is neither shown as chosen nor replaced by whatever happens to be first.
+  - **`defaultOpen`, `open`, `onOpenChange`**, for the consumer whose control
+    appears in response to an edit gesture: open the popup as the row enters edit
+    mode, so choosing costs one click rather than two, and read a close that
+    followed no `onValueChange` as a cancel.
+  - **Form participation and `FormField` wiring** exactly as `RoleMenu` does
+    them: a hidden input when `name` is set, nothing submitted while disabled, the
+    enclosing field's label naming the trigger, and `aria-label` composing purpose
+    with the current value.
+
+  **The option list is drawn to be read as the choice**, which is the one
+  visible change to an existing component: `Combobox` renders the same list, so
+  its popup picks all three corrections up. Options take the full text colour
+  rather than the muted one, which came from a popup that hangs under a field
+  holding the answer; where the popup *is* the choice, options dimmer than the
+  heading over them read as less available than the label for them. The current
+  option carries a check and a medium weight rather than a fill alone, because
+  that fill is `--ssui-surface-muted` on `--ssui-surface-elevated` — a clear step
+  in a light theme and almost none in a dark one. And the keyboard highlight now
+  wins the background over the selected fill, so it stays visible on the selected
+  row, which for `SelectMenu` is the row a popup opens on.
+
+  **A bounded popup starts at the field's own width** and grows only if an option
+  needs more, so the two read as one control. It used to carry a fixed minimum for
+  both variants, which made the popup of any field narrower than that minimum
+  overhang it. An inline trigger is as wide as its text, which is no width for a
+  list, so it keeps a floor of its own.
+
+  **`Popover`** — `Popover`, `PopoverTrigger`, `PopoverContent`, `PopoverAnchor`,
+  `PopoverClose`, `PopoverPortal` — is exported alongside it: the thin styled
+  wrapper `DropdownMenu` already has, on `@radix-ui/react-popover`, a new direct
+  dependency sharing its internals with the dialog and dropdown-menu packages
+  already here. `SelectMenu` is built on it rather than on `DropdownMenu` because a
+  menu's roving focus and typeahead both fight a filter field.
+
+  **What this does not do, on purpose.** It does not replace `Select`. On a phone
+  a native `<select>` opens the platform's own picker — thumb-sized, familiar,
+  outside the page — and `SelectMenu` cannot and will not. For a bounded field in
+  an ordinary form that is worth more than a themed popup, and `Select` stays the
+  default there. `docs/packages/saas-ui.md` now tables all four single-choice
+  controls — `Select`, `SelectMenu`, `Combobox`, `RoleMenu` — and which case each
+  answers, and the three older components' doc comments point at that table
+  rather than carrying partial copies of it. No multi-select: a chip-holding
+  trigger and checkable rows roughly double the API and the test matrix, and are
+  a change of their own.
+
+## 0.11.0
+
+### Minor Changes
+
+- **Four additive form-primitive changes, every default unchanged.** Found by a
+  consumer adopting these components rather than by reading them; grouped because
+  they ship in one release, not because they are otherwise related.
+
+  - **`--ssui-border-control`.** A control's boundary is now separable from a
+    container's edge. Six boundaries read it — `Input`, `Textarea`, `Select`,
+    `Combobox`, `Checkbox`, and `AuditLog`'s filter selects — as
+    `var(--ssui-border-control,var(--ssui-border))`, the fallback pattern
+    `--ssui-switch-track` already uses. The package defines no value for it
+    anywhere, so **this is a visual no-op until a consumer sets it**, and setting
+    it is the whole of the opt-in.
+
+    WCAG 1.4.11 asks 3:1 of a boundary needed to identify an interactive control
+    and exempts a container's edge; those are two jobs and one token was doing
+    both, so raising a text field's edge meant raising eighteen container edges
+    with it. Worth being blunt rather than reassuring about what this does not
+    fix: the package's own `--ssui-border` is `#d0d5dd`, **1.47:1** on white, and
+    that is still what a control boundary resolves to if you do nothing. A
+    default that met the floor would darken every control in every consuming app
+    on a version bump, which is the decision this token exists to hand to the
+    consumer rather than make for them. See the token contract in
+    `docs/packages/saas-ui.md`.
+
+  - **`Select` gains `size`.** `"sm"` is 32px/12px with the chevron re-inset, to
+    sit in a row of `Button size="sm"`. `"md"` is today's styling verbatim and
+    the default. The name is taken over from the native `size` attribute, which
+    sets visible rows on a list-box select and is meaningless on the collapsed
+    control this styles.
+
+  - **`ChoiceCardGroup` gains `variant`.** `"list"` draws one bordered container
+    of divided rows — selection carried by a fill, the radio, and the title's
+    weight rather than a per-option border, with hover scoped to unchosen rows so
+    it cannot dim the chosen one. `"card"` remains the default and is unchanged.
+    Both shapes are legitimate; boxing _only_ the chosen option is the third
+    convention and the one that does not work. `TimeZoneField` takes the same
+    prop and passes it through.
+
+  - **`Combobox` gains `onCreate` / `createLabel` / `isDuplicate`.** When
+    `onCreate` is set, and the trimmed query matches no existing option, a create
+    entry joins the listbox as a real option — arrow-navigable,
+    Enter-committable, in the same index space — so no consumer needs a parallel
+    keyboard path to offer one row. It suppresses `emptyMessage`, and passes the
+    query to `onCreate` unnormalized, because what the created thing is called is
+    a product rule.
+
+    `isDuplicate` is what decides "no existing option", and it defaults to
+    case-insensitive equality on an option's `label` or `value`. Exact equality
+    would be the obvious default and is the wrong one: the offer is only honest
+    if it agrees with the normalization the consumer was just handed, and casing
+    is the cheapest way for the two to disagree — with `urgent` in the list,
+    typing `Urgent` would offer to create it, the consumer would lowercase it,
+    and the user has taken an action that did nothing or made a duplicate. Pass
+    your own when your rule goes further than casing.
+
+  Four more landed after a consumer reviewed the running app, and they are the
+  reason to take this release rather than the one before it:
+
+  - **`ChoiceCard` no longer misreports what was saved.** React resets a
+    `<form action={fn}>` once the action resolves, and a reset restores every
+    control to its content attribute. A controlled radio only ever had its
+    `checked` _property_ written, so after a successful save the group snapped
+    back to whatever was selected on first render, while the surrounding state,
+    the hidden inputs, and the stored value all held the new selection. The write
+    succeeded and only the control disagreed, which reads to a user as "my change
+    did not take". `defaultChecked` now tracks the selection.
+
+  - **`Combobox`'s field is a search box, not editable text.** It used to keep
+    the committed label in the input, so a caret landed inside it, typing
+    appended to it, and the result matched nothing — and it invited the belief
+    that the text was the value and could be corrected in place, which it never
+    was. Focus now starts an empty query and the committed value moves to the
+    placeholder, so it stays visible while searching and cannot be edited into
+    something that was never a choice.
+
+  - **`ComboboxOption.inputLabel`** — the text the field shows once an option is
+    committed, defaulting to `label`. Where `trailing` carries part of an
+    option's identity rather than decoration, the collapsed field used to drop
+    it. `TimeZoneField` uses it to keep a chosen zone's GMT offset on screen.
+
+  - **A consumer's `filter` now runs with an empty query** rather than being
+    skipped while nothing is typed. A predicate that only searches is
+    unaffected; one that _excludes_ had its rule ignored for exactly as long as
+    the field was empty, which is the state the popup opens in.
+
+  Two more came out of the same consumer looking at the running app a second
+  time, and both are visible changes to what this package already rendered:
+
+  - **`ChoiceCard`'s description is body text.** It was `text-xs` on
+    `--ssui-text-subtle`, a pairing that fails the contrast floor on the row
+    most likely to be read: measured against a selected row's
+    `--ssui-accent-subtle` fill in a consuming app, 2.87:1 light and 3.77:1
+    dark, with unselected rows at 3.31:1 light, where 12px body text wants
+    4.5:1. It is now `text-sm` on `--ssui-text-muted`, which clears the floor on
+    every one of those pairings. The size half matters independently: the local
+    treatments this component replaced across one consumer ran 14px, 12px, and
+    11px, and normalising on the smallest silently shrank the caller whose
+    descriptions are whole sentences. **This changes existing rendering** — a
+    caller wanting a terser hint can pass `children` and size it itself.
+
+  - **`Combobox` gains `keepOpenOnSelect`.** Off by default. When set, a commit
+    clears the query and leaves the popup open instead of closing, for the
+    picker that adds to a set rather than setting a value. Without it such a
+    caller pays a full open-the-control round trip per item, and — if it keeps
+    its own panel open around the control, as a tag picker does — is left
+    showing an empty field with no list beneath it, which reads as inert rather
+    than as ready for the next choice.
+
+  A review of the change closed four more gaps in it, three of them in the parts
+  it had shipped to improve accessibility:
+
+  - **The list variant no longer clips its own focus ring.** The container
+    carried `overflow-hidden` to keep the first and last row's fills inside its
+    radius. A Tailwind ring is a box-shadow drawn _outside_ the element, and a
+    list row has no border or radius of its own, so it fills the container's
+    padding box exactly — the clip amputated both vertical sides of every row's
+    focus indicator plus the outer edges of the first and last. A keyboard user
+    tabbing in saw one horizontal line, easily read as the divider. The rows now
+    round their own outer corners instead, which squares the fills off without
+    clipping anything.
+
+  - **The committed value is no longer styled as a hint.** Moving it into the
+    placeholder gave it `--ssui-text-subtle` — the pairing this same release
+    retired from `ChoiceCard`'s description for measuring 2.87:1. It now takes
+    `--ssui-text-muted` while a true placeholder stays subtle, and it is exposed
+    through `aria-describedby` as well, because screen-reader handling of
+    placeholder text is inconsistent and the field is empty while you search.
+
+  - **The default filter searches `inputLabel`.** An option showing
+    `Asia/Tokyo (GMT+09:00)` in the collapsed field was not findable by that
+    string once focus cleared the box — displayed but unsearchable.
+
+  - **`AuditLog`'s filters are the shared `Select`.** They were a hand-rolled
+    `<select>` on a local class string, which existed only because `Select` had
+    no size that fitted an inline filter row; `size="sm"` is that size. The copy
+    had already drifted — no focus ring, no chevron. **This changes existing
+    rendering**: the filters are 32px rather than 36px and gain the chevron and
+    the focus ring.
+
+  Existing behavior is otherwise unchanged: of the 174 tests predating this
+  release, the only two edited are the `TimeZoneField` assertions that pinned the
+  bare zone name in the collapsed field — the contract `inputLabel` deliberately
+  changes.
+
 ## 0.10.4
 
 ### Patch Changes
 
-- First release published with an npm provenance attestation. The package contents
-  are unchanged from `0.10.2`; what is new is that the registry now records where
-  this artifact came from — this repository, the commit it was built from, and the
-  workflow run that built it — signed by the CI identity and recorded in a public
-  transparency log, so a consumer can check a version's origin rather than trust
-  its number.
-
-  That check is what was missing when two vendored tarballs, `@forwardreach/saas-ui@0.9.1`
-  and `@forwardreach/saas-mcp@0.1.3`, turned out to carry versions no commit in this
-  repository ever produced. One left a consumer a month stale behind a _higher_
-  version number than the real thing. Nothing in the pipeline could have caught
-  either, because a locally packed tarball records no origin at all.
+- **No provenance attestation, and none is coming.** Like `0.10.3`, this release
+  existed to carry one and does not; contents remain identical to `0.10.2`.
 
-  `0.10.3` was meant to be this release and shipped without an attestation; see its
-  entry for why. Both numbers stay retired rather than reissued.
+  npm refuses a provenance attestation whose GitHub source repository is
+  private, and this repository is private — the package being public on npm is
+  not sufficient, because the source repository is what an attestation has to
+  name. So no version of this package will carry one unless that changes. Use
+  the version lineage and the changelog to answer "which code is this?", and see
+  `future.md` for the packing-provenance work that remains open.
 
-  Verify an installed copy with `npm audit signatures`, or from a clone of this
-  repository with `node scripts/verify-provenance.mjs @forwardreach/saas-ui@<version>`.
-  Neither needs registry credentials. Versions published before this one cannot
-  gain an attestation retroactively.
+  This was established the expensive way: a third attempt generated and signed a
+  sigstore bundle and the registry rejected it with `422 ... Unsupported GitHub
+Actions source repository visibility: "private"`. That attempt published
+  nothing, so `0.10.4` is the current release.
 
 ## 0.10.3
 
@@ -32,22 +252,21 @@
 - **No provenance attestation, despite what this release was for.** `0.10.3` was
   published to be the first artifact carrying one, and it is not: the package
   contents are identical to `0.10.2` and the registry reports no
-  `dist.attestations` for it. Use `0.10.4` or later if you want a version whose
-  origin you can check; this number is spent and will not be reissued.
-
-  The cause is worth recording, because it is exactly the silent failure the
-  verification step was added to catch. `changeset publish` detects a pnpm
-  workspace and shells out to `pnpm publish`, and pnpm does not read arbitrary
-  `NPM_CONFIG_*` environment variables into its configuration — it reads
-  `provenance` as an rc option only. So `NPM_CONFIG_PROVENANCE=true` was
-  accepted by the shell, ignored by the publisher, and the package went out
-  with no attestation and no warning of any kind. Nothing in the publish output
-  suggested anything was wrong. `pnpm config get provenance` even reports
-  `true` for that env var, so it is not a usable pre-flight check either.
-
-  The release failed red rather than reporting success, which is the property
-  that mattered: the post-publish check queried the registry, found no
-  attestation, and stopped the run before tags were pushed.
+  `dist.attestations` for it. It is real and installable; it is simply the same
+  code as `0.10.2` under a number that bought nothing. See `0.10.4`.
+
+  Two mechanisms were tried before the real blocker surfaced, and both failed
+  silently, which is worth recording. `changeset publish` detects a pnpm
+  workspace and shells out to `pnpm publish`; pnpm does not read arbitrary
+  `NPM_CONFIG_*` environment variables into its configuration, and
+  libnpmpublish gates provenance on `provenance === true`, a strict boolean
+  identity check. So both `NPM_CONFIG_PROVENANCE=true` (this release) and
+  `provenance=true` in an rc file (`0.10.4`) were accepted by the shell and
+  ignored by the publisher, with nothing in the publish output to say so.
+  `pnpm config get provenance` even reports `true` for the environment variable
+  the publisher ignores, so it is not a usable pre-flight check.
+
+  Neither number is reissued.
 
 ## 0.10.2
 

package/dist/components/audit-log.js

@@ -1,7 +1,7 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import * as React from "react";
-import { cn } from "../utils/cn.js";
+import { Select } from "./select.js";
 import { SettingsSection } from "./settings-section.js";
 function defaultFormatTimestamp(iso) {
     const date = new Date(iso);
@@ -9,7 +9,6 @@ function defaultFormatTimestamp(iso) {
         return iso;
     return new Intl.DateTimeFormat(undefined, { dateStyle: "medium", timeStyle: "short" }).format(date);
 }
-const selectClass = "h-9 rounded-[var(--ssui-radius)] border border-[color:var(--ssui-border)] bg-[color:var(--ssui-surface)] px-2 text-xs text-[color:var(--ssui-text)]";
 const targetBadgeClass = "inline-flex items-center gap-1 rounded-md bg-[color:var(--ssui-surface-muted)] px-1.5 py-0.5 text-xs text-[color:var(--ssui-text-muted)]";
 /**
  * A domain-agnostic audit log: a titled section with optional filter dropdowns,
@@ -20,5 +19,11 @@ const targetBadgeClass = "inline-flex items-center gap-1 rounded-md bg-[color:va
  * reuse it directly.
  */
 export function AuditLog({ title = "Activity", description, icon, entries, filters = [], loading = false, error, emptyState = "No activity has been recorded.", renderTargetLink, formatTimestamp = defaultFormatTimestamp, }) {
-    return (_jsxs(SettingsSection, { action: _jsx("span", { className: "text-xs text-[color:var(--ssui-text-muted)]", children: loading ? "Loading..." : `${entries.length} events` }), description: description, icon: icon, title: title, children: [filters.length > 0 && (_jsx("div", { className: "flex flex-wrap gap-2", children: filters.map((filter) => (_jsx("select", { "aria-label": filter.ariaLabel, className: cn(selectClass, "min-w-32"), onChange: (event) => filter.onChange(event.target.value), value: filter.value, children: filter.options.map((option) => (_jsx("option", { value: option.value, children: option.label }, option.value))) }, filter.id))) })), error && _jsx("div", { className: "mt-2 text-xs text-red-600", children: error }), _jsxs("div", { className: "mt-3 divide-y divide-[color:var(--ssui-border)] rounded-[var(--ssui-radius)] border border-[color:var(--ssui-border)]", children: [entries.length === 0 && _jsx("div", { className: "px-3 py-6 text-center text-sm text-[color:var(--ssui-text-muted)]", children: emptyState }), entries.map((entry) => (_jsxs("details", { children: [_jsxs("summary", { className: "grid cursor-pointer list-none gap-2 px-3 py-3 md:grid-cols-[11rem_minmax(0,1fr)_8rem_8rem]", children: [_jsx("div", { className: "text-xs text-[color:var(--ssui-text-muted)]", children: formatTimestamp(entry.timestamp) }), _jsxs("div", { className: "min-w-0", children: [_jsx("div", { className: "truncate text-sm font-medium", children: entry.title }), _jsxs("div", { className: "mt-1 flex flex-wrap items-center gap-1 text-xs text-[color:var(--ssui-text-muted)]", children: [entry.actorLabel && _jsx("span", { className: "truncate font-medium text-[color:var(--ssui-text)]", children: entry.actorLabel }), (entry.badges ?? []).map((badge) => (_jsx("span", { children: badge }, badge)))] })] }), _jsx("div", { className: "text-xs text-[color:var(--ssui-text-muted)]", children: entry.outcome }), _jsx("div", { className: "flex flex-wrap gap-1", children: (entry.targetIds ?? []).slice(0, 2).map((targetId) => (_jsx(React.Fragment, { children: renderTargetLink ? renderTargetLink(targetId) : _jsx("span", { className: targetBadgeClass, children: "Record" }) }, targetId))) })] }), _jsxs("div", { className: "space-y-3 border-t border-[color:var(--ssui-border)] px-3 py-3", children: [entry.details && entry.details.length > 0 && (_jsx("div", { className: "grid gap-2 text-xs text-[color:var(--ssui-text-muted)] md:grid-cols-3", children: entry.details.map((detail) => (_jsxs("div", { children: [detail.label, ": ", detail.value] }, detail.label))) })), entry.targetIds && entry.targetIds.length > 0 && (_jsx("div", { className: "flex flex-wrap gap-1.5", children: entry.targetIds.map((targetId) => (_jsx(React.Fragment, { children: renderTargetLink ? renderTargetLink(targetId) : _jsxs("span", { className: targetBadgeClass, children: ["Record ", targetId] }) }, targetId))) })), entry.metadata !== undefined && entry.metadata !== null && (_jsx("pre", { className: "max-h-56 overflow-auto rounded-[var(--ssui-radius)] border border-[color:var(--ssui-border)] bg-[color:var(--ssui-surface-muted)] p-3 font-mono text-xs text-[color:var(--ssui-text-muted)]", children: JSON.stringify(entry.metadata, null, 2) }))] })] }, entry.id)))] })] }));
+    return (_jsxs(SettingsSection, { action: _jsx("span", { className: "text-xs text-[color:var(--ssui-text-muted)]", children: loading ? "Loading..." : `${entries.length} events` }), description: description, icon: icon, title: title, children: [filters.length > 0 && (_jsx("div", { className: "flex flex-wrap gap-2", children: filters.map((filter) => (
+                // The shared small select rather than a local class string. This
+                // was a hand-rolled `<select>` only because `Select` had no size
+                // that fitted an inline filter row; it has one now, and keeping the
+                // copy meant a second control drifting away from the first — it had
+                // already lost the focus ring and the chevron.
+                _jsx(Select, { "aria-label": filter.ariaLabel, className: "min-w-32", onChange: (event) => filter.onChange(event.target.value), size: "sm", value: filter.value, children: filter.options.map((option) => (_jsx("option", { value: option.value, children: option.label }, option.value))) }, filter.id))) })), error && _jsx("div", { className: "mt-2 text-xs text-red-600", children: error }), _jsxs("div", { className: "mt-3 divide-y divide-[color:var(--ssui-border)] rounded-[var(--ssui-radius)] border border-[color:var(--ssui-border)]", children: [entries.length === 0 && _jsx("div", { className: "px-3 py-6 text-center text-sm text-[color:var(--ssui-text-muted)]", children: emptyState }), entries.map((entry) => (_jsxs("details", { children: [_jsxs("summary", { className: "grid cursor-pointer list-none gap-2 px-3 py-3 md:grid-cols-[11rem_minmax(0,1fr)_8rem_8rem]", children: [_jsx("div", { className: "text-xs text-[color:var(--ssui-text-muted)]", children: formatTimestamp(entry.timestamp) }), _jsxs("div", { className: "min-w-0", children: [_jsx("div", { className: "truncate text-sm font-medium", children: entry.title }), _jsxs("div", { className: "mt-1 flex flex-wrap items-center gap-1 text-xs text-[color:var(--ssui-text-muted)]", children: [entry.actorLabel && _jsx("span", { className: "truncate font-medium text-[color:var(--ssui-text)]", children: entry.actorLabel }), (entry.badges ?? []).map((badge) => (_jsx("span", { children: badge }, badge)))] })] }), _jsx("div", { className: "text-xs text-[color:var(--ssui-text-muted)]", children: entry.outcome }), _jsx("div", { className: "flex flex-wrap gap-1", children: (entry.targetIds ?? []).slice(0, 2).map((targetId) => (_jsx(React.Fragment, { children: renderTargetLink ? renderTargetLink(targetId) : _jsx("span", { className: targetBadgeClass, children: "Record" }) }, targetId))) })] }), _jsxs("div", { className: "space-y-3 border-t border-[color:var(--ssui-border)] px-3 py-3", children: [entry.details && entry.details.length > 0 && (_jsx("div", { className: "grid gap-2 text-xs text-[color:var(--ssui-text-muted)] md:grid-cols-3", children: entry.details.map((detail) => (_jsxs("div", { children: [detail.label, ": ", detail.value] }, detail.label))) })), entry.targetIds && entry.targetIds.length > 0 && (_jsx("div", { className: "flex flex-wrap gap-1.5", children: entry.targetIds.map((targetId) => (_jsx(React.Fragment, { children: renderTargetLink ? renderTargetLink(targetId) : _jsxs("span", { className: targetBadgeClass, children: ["Record ", targetId] }) }, targetId))) })), entry.metadata !== undefined && entry.metadata !== null && (_jsx("pre", { className: "max-h-56 overflow-auto rounded-[var(--ssui-radius)] border border-[color:var(--ssui-border)] bg-[color:var(--ssui-surface-muted)] p-3 font-mono text-xs text-[color:var(--ssui-text-muted)]", children: JSON.stringify(entry.metadata, null, 2) }))] })] }, entry.id)))] })] }));
 }

package/dist/components/checkbox.js

@@ -9,7 +9,7 @@ import { useFormFieldProps } from "./form-field.js";
  * support and platform semantics come from the browser, and only the box itself
  * needs theming. Participates in `FormField` wiring like the other controls.
  */
-export const Checkbox = React.forwardRef(({ className, ...props }, ref) => (_jsx("input", { ref: ref, type: "checkbox", className: cn("size-4 shrink-0 cursor-pointer rounded-[calc(var(--ssui-radius)/2)] border border-[color:var(--ssui-border)] accent-[color:var(--ssui-primary)] transition-shadow focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[color:var(--ssui-focus-ring)] focus-visible:ring-offset-2 focus-visible:ring-offset-[color:var(--ssui-bg)] disabled:cursor-not-allowed disabled:opacity-50", className), ...useFormFieldProps(props) })));
+export const Checkbox = React.forwardRef(({ className, ...props }, ref) => (_jsx("input", { ref: ref, type: "checkbox", className: cn("size-4 shrink-0 cursor-pointer rounded-[calc(var(--ssui-radius)/2)] border border-[color:var(--ssui-border-control,var(--ssui-border))] accent-[color:var(--ssui-primary)] transition-shadow focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[color:var(--ssui-focus-ring)] focus-visible:ring-offset-2 focus-visible:ring-offset-[color:var(--ssui-bg)] disabled:cursor-not-allowed disabled:opacity-50", className), ...useFormFieldProps(props) })));
 Checkbox.displayName = "Checkbox";
 const CheckboxGroupContext = React.createContext(null);
 /**

package/dist/components/choice-card.d.ts

@@ -1,4 +1,5 @@
 import * as React from "react";
+export type ChoiceGroupVariant = "card" | "list";
 export interface ChoiceCardGroupProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange"> {
     /** Form field name shared by the underlying radios. */
     name?: string;
@@ -9,13 +10,32 @@ export interface ChoiceCardGroupProps extends Omit<React.HTMLAttributes<HTMLDivE
     onValueChange?: (value: string) => void;
     /** Accessible label for the radio group. */
     "aria-label"?: string;
+    /**
+     * How the group is drawn. Defaults to `"card"`.
+     *
+     * `"card"` boxes every option and lays them out in a responsive two-column
+     * grid — the selection-card treatment, for a choice that earns that weight.
+     * `"list"` draws one bordered container with divided rows inside it.
+     *
+     * The two are not interchangeable and the reason to have both is that boxing
+     * *only the chosen* option is the third convention, and it is the one that
+     * does not work: it reads as that row being the only live control on the
+     * page. So either every option gets a border or none does. Boxing none is
+     * right for an ordinary settings question, but leaves the options floating
+     * with nothing saying they are one question — a pair of them in a two-column
+     * grid drifts far enough apart to read as two unrelated fields. The
+     * container answers that without spending a border per option.
+     */
+    variant?: ChoiceGroupVariant;
 }
 /**
- * Radio group rendered as selectable bordered cards. Uses native radio
- * inputs, so form participation and arrow-key navigation between cards come
- * from the browser. Children are `ChoiceCard`s.
+ * Radio group rendered as selectable cards or as a bordered list. Uses native
+ * radio inputs, so form participation and arrow-key navigation between options
+ * come from the browser. Children are `ChoiceCard`s, which read the variant
+ * from this group rather than taking it themselves — a `ChoiceCard` outside a
+ * group is already an error, so the context is where the variant belongs.
  */
-export declare function ChoiceCardGroup({ name, value, defaultValue, onValueChange, className, children, ...props }: ChoiceCardGroupProps): import("react/jsx-runtime").JSX.Element;
+export declare function ChoiceCardGroup({ name, value, defaultValue, onValueChange, variant, className, children, ...props }: ChoiceCardGroupProps): import("react/jsx-runtime").JSX.Element;
 export interface ChoiceCardProps extends Omit<React.LabelHTMLAttributes<HTMLLabelElement>, "title"> {
     /** Value submitted when this card is selected. */
     value: string;
@@ -26,8 +46,10 @@ export interface ChoiceCardProps extends Omit<React.LabelHTMLAttributes<HTMLLabe
     disabled?: boolean;
 }
 /**
- * One selectable card inside a `ChoiceCardGroup`: a bordered label wrapping a
- * native radio plus title and supporting text. The selected card gets the
- * emphasized border and muted fill.
+ * One option inside a `ChoiceCardGroup`: a label wrapping a native radio plus
+ * title and supporting text. In the card variant it is a bordered box whose
+ * selected state is an emphasized border and muted fill; in the list variant
+ * it is a divided row that carries no border of its own and marks selection
+ * with a fill.
  */
 export declare function ChoiceCard({ value, title, description, disabled, className, children, ...props }: ChoiceCardProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/choice-card.js

@@ -4,11 +4,13 @@ import * as React from "react";
 import { cn } from "../utils/cn.js";
 const ChoiceCardGroupContext = React.createContext(null);
 /**
- * Radio group rendered as selectable bordered cards. Uses native radio
- * inputs, so form participation and arrow-key navigation between cards come
- * from the browser. Children are `ChoiceCard`s.
+ * Radio group rendered as selectable cards or as a bordered list. Uses native
+ * radio inputs, so form participation and arrow-key navigation between options
+ * come from the browser. Children are `ChoiceCard`s, which read the variant
+ * from this group rather than taking it themselves — a `ChoiceCard` outside a
+ * group is already an error, so the context is where the variant belongs.
  */
-export function ChoiceCardGroup({ name, value, defaultValue, onValueChange, className, children, ...props }) {
+export function ChoiceCardGroup({ name, value, defaultValue, onValueChange, variant = "card", className, children, ...props }) {
     const generatedName = React.useId();
     const [uncontrolledValue, setUncontrolledValue] = React.useState(defaultValue);
     const selected = value ?? uncontrolledValue;
@@ -20,13 +22,27 @@ export function ChoiceCardGroup({ name, value, defaultValue, onValueChange, clas
                 setUncontrolledValue(next);
             onValueChange?.(next);
         },
-    }), [name, generatedName, selected, value, onValueChange]);
-    return (_jsx("div", { role: "radiogroup", className: cn("grid gap-2 md:grid-cols-2", className), ...props, children: _jsx(ChoiceCardGroupContext.Provider, { value: contextValue, children: children }) }));
+        variant,
+    }), [name, generatedName, selected, value, onValueChange, variant]);
+    return (_jsx("div", { role: "radiogroup", className: cn(variant === "list"
+            ? // Deliberately *not* `overflow-hidden`, which is the obvious way to
+                // stop the first and last row's fills overhanging the container's
+                // radius and is the wrong one. A Tailwind ring is a box-shadow drawn
+                // outside the element's border box, and a list row fills this
+                // container's padding box exactly — so clipping here amputates the
+                // row's own focus ring: both vertical sides on every row, plus the
+                // top of the first and the bottom of the last. A keyboard user
+                // tabbing in would see a stray horizontal line easily read as the
+                // `divide-y` rule. The rows round their own outer corners instead.
+                "divide-y divide-[color:var(--ssui-border)] rounded-[var(--ssui-radius)] border border-[color:var(--ssui-border)] bg-[color:var(--ssui-surface)]"
+            : "grid gap-2 md:grid-cols-2", className), ...props, children: _jsx(ChoiceCardGroupContext.Provider, { value: contextValue, children: children }) }));
 }
 /**
- * One selectable card inside a `ChoiceCardGroup`: a bordered label wrapping a
- * native radio plus title and supporting text. The selected card gets the
- * emphasized border and muted fill.
+ * One option inside a `ChoiceCardGroup`: a label wrapping a native radio plus
+ * title and supporting text. In the card variant it is a bordered box whose
+ * selected state is an emphasized border and muted fill; in the list variant
+ * it is a divided row that carries no border of its own and marks selection
+ * with a fill.
  */
 export function ChoiceCard({ value, title, description, disabled, className, children, ...props }) {
     const group = React.useContext(ChoiceCardGroupContext);
@@ -34,7 +50,71 @@ export function ChoiceCard({ value, title, description, disabled, className, chi
         throw new Error("ChoiceCard must be rendered inside a ChoiceCardGroup");
     }
     const selected = group.value === value;
-    return (_jsxs("label", { className: cn("flex cursor-pointer gap-2 rounded-[var(--ssui-radius)] border px-3 py-2 transition-colors has-[:focus-visible]:ring-2 has-[:focus-visible]:ring-[color:var(--ssui-focus-ring)]", selected
-            ? "border-[color:var(--ssui-border-strong)] bg-[color:var(--ssui-surface-muted)] text-[color:var(--ssui-text)]"
-            : "border-[color:var(--ssui-border)] text-[color:var(--ssui-text-muted)] hover:bg-[color:var(--ssui-overlay-hover)]", disabled && "cursor-not-allowed opacity-50", className), ...props, children: [_jsx("input", { checked: selected, className: "mt-0.5 size-4 shrink-0 accent-current focus-visible:outline-none", disabled: disabled, name: group.name, onChange: () => group.setValue(value), type: "radio", value: value }), _jsxs("span", { className: "min-w-0", children: [_jsx("span", { className: "block text-sm font-medium", children: title }), description ? (_jsx("span", { className: "block text-xs text-[color:var(--ssui-text-subtle)]", children: description })) : null, children] })] }));
+    const list = group.variant === "list";
+    // Keep the radio's *default* in step with its current state, so a form reset
+    // lands on what is selected now rather than on what was selected first.
+    //
+    // This is not defensive coding; it is the difference between a settings form
+    // that reports the truth and one that lies. React resets a `<form action={fn}>`
+    // once the action resolves, and a reset restores every control to its content
+    // attribute. For a controlled radio React only ever writes the `checked`
+    // *property*, so the attribute keeps whatever the first render put there — and
+    // after a successful save the group snaps back to the option that was selected
+    // when the page loaded, while the surrounding state, the hidden inputs, and the
+    // database all hold the new one. The save worked; only the control disagrees,
+    // which is worse than a visible failure.
+    //
+    // `defaultChecked` is the property backing that attribute, so assigning it is
+    // the direct way to say "this is what a reset should return to".
+    const inputRef = React.useRef(null);
+    React.useEffect(() => {
+        if (inputRef.current)
+            inputRef.current.defaultChecked = selected;
+    }, [selected]);
+    return (_jsxs("label", { className: cn("flex cursor-pointer gap-2 transition-colors has-[:focus-visible]:ring-2 has-[:focus-visible]:ring-[color:var(--ssui-focus-ring)]", list
+            ? // No border: the container supplies it, and the dividers between
+                // rows are its `divide-y`. Selection is the fill plus the radio plus
+                // the title's weight — deliberately not a border, because the border
+                // here groups the options rather than marking one of them.
+                //
+                // The first and last rows do round their outer corners, so their
+                // fills square off against the container's radius. That is the job
+                // `overflow-hidden` on the container would have done, moved here
+                // because clipping there would cut the focus ring these rows draw
+                // outside themselves.
+                "items-start gap-3 p-3 first:rounded-t-[var(--ssui-radius)] last:rounded-b-[var(--ssui-radius)]"
+            : "rounded-[var(--ssui-radius)] border px-3 py-2", list
+            ? selected
+                ? // An opaque fill, not an alpha of one: a translucent tint over
+                    // the surface composites to within a value or two of the hover
+                    // highlight, which puts the chosen row and a merely pointed-at
+                    // one at the same weight.
+                    "bg-[color:var(--ssui-accent-subtle)] text-[color:var(--ssui-text)]"
+                : // Hover is scoped to unchosen rows. The hover overlay sits
+                    // *below* the selected fill, so applying it unscoped would
+                    // visibly dim the chosen row when you point at it.
+                    "text-[color:var(--ssui-text-muted)] hover:bg-[color:var(--ssui-overlay-hover)]"
+            : selected
+                ? "border-[color:var(--ssui-border-strong)] bg-[color:var(--ssui-surface-muted)] text-[color:var(--ssui-text)]"
+                : "border-[color:var(--ssui-border)] text-[color:var(--ssui-text-muted)] hover:bg-[color:var(--ssui-overlay-hover)]", disabled && "cursor-not-allowed opacity-50", className), ...props, children: [_jsx("input", { ref: inputRef, checked: selected, 
+                // `accent-current` so the dot is the row's own foreground rather than
+                // the user agent's blue, which matters more in the list variant where
+                // the radio is the primary marker rather than one signal among several.
+                className: "mt-0.5 size-4 shrink-0 accent-current focus-visible:outline-none", disabled: disabled, name: group.name, onChange: () => group.setValue(value), type: "radio", value: value }), _jsxs("span", { className: "min-w-0", children: [_jsx("span", { className: "block text-sm font-medium", children: title }), description ? (
+                    // Same size as the title and one step down in colour, not two. A
+                    // description here is the content that decides the choice — often a
+                    // full sentence — so it is read, not glanced at, and `text-subtle`
+                    // put it below the contrast floor on the row most likely to be read:
+                    // against the selected row's `--ssui-accent-subtle` fill it measured
+                    // 2.87:1 in a consuming app's light theme and 3.77:1 in its dark
+                    // one, where 12px text wants 4.5:1. Unselected rows fared little
+                    // better at 3.31:1 light. `--ssui-text-muted` clears the floor on every one of
+                    // those pairings with room to spare.
+                    //
+                    // 14px rather than 12px because the three-way split this component
+                    // replaced across its consumers ran 14px, 12px, and 11px, and
+                    // normalising on the smallest silently shrank the one caller whose
+                    // descriptions are whole sentences. A caller wanting a terser hint
+                    // can still pass `children` and size it itself.
+                    _jsx("span", { className: "block text-sm text-[color:var(--ssui-text-muted)]", children: description })) : null, children] })] }));
 }