@nurix/etna 0.20.36 → 0.20.38

package/data/harnesses/code/skills/design/components/index.md

@@ -2,7 +2,7 @@
 
 > **Generated folder — never hand-edit.** Everything under `skills/design/components/` is emitted by the components-repo regen instruction set (`docs/skills/design/components-regen-spec.md`, run against the `@nurix/components` library checkout). Regeneration may reshape any file beneath this one; the design skill's only seam with this folder is this index.
 
-**Load contract.** This index loads in **both** positions of the project's `primitives` switch (`design.md`, `primitives: nurix | native`) — it is how the skill knows what chrome *exists* to compose with. The per-category deep references beside it ([inputs](inputs.md), [overlays](overlays.md), [collections](collections.md), [navigation](navigation.md), [layout](layout.md), [feedback](feedback.md), [charts](charts.md), [typography](typography.md), [media](media.md), [motion](motion.md), [hooks](hooks.md), [utils](utils.md), plus [setup](setup.md) for install/Tailwind wiring) load **only under `primitives: nurix`**, and only when that category is touched.
+**Load contract.** This index loads in **both** positions of the project's `primitives` switch (`design.md`, `primitives: nurix | native`) — it is how the skill knows what chrome *exists* to compose with. The per-category deep references beside it ([inputs](inputs.md), [overlays](overlays.md), [collections](collections.md), [navigation](navigation.md), [layout](layout.md), [feedback](feedback.md), [charts](charts.md), [typography](typography.md), [media](media.md), [motion](motion.md), [hooks](hooks.md), [utils](utils.md), plus [setup](setup.md) for install, styles, peer families and personality) load **only under `primitives: nurix`**, and only when that category is touched.
 
 **The ratchet.** Deep references bind only when `@nurix/components` is actually importable in the target project: the intake probe defaults the switch, the recorded `primitives:` line is the authority. Under `nurix`, a row binds to its **nurix** column and the category reference supplies the API. Under `native`, the per-category references never load; a row binds to its **shadcn** column (when the project uses shadcn/ui) or to the **fallback** column — a semantic-HTML/behavior spec the model implements with the incumbent stack.
 
