@cascivo/react 0.1.0 → 0.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 # @cascivo/react
 
-> Prebuilt cascade design system components — use without copying source
+> Prebuilt cascivo design system components — use without copying source
 
 [cascivo.com](https://cascivo.com) · [Docs](https://docs.cascivo.com) · [Storybook](https://storybook.cascivo.com) · [GitHub](https://github.com/urbanisierung/cascivo)
 
@@ -15,9 +15,9 @@ can coexist in one project.
 ## Use
 
 ```tsx
-// once, in your entry file
-import '@cascivo/react/styles.css'
-import '@cascivo/themes/light'
+// once, in your entry file — two imports get you a fully themed setup
+import '@cascivo/react/styles.css' // component styles
+import '@cascivo/themes/all' // tokens (once) + base typography + light & dark
 
 // anywhere
 import { Button, Card, CardContent, Toggle } from '@cascivo/react'
@@ -36,182 +36,240 @@ export function App() {
 }
 ```
 
-Theming works exactly like the copy-paste flow: import a theme stylesheet and
-scope it with `data-theme="light" | "dark" | "warm"` on any container. Brand
+`@cascivo/themes/all` is the recommended single import: it loads `@cascivo/tokens`
+**once**, applies the base typography layer (so plain markup uses the sans font,
+not the browser serif default), and ships both the `light` and `dark` themes.
+
+Prefer à-la-carte? Import only the themes you need — each self-imports the tokens
+(deduped by URL, so light + dark load tokens once):
+
+```tsx
+import '@cascivo/react/styles.css'
+import '@cascivo/themes/base' // base typography (font/line-height/color)
+import '@cascivo/themes/light'
+import '@cascivo/themes/dark'
+```
+
+Scope a theme with `data-theme="light" | "dark" | "warm"` on any container. Brand
 adaptation happens by overriding `--cascivo-*` custom properties — no rebuild
 needed.
 
+### CSS layer ordering
+
+cascivo ships its styles in cascade layers, ordered lowest → highest priority:
+
+```
+cascivo.base  <  cascivo.theme  <  cascivo.component
+```
+
+**Unlayered** CSS in your app always beats every cascivo layer regardless of
+specificity, so your own (unlayered) styles win by default. To override cascivo
+from within a layer, declare a layer ordered after `cascivo.component`. See
+`CSS-LAYERS-PITFALL.md` for the full story and the recommended `@layer`
+declaration. Token names and aliases are documented in `TOKENS.md`.
+
 All components are client components (`'use client'` is preserved in the
 bundle), so the package works in Next.js App Router projects out of the box.
 
+## Migrating from shadcn/ui?
+
+See [`MIGRATING-FROM-SHADCN.md`](https://github.com/urbanisierung/cascivo/blob/main/docs/MIGRATING-FROM-SHADCN.md)
+for the variant/prop mapping (e.g. Button `default/outline` → `primary/secondary`,
+there is no `outline`) and the CSS-setup delta vs Tailwind.
+
+<!-- COMPONENT_INDEX:START -->
+
+## Component index
+
+158 components, exported from `@cascivo/react`. Full props, examples, and live demos at [docs.cascivo.com](https://docs.cascivo.com).
+
+### Inputs
+
+- **Button** — Triggers an action or event
+- **ButtonGroup** — Visually joins a set of related buttons into a single segmented control
+- **Calendar** — An accessible standalone month-grid date picker.
+- **Checkbox** — Binary toggle for forms, with indeterminate support
+- **CheckboxCard** — Multi-selectable card backed by a native checkbox. Use multiple independent CheckboxCards for multi-select scenarios.
+- **ColorPicker** — Interactive color selection widget with saturation/lightness area, hue and alpha sliders
+- **Combobox** — Filterable single-select with an animated custom listbox, built on the dropdown open/close machine
+- **CopyButton** — Icon button that copies a value to the clipboard with copied feedback
+- **DatePicker** — An accessible date-picker with a calendar popover.
+- **DateRangePicker** — A dual-calendar picker for selecting a contiguous date range.
+- **Editable** — Inline click-to-edit text field
+- **Field** — Form-field wrapper composing label, control, description, and error
+- **FileUploader** — Drag-and-drop file upload zone with file list and status indicators.
+- **Filter** — A group of toggleable pill or outline buttons for filtering content by category
+- **Form** — Typed signal-based form store (createForm/useForm) with sync/async validation and a thin Form element wrapper
+- **IconButton** — Square, icon-only button with a required accessible label
+- **Input** — Text input field with optional label, hint, and error state
+- **InputGroup** — Prefix/suffix addon wrapper for Input; InputGroupAddon renders inline icons/units inside the field border; ButtonGroup collapses adjacent button borders
+- **Label** — Accessible caption for a form control
+- **MultiSelect** — Searchable multi-value select with popover listbox
+- **NativeSelect** — A styled native <select> that keeps platform form/keyboard behavior with a custom chevron and focus ring
+- **NumberInput** — Numeric input with stepper buttons, clamping, precision, and locale formatting
+- **OtpInput** — Segmented one-time code input
+- **PasswordInput** — Password input with reveal toggle and optional strength meter
+- **Radio** — Single choice from a set, grouped with RadioGroup
+- **RadioCard** — Selectable card backed by a native radio input. Use RadioCardGroup for single-select groups.
+- **RatingGroup** — Star rating input with accessible radio group pattern
+- **Search** — Search input with debounced search callback and clear button
+- **SegmentedControl** — Mutually exclusive toggle group
+- **Select** — Native select menu styled to match the design system
+- **Slider** — Range input for selecting a value within bounds
+- **Swap** — Animated toggle between two icon/content states with rotate or flip transition
+- **TagsInput** — Free-form multi-value chip input
+- **Textarea** — Multi-line text input with optional label, hint, and error state
+- **Tile** — A selectable card with radio (single) or checkbox (multi) semantics, toggled by click or keyboard
+- **TimePicker** — Native time input wrapper with label, hint, error, and size variants
+- **Toggle** — On/off switch built as an accessible button
+- **ToggleGroup** — A set of toggle buttons for single or multiple selection
+
+### Display
+
+- **Alert** — Highlights a short, important message inline
+- **Avatar** — Displays a user image with initials fallback
+- **Badge** — Small status label or category indicator
+- **Blockquote** — Quoted passage with optional attribution footer
+- **Card** — Container for grouping related content
+- **Carousel** — Scroll-snap slide deck with previous/next controls and dot indicators
+- **ChatBubble** — Message bubble for chat and messaging UIs with avatar, name, and timestamp support
+- **Code** — Inline code span for identifiers, commands, and short snippets
+- **CodeSnippet** — Displays code (inline, single-line, or multi-line) with an optional copy button, lightweight built-in syntax highlighting for bash/css/js/ts, and an optional terminal-window look
+- **Collapsible** — A single disclosure region toggled open and closed by its trigger
+- **ConsoleApp** — Carbon-parity console shell: ShellHeader + icon-rail SideNav + HeaderPanel notifications/switcher + collapsible aside + main content.
+- **ContainedList** — Labelled list of rows inside a bordered container
+- **DashboardCharts** — Dashboard layout with KPI tiles, line chart, bar chart, and pie chart.
+- **DataList** — Key-value pairs rendered as a description list
+- **DataTable** — Signal-driven data table with client/server sort, filter, pagination, multi-selection, expandable rows, and CSS content-visibility row containment for large datasets
+- **EmptyDashboard** — Dashboard page showing an empty state with a call-to-action button.
+- **EmptyState** — Placeholder for views that have no data to display
+- **Heading** — Section heading with semantic level decoupled from visual size
+- **Item** — Generic content row primitive with media, content, and action regions
+- **Kbd** — Displays a keyboard key or shortcut
+- **List** — Styled unordered or ordered list with ListItem
+- **LoginPage** — Authentication login page with email and password form.
+- **NotificationCenter** — A list of notification alerts with a mark-all-read action.
+- **PageWithBreadcrumb** — A centered content page with a breadcrumb navigation and page header.
+- **Prose** — Wrapper that styles raw descendant HTML — headings, lists, code, quotes, tables
+- **Separator** — Visual or semantic divider between content
+- **SettingsFormPage** — Settings page with profile form inside a two-column settings layout.
+- **SidebarApp** — Full app shell with collapsible side navigation and top header.
+- **Skeleton** — Animated loading placeholder that mirrors the shape of pending content
+- **Stat** — Displays a key metric with optional delta, trend direction and help text
+- **StatsCards** — Grid of KPI stat cards with trend badges.
+- **Status** — Colored dot with a label communicating the state of a system or entity
+- **StructuredList** — Tabular row list for scannable data, optionally single-selectable
+- **Tag** — Compact chip for labeling, categorizing, or filtering content
+- **Text** — Body text with size, weight, and muted variants
+- **Timeline** — Ordered sequence of events with status markers and a connector line
+- **TreeView** — Hierarchical, expandable tree of nodes with keyboard navigation and selection
+- **UsersTablePage** — Full users management page with table, search, and invite action.
+- **VisuallyHidden** — Hides content visually while keeping it available to screen readers
+
+### Overlay
+
+- **AlertDialog** — Confirmation dialog requiring explicit user action; no light-dismiss
+- **CommandMenu** — Cmd+K command palette with fuzzy search over grouped commands
+- **ContextMenu** — Right-click context menu anchored at pointer coordinates via CSS custom properties
+- **Drawer** — Edge-anchored dialog panel that slides in from a screen edge with CSS-only enter/exit motion
+- **Dropdown** — Menu of actions revealed from a trigger
+- **HoverCard** — Hover-triggered popover with configurable open/close delay
+- **Menu** — Dropdown menu with keyboard navigation, built on usePopover
+- **Modal** — Accessible dialog overlay using native <dialog> element
+- **OverflowMenu** — Kebab icon button revealing a menu of row-level actions
+- **Popover** — Anchored floating panel built on CSS Anchor Positioning + Popover API
+- **Sheet** — Slide-in panel from any edge, using popover=manual and @starting-style animations
+- **Toast** — Transient notification surfaced via the useToast hook
+- **Toggletip** — A click-triggered info popover for supplementary, selectable content
+- **Tooltip** — Contextual label shown on hover or focus
+
+### Navigation
+
+- **Accordion** — Vertically stacked, collapsible content sections
+- **Breadcrumb** — Shows the current page location within a navigation hierarchy
+- **Dock** — Fixed bottom navigation bar for mobile app shells with up to 5 items
+- **Header** — App top bar with brand, primary navigation links, and an actions slot
+- **HeaderPanel** — Non-modal panel anchored below the shell header at the inline-end edge — hosts notifications, app switcher, user settings
+- **Link** — Styled anchor for navigation, standalone or inline within prose
+- **Menubar** — Horizontal application menu bar with keyboard-navigable dropdown menus
+- **MenuButton** — A button that opens an anchored action menu of one-shot commands
+- **NavigationMenu** — Site navigation bar with links and dropdown flyout panels
+- **Pagination** — Controls for navigating paged data sets, with page size selection
+- **ProgressIndicator** — Shows progress through the steps of a multi-step flow
+- **ShellHeader** — Console application header: brand with prefix, dropdown nav menus, global icon actions, hamburger, skip-to-content
+- **SideNav** — Collapsible sidebar navigation with optional icons and one level of grouping
+- **SkipNav** — Skip link that jumps keyboard users past the navigation to the main content
+- **Steps** — Visual progress indicator for multi-step flows with horizontal and vertical orientations
+- **Switcher** — App/product switcher list — lives inside HeaderPanel, renders links with active indicator and optional dividers
+- **Tabs** — Switch between related panels of content
+
+### Layout
+
+- **AppShell** — Sticky-header + full-height side-nav + single-scroll-container layout with an animated, accessible nav toggle.
+- **AppShell** — Full-page application shell with persisted collapsible sidebar. Includes a signal-driven top progress bar with determinate progress, error state, and dismissible error strip.
+- **AspectRatio** — Constrains content to a fixed width-to-height ratio
+- **AuthLayout** — Centered card layout for authentication pages (login, register, forgot password).
+- **AutoGrid** — Media-query-free responsive grid — columns auto-fill based on available space.
+- **Center** — Horizontally centered container with a configurable max-width.
+- **Columns** — Equal-width multi-column layout that collapses to single column on narrow viewports.
+- **Cta** — Call-to-action band — quiet hairline-bordered section with title, description, and centered actions. Replace demo content before shipping.
+- **DashboardLayout** — Dashboard page layout with stats strip, main content area, and optional aside.
+- **FeatureGrid** — Feature section — AutoGrid of items with optional title, description, and icon slots. Icons are optional; the grid works text-only. Replace demo content before shipping.
+- **Grid** — CSS grid layout primitive with responsive column collapsing.
+- **Hero** — Page hero section — centered or split layout with eyebrow, title, description, actions and media slots. Replace demo content before shipping.
+- **Indicator** — Positions an overlay element (badge, dot, count) at a corner of its child
+- **Join** — Groups adjacent children into a seamless joined element by removing interior borders and radii
+- **Masonry** — Masonry layout — native CSS masonry where supported, multi-column fallback elsewhere (fallback orders items top-to-bottom per column).
+- **MediaMasonry** — Masonry gallery section — native CSS masonry where supported, multi-column fallback elsewhere (fallback orders tiles top-to-bottom per column). Tiles style themselves; section provides only the layout shell.
+- **PageFooter** — Site footer — AutoGrid of link groups with a brand/meta bottom row. Renders a <footer> element with a <nav aria-label="Footer"> wrapping the link columns.
+- **PageHeader** — Page-level header with title, description, breadcrumb, and actions slots.
+- **Resizable** — Two-pane splitter whose divider can be dragged or keyboard-nudged to reallocate space
+- **ScrollArea** — A scroll container with styled, slim scrollbars and overflow shadows
+- **Section** — Page-section shell with block padding, centered inner width, and stack gap.
+- **SettingsLayout** — Two-column settings page layout with a fixed-width menu and fluid content area.
+- **Spacer** — Fixed-height spacing block using design token steps.
+- **SplitView** — Resizable two-pane split layout with keyboard and pointer drag support.
+- **Stack** — Overlaps children in a CSS grid stack with a configurable offset to create a card-pile effect
+- **Stack** — Flex layout primitive for vertical or horizontal stacking with gap control.
+- **StatsBand** — KPI strip — horizontal band of stats with optional delta and inline sparkline trend. Wraps via AutoGrid on narrow containers. No visible heading; provide aria-label for accessibility.
+
+### Feedback
+
+- **InlineLoading** — Compact inline status indicator that pairs a label with a loading, success, or error state
+- **Notification** — Inline, actionable notification banner that surfaces a titled message with an optional recovery action
+- **Progress** — Horizontal bar showing the completion progress of a tracked operation
+- **ProgressBar** — Shows determinate or indeterminate progress of a task
+- **ProgressCircle** — Circular determinate progress indicator rendered as an SVG arc
+- **RadialProgress** — Circular progress indicator using conic-gradient, with percentage label and variant colors
+- **Spinner** — Indeterminate loading indicator
+
+### Charts
+
+- **AreaChart** — Area chart with optional stacking, multi-series support, and hover tooltip.
+- **BarChart** — Bar chart with vertical/horizontal orientation, grouped or stacked modes, and multi-series support.
+- **Boxplot** — Box-and-whisker plot with five-number summary and outlier dots per series.
+- **BubbleChart** — Bubble chart mapping x, y, and size dimensions; radius is area-proportional via sqrt scale.
+- **Bullet** — Bullet chart with background range bands, measure bar, and target tick.
+- **ComboChart** — Combination bar + line chart on shared or dual y-axes.
+- **Heatmap** — Two-dimensional heatmap with band scales and color-mix cell interpolation.
+- **Histogram** — Frequency histogram using Freedman–Diaconis binning with hover tooltips.
+- **Kpi** — KPI card showing a primary metric with optional delta indicator, icon, and sparkline.
+- **LineChart** — Time-series or numeric line chart with multi-series support, hover tooltip, and legend.
+- **Meter** — Progress meter in bar or gauge variant with threshold coloring.
+- **PieChart** — Pie or donut chart with hover segments and optional legend.
+- **Radar** — Radar / spider chart with polar grid rings, spokes, and multi-series polygon overlays.
+- **ScatterChart** — Scatter plot with variable point radius, multi-series, and hover tooltip.
+- **Sparkline** — Compact inline sparkline for embedding trend data in dashboards or KPI cards.
+- **Treemap** — Squarified treemap for visualizing part-to-whole hierarchical data.
+
+<!-- COMPONENT_INDEX:END -->
+
 ## Install
 
 ```sh
 pnpm add @cascivo/react
 ```
 
-## Components
-
-| Name                       | Category   | Description                                                                                                                                                                                                     |
-| -------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| accordion                  | navigation | Vertically stacked, collapsible content sections                                                                                                                                                                |
-| alert                      | display    | Highlights a short, important message inline                                                                                                                                                                    |
-| alert-dialog               | overlay    | Confirmation dialog requiring explicit user action; no light-dismiss                                                                                                                                            |
-| aspect-ratio               | layout     | Constrains content to a fixed width-to-height ratio                                                                                                                                                             |
-| avatar                     | display    | Displays a user image with initials fallback                                                                                                                                                                    |
-| badge                      | display    | Small status label or category indicator                                                                                                                                                                        |
-| blockquote                 | display    | Quoted passage with optional attribution footer                                                                                                                                                                 |
-| breadcrumb                 | navigation | Shows the current page location within a navigation hierarchy                                                                                                                                                   |
-| button                     | inputs     | Triggers an action or event                                                                                                                                                                                     |
-| button-group               | inputs     | Visually joins a set of related buttons into a single segmented control                                                                                                                                         |
-| calendar                   | inputs     | An accessible standalone month-grid date picker.                                                                                                                                                                |
-| card                       | display    | Container for grouping related content                                                                                                                                                                          |
-| carousel                   | display    | Scroll-snap slide deck with previous/next controls and dot indicators                                                                                                                                           |
-| chat-bubble                | display    | Message bubble for chat and messaging UIs with avatar, name, and timestamp support                                                                                                                              |
-| checkbox                   | inputs     | Binary toggle for forms, with indeterminate support                                                                                                                                                             |
-| checkbox-card              | inputs     | Multi-selectable card backed by a native checkbox. Use multiple independent CheckboxCards for multi-select scenarios.                                                                                           |
-| code                       | display    | Inline code span for identifiers, commands, and short snippets                                                                                                                                                  |
-| code-snippet               | display    | Displays code (inline, single-line, or multi-line) with an optional copy button; no syntax highlighting                                                                                                         |
-| collapsible                | display    | A single disclosure region toggled open and closed by its trigger                                                                                                                                               |
-| color-picker               | inputs     | Interactive color selection widget with saturation/lightness area, hue and alpha sliders                                                                                                                        |
-| combobox                   | inputs     | Filterable single-select with an animated custom listbox, built on the dropdown open/close machine                                                                                                              |
-| command-menu               | overlay    | Cmd+K command palette with fuzzy search over grouped commands                                                                                                                                                   |
-| contained-list             | display    | Labelled list of rows inside a bordered container                                                                                                                                                               |
-| context-menu               | overlay    | Right-click context menu anchored at pointer coordinates via CSS custom properties                                                                                                                              |
-| copy-button                | inputs     | Icon button that copies a value to the clipboard with copied feedback                                                                                                                                           |
-| data-list                  | display    | Key-value pairs rendered as a description list                                                                                                                                                                  |
-| data-table                 | display    | Signal-driven data table with client/server sort, filter, pagination, multi-selection, expandable rows, and CSS content-visibility row containment for large datasets                                           |
-| date-picker                | inputs     | An accessible date-picker with a calendar popover.                                                                                                                                                              |
-| date-range-picker          | inputs     | A dual-calendar picker for selecting a contiguous date range.                                                                                                                                                   |
-| dock                       | navigation | Fixed bottom navigation bar for mobile app shells with up to 5 items                                                                                                                                            |
-| drawer                     | overlay    | Edge-anchored dialog panel that slides in from a screen edge with CSS-only enter/exit motion                                                                                                                    |
-| dropdown                   | overlay    | Menu of actions revealed from a trigger                                                                                                                                                                         |
-| editable                   | inputs     | Inline click-to-edit text field                                                                                                                                                                                 |
-| empty-state                | display    | Placeholder for views that have no data to display                                                                                                                                                              |
-| field                      | inputs     | Form-field wrapper composing label, control, description, and error                                                                                                                                             |
-| file-uploader              | inputs     | Drag-and-drop file upload zone with file list and status indicators.                                                                                                                                            |
-| filter                     | inputs     | A group of toggleable pill or outline buttons for filtering content by category                                                                                                                                 |
-| form                       | inputs     | Typed signal-based form store (createForm/useForm) with sync/async validation and a thin Form element wrapper                                                                                                   |
-| header                     | navigation | App top bar with brand, primary navigation links, and an actions slot                                                                                                                                           |
-| header-panel               | navigation | Non-modal panel anchored below the shell header at the inline-end edge — hosts notifications, app switcher, user settings                                                                                       |
-| heading                    | display    | Section heading with semantic level decoupled from visual size                                                                                                                                                  |
-| hover-card                 | overlay    | Hover-triggered popover with configurable open/close delay                                                                                                                                                      |
-| icon-button                | inputs     | Square, icon-only button with a required accessible label                                                                                                                                                       |
-| indicator                  | layout     | Positions an overlay element (badge, dot, count) at a corner of its child                                                                                                                                       |
-| inline-loading             | feedback   | Compact inline status indicator that pairs a label with a loading, success, or error state                                                                                                                      |
-| input                      | inputs     | Text input field with optional label, hint, and error state                                                                                                                                                     |
-| input-group                | inputs     | Prefix/suffix addon wrapper for Input; InputGroupAddon renders inline icons/units inside the field border; ButtonGroup collapses adjacent button borders                                                        |
-| item                       | display    | Generic content row primitive with media, content, and action regions                                                                                                                                           |
-| join                       | layout     | Groups adjacent children into a seamless joined element by removing interior borders and radii                                                                                                                  |
-| kbd                        | display    | Displays a keyboard key or shortcut                                                                                                                                                                             |
-| label                      | inputs     | Accessible caption for a form control                                                                                                                                                                           |
-| link                       | navigation | Styled anchor for navigation, standalone or inline within prose                                                                                                                                                 |
-| list                       | display    | Styled unordered or ordered list with ListItem                                                                                                                                                                  |
-| menu                       | overlay    | Dropdown menu with keyboard navigation, built on usePopover                                                                                                                                                     |
-| menu-button                | navigation | A button that opens an anchored action menu of one-shot commands                                                                                                                                                |
-| menubar                    | navigation | Horizontal application menu bar with keyboard-navigable dropdown menus                                                                                                                                          |
-| modal                      | overlay    | Accessible dialog overlay using native <dialog> element                                                                                                                                                         |
-| multi-select               | inputs     | Searchable multi-value select with popover listbox                                                                                                                                                              |
-| native-select              | inputs     | A styled native <select> that keeps platform form/keyboard behavior with a custom chevron and focus ring                                                                                                        |
-| navigation-menu            | navigation | Site navigation bar with links and dropdown flyout panels                                                                                                                                                       |
-| notification               | feedback   | Inline, actionable notification banner that surfaces a titled message with an optional recovery action                                                                                                          |
-| number-input               | inputs     | Numeric input with stepper buttons, clamping, precision, and locale formatting                                                                                                                                  |
-| otp-input                  | inputs     | Segmented one-time code input                                                                                                                                                                                   |
-| overflow-menu              | overlay    | Kebab icon button revealing a menu of row-level actions                                                                                                                                                         |
-| pagination                 | navigation | Controls for navigating paged data sets, with page size selection                                                                                                                                               |
-| password-input             | inputs     | Password input with reveal toggle and optional strength meter                                                                                                                                                   |
-| popover                    | overlay    | Anchored floating panel built on CSS Anchor Positioning + Popover API                                                                                                                                           |
-| progress                   | feedback   | Horizontal bar showing the completion progress of a tracked operation                                                                                                                                           |
-| progress-bar               | feedback   | Shows determinate or indeterminate progress of a task                                                                                                                                                           |
-| progress-circle            | feedback   | Circular determinate progress indicator rendered as an SVG arc                                                                                                                                                  |
-| progress-indicator         | navigation | Shows progress through the steps of a multi-step flow                                                                                                                                                           |
-| prose                      | display    | Wrapper that styles raw descendant HTML — headings, lists, code, quotes, tables                                                                                                                                 |
-| radial-progress            | feedback   | Circular progress indicator using conic-gradient, with percentage label and variant colors                                                                                                                      |
-| radio                      | inputs     | Single choice from a set, grouped with RadioGroup                                                                                                                                                               |
-| radio-card                 | inputs     | Selectable card backed by a native radio input. Use RadioCardGroup for single-select groups.                                                                                                                    |
-| rating-group               | inputs     | Star rating input with accessible radio group pattern                                                                                                                                                           |
-| resizable                  | layout     | Two-pane splitter whose divider can be dragged or keyboard-nudged to reallocate space                                                                                                                           |
-| scroll-area                | layout     | A scroll container with styled, slim scrollbars and overflow shadows                                                                                                                                            |
-| search                     | inputs     | Search input with debounced search callback and clear button                                                                                                                                                    |
-| segmented-control          | inputs     | Mutually exclusive toggle group                                                                                                                                                                                 |
-| select                     | inputs     | Native select menu styled to match the design system                                                                                                                                                            |
-| separator                  | display    | Visual or semantic divider between content                                                                                                                                                                      |
-| sheet                      | overlay    | Slide-in panel from any edge, using popover=manual and @starting-style animations                                                                                                                               |
-| shell-header               | navigation | Console application header: brand with prefix, dropdown nav menus, global icon actions, hamburger, skip-to-content                                                                                              |
-| side-nav                   | navigation | Collapsible sidebar navigation with optional icons and one level of grouping                                                                                                                                    |
-| skeleton                   | display    | Animated loading placeholder that mirrors the shape of pending content                                                                                                                                          |
-| skip-nav                   | navigation | Skip link that jumps keyboard users past the navigation to the main content                                                                                                                                     |
-| slider                     | inputs     | Range input for selecting a value within bounds                                                                                                                                                                 |
-| spinner                    | feedback   | Indeterminate loading indicator                                                                                                                                                                                 |
-| stack                      | layout     | Overlaps children in a CSS grid stack with a configurable offset to create a card-pile effect                                                                                                                   |
-| stat                       | display    | Displays a key metric with optional delta, trend direction and help text                                                                                                                                        |
-| status                     | display    | Colored dot with a label communicating the state of a system or entity                                                                                                                                          |
-| steps                      | navigation | Visual progress indicator for multi-step flows with horizontal and vertical orientations                                                                                                                        |
-| structured-list            | display    | Tabular row list for scannable data, optionally single-selectable                                                                                                                                               |
-| swap                       | inputs     | Animated toggle between two icon/content states with rotate or flip transition                                                                                                                                  |
-| switcher                   | navigation | App/product switcher list — lives inside HeaderPanel, renders links with active indicator and optional dividers                                                                                                 |
-| tabs                       | navigation | Switch between related panels of content                                                                                                                                                                        |
-| tag                        | display    | Compact chip for labeling, categorizing, or filtering content                                                                                                                                                   |
-| tags-input                 | inputs     | Free-form multi-value chip input                                                                                                                                                                                |
-| text                       | display    | Body text with size, weight, and muted variants                                                                                                                                                                 |
-| textarea                   | inputs     | Multi-line text input with optional label, hint, and error state                                                                                                                                                |
-| tile                       | inputs     | A selectable card with radio (single) or checkbox (multi) semantics, toggled by click or keyboard                                                                                                               |
-| time-picker                | inputs     | Native time input wrapper with label, hint, error, and size variants                                                                                                                                            |
-| timeline                   | display    | Ordered sequence of events with status markers and a connector line                                                                                                                                             |
-| toast                      | overlay    | Transient notification surfaced via the useToast hook                                                                                                                                                           |
-| toggle                     | inputs     | On/off switch built as an accessible button                                                                                                                                                                     |
-| toggle-group               | inputs     | A set of toggle buttons for single or multiple selection                                                                                                                                                        |
-| toggletip                  | overlay    | A click-triggered info popover for supplementary, selectable content                                                                                                                                            |
-| tooltip                    | overlay    | Contextual label shown on hover or focus                                                                                                                                                                        |
-| tree-view                  | display    | Hierarchical, expandable tree of nodes with keyboard navigation and selection                                                                                                                                   |
-| visually-hidden            | display    | Hides content visually while keeping it available to screen readers                                                                                                                                             |
-| layout/app-shell           | layout     | Full-page application shell with persisted collapsible sidebar. Includes a signal-driven top progress bar with determinate progress, error state, and dismissible error strip.                                  |
-| layout/auth-layout         | layout     | Centered card layout for authentication pages (login, register, forgot password).                                                                                                                               |
-| layout/auto-grid           | layout     | Media-query-free responsive grid — columns auto-fill based on available space.                                                                                                                                  |
-| layout/center              | layout     | Horizontally centered container with a configurable max-width.                                                                                                                                                  |
-| layout/columns             | layout     | Equal-width multi-column layout that collapses to single column on narrow viewports.                                                                                                                            |
-| layout/dashboard-layout    | layout     | Dashboard page layout with stats strip, main content area, and optional aside.                                                                                                                                  |
-| layout/grid                | layout     | CSS grid layout primitive with responsive column collapsing.                                                                                                                                                    |
-| layout/masonry             | layout     | Masonry layout — native CSS masonry where supported, multi-column fallback elsewhere (fallback orders items top-to-bottom per column).                                                                          |
-| layout/page-header         | layout     | Page-level header with title, description, breadcrumb, and actions slots.                                                                                                                                       |
-| layout/section             | layout     | Page-section shell with block padding, centered inner width, and stack gap.                                                                                                                                     |
-| layout/settings-layout     | layout     | Two-column settings page layout with a fixed-width menu and fluid content area.                                                                                                                                 |
-| layout/spacer              | layout     | Fixed-height spacing block using design token steps.                                                                                                                                                            |
-| layout/split-view          | layout     | Resizable two-pane split layout with keyboard and pointer drag support.                                                                                                                                         |
-| layout/stack               | layout     | Flex layout primitive for vertical or horizontal stacking with gap control.                                                                                                                                     |
-| block/console-app          | display    | Carbon-parity console shell: ShellHeader + icon-rail SideNav + HeaderPanel notifications/switcher + collapsible aside + main content.                                                                           |
-| block/dashboard-charts     | display    | Dashboard layout with KPI tiles, line chart, bar chart, and pie chart.                                                                                                                                          |
-| block/empty-dashboard      | display    | Dashboard page showing an empty state with a call-to-action button.                                                                                                                                             |
-| block/login-page           | display    | Authentication login page with email and password form.                                                                                                                                                         |
-| block/notification-center  | display    | A list of notification alerts with a mark-all-read action.                                                                                                                                                      |
-| block/page-with-breadcrumb | display    | A centered content page with a breadcrumb navigation and page header.                                                                                                                                           |
-| block/settings-form-page   | display    | Settings page with profile form inside a two-column settings layout.                                                                                                                                            |
-| block/sidebar-app          | display    | Full app shell with collapsible side navigation and top header.                                                                                                                                                 |
-| block/stats-cards          | display    | Grid of KPI stat cards with trend badges.                                                                                                                                                                       |
-| block/users-table-page     | display    | Full users management page with table, search, and invite action.                                                                                                                                               |
-| chart/area-chart           | chart      | Area chart with optional stacking, multi-series support, and hover tooltip.                                                                                                                                     |
-| chart/bar-chart            | chart      | Bar chart with vertical/horizontal orientation, grouped or stacked modes, and multi-series support.                                                                                                             |
-| chart/boxplot              | chart      | Box-and-whisker plot with five-number summary and outlier dots per series.                                                                                                                                      |
-| chart/bubble-chart         | chart      | Bubble chart mapping x, y, and size dimensions; radius is area-proportional via sqrt scale.                                                                                                                     |
-| chart/bullet               | chart      | Bullet chart with background range bands, measure bar, and target tick.                                                                                                                                         |
-| chart/combo-chart          | chart      | Combination bar + line chart on shared or dual y-axes.                                                                                                                                                          |
-| chart/heatmap              | chart      | Two-dimensional heatmap with band scales and color-mix cell interpolation.                                                                                                                                      |
-| chart/histogram            | chart      | Frequency histogram using Freedman–Diaconis binning with hover tooltips.                                                                                                                                        |
-| chart/kpi                  | chart      | KPI card showing a primary metric with optional delta indicator, icon, and sparkline.                                                                                                                           |
-| chart/line-chart           | chart      | Time-series or numeric line chart with multi-series support, hover tooltip, and legend.                                                                                                                         |
-| chart/meter                | chart      | Progress meter in bar or gauge variant with threshold coloring.                                                                                                                                                 |
-| chart/pie-chart            | chart      | Pie or donut chart with hover segments and optional legend.                                                                                                                                                     |
-| chart/radar                | chart      | Radar / spider chart with polar grid rings, spokes, and multi-series polygon overlays.                                                                                                                          |
-| chart/scatter-chart        | chart      | Scatter plot with variable point radius, multi-series, and hover tooltip.                                                                                                                                       |
-| chart/sparkline            | chart      | Compact inline sparkline for embedding trend data in dashboards or KPI cards.                                                                                                                                   |
-| chart/treemap              | chart      | Squarified treemap for visualizing part-to-whole hierarchical data.                                                                                                                                             |
-| section/cta                | layout     | Call-to-action band — quiet hairline-bordered section with title, description, and centered actions. Replace demo content before shipping.                                                                      |
-| section/feature-grid       | layout     | Feature section — AutoGrid of items with optional title, description, and icon slots. Icons are optional; the grid works text-only. Replace demo content before shipping.                                       |
-| section/hero               | layout     | Page hero section — centered or split layout with eyebrow, title, description, actions and media slots. Replace demo content before shipping.                                                                   |
-| section/media-masonry      | layout     | Masonry gallery section — native CSS masonry where supported, multi-column fallback elsewhere (fallback orders tiles top-to-bottom per column). Tiles style themselves; section provides only the layout shell. |
-| section/page-footer        | layout     | Site footer — AutoGrid of link groups with a brand/meta bottom row. Renders a <footer> element with a <nav aria-label="Footer"> wrapping the link columns.                                                      |
-| section/stats-band         | layout     | KPI strip — horizontal band of stats with optional delta and inline sparkline trend. Wraps via AutoGrid on narrow containers. No visible heading; provide aria-label for accessibility.                         |
-
 ---
 
 [cascivo.com](https://cascivo.com) · [Docs](https://docs.cascivo.com) · [Storybook](https://storybook.cascivo.com) · [GitHub](https://github.com/urbanisierung/cascivo) · AI agents: use [`@cascivo/mcp`](https://github.com/urbanisierung/cascivo/tree/main/packages/mcp) and [`registry.json`](https://github.com/urbanisierung/cascivo/blob/main/registry.json) · MIT