@vegastack/design 0.7.17 → 0.7.19

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/package.json +2 -2
  2. package/skills/vegastack-design-system/SKILL.md +51 -30
  3. package/skills/vegastack-design-system/references/components.md +18 -15
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vegastack/design",
3
- "version": "0.7.17",
3
+ "version": "0.7.19",
4
4
  "description": "VegaStack design system — cn utility, icon runtime, Tailwind v4 preset, and the vegastack-design CLI (tokens ship separately as @vegastack/design-tokens)",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -70,7 +70,7 @@
70
70
  "test": "node test/compare.test.mjs && node test/check-updates.test.mjs && node test/skills-install.test.mjs && node test/doctor.test.mjs"
71
71
  },
72
72
  "dependencies": {
73
- "@vegastack/design-tokens": "^0.7.1",
73
+ "@vegastack/design-tokens": "^0.7.18",
74
74
  "clsx": "^2.1.1",
75
75
  "tailwind-merge": "^3.6.0",
76
76
  "tsconfig-paths": "^4.2.0",
package/skills/vegastack-design-system/SKILL.md CHANGED
@@ -80,6 +80,16 @@ link` (upstream's set, verbatim). `destructive` is a soft tint, not a solid red
80
80
  - **Empty is tiered** — nothing yet, no matches ("Clear filters"), couldn't load (`role="alert"`,
81
81
  "Try again"), blocked. Pick the tier from the empty-state foundation
82
82
  (<https://design.vegastack.com/docs/foundations/empty-states>); never leave a region blank.
83
+ `Empty` always shows an icon (`icon`, `Inbox` by default). In a `DataList`, use `emptyState` for
84
+ "nothing yet" and `noResults={{ onClear }}` for "no matches" (SearchX, "No matches", "Clear
85
+ filters" wired to the FilterBar's `onClear`) — never hand-roll empty markup.
86
+ - **List toolbars are one recipe** — `FilterBar`: search (~320px) left; right, the Filters (n)
87
+ toggle, then views as `Tabs` (default variant, `TabsList size="sm"`, optional leading icons), then
88
+ the layout switch as an icon `ToggleGroup`, furthest right. Filters are `FilterBarFacet` /
89
+ `DateRangeFilter` chips (compact, rounded-md, tinted when set) on the toggled row; people facets
90
+ take `itemToSecondaryLabel={(p) => p.email}`. Use Tabs for scope/views, an icon ToggleGroup for
91
+ List/Board. Tables are `DataList` with `sortable` columns (`compare`, `sortFirst`,
92
+ `sortMode="client"`) and `rowActions` (the ⋯ column, always last); row links are never underlined.
83
93
  - **`alert`** for an in-content notice — `variant` is `default · destructive · success · warning ·
84
94
  info`, each an ink on the `card` surface with a required icon; **`announcement-banner`** only for
85
95
  the full-width inverse strip at the very top of the page.
@@ -102,32 +112,32 @@ info`, each an ink on the `card` surface with a required icon; **`announcement-b
102
112
 
103
113
  A component's name undersells it. Before composing something by hand, check this list:
104
114
 
105
- | Component | What it already does |
106
- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
107
- | `Command` | Renders inline as well as in `CommandDialog` (wide 820px palette by default). `CommandFilters` holds type chips (`ToggleGroup wrap`) and Selects under the input; bare `<CommandFooter />` shows ↵/⌘↵/Esc `Kbd` hints; `CommandLoading` shows the animated search icon. An item's check mark is `data-checked` — visual only, so it is not a form value. |
108
- | `Combobox` | `multiple` with `ComboboxChips`; `filter={null}` hands filtering to your server. |
109
- | `SearchableSelect` | The Select-shaped search picker, with `clearable`. `multiple` for several values; `remote` plus `useAsyncSearch` hands search and paging to your server. |
110
- | `Item` | A link tile with `render={<a />}`; `ItemGroup` gives a set of items list semantics. |
111
- | `DialogContent` · `SheetContent` | `size`: `sm · default · lg · xl` (a side sheet). Never a width class. |
112
- | `DataList` | Per-column `mobile` (`merge` · `visible` · `hidden`), `minWidth`, and `mergedRender` so a merged value keeps its context (`4 to review`), `mergedLayout="line"` for one compact meta line. `DataGrid` adds editing, multi-key sort and a column picker; `Table` is static markup. |
113
- | `DataList` paging and rows | `loadMore` for keyset paging, `getRowHref` for rows that are links, `rowProps` for `data-*` and a `highlighted` new row, `sections` + `getRowSection` for collapsible groups, and `rowActionsColumn` for a per-row menu. |
114
- | `LoadMore` · `useAsyncSearch` | The Load more footer of a keyset list (keeps its width while loading, "Try again", an end caption) · the server-search engine: debounce, dropped stale responses, cursor paging. |
115
- | `SortableList` | `layout="grid"` reorders tiles as well as rows. |
116
- | `FilterBar` / `FilterBuilder` | `FilterBar` is a flat chip row with search, and `FilterBarFacet` is a "Status: Open" facet on `SearchableSelect` (single or `multiple`, local or `remote`); `FilterBuilder` (the `filter-bar-managed` item) edits a nested and/or tree over your field vocabulary. All controlled. |
117
- | `Stat` | `StatDelta` for change, `StatEmpty` for nothing to report. |
118
- | `PropertyList` · `DataList` · `SettingsRow` | A record's facts · many records · one setting with its control. |
119
- | `ActionBar` | The docked bar for bulk selection ("5 selected"), unsaved changes and batch progress. |
120
- | `TruncatedText` · `IconText` · `TableCellText` | Overflow detection, hover and keyboard reveal, and tap-to-toggle on touch. |
121
- | `RelativeTime` | `mode="ago"` ("3 minutes ago") or `mode="day"` ("Yesterday"). |
122
- | `EditableCell` · `AutoSaveInput` · `useInlineEdit` | Click-to-edit in a table (`wrap` + `flush` for a page title) · a field that saves as you type, with its status · the hook `EditableCell` is built on. |
123
- | `AttachmentGroup` · `Dropzone` · `useFileDrop` | A file list with per-file state · a drop target · the drop and paste engine. |
124
- | `PageHeader` | Title, description, `breadcrumb`, a back link (`backHref`) and `actions`. |
125
- | `MultiStepForm` · `Stepper` · `Questionnaire` · `Tabs` | A form in steps · progress display (`navigable` on request) · one question at a time · peer regions. |
126
- | `NativeSelect` | The platform `<select>`, so a touch device opens its own picker. |
127
- | `Board` | A column's `lockedReason` explains why it cannot take a card; `itemLinkRender` is a template, the card's `href` wins. |
128
- | `AudioPlayer` | `mediaRef` to drive playback, a transcript button and a waveform; `docked` pins it to the bottom of a scroll column, `onOpenChange` adds its close button, `actionsRef` seeks it, and `onSourceExpired` renews an expired signed URL once. |
129
- | `Tabs` | `TabsList variant="line"` and `Tabs orientation="vertical"`; route tabs draw a `nav` from `tabsListVariants` and `tabsTriggerVariants`, which need no `data-orientation`. |
130
- | `MessageScroller` | `defaultScrollPosition` (`start` · `end` · `last-anchor`), `scrollToMessage` from `useMessageScroller()`, and `useMessageScrollerVisibility()`. |
115
+ | Component | What it already does |
116
+ | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
117
+ | `Command` | Renders inline as well as in `CommandDialog` (wide 820px palette by default). `CommandFilters` holds type chips (`ToggleGroup wrap`) and Selects under the input; bare `<CommandFooter />` shows ↵/⌘↵/Esc `Kbd` hints; `CommandLoading` shows the animated search icon. An item's check mark is `data-checked` — visual only, so it is not a form value. |
118
+ | `Combobox` | `multiple` with `ComboboxChips`; `filter={null}` hands filtering to your server. |
119
+ | `SearchableSelect` | The Select-shaped search picker, with `clearable`. `multiple` for several values; `remote` plus `useAsyncSearch` hands search and paging to your server. |
120
+ | `Item` | A link tile with `render={<a />}`; `ItemGroup` gives a set of items list semantics. |
121
+ | `DialogContent` · `SheetContent` | `size`: `sm · default · lg · xl` (a side sheet). Never a width class. |
122
+ | `DataList` | Per-column `mobile` (`merge` · `visible` · `hidden`), `minWidth`, and `mergedRender` so a merged value keeps its context (`4 to review`), `mergedLayout="line"` for one compact meta line. `DataGrid` adds editing, multi-key sort and a column picker; `Table` is static markup. |
123
+ | `DataList` paging and rows | `loadMore` for keyset paging, `getRowHref` for rows that are links, `rowProps` for `data-*` and a `highlighted` new row, `sections` + `getRowSection` for collapsible groups, and `rowActionsColumn` for a per-row menu. |
124
+ | `LoadMore` · `useAsyncSearch` | The Load more footer of a keyset list (keeps its width while loading, "Try again", an end caption) · the server-search engine: debounce, dropped stale responses, cursor paging. |
125
+ | `SortableList` | `layout="grid"` reorders tiles as well as rows. |
126
+ | `FilterBar` / `FilterBuilder` | `FilterBar` is a flat chip row with search, and `FilterBarFacet` is a "Status: Open" facet on `SearchableSelect` (single or `multiple`, local or `remote`); `FilterBuilder` (the `filter-bar-managed` item) edits a nested and/or tree over your field vocabulary. All controlled. |
127
+ | `Stat` | `StatDelta` for change, `StatEmpty` for nothing to report. |
128
+ | `PropertyList` · `DataList` · `SettingsRow` | A record's facts · many records · one setting with its control. |
129
+ | `ActionBar` | The docked bar for bulk selection ("5 selected"), unsaved changes and batch progress. |
130
+ | `TruncatedText` · `IconText` · `TableCellText` | Overflow detection, hover and keyboard reveal, and tap-to-toggle on touch. |
131
+ | `RelativeTime` | `mode="ago"` ("3 minutes ago") or `mode="day"` ("Yesterday"). |
132
+ | `EditableCell` · `AutoSaveInput` · `useInlineEdit` | Click-to-edit in a table (`wrap` + `flush` for a page title) · a field that saves as you type, with its status · the hook `EditableCell` is built on. |
133
+ | `AttachmentGroup` · `Dropzone` · `useFileDrop` | A file list with per-file state · a drop target · the drop and paste engine. |
134
+ | `PageHeader` | Title, description, `breadcrumb`, a back link (`backHref`) and `actions`. |
135
+ | `MultiStepForm` · `Stepper` · `Questionnaire` · `Tabs` | A form in steps · progress display (`navigable` on request) · one question at a time · peer regions. |
136
+ | `NativeSelect` | The platform `<select>`, so a touch device opens its own picker. |
137
+ | `Board` | A column's `lockedReason` explains why it cannot take a card; `itemLinkRender` is a template, the card's `href` wins. |
138
+ | `AudioPlayer` | `mediaRef` to drive playback, a transcript button and a waveform; `docked` pins it to the bottom of a scroll column, `variant="floating"` is the centred pill, `onOpenChange` adds its close button, `actionsRef` seeks it, and `onSourceExpired` renews an expired signed URL once. `AudioPlayerProvider` + `GlobalAudioPlayer` + `useGlobalPlayer()` keep one recording playing across routes. |
139
+ | `Tabs` | `TabsList variant="line"` and `Tabs orientation="vertical"`; route tabs draw a `nav` from `tabsListVariants` and `tabsTriggerVariants`, which need no `data-orientation`. `useTabsSwipe` adds a touch swipe between controlled tabs. |
140
+ | `MessageScroller` | `defaultScrollPosition` (`start` · `end` · `last-anchor`), `scrollToMessage` from `useMessageScroller()`, and `useMessageScrollerVisibility()`. |
131
141
 
132
142
  ### Which component for X
133
143
 
@@ -150,7 +160,15 @@ A component's name undersells it. Before composing something by hand, check this
150
160
  edge: give it `data-slot="sheet-cancel"` and `SheetFooter` pushes it left with `me-auto`.
151
161
  - **Feedback after an action** → `toast.add({ title })`.
152
162
  - **A recording's text beside its player** → `Transcript` (follows `currentTime`, seeks through
153
- `onSeek`, searches) with a `docked` `AudioPlayer` at the bottom of the column.
163
+ `onSeek`, searches; `TranscriptSpeakers` + `onSpeakerRename` for speaker chips) with a `docked`
164
+ `AudioPlayer` at the bottom of the column — or, when playback must survive navigation, one
165
+ `AudioPlayerProvider` in the app shell, `GlobalAudioPlayer` at the end of the main column and
166
+ `useGlobalPlayer().open(track, { at })` / `useGlobalPlayerTime()` on the page.
167
+ - **A record page's header** → an inline-editable title, a `MetaLine` of icon + text facts,
168
+ `RecordChip`s for the records it links to (a picker trigger with a ↗ link), and one `StatusLine`
169
+ for its processing state (progress, or an error with its reason and Retry inline). The body is
170
+ default `Tabs` stretched full width (`TabsList className="w-full"`) with `useTabsSwipe` on the
171
+ panels, and no cards around the panels.
154
172
  - **A list that pages by cursor** → `DataList` `loadMore` (or `LoadMore` under your own list), with
155
173
  `useAsyncSearch` when the search runs on the server.
156
174
 
@@ -185,7 +203,7 @@ on shadcn's `neutral` base. Always use the utility, never a raw value.
185
203
  | Fill | `bg-primary` (solid action, every checked control) · `bg-secondary` (soft) · `bg-muted` (well, track, skeleton) · `bg-accent` (hover) |
186
204
  | Text | `text-foreground` · `text-muted-foreground` · `text-{primary,secondary,accent,card,popover}-foreground` |
187
205
  | Status | `bg-{destructive,success,warning,info}` · `-foreground` (ink ON the fill) · `-text` (ink on the page or on the family's own tint) |
188
- | Border | `border-border` · `border-input` — there are no rings; focus is one global outline |
206
+ | Border | `border-border` · `border-input` — there are no rings; focus is a global background tint (Tabs alone keep a ring) |
189
207
  | Radius | `rounded-{sm,md,lg,xl,2xl}` — all derived from the single `--radius` |
190
208
  | Type | Tailwind's own `text-{xs…7xl}`. `text-sm` is 14px, `text-base` is 16px. Line-height and letter-spacing above `text-base` come from the theme — never write `tracking-*`, an arbitrary `text-[13px]`, or `uppercase` |
191
209
  | Font | `font-sans` `font-mono` `font-serif` `font-heading` |
@@ -316,8 +334,11 @@ contract.
316
334
  **Don't**
317
335
 
318
336
  - Hardcode a hex, a px value, or a raw Tailwind palette class (`bg-neutral-900`, `text-red-500`).
319
- - Add a focus ring or glow. Focus is one global outline, and text entry tints its border instead;
320
- `ring-3`, `ring-ring/50` and `focus-visible:ring-*` are rejected by lint.
337
+ - Add a focus ring, outline or glow. No focus rings anywhere except Tabs: `base.css` paints a subtle
338
+ background tint on `:focus-visible` and text entry tints its border instead; `ring-3`,
339
+ `ring-ring/50`, `focus-visible:ring-*` and `focus-visible:outline-*` are rejected by lint.
340
+ - Leave a neutral hover on a button inside a tinted container — a status `Alert` already gives its
341
+ buttons the family's own hover; don't override it back to `hover:bg-muted`.
321
342
  - Set `outline-none` without providing another focus affordance.
322
343
  - Use a status FILL as ink on its own tint — `bg-destructive/10 text-destructive` measures 3.99:1.
323
344
  The ink on a tint is `-text`.
package/skills/vegastack-design-system/references/components.md CHANGED
@@ -3,7 +3,7 @@
3
3
  <!-- GENERATED — do not hand-edit. Regenerated from the design system's component contract,
4
4
  which is the authority for membership and counts. -->
5
5
 
6
- **115 components**, plus 467 animated-icon items, 12 hooks (`use-animation-replay`, `use-announcer`, `use-async-search`, `use-drag-reorder`, `use-file-drop`, `use-inline-edit`, `use-list-nav`, `use-media-query`, `use-mobile`, `use-modal-inert`, `use-overflow`, `use-platform`), 10 starter blocks (`app-shell-01`, `board-01`, `command-search-01`, `list-page-01`, `login-01`, `notifications-01`, `review-split-01`, `settings-01`, `settings-02`, `status-pages-01`), 68 chart blocks across 7 families, and 3 data libs (`date-time`, `geo-data`, `drag-item`) — 675 registry items in total.
6
+ **118 components**, plus 467 animated-icon items, 13 hooks (`use-animation-replay`, `use-announcer`, `use-async-search`, `use-drag-reorder`, `use-file-drop`, `use-inline-edit`, `use-list-nav`, `use-media-query`, `use-mobile`, `use-modal-inert`, `use-overflow`, `use-platform`, `use-tabs-swipe`), 10 starter blocks (`app-shell-01`, `board-01`, `command-search-01`, `list-page-01`, `login-01`, `notifications-01`, `review-split-01`, `settings-01`, `settings-02`, `status-pages-01`), 68 chart blocks across 7 families, and 3 data libs (`date-time`, `geo-data`, `drag-item`) — 679 registry items in total.
7
7
 
8
8
  Install any of them with `shadcn add @vegastack/<name>`. Animated icons install as
9
9
  `@vegastack/icon-<name>`; the bare name is reserved for components, so a component whose name
@@ -39,9 +39,10 @@ starts with `icon-` is a component and never an icon.
39
39
  - **`number-field`** — Locale-aware numeric input on Base UI's NumberField in upstream's InputGroup chrome, with full-height flanking steppers.
40
40
  - **`password-input`** — A password field with a show/hide toggle, composed from InputGroup, forwarding native input props and the ref to the inner input.
41
41
  - **`radio-group`** — Mutually-exclusive options with arrow-key navigation and a 24px invisible hit area (A11Y-2).
42
+ - **`record-chip`** — A pill that shows the record something belongs to and picks another: icon, name and a chevron as a picker trigger, plus an arrow link to the record.
42
43
  - **`region-select`** — A searchable picker of states/provinces for a country, with a free-text fallback for countries with no subdivisions. A thin wrapper over SearchableSelect fed by the geo-data item.
43
44
  - **`search-input`** — A token-safe search field with a consistent clear action and controlled or uncontrolled native input semantics.
44
- - **`searchable-select`** — The Select-shaped Combobox preset: a full-width trigger, an in-panel search field, a check on the selected row and an optional clear control. Single-select, controlled through value/onValueChange.
45
+ - **`searchable-select`** — The Select-shaped Combobox preset: a full-width trigger, an in-panel search field, a tick on the selected row (matched by key, so async options tick too), a standard person option (name plus muted email, both searched) and an optional clear control. Single or multiple, controlled through value/onValueChange.
45
46
  - **`select`** — A dropdown for one value — trigger, grouped scrollable popup and item-aligned positioning.
46
47
  - **`slider`** — A number or range over a continuous track — horizontal or vertical, any number of thumbs.
47
48
  - **`switch`** — An on/off toggle for instant settings — two sizes and a 24px invisible hit area (A11Y-2).
@@ -51,6 +52,7 @@ starts with `icon-` is a component and never an icon.
51
52
 
52
53
  - **`chip`** — The one labelled pill primitive — 10 decorative hues, two tiers, an optional selection rung, and a real 24x24 remove control. Behind Tag and FilterChip; ComboboxChip is Base UI's own chip, not this primitive.
53
54
  - **`code-block`** — A code panel with a language header and copy affordance — the shared code surface for chat transcripts, docs, and examples.
55
+ - **`meta-line`** — An icon + text meta line under a record title: wrapping facts such as type, date and time, duration and owner, in the muted ink.
54
56
  - **`stat`** — A labelled value block — muted label over a value, honest faint empty state, optional delta line. Two scales.
55
57
  - **`tag-group`** — Hue-tinted label chips on the 10-hue tag palette, with +N overflow collapsing and removable tags.
56
58
 
@@ -64,8 +66,8 @@ starts with `icon-` is a component and never an icon.
64
66
  - **`carousel`** — A slide track with previous and next controls — horizontal or vertical, any slide size or spacing, Embla options, events and plugins.
65
67
  - **`chart`** — A themed Recharts wrapper — a ChartConfig that maps each series to a colour and a label, a bordered tooltip and legend, and Recharts' own built-in keyboard + screen-reader layer.
66
68
  - **`collapsible`** — An interactive component which expands and collapses a panel, with an animated height and a trigger you supply.
67
- - **`empty`** — A zero-data placeholder — media, title, description and a content slot.
68
- - **`item`** — A composable row for list and feed content — media, title, description, actions.
69
+ - **`empty`** — A zero-data placeholder — always an icon (the icon prop, Inbox by default), title, description and a content slot, with a compact sm size for inline empties. The one empty-state markup: DataList's emptyState and noResults (SearchX, "No matches", Clear filters) are built on it.
70
+ - **`item`** — A composable row for list and feed content — media, title, description, actions — with a highlighted flash for a just-changed row.
69
71
  - **`kbd`** — A keyboard-key chip, and a group that lays several of them out inline.
70
72
  - **`markdown-view`** — Render a markdown string to safe, token-styled HTML — headings, lists, code, blockquotes, links, GFM tables — XSS-safe, no raw HTML.
71
73
  - **`relative-time`** — One Intl-based dates & times module — formatRelative, formatDuration, formatDate, formatDateTime, formatDateRange, formatTimeOfDay, formatDueLabel, groupByDay, time-zone cookie + provider — and the RelativeTime, DateTime, Duration and DueLabel components with absolute-time tooltips.
@@ -77,10 +79,10 @@ starts with `icon-` is a component and never an icon.
77
79
  ## Data
78
80
 
79
81
  - **`data-grid`** — The full-parity grid — TanStack-sorted multi-key sort, column picker with responsive revelation, collapsible grouping, keyboard-continuous load-more, opt-in virtualization, and an APG grid keyboard layer with inline cell editing.
80
- - **`data-list`** — A generic, typed data table — configurable columns, row selection, sortable headers, plus loading and empty states.
82
+ - **`data-list`** — A generic, typed data table — configurable columns, row selection, sortable columns (indicator, custom compare and first direction, client or manual), a standard rowActions ⋯ column always last, untinted-link rows (no underline), loading, and Empty-based emptyState and noResults states.
81
83
  - **`data-list-pager`** — A controlled paging footer for DataList — a tabular-numeral range summary, a rows-per-page Select, and a windowed Pagination that hides on a single page.
82
84
  - **`data-table-parts`** — The chrome DataList and DataGrid share — sort header, selection cells, skeleton rows, the empty row, column class rules, and the selection/sort/controlled-state hooks.
83
- - **`filter-bar`** — The two-row toolbar above a list or table — search, scope and view on top, filters below, folding into a sheet on a narrow screen.
85
+ - **`filter-bar`** — The two-row toolbar above a list or table — search (~320px) left; a Filters (n) toggle, scope Tabs and the view switch right; compact rounded-md filter chips (FilterBarFacet, DateRangeFilter with presets) on a toggled row 12px below that scrolls sideways on a phone.
84
86
  - **`filter-bar-managed`** — The controlled nested and/or filter builder — host-injected field grammar (vocabulary + per-type value editors), depth and condition caps, focus-managed removal, and a removable FilterChip summary.
85
87
  - **`load-more`** — The shared Load more footer for keyset lists — an outline button that keeps its width while loading, an error line with Try again, and an optional end caption.
86
88
  - **`property-list`** — Record-facts rows: an icon+label column beside a value column, as an accessible definition list.
@@ -90,13 +92,13 @@ starts with `icon-` is a component and never an icon.
90
92
 
91
93
  - **`alert-dialog`** — A modal that interrupts for a decision — an optional media slot, two sizes and an action/cancel footer.
92
94
  - **`context-menu`** — The same menu vocabulary opened by right-click, positioned at the pointer.
93
- - **`dialog`** — A modal overlay — a backdrop, a centred popup, an optional close button and a plain, right-aligned footer.
95
+ - **`dialog`** — A modal overlay — backdrop, centred popup, a plain right-aligned footer and an optional close button; opens onto the first field or the popup, never the close ×.
94
96
  - **`drawer`** — A swipeable panel with snap points — four directions, a swipe handle, nesting and a non-modal mode.
95
97
  - **`dropdown-menu`** — An anchored action menu — items, submenus, checkboxes, radio groups, shortcuts and a destructive variant.
96
98
  - **`hover-card`** — A preview surface that opens on hover or focus, with configurable delays and sides.
97
99
  - **`panel-search`** — The sticky, box-free search row a filtering popup puts at the top of its panel (decision OVL-11) — shared by EmojiPicker and ShortcutOverlay.
98
100
  - **`popover`** — An anchored, dismissible surface for secondary content, with a header, title and description.
99
- - **`sheet`** — A panel that slides in from any edge — Dialog semantics with a side, a header and a footer.
101
+ - **`sheet`** — A panel that slides in from any edge — Dialog semantics with a side, a header and a footer; opens onto the first field, never the close ×; a left sheet can dock beside the sidebar rail (beside).
100
102
  - **`shortcut-overlay`** — The ?-triggered dialog listing keyboard shortcuts, rendered from a declaration registry (keys, label, category, when) — grouped, filterable, platform-aware via use-platform + Kbd.
101
103
  - **`tooltip`** — A floating label on hover or focus, portaled inside the theme scope (OVL-13).
102
104
 
@@ -107,20 +109,21 @@ starts with `icon-` is a component and never an icon.
107
109
  - **`menubar`** — A persistent horizontal bar of menus — application-style File / Edit / View navigation.
108
110
  - **`multi-step-form`** — A guarded, branching flow around a Stepper — conditional steps, sync and async advance guards, locking, reachability-derived deep links and resume, and a phone layout chosen from the same predicate. Owns no fields and no validator.
109
111
  - **`navigation-menu`** — A collection of links for navigating websites — triggers that open one shared panel, and plain links styled to match.
110
- - **`page-header`** — The standardized header at the top of a page — back button, breadcrumb trail, title, description, actions, secondary menu, and a favorite star.
112
+ - **`page-header`** — The standardized header at the top of a page — back button, breadcrumb trail, title, description, actions, secondary menu, and a favorite star — plus SectionHeading for in-page section titles (sm and md sizes, a muted eyebrow variant, trailing actions).
111
113
  - **`pagination`** — Page navigation — previous/next, numbered page links, an ellipsis for long ranges, and the active page.
112
- - **`sidebar`** — A composable, themeable and customizable sidebar — a provider, a collapsible panel with header, content and footer, labelled groups, menu rows with actions, badges and submenus, a rail and a trigger.
114
+ - **`sidebar`** — A collapsible app navigation rail — header/content/footer, labelled groups, menu items with active and open (menu-trigger) states, and an expand/collapse trigger.
113
115
  - **`stepper`** — A bounded linear process as an ordered list — seven step states on a numbered rail that fills in behind you, aria-current=step, orientation chosen from the step count, and a compact summary below a container width.
114
- - **`tabs`** — A set of layered sections of content — known as tab panels — that are displayed one at a time.
116
+ - **`tabs`** — Layered content sections — default (segmented) or line variants, compact size, optional leading icons and counts, horizontal or vertical, full keyboard navigation. Use Tabs for scope/views (My tasks | Team tasks); use an icon ToggleGroup for List/Board layout switches. The one component that keeps a focus ring.
115
117
 
116
118
  ## Feedback
117
119
 
118
120
  - **`action-bar`** — Floating contextual bar — status region + action children, CSS-only enter/exit, raised band. Bulk selection, unsaved changes, and batch progress are recipes over it.
119
- - **`alert`** — A status banner — upstream's two variants plus our three extra status tones (COL-12).
121
+ - **`alert`** — A status banner — upstream's two variants plus our three extra status tones (COL-12); buttons inside a status alert hover in the family's own tint and ink, never white.
120
122
  - **`progress`** — Displays an indicator showing the completion progress of a task, typically displayed as a progress bar.
121
123
  - **`provider`** — The single app-root wrapper — theme (next-themes), Base UI toasts, tooltip delays, and text direction in one mount-once component.
122
124
  - **`skeleton`** — A pulsing placeholder that reserves layout space while content loads.
123
125
  - **`spinner`** — An indeterminate loading indicator that inherits its host's ink.
126
+ - **`status-line`** — A slim inline status: info, progress (spinner) or error (destructive ink, role=alert), with an optional inline action.
124
127
  - **`toast`** — Brief, non-blocking notifications — a stacking Base UI Toast surface with typed icons, actions and promise toasts.
125
128
 
126
129
  ## Layout
@@ -136,9 +139,9 @@ starts with `icon-` is a component and never an icon.
136
139
 
137
140
  ## Media
138
141
 
139
- - **`audio-player`** — A custom audio transport with play/pause, skip, seek, a tappable speed control, and keyboard shortcuts (mute on the M key); a single line on a wide player, two lines with an optional transcript control on a narrow, mobile-width player. Docks to the bottom of a scroll column with a close, resolves a lazy source on first play, and seeks from outside through actionsRef.
142
+ - **`audio-player`** — A compact custom audio transport with play/pause, skip, seek, a tappable speed control, and keyboard shortcuts — a single line on a wide player, two lines with an optional transcript control on a narrow, mobile-width player; a floating pill variant and a global AudioPlayerProvider + useGlobalPlayer that keep one recording playing across routes.
140
143
  - **`image`** — A presentational framed image with aspect-ratio, rounding, a loading skeleton, and an error fallback.
141
- - **`inbox`** — The notification Inbox: frame with header actions, All | Unread chips, sticky day groups, full-bleed rows with avatar or icon, rich titles, action chips, hover read toggle and menu, and empty, loading and error states.
144
+ - **`inbox`** — The notification Inbox: frame with header actions, All | Unread chips, sticky day groups, full-bleed rows with avatar or icon and an unread tint (no dot), rich titles, action chips, a fixed right column with the time over the hover actions (read toggle and menu), and empty, loading and error states.
142
145
  - **`media-player-controls`** — The shared media transport — play/pause, skip, seek, elapsed/duration, mute + volume, playback speed, and one keyboard shortcut map (useMediaShortcuts) — composed by Audio Player and Video Player.
143
146
  - **`notification-bell`** — A bell icon button with an unread-count badge overlay, plus the shared NotificationDot unread marker. Presentational — the app supplies the count.
144
147
  - **`video-player`** — A framed video player with the same grouped custom transport controls as Audio Player.
@@ -159,7 +162,7 @@ starts with `icon-` is a component and never an icon.
159
162
  - **`message`** — Layout primitives for a conversation row - avatar anchoring, content column, header/footer slots, start/end alignment. Server-safe.
160
163
  - **`message-scroller`** — An auto-scrolling conversation viewport (not virtualised) - pins to the latest message, preserves position on prepend, tracks the anchor, and a floating scroll-to-end button.
161
164
  - **`questionnaire`** — A guided one-question-at-a-time form — choices, freeform answers, skip, shortcuts, validation, resume and conditional items, built on the @shadcn/react questionnaire state machine.
162
- - **`transcript`** — A timestamped, speaker-labelled transcript on MessageScroller's primitive - marks the line playing at currentTime, follows it, pauses on a user scroll with a Back to current line button, seeks from each timestamp, and searches with highlighted, announced matches.
165
+ - **`transcript`** — A timestamped, speaker-labelled transcript on MessageScroller's primitive - turns with a coloured speaker dot, the line playing at currentTime followed with a Back to current line button, seek from each timestamp, highlighted announced search, speaker chips with rename, and progressive mounting of long transcripts.
163
166
 
164
167
  ## Marketing
165
168