@@ -10,136 +10,158 @@ Columns: `concept` (the composable idea) · `category` (which deep reference cov
 
 ```csv
 concept,category,nurix,shadcn,fallback
-button,inputs,Button (element/button),Button,"native <button>, variants via class, focus-visible ring"
-text-input,inputs,"Input (element/input) — onSave commit, regex validator",Input,"<input type=text>, commit on blur/Enter"
-number-input,inputs,"NumberInput (element/number-input) — min/max/step",—,"<input inputmode=numeric>, clamp on commit, Escape reverts"
-textarea,inputs,"Textarea (element/textarea) — Cmd/Ctrl+Enter commits",Textarea,"<textarea>, blur commits, Escape resets draft"
+button,inputs,"Button (element/button) — variant + intent=danger, isIconOnly, loading",Button,"native <button>, variants via class, focus-visible ring"
+text-input,inputs,"Input (element/input) — onValueCommitted on Enter/blur, validate function",Input,"<input type=text>, commit on blur/Enter"
+number-input,inputs,"NumberInput (element/number-input) — min/max/step, empty commits null",—,"<input inputmode=numeric>, clamp on commit, Escape reverts"
+textarea,inputs,"Textarea (element/textarea) — Cmd/Ctrl+Enter commits, autosize",Textarea,"<textarea>, blur commits, Escape resets draft"
 inline-edit,inputs,"InlineEdit (element/inline-edit) — click-to-edit contentEditable span",—,"span[contenteditable] reading as a label until focused, Enter/blur commits, Escape reverts"
 checkbox,inputs,Checkbox (element/checkbox),Checkbox,"<input type=checkbox> + label, indeterminate via JS"
 switch,inputs,Switch (element/switch),Switch,"role=switch button, aria-checked, Space toggles"
-radio-group,inputs,"RadioGroup + card/segmented variants (element/radio-group)",RadioGroup,"fieldset of <input type=radio>, arrow-key roving focus"
+radio-group,inputs,"RadioGroup + RadioGroup.Card (element/radio-group)",RadioGroup,"fieldset of <input type=radio>, arrow-key roving focus"
 combobox,inputs,"Combobox — searchable, multi, async (compound/combobox)","Combobox (Popover + Command)","input + filtered listbox popup, typeahead, option objects not raw values"
-calendar,inputs,"Calendar (compound/calendar) — react-day-picker",Calendar,"month grid <table>, arrow-key day navigation"
+calendar,inputs,"Calendar · Calendar.Range (compound/calendar) — react-day-picker",Calendar,"month grid <table>, arrow-key day navigation"
 select,inputs,"Select — closed listbox, one string value, no query field (element/select)",Select,"<select> or listbox popup, typeahead, one string value"
 date-picker,inputs,DatePicker (compound/date-picker),Date Picker (Calendar + Popover),"<input type=date> or calendar popover, ISO value"
-date-range-picker,inputs,"DateRangePicker — presets sidebar (compound/date-picker)",—,"two bound date inputs, partial selection reverts on close"
+date-range-picker,inputs,"DatePicker.Range — presets column (compound/date-picker)",—,"two bound date inputs, partial selection reverts on close"
 slider,inputs,Slider (element/slider),Slider,"<input type=range> with visible value readout"
 rating,inputs,Rating (element/rating),—,"radio group of icon buttons, half-step optional"
 toggle,inputs,"Toggle · ToggleGroup (element/toggle, compound/toggle-group)","Toggle, Toggle Group","aria-pressed buttons, single or multiple selection"
 otp-input,inputs,InputOTP (compound/input-otp),Input OTP,"segmented one-char inputs, paste distributes across slots"
-icon-picker,inputs,"IconPicker · Icon (compound/icon-picker)",—,"searchable icon grid in a popover, categorized"
-file-upload,inputs,"FileUpload family — dropzone, list, item progress (compound/file-picker) · FilePreview (compound/file-preview)",—,"<input type=file> + drop zone, previews, size and count caps"
-form-field,inputs,"Cell — label/content/helper/error slots (compound/cell)",Form + FormField (react-hook-form),"label + control + helper in one block, error slot below control"
+icon-picker,inputs,"IconPicker (compound/icon-picker) · Icon (element/icon) — optional peer @tanstack/react-virtual + fuse.js",—,"searchable icon grid in a popover, categorized"
+file-upload,inputs,"FilePicker + useFilePicker — dropzone, list, item progress (compound/file-picker) · FilePreview (compound/file-preview)",—,"<input type=file> + drop zone, previews, size and count caps"
+form-field,inputs,"Cell — label/field/helper/error slots, inline mode (compound/cell)",Form + FormField (react-hook-form),"label + control + helper in one block, error slot below control"
 form-validation,inputs,,Form (react-hook-form),"form element with submit-time validation and inline field errors"
-rich-text-editor,inputs,,—,"@tiptap/react editor with toolbar and markdown shortcuts"
+rich-text-editor,inputs,"TiptapEditor (block/tiptap-editor) — markdown in/out; optional peer @tiptap/* + tiptap-markdown",—,"@tiptap/react editor with toolbar and markdown shortcuts"
 code-editor,inputs,,—,"@monaco-editor/react, mono, optional read-only diff mode"
+message-composer,collections,"Composer + useStagedFiles (block/composer)",—,"form with autosizing textarea, Enter sends and Shift+Enter breaks a line, attach and send buttons, live reason line"
+action-cluster,inputs,"ActionCluster — inline, pinned and overflow actions (compound/action-cluster)",—,"toolbar row of buttons, extra actions in a More actions menu button, pinned actions always visible"
+reaction,inputs,"Reaction · Reaction.Add (compound/reaction)",—,"row of aria-pressed emoji chip buttons with counts, +N overflow pill, add button"
+voice-waveform,collections,"MicInput (compound/mic-input) — optional peer react-voice-visualizer for recorder mode",—,"aria-pressed mic toggle button plus live mic level bars; record-then-review via MediaRecorder"
 modal-dialog,overlays,Dialog (compound/dialog),Dialog,"<dialog> or fixed layer, focus trap, ESC closes, header→body→footer"
-confirm-dialog,overlays,"Dialog variant=danger — non-dismissible (compound/dialog)",Alert Dialog,"modal with explicit confirm/cancel, no outside-click dismiss"
-side-panel,overlays,Sheet (block/sheet),Sheet,"fixed aside, focus-trapped, ESC closes, interruptible slide"
+confirm-dialog,overlays,"Dialog intent=""danger"" — alert dialog, dismissible={false} by default (compound/dialog)",Alert Dialog,"modal with explicit confirm/cancel, no outside-click dismiss"
+side-panel,overlays,Sheet side=start|end (block/sheet),Sheet,"fixed aside, focus-trapped, ESC closes, interruptible slide"
 bottom-drawer,overlays,Sheet side=bottom (block/sheet),Drawer (vaul),"fixed bottom panel spanning full width"
-command-palette,overlays,Command (compound/command),Command (cmdk),"filtered list in a dialog, ⌘K opens, arrow-key + Enter"
+command-palette,overlays,"Command · Command.Dialog (compound/command)",Command (cmdk),"filtered list in a dialog, ⌘K opens, arrow-key + Enter"
 dropdown-menu,overlays,DropdownMenu (compound/dropdown-menu),Dropdown Menu,"role=menu under a trigger, arrow-key nav, outside click closes"
 context-menu,overlays,ContextMenu (compound/context-menu),Context Menu,"right-click menu at pointer position"
 speed-dial,overlays,SpeedDial (compound/speed-dial),—,"floating trigger button that fans a bounded set of icon actions out along one axis; the trigger doubles as the close affordance"
+action-bar,overlays,ActionBar (compound/action-bar),—,"toolbar of icon buttons anchored to the item it acts on, revealed on hover/focus, always visible on touch"
 popover,overlays,Popover (element/popover),Popover,"anchored floating panel, dismiss on outside/ESC"
-hover-card,overlays,HoverCard (element/popover),Hover Card,"preview panel on hover intent, delayed open/close"
+hover-card,overlays,"Popover — Popover.Trigger openOnHover (element/popover)",Hover Card,"preview panel on hover intent, delayed open/close"
 tooltip,overlays,Tooltip (element/tooltip),Tooltip,"short hint on hover/focus, never load-bearing content"
 data-table,collections,"Table + defineColumn (block/table)","<Table> + TanStack Table","semantic <table>, sticky header, tabular-nums, real pagination, status chips"
-table-primitives,collections,UiTable* family (block/ui-table),Table,"bare styled <table>/<thead>/<tbody> parts"
-list,collections,"List + ListToolbar + ListPagination (block/list)",—,"<ul> of rows with toolbar and pager"
-record-header,collections,,—,"page-top block: breadcrumbs, title, status bar, actions"
-page-header-stats,collections,"Heading (element/heading) · Stat (element/stat) — composed at the call site",—,"title row + KPI strip + back link"
+table-primitives,collections,"UiTable + UiTable.Header/.Body/.Row/.Head/.Cell (block/ui-table)",Table,"bare styled <table>/<thead>/<tbody> parts"
+list,collections,"List + List.Toolbar + List.Pagination (block/list)",—,"<ul> of rows with toolbar and pager"
+record-header,collections,"FieldGrid arrangement=strip (compound/field-grid) — composed at the call site",—,"page-top block: breadcrumbs, title, status bar, actions"
+page-header-stats,collections,"Stat (element/stat) — composed at the call site",—,"title row + KPI strip + back link"
 gantt-timeline,collections,,—,"time-scaled task rows, date axis, horizontal scroll"
-changes-feed,collections,ChangesList (block/changes-list),—,"grouped change-history feed, entity + operation labels"
-message-thread,collections,"MessageScroller + useMessageScroller (block/message-scroller)",—,"scrolling feed pinned to bottom, jump-to-new button"
+changes-feed,collections,"List — activity-feed composition with groupBy (block/list)",—,"grouped change-history feed, entity + operation labels"
+message-thread,collections,"AnchoredScroller + useAnchoredScroller (block/anchored-scroller)",—,"scrolling feed pinned to bottom, jump-to-new button"
 chat-bubble,collections,,—,"aligned bubble rows with reactions row"
-attachment,collections,"FilePreview (compound/file-preview)",—,"file card: media, title, actions, error state, dashed idle border"
+attachment,media,"FilePreview + getFileTypeIcon (compound/file-preview)",—,"file card: media, title, actions, error state, dashed idle border"
 thread-marker,collections,"Marker — separator/border variants (element/marker)",—,"inline separator row with icon and label"
 json-viewer,collections,,—,"react18-json-view collapsible tree, mono"
 virtualized-list,collections,,—,"react-window fixed-row virtualization for 1k+ rows"
 kanban-board,collections,,—,"flex columns of cards, @dnd-kit drag between columns, per-column count"
 event-calendar,collections,,—,"month/week grid of events, today marker, overflow +N"
-description-list,collections,,—,"<dl> two-column key/value grid, tabular values"
+description-list,collections,"FieldGrid (compound/field-grid)",—,"<dl> two-column key/value grid, tabular values"
 filter-toolbar,collections,,—,"row of faceted filter chips + clear-all + result count"
 vertical-timeline,collections,,—,"ordered event list with time rail and node markers"
-sidebar,navigation,"Sidebar family + Brand/Switcher/ItemGroup/UserMenu/Callout (block/sidebar)",Sidebar,"fixed <nav>: brand + icon sections + badges + user footer, collapsible to icons"
-file-tree,navigation,FileTree (block/sidebar),—,"nested tree with disclosure carets, keyboard nav"
+sidebar,navigation,"Sidebar namespace — Sidebar.Provider/.Inset/.Menu*/.Brand/.Switcher/.ItemGroup/.UserMenu/.CommandTrigger + useSidebar (block/sidebar)",Sidebar,"fixed <nav>: brand + icon sections + badges + user footer, collapsible to icons"
+file-tree,collections,Tree + useTree (block/tree),—,"nested tree with disclosure carets, keyboard nav"
 breadcrumb,navigation,Breadcrumb (compound/breadcrumb),Breadcrumb,"<nav aria-label=breadcrumb>, current page unlinked"
-tabs,navigation,Tabs (compound/tabs),Tabs,"role=tablist, arrow-key switching, one panel per tab"
-pagination,navigation,Pagination (compound/pagination),Pagination,"page buttons + prev/next, aria-current on active page"
+tabs,navigation,"Tabs — Tabs.List/.Trigger/.Content/.Contents, variant default|underline (compound/tabs)",Tabs,"role=tablist, arrow-key switching, one panel per tab"
+pagination,navigation,Pagination + getPageRange (compound/pagination),Pagination,"page buttons + prev/next, aria-current on active page"
 navbar,navigation,,—,"horizontal top <nav> with links and actions"
-navigation-menu,navigation,NavigationMenu (compound/navigation-menu),Navigation Menu,"top-level nav with flyout panels"
+navigation-menu,navigation,NavigationMenu + navigationMenuTriggerStyle (compound/navigation-menu),Navigation Menu,"top-level nav with flyout panels"
 menubar,navigation,Menubar (compound/menubar),Menubar,"desktop-app menu strip with full keyboard model"
 icon-rail,navigation,VerticalIconBar (block/vertical-icon-bar),—,"narrow vertical icon strip with tooltips"
 stepper,navigation,,—,"ordered steps with done/current/todo states, aria-current=step"
 alert,feedback,Alert (compound/alert),Alert,"role=alert block, tone via border + icon"
-empty-state,feedback,EmptyState (compound/empty-state),Empty,"icon + heading + motivation line + primary action"
+empty-state,feedback,Empty (compound/empty-state),Empty,"icon + heading + motivation line + primary action"
 error-boundary,feedback,ErrorBoundary (lib/error-boundary),—,"React boundary rendering a retry block"
-not-found,feedback,NotFound (compound/empty-state),—,"404 block with a way back"
+error-state,feedback,ErrorState (compound/error-state),—,"failed-load block: danger icon, message, retry button"
+not-found,feedback,Empty — composed 404 (compound/empty-state),—,"404 block with a way back"
 skeleton,feedback,Skeleton (element/skeleton),Skeleton,"pulsing placeholder matching the final layout"
 loader,feedback,Loader (element/loader),Spinner,"centered spinner with optional label"
 text-spinner,feedback,,—,"animated unicode frames inline with text"
 progress,feedback,Progress (element/progress),Progress,"role=progressbar with aria-valuenow"
-toast,feedback,Toaster (compound/sonner),Sonner,"stacked corner notifications, auto-dismiss, action slot"
-typing-indicator,feedback,"Loader — pulsing dots (element/loader)",—,"three-dot pulse row"
-sparkline,charts,"Spark — line|bar|pie (element/spark)",—,"inline no-axis SVG mark, token or self-contained color"
-status-timeline,charts,"StatusTimeline + .Skeleton (compound/status-timeline)",—,"one stacked bar per day of uptime status, hover card per day — no axis, not a bar chart"
-inline-line,charts,"Spark — line (element/spark)",—,"compact line SVG with skeleton"
-pie-donut,charts,"Chart — pie spec (block/chart)",—,"SVG arcs, max ~6 slices, center slot in doughnut"
+toast,feedback,Toaster + toast (compound/toast),Sonner,"stacked corner notifications, auto-dismiss, action slot"
+typing-indicator,feedback,Loader with label (element/loader),—,"three-dot pulse row"
+notification-badge,feedback,NotificationBadge (element/notification-badge),Badge,"small count or dot pinned to a trigger corner, hidden at zero"
+system-banner,feedback,SystemBanner + SystemBanner.Stack (element/system-banner),—,"full-width shell banner above the app, role=status, optional action and dismiss"
+issue-reporter,feedback,IssueReporter (block/issue-reporter),—,"report dialog: description field, screenshot attach, environment details"
+sparkline,charts,"Spark — line|area|bar|pie (element/spark)",—,"inline no-axis SVG mark, token or self-contained color"
+status-timeline,charts,"StatusTimeline — loading prop renders the skeleton · formatDateRange (compound/status-timeline)",—,"one stacked bar per day of uptime status, hover card per day — no axis, not a bar chart"
+inline-line,charts,"Spark — line|area (element/spark)",—,"compact line SVG, null values draw as gaps"
+pie-donut,charts,"Chart — pie spec, encode.donut / half / center (block/chart)",—,"SVG arcs, max ~6 slices, center slot in doughnut"
 segmented-progress,charts,"Chart — progress spec (block/chart)",—,"stacked horizontal segments with legend"
 area-chart,charts,"Chart — area spec (block/chart)",Chart (recharts),"axes + gridlines + filled series + tooltip"
 bar-chart,charts,"Chart — bar spec (block/chart)",Chart (recharts),"grouped/stacked bars, value labels opt-in"
 line-chart,charts,"Chart — line spec (block/chart)",Chart (recharts),"multi-series lines, reference lines, brush"
-scatter-chart,charts,"Chart — scatter spec (block/chart)",—,"x/y point field, hover ring, box select"
-composed-chart,charts,"Chart — composed spec (block/chart)",—,"mixed marks over one shared scale pair"
-histogram,charts,"Chart — bar spec with mode: histogram (block/chart)",—,"binned bars over a continuous axis"
-bullet-chart,charts,"Bullet (gauge; also charts)",—,"measure bar + target tick + zone bands"
-funnel,charts,"Chart — funnel spec (block/chart)",—,"ordered stage bands, percent-of-previous labels"
+scatter-chart,charts,"Chart — scatter spec, dashboard context (block/chart)",—,"x/y point field, hover ring, box select"
+composed-chart,charts,"Chart — composed spec, dashboard context (block/chart)",—,"mixed marks over one shared scale pair"
+histogram,charts,"Chart — bar spec with encode.mode: histogram (block/chart)",—,"binned bars over a continuous axis"
+bullet-chart,charts,"Chart — gauge spec with encode.shape: bullet + zone/target overlays (block/chart)",—,"measure bar + target tick + zone bands"
+funnel,charts,"Chart — funnel spec, dashboard context (block/chart)",—,"ordered stage bands, percent-of-previous labels"
 gauge,charts,"Chart — gauge spec (block/chart)",—,"value arc with threshold zones and center readout"
-contribution-heatmap,charts,"Chart — heatmap-calendar spec (block/chart)",—,"calendar cell grid with level legend"
-matrix-heatmap,charts,"Chart — heatmap-matrix spec (block/chart)",—,"x-by-y cell matrix on the tokenized ramp"
-radar,charts,"Chart — radar spec (block/chart)",—,"spider axes with series polygons"
+contribution-heatmap,charts,"Chart — heatmap-calendar spec, dashboard context (block/chart)",—,"calendar cell grid with level legend"
+matrix-heatmap,charts,"Chart — heatmap-matrix spec, dashboard context (block/chart)",—,"x-by-y cell matrix on the tokenized ramp"
+radar,charts,"Chart — radar spec, dashboard context (block/chart)",—,"spider axes with series polygons"
 ring,charts,"Chart — ring spec (block/chart)",—,"segmented circular progress with center info"
 chart-chrome,charts,"Chart chrome — legend, tooltip and empty state set by the spec theme · ChartErrorCard (block/chart)",—,"shared empty/tooltip/legend chrome for inline charts"
-card,layout,Card family (block/card),Card,"bordered section: header, content, footer"
-stat-card,layout,"Stat (element/stat) · Chart — stat spec (block/chart)",—,"number + comparison + trend + state + door, composable regions"
-accordion,layout,Accordion (compound/accordion),Accordion,"stacked disclosure sections, single or multiple open"
-collapsible-panel,layout,SidePanel (block/side-panel),—,"in-flow side region docked left or right that collapses to a rail instead of disappearing; siblings reflow, nothing overlays"
-collapsible,layout,"Collapsible (element/collapsible) · CollapsiblePanel (compound/accordion)",Collapsible,"button-controlled region with hidden state"
-split-panes,layout,ResizablePanelGroup (block/resizable),Resizable,"draggable divider panes, keyboard resize"
+chart-kernel,charts,"resolveSeriesColors · buildColorScale · formatCompactNumber · isChartDataEmpty (lib/chart-kernel) · arc and line geometry, a narrower colour entry (lib/chart-kernel/arc, lib/chart-kernel/colors, lib/chart-kernel/line)",—,"token-resolved series colors, magnitude color scales, Intl number/date formatters, SVG arc and line path helpers for a bespoke mark"
+page-block,layout,Block (block/block),—,"semantic page region (section/header/footer/main) that stacks children on the density gap and owns the insets; draws nothing"
+card,layout,"Card + Card.Header/.Header.Action/.Title/.Description/.Content/.Footer (block/card)",Card,"bordered section: header, content, footer"
+stat-card,typography,"Stat (element/stat) · Chart — stat spec (block/chart)",—,"number + comparison + trend + state + door, composable regions"
+item,layout,"Item + Item.Media/.Content/.Title/.Description/.Actions/.Header/.Footer/.Group/.Separator (element/item)",Item,"list/menu row: leading media, title + description, trailing actions"
+row,layout,Row (element/row),—,"horizontal flex row that owns only the gap between its children, no padding or margin"
+spacer,layout,Spacer (element/spacer),—,"aria-hidden flex-grow element that pushes siblings to opposite edges"
+accordion,layout,"Accordion + Accordion.Item/.Header/.Trigger/.Panel (compound/accordion)",Accordion,"stacked disclosure sections, single or multiple open"
+collapsible-panel,layout,"SidePanel + SidePanel.Trigger/.Panel (block/side-panel)",—,"in-flow side region docked at the inline start or end that collapses to a rail instead of disappearing; siblings reflow, nothing overlays"
+collapsible,layout,"Collapsible + Collapsible.Trigger/.Panel/.Indicator (element/collapsible)",Collapsible,"button-controlled region with hidden state"
+split-panes,layout,"Resizable + Resizable.Panel/.Handle (block/resizable)",Resizable,"draggable divider panes, keyboard resize"
 scroll-area,layout,ScrollArea (element/scroll-area),Scroll Area,"styled overflow container, visible-on-hover scrollbar"
-separator,layout,"Separator (element/separator) · SeparatorWithText (element/separator)",Separator,"<hr>/role=separator, optional centered label"
+separator,layout,"Separator (element/separator) — children render the labeled form",Separator,"<hr>/role=separator, optional centered label"
 aspect-ratio,layout,AspectRatio (element/aspect-ratio),Aspect Ratio,"CSS aspect-ratio box"
-carousel,layout,Carousel (compound/carousel),Carousel,"scroll-snap track with prev/next controls"
+carousel,layout,"Carousel + Carousel.Content/.Item/.Previous/.Next · LoadingCarousel (compound/carousel)",Carousel,"scroll-snap track with prev/next controls"
 bento-grid,layout,,—,"asymmetric feature grid with spanning cells"
 editable-card,layout,,—,"card with edit-in-place body and commit footer"
-drag-reorder,layout,Sortable family (compound/sortable),—,"dnd-kit list reorder, keyboard sortable, drag overlay ghost"
+drag-reorder,layout,"Sortable + Sortable.Content/.Item/.ItemHandle/.Overlay, useSortableItem, arrayMove (compound/sortable)",—,"dnd-kit list reorder, keyboard sortable, drag overlay ghost"
 text,typography,,Typography,"semantic p/span with size and weight scale"
-badge,typography,"Chip (element/chip)",Badge,"small status pill, tokenized tone"
-chip,typography,"Chip (element/chip) · Option display (element/select)",—,"removable tag, optional color dot"
+badge,typography,"Chip (element/chip)",Badge,"small status pill, intent color from tokens"
+chip,typography,"Chip (element/chip)",—,"removable tag, optional color dot"
 code,typography,Code (element/code),—,"inline <code>, mono"
+code-block,typography,"CodeBlock · highlightCode · parseUnifiedDiff · ansiToLines (compound/code-block)",—,"<pre><code> block with line numbers, diff rows and a copy control, syntax-highlighted"
 kbd,typography,Kbd (element/kbd),Kbd,"<kbd> keycap"
 label,typography,Label (element/label),Label,"<label for> bound to a control"
 link,typography,Link (element/link),—,"<a> with underline discipline"
 secure-text,typography,"SecureText · maskText (element/secure-text)",—,"masked value with reveal toggle, mono"
 markdown,typography,Markdown (element/markdown),—,"react-markdown rendering with typographic defaults"
-avatar,media,Avatar (element/avatar),Avatar,"image with initials fallback, round"
+timestamp,typography,"Timestamp · DEFAULT_RELATIVE_THRESHOLD (element/timestamp)",—,"<time datetime> reading relative near now and absolute beyond, exact time in title"
+avatar,media,"Avatar · AvatarGroup (element/avatar)",Avatar,"image with initials fallback, round"
 copy-button,media,CopyButton (compound/copy-button),—,"clipboard write with copied-state swap"
-icon,media,"Icon · IconPicker (compound/icon-picker) + iconsData (lib/icons-data)",—,"lucide icon by name, consistent stroke and size grid"
-voice-waveform,chat,"MicInput (compound/mic-input)",—,"latched dictation button plus mic level bars; button={false} for the meter alone, recorder={…} for record-then-review"
+icon,media,"Icon (element/icon) · iconsData (lib/icons-data) · IconPicker (compound/icon-picker)",—,"lucide icon by name, consistent stroke and size grid"
+image,media,Image (element/image),—,"<img> in a reserved aspect-ratio box, skeleton while loading, alt-text placeholder on error instead of the broken-image glyph"
 brand-logo,media,"Logo — blue-black|white-white|lime-white|blue-white (element/logo)",—,"inline SVG logo sized by height"
-shine-border,media,ShineBorder (effect/shine-border),—,"animated gradient border wrapper, decorative"
-theme-toggle,media,"ThemeToggle (effect/theme-toggle)",—,"light/dark switch toggling the .dark class on the root element"
-view-switcher,media,ViewSwitcher (compound/tabs),—,"segmented control switching view-type projections"
-animated-number,motion,"AnimatedNumber (element/animated-number) · SlidingNumber (element/animated-number)",—,"tick-up numerals, renders plain text until JS ready"
+shine-border,motion,ShineBorder (effect/shine-border),—,"animated gradient border wrapper, decorative"
+theme-toggle,inputs,ThemeToggle (element/theme-toggle),—,"light/dark switch toggling the .dark class on the root element"
+view-switcher,media,ToggleGroup (compound/toggle-group),—,"segmented control switching view-type projections"
+animated-number,motion,"AnimatedNumber · AnimatedNumber.Group (element/animated-number)",—,"tick-up numerals, renders plain text until JS ready"
 stagger-entrance,motion,"AnimatedList (effect/animated-list)",—,"staggered child arrival, identity moments only, never on 100×/day actions"
-text-effects,motion,"TextEffect · TextMorph · TextScramble · TextShimmer (effect/*)",—,"per-character text animation, low-frequency surfaces only"
-morphing-overlay,motion,"MorphingDialog · MorphingPopover (effect/*)",—,"trigger morphs into overlay, interruptible"
-panel-transitions,motion,"TransitionPanel (effect/transition-panel) · Accordion (compound/accordion) · Tabs (compound/tabs)",—,"crossfade/slide between sibling panels, height-animated reveal, interruptible"
-decorative-effects,motion,"Spotlight · GlowEffect · AnimatedBackground · InfiniteSlider · Highlight (effect/*, effect/*)",—,"pointer-tracked washes and loops, decorative only, never on data"
+text-effects,motion,"TextEffect · TextMorph · TextScramble · TextShimmer · TypingAnimation (effect/text-effects) · DiaTextReveal (effect/dia-text-reveal)",—,"per-character text animation, low-frequency surfaces only"
+streaming-cursor,collections,"StreamingCursor (effect/streaming-cursor)",—,"inline blinking caret after the last streamed token while a response is in flight, aria-hidden, steady under reduced motion"
+animated-icons,motion,"AnimateIcon + animated icon set (effect/icons)",—,"static SVG icon, optional one-shot transform on hover or tap, none under reduced motion"
+morphing-overlay,motion,"Dialog.MorphTrigger (compound/dialog) · Popover.MorphTrigger (element/popover)",—,"trigger morphs into overlay, interruptible"
+panel-transitions,motion,"TransitionPanel (effect/transition-panel) · Tabs (compound/tabs) · Accordion (compound/accordion) · Collapsible (element/collapsible)",—,"crossfade/slide between sibling panels, height-animated reveal, interruptible"
+decorative-effects,motion,"Spotlight (effect/spotlight) · GlowEffect (effect/glow-effect) · Grainient (effect/grainient) · InfiniteSlider (effect/infinite-slider) · Highlight (effect/highlight)",—,"pointer-tracked washes and loops, decorative only, never on data"
 dynamic-toolbar,motion,,—,"toolbar expanding to contextual actions"
-utility-hooks,hooks,"useClickOutside · useFileUpload · useMediaQuery · useIsMobile (lib/*)",—,"outside-click, file-upload state, matchMedia boolean, <768px boolean"
-class-merge,utils,cn (lib/utils),cn,"clsx + tailwind-merge"
-formatting-utils,utils,"formatDate (lib/format) · generateId (lib/id) · formatRelativeTime (lib/time)",—,"Intl date formatting, nanoid ids, relative-time strings"
-composition-utils,utils,"getStrictContext (lib/get-strict-context) · composeRefs (lib/compose-refs)",—,"throwing Provider/hook pair, ref composition"
+utility-hooks,hooks,"useClickOutside · useControllableState · useDebounce · useEventListener · useFilter · useFreshness · useIntersectionObserver · useInterval · useKeyPress · useMeasure · useMediaQuery · useIsMobile · useOverflowCount · useRangeSelect · useRovingFocus · useScrollOverflow · useSearchSource · createStaticSource · useSmoothResize · useTimeout (hooks/use-click-outside, hooks/use-controllable-state, hooks/use-debounce, hooks/use-event-listener, hooks/use-filter, hooks/use-freshness, hooks/use-intersection-observer, hooks/use-interval, hooks/use-key-press, hooks/use-measure, hooks/use-media-query, hooks/use-mobile, hooks/use-overflow-count, hooks/use-range-select, hooks/use-roving-focus, hooks/use-scroll-overflow, hooks/use-search-source, hooks/use-smooth-resize, hooks/use-timeout)",—,"outside-press dismissal, controlled/uncontrolled state, debounced value, event subscription, locale-aware match, refresh + staleness state, intersection and resize observers, interval and timeout, key shortcut, matchMedia boolean, <768px boolean, +N overflow count, shift-click range select, roving tabindex, scroll-edge data attributes, async search source, animated height"
+upload-adapter,hooks,useUppyState · createUppyUploadHandler (lib/uppy-adapter),—,"caller-owned upload engine bound to a file picker's upload callback: per-file progress, success and error, one promise per batch"
+class-merge,utils,"mergeBaseClassName · isMobileDevice (lib/utils); cn from the cn package",cn,"clsx + tailwind-merge (the cn package); a Base UI state-callback className needs a wrapper that calls it before merging"
+formatting-utils,utils,"formatDate (lib/format) · generateId (lib/id) · formatRelativeTime · useNow (lib/time)",—,"Intl date formatting, nanoid ids, relative-time strings"
+composition-utils,utils,"getStrictContext (lib/get-strict-context) · composeRefs · useComposedRefs (lib/compose-refs) · Slot (lib/slot)",—,"throwing Provider/hook pair, ref composition, asChild prop-merging slot"
+color-utils,utils,readableOn (lib/color),—,"WCAG relative-luminance pick of white or near-black ink for a foreign hex fill"
+config-version,utils,upgradeConfig (lib/config-version),—,"version field on stored configs, versionless reads as 1, per-version migration steps that spread unknown fields"
+personality,setup,"PersonalityStyle · compileToCss · compileToVars · validatePersonality · diagnosePersonality · explainPersonality · PERSONALITY_DEFAULTS (lib/personality)",—,"product token file restating density padding/gap, motion durations, radius scale, elevation and accent custom properties at :root; no trait compiler"
 ```