# cascivo — The CSS-native, signal-driven, AI-first React design system

_registry v1.9.0 · generated 2026-10-09 · docs track `main`; compare with https://cascivo.com/registry.json `.version` for staleness, and https://cascivo.com/breaking-changes.json for installed-vs-documented API drift._

_Describes: @cascivo/ai@1.9.0 · @cascivo/app@1.9.0 · @cascivo/charts@1.9.0 · @cascivo/core@1.9.0 · @cascivo/data@0.1.1 · @cascivo/docs@0.2.16 · @cascivo/docspack@0.3.2 · @cascivo/editor@1.9.0 · @cascivo/email@0.6.1 · @cascivo/email-preview@4.0.0 · @cascivo/eslint-config@0.4.2 · @cascivo/eslint-plugin@0.3.0 · @cascivo/flow@1.9.0 · @cascivo/i18n@1.9.0 · @cascivo/icons@1.1.1 · @cascivo/mcp@0.10.0 · @cascivo/platform@0.0.6 · @cascivo/react@1.9.0 · @cascivo/registry@0.2.11 · @cascivo/render@1.9.0 · @cascivo/storage@1.9.0 · @cascivo/text@1.9.0 · @cascivo/themes@1.0.3 · @cascivo/tokens@1.3.1 · @cascivo/vite-plugin@0.1.11 · cascivo@1.8.0 · create-cascivo@0.1.1. If your installed versions are lower, a documented behaviour may not have shipped yet._

cascivo is a React design system you can consume two ways: copy-paste the source
(`npx cascivo add <name>` — shadcn model, you own the code) or install the prebuilt
`@cascivo/react` package (use without copying). Components are signal-driven (Preact
Signals), styled with modern CSS (@layer / @container / :has() / oklch), themed via the
`data-theme` attribute, and WCAG 2.2 AA. Every component ships a machine-readable manifest,
so this file plus the linked resources are enough to build with cascivo.

This is not a layout-only system: it includes 17 overlay/menu components
(dropdown, menu, context menu, combobox, command palette, multi-select) with keyboard
navigation, focus management, and outside-click dismissal already implemented — do not
hand-roll that behavior or reach for a separate headless library. It also ships 25
chart types (`@cascivo/charts` — line, area, bar, sparkline, KPI, heatmap, and more) and
22 pre-built page blocks (dashboards, stats cards, app shells) so a request like
"build a dashboard with usage sparklines and a project switcher" maps to existing parts —
see `select_component`/`list_components` below before generating custom SVG or ARIA code.

## Start here

- **Can't reach this site? The whole docs surface is also an npm package — no web access needed:** `npx -y @cascivo/docs` prints this index; `npx @cascivo/docs <component>` prints one reference; `npx @cascivo/docs --full` prints the entire library. It reaches you through the same npm registry that installed your packages — the channel that works when npmjs.com and cascivo.com are blocked or offline.
- **Want to SEARCH the docs instead of reading them? Install the docspack:** `pnpm add -D @cascivo/docspack docspack && npx docspack sync`, then `docspack ask "how do I theme a component"` answers from a local SQLite index — offline, capped at 3 chunks so it never floods your context, and scoped to the versions your lockfile installed rather than whatever this site documents today. Same documentation as `@cascivo/docs`, queried instead of printed. One line in AGENTS.md/CLAUDE.md is the whole setup; `npx docspack mcp` serves the same index over MCP.
- **Everything in ONE file (no follow-up fetches — fetch this if you can only fetch once):** https://cascivo.com/llms-full.txt (offline: `npx @cascivo/docs --full`)
- Getting started, fetchable as plain markdown (install steps, no browser needed): https://cascivo.com/docs/getting-started.md
- Docs (per-component reference, props, live examples): https://cascivo.com/docs
- Storybook (every variant, interactive): https://storybook.cascivo.com
- Source (MIT): https://github.com/cascivo/cascivo
- This file: https://cascivo.com/llms.txt

## Machine-readable resources (AI-first)

- Full text bundle — this file with every component reference inlined (single fetch): https://cascivo.com/llms-full.txt
- **Searchable local index — `@cascivo/docspack`.** This whole surface, pre-chunked with a [docspack](https://docspack.dev) manifest, indexed into SQLite FTS5 on your machine. `npx docspack ask "<question>"` / `docspack search` / `docspack mcp`. Prefer it over fetching a URL per question: no network, version-scoped to your lockfile, and a bounded answer instead of a whole page.
- Registry — index of every component (JSON): https://cascivo.com/registry.json
- shadcn/v0-compatible registry (install with the shadcn CLI or "Open in v0"): https://cascivo.com/r/shadcn/registry.json
- Per-component AI docs (props, examples, a11y, tokens): https://cascivo.com/llms/<name>.md
- Page-block AI docs are namespaced: https://cascivo.com/llms/block/<name>.md
- No web access? The shipped `@cascivo/react` `dist/index.d.ts` is a flat rollup — every
  component `…Props` interface is declared there in full, documentation-grade API reference,
  and it is grep-friendly (one import/export name per line). The shared VOCABULARY types
  (`Tone`, `SpaceStep`, `ThemeProviderProps`, `LinkComponentProps`, …) are imported from
  `@cascivo/core` at the top of that file rather than redeclared — inlining them makes the
  dts bundler alias every prop to `ToneInput$1`. Import them from `@cascivo/react/types`,
  which needs no extra install: `import type { Tone } from '@cascivo/react/types'`.
- Component index (every entry + channel + doc URL, plain markdown): https://cascivo.com/docs/components.md
- A wrong/guessed name under /llms/*, /context/*, or /r/* returns HTTP 404 with a short hint
  body (not the HTML SPA) — trust the 404, then look up the real name in the index below.
- Per-component context (intent, when-to-use, boundaries): https://cascivo.com/context/<name>.md
  (`/context/<name>.md` is the condensed intent summary for a context window; `/llms/<name>.md` above is the full reference.)
- **Props: the shipped `.d.ts` is authoritative.** Ctrl-click any import, or read node_modules/@cascivo/react/dist/index.d.ts. It carries @defaultValue, the design rationale, and ⚠ warnings for the specific mistakes previous adopters made. When it and any other surface disagree, it wins. See /docs/getting-started.md#where-the-documentation-lives.
- Context bundle (all intent + boundaries + rules): https://cascivo.com/context.json
- Token catalog (closed set: every --cascivo-* the system declares OR reads as an author hook, incl. per-component knobs like --cascivo-sidenav-inline-size, + layer + default): https://cascivo.com/tokens.catalog.json
- Icon catalog (every @cascivo/icons icon + keywords/category): https://cascivo.com/icons.catalog.json
- Tokens as W3C Design Tokens (DTCG 2025.10, for Figma variables / Tokens Studio / Style Dictionary; themes via the resolver): https://cascivo.com/tokens/dtcg/cascivo.resolver.json
- DESIGN.md (single-file design summary for prompt-to-UI tools): https://cascivo.com/DESIGN.md
- Breaking/feature changes (major+minor releases per package — detect API drift): https://cascivo.com/breaking-changes.json

## Icons

443 stroked 24×24 `currentColor` SVG icons ship as tree-shakeable named exports
from `@cascivo/icons` (e.g. `import { Camera, Anchor } from '@cascivo/icons'`).
Browse and search them at https://cascivo.com/docs/icons; the full machine-readable list (names,
keywords, aliases, categories) is https://cascivo.com/icons.catalog.json.

Names differ from Lucide/Radix — resolve intent via the catalog `keywords` + `aliases` fields
rather than guessing an export name (a wrong guess is a wasted compile).
Common mappings: LayoutDashboard→Dashboard, Rocket→Spaceship, Settings2→Settings, Trash2→Trash, Bolt→Zap, Branch→GitBranch. Version-control icons exist:
`GitBranch`, `GitCommit`, `GitMerge`, `GitPullRequest`.

Component names differ from peer systems too. `Switch` IS `Toggle`; `Dialog` IS
`Modal`. Every mapping below resolves for real — `cascivo add switch` installs
`toggle`, the MCP `get_component("Dialog")` returns `modal`, and
`import { Switch } from '@cascivo/react'` compiles.
Mappings: AILabel→AiBadge, AiGeneratedDisclaimer→AiDisclaimer, AvatarStack→AvatarGroup, ChipInput→TagsInput, Chip→Tag, CircularProgress→Spinner, Citation→InlineCitation, CommandPalette→CommandMenu, ConfirmDialog→AlertDialog, Context→ContextMeter, Dialog→Modal, Disclosure→Collapsible, DropdownMenu→Dropdown, EmptyView→EmptyState, Layout→AppShell, LinearProgress→InlineLoading, MoreMenu→OverflowMenu, NavigationDrawer→Drawer, NumberField→NumberInput, PinInput→OtpInput, Placeholder→Skeleton, Popper→Popover, Rating→RatingGroup, ResponseActions→MessageActions, SegmentedButton→SegmentedControl, SelectNative→NativeSelect, SideSheet→Sheet, Sidebar→SideNav, Snackbar→Toast, SourceList→Sources, Suggestions→PromptSuggestions, Switch→Toggle, Table→DataTable, TerminalWindow→Terminal, TextShimmer→ShimmerText, ThinkingBar→AiStatus, Think→Reasoning, ThoughtChain→ChainOfThought, ToggleButtonGroup→ToggleGroup, Tool→ToolCall, Typewriter→StreamingText, TypingDots→TypingIndicator.

Pure-CSS glyphs (experimental): a small opt-in set of UI glyphs, rendered with
`clip-path: shape()` and no SVG — color via `currentColor`, size via
`--cascivo-glyph-size`, plus zero-JS state morphs via `transition: clip-path`.
Use `import { Glyph } from '@cascivo/icons'` with `import '@cascivo/icons/glyphs.css'`,
or the class form `<span class="cascivo-glyph" data-glyph="chevron-down">`. Glyphs:
`chevron-{down,up,left,right}`, `x`, `check`, `plus`, `minus`, `menu`,
`arrow-{right,left,up,down}`, and the `chevron-toggle` morph. Baseline-2026 only
(Chrome 135+, Safari 18.4+, Firefox 148+) — painting is gated behind `@supports`;
prefer the SVG icons for a wider browser floor or for print.

## Email (@cascivo/email)

HTML email is a separate render target with its own primitives — do NOT send
`@cascivo/react` components through an email. Clients strip `<style>`, ignore `rem`,
and Outlook Windows renders through Word: no flex, no grid, no custom properties.

`import { renderEmail, Html, Head, Body, Preview, Container, Section, Text } from '@cascivo/email'`
— table-based, inline-styled, no client JS, no runtime dependencies. Themed from the
same twelve themes, resolved to literal hex at render time.

The whole component set, and the ONLY components valid inside an email:

- Document: `Html`, `Head`, `Body`, `Preview`, `Style`
- Layout: `Container`, `Section`, `Row`, `Column`, `Spacer`, `Hr`
- Typography: `Heading`, `Text`, `Link`, `List`, `Footer`
- Content: `Button`, `Card`, `Alert`, `Badge`, `Img`, `Markdown`

Props, defaults and a worked example for each, with rendered previews:
https://cascivo.com/docs/email-primitives.md (https://cascivo.com/docs/email/components).

- `renderEmail(element, { theme, subject, tier })` -> `{ html, text, preheader, stats }`.
  `assertSendable(result)` throws on a missing subject/preheader/text or a body over
  the Gmail clip budget. `analyze(html)` says where the bytes went.
- `Markdown` renders runtime-fetched prose (an allowlisted node set, straight to the
  primitives — raw HTML in the source stays literal text, and only `http:`/`https:`/
  `mailto:` URLs are emitted).
- `lint(html, features)` checks a render against the Can I email matrix. The matrix is
  NOT bundled (it is ~483 KB) — fetch https://www.caniemail.com/api/data.json and pass
  it through `indexFeatures(data)`.
- `planMigration(importedNames)` maps a React Email template onto the cascivo set and
  names every gap with its reason.
- Fonts repeat inline on every text element because Outlook does not inherit them into
  table content. Shorten or rebrand the stack with `--cascivo-email-font-{sans,serif,mono}`
  on the palette passed to `renderEmail({ theme })`.

Full recipe: https://cascivo.com/docs/recipe-email.md. Components: https://cascivo.com/docs/email-primitives.md. Client support: https://cascivo.com/docs/email-client-support.md.

## How to use it

Two consumption paths — they share the same tokens/themes and can coexist:

A. Prebuilt package — fastest, use without copying source:

```sh
pnpm add @cascivo/react @cascivo/themes @preact/signals-react
```

```tsx
import '@cascivo/react/styles.css' // component styles (structure only)
import '@cascivo/themes/light-dark.css'  // tokens (once) + base typography + light & dark
                                       // swap for all.css only if you ship a theme picker (all twelve, ~2x)
import { Button, Card } from '@cascivo/react'
```

   CSS note: with a bundler (CSR) per-component CSS auto-includes and tree-shakes, so the
   `@cascivo/react/styles.css` line above is optional; under Vite SSR / TanStack Start it is
   required (see SSR SETUP below) and ships the full sheet (~273 KB / ~37 KB gzip).

   TypeScript note: the bare `.css` side-effect imports above need ambient CSS-module types or
   `tsc --noEmit` errors with TS2307 (TS2882 under noUncheckedSideEffectImports). Add
   `src/vite-env.d.ts` with `/// <reference types="vite/client" />`, or `declare module '*.css'`.

   Dashboards / data viz: charts are a SEPARATE install — `pnpm add @cascivo/charts`, then
   `import { AreaChart } from '@cascivo/charts'`. `@cascivo/react` exports no charts. The code
   editor (`@cascivo/editor`) and flow canvas (`@cascivo/flow`) are separate installs too.

   Trade-offs: smallest setup, updates via npm; you do not edit component internals.

   Themes: two recipes. `@cascivo/themes/all` = tokens + base + light + dark
   (~41 KB / ~9 KB gzip). Shipping ONE theme? Import `@cascivo/themes/base` +
   `@cascivo/themes/<name>` instead (~28 KB / ~7 KB gzip). The export name IS the
   attribute value: import `@cascivo/themes/dark` and set `data-theme="dark"`. Twelve
   first-party themes: light, dark, warm, flat, minimal, midnight, pastel, brutalist,
   corporate, terminal, cyberpunk, arcade (`base` = required scaffold, not a theme;
   `tailwind` = a bridge stylesheet). For a user-switchable theme use `<ThemeProvider>`
   + `themePreloadScript()` (no-FOUC SSR); for a fixed theme hard-code `data-theme`
   on `<html>`. Initial-theme precedence: persisted > `defaultTheme` (if passed) > OS
   `prefers-color-scheme` > light — pass `defaultTheme` to keep a dark app dark on a
   light-OS visitor. Under SSR add `suppressHydrationWarning` to the `<html>` the
   preload script writes to. Full table + SSR recipe: docs/getting-started.md.

B. Copy-paste source — own and customize the code (shadcn model):

```sh
npx cascivo add button card
```

   Runtime deps for copied source: `@cascivo/core`, `@cascivo/tokens`, `@cascivo/themes`, and the
   `@preact/signals-react` peer. `cascivo init` installs all of them (plus `cascivo` as a dev dep
   for the generated config); `cascivo add` installs any extra a component declares (e.g. @cascivo/i18n).

   Trade-offs: full control over internals; updates are a manual re-add.

Required CSS import order (both paths): components -> tokens+theme -> brand overrides (last).
`@cascivo/react/styles.css` is structure-only and needs a theme + tokens for color.

Charts, the code editor, and flow ship their own stylesheet — and import it themselves, so on
a BUNDLER build there is nothing to add: `dist/index.js` starts with `import "./charts.css"`.
Import `'@cascivo/charts/styles.css'` (likewise `@cascivo/editor/styles.css`,
`@cascivo/flow/styles.css`) only for a NO-BUNDLER build, or an SSR setup that externalises
dependencies — there the CSS-free `node` export condition loads and nothing pulls the sheet in.
Skipping it on those paths renders the chart's screen-reader data-table fallback visibly.
Importing it when you did not need to is harmless; the bundler dedupes it.

SSR (Vite SSR / TanStack Start / Remix / workerd): works with ZERO Vite config on
`@cascivo/react` >= 0.10 — no `ssr.noExternal`, no plugin, no `<ClientOnly>` wrappers. The
package ships a CSS-free copy of its module graph under the `node` export condition, so a
server ESM loader never sees a `.css` import. Charts server-render and hydrate too.
Import a theme once in your root route/entry for color: `@cascivo/themes/all.css` (or the
all-in-one `@cascivo/react/styles.css`).
ONLY on `@cascivo/react` < 0.10: an unconfigured SSR build throws `Unknown file extension
".css"` — pin >= 0.10, or add `ssr: { noExternal: [/^@cascivo\//] }` (or the `cascivoSsr()`
plugin from `@cascivo/vite-plugin`). Full recipe + the legacy path: USING-WITH-VITE-SSR.md.

C. shadcn CLI / v0 — install any component from the shadcn-compatible registry:

```sh
npx shadcn@latest add https://cascivo.com/r/shadcn/button.json
```

Every registry item inlines its own source and lists its cascivo dependencies as absolute
`https://cascivo.com/r/shadcn/<name>.json` URLs, so the shadcn CLI resolves them transitively. To add
cascivo as a named registry in `components.json` (then `npx shadcn add @cascivo/<name>`):

```json
{ "registries": { "@cascivo": "https://cascivo.com/r/shadcn/{name}.json" } }
```

The registry index (all items) is https://cascivo.com/r/shadcn/registry.json.

## CSS layer contract (follow when generating or editing CSS)

cascivo styles live in cascade layers. Layer order beats selector specificity, so:

1. Every declaration goes inside an `@layer` block. Unlayered CSS beats all layers regardless
   of specificity — never emit it.
2. Never invent layer names. The only layers you write: your app slot (e.g. `cascivo.example`,
   declared in your order statement) for page styles, and `@layer cascivo.override { … }` for
   hotfixes/one-off overrides — it beats everything cascivo ships.
3. Never nest layers deeper than the shipped `cascivo.blocks.<name>` pattern. For sub-elements
   (a badge in a card, a dot in a badge) use native CSS nesting inside one layer block, not new
   sublayers.
4. Third-party CSS: `@import url(…) layer(vendor);` with `vendor` declared before the cascivo
   layers. Never import vendor CSS from JavaScript.
5. Style with `--cascivo-*` tokens, not raw values.

Canonical order (lowest → highest priority):
`@layer vendor, cascivo.reset, cascivo.base, cascivo.tokens, cascivo.component, cascivo.platform, cascivo.theme, cascivo.blocks, cascivo.override;`
Full recipe: https://github.com/cascivo/cascivo/blob/main/docs/CSS-LAYERS-PITFALL.md.

## Shared vocabulary types (importing Tone / SpaceStep)

`Status.status` and `Badge.variant` are typed `ToneInput`; every layout `gap` is a numeric
`SpaceStep`. To name those types — e.g. a `Record<DeployState, Tone>` map, which
almost every dashboard writes:

- Prebuilt path: `import type { Tone } from '@cascivo/react/types'`
- Copied-source path: `import type { Tone } from '@cascivo/core'`

The subpath exports Tone, ToneAlias, ToneInput, Progress, ProgressAlias, ProgressInput,
SpaceStep, RovingOrientation. Do NOT add @cascivo/core to a prebuilt app to reach them —
it is a transitive dependency there and pinning it creates a lockstep-version trap.

## Routing (two kinds of link, wired two different ways)

Getting this wrong is the single most-reported friction in adopter reports. There is no
third mechanism — do not intercept `onClick`, and do not wrap nav items by hand.

1. **Config-driven navs** (SideNav, ShellHeader, Breadcrumb, Switcher, Dock) render through a
   module singleton. Register your router `Link` ONCE at app startup:
   ```tsx
   import { setLinkComponent } from '@cascivo/react'
   import type { LinkComponentProps } from '@cascivo/react'
   import { Link } from 'react-router' // or '@tanstack/react-router'
   setLinkComponent(({ href, ...rest }: LinkComponentProps) => <Link to={href ?? '#'} {...rest} />)
   ```
   React Router's `to` is required, so supply a fallback — cascivo passes `href: undefined`
   for a disabled item. Next.js's `Link` takes `href`, so `setLinkComponent(Link)`.
2. **Links you write in page content** use `asChild`, which puts cascivo styling on YOUR element:
   ```tsx
   <Link asChild><RouterLink to="/projects/alpha">alpha</RouterLink></Link>
   ```
   `Button`, `TabsTrigger` and the other `asChild`-capable components take the same treatment —
   URL-driven tabs should be real anchors, not `onValueChange` navigations.

Full guide (active-item prefix matching, URL-driven tabs, what `asChild` guarantees): https://cascivo.com/docs/using-with-a-router.md

## Reactivity & state (signals, not React hooks)

**Consuming components requires no signals.** Pass plain props, use `useState` in YOUR own code,
and render `<Button onClick={…}>` / `<Modal open={…}>` like any React library — you never need
`useSignals()` unless your own component body reads a `signal.value` during render. Signals are
how cascivo works INTERNALLY; they are not a precondition for using it.

The rules below apply when you OWN reactive state — authoring a cascivo-style component, or opting
into cascivo's reactive store. There, prefer signals over React hooks: mixing the two (mirroring a
signal into `useState`, or vice-versa) causes the "state fights the DOM / toggle does nothing"
bugs. And in any app WITHOUT the Babel signals transform (every consumer app), a component that
reads `signal.value` in render MUST call `useSignals()` (from `@cascivo/core`) as its first
statement, or it never re-renders. When you do own reactive state, use these:

- Local state -> `const [count, setCount] = useSignalState(initial)`: read `count.value` in render, write `setCount(next)` / `setCount((n) => n + 1)`. Derived -> `useComputed(fn)`. The signal IS the state.
  ⚠ WRITE THROUGH THE SETTER: never `count.value = next` on a signal a hook returned. That assignment fails the React Compiler build ('This value cannot be modified') and is reported by `react-hooks/immutability`, which `eslint-plugin-react-hooks@7` (`recommended-latest`) enables by default. The setter form passes both (checked by `pnpm compiler:check`). Writing `.value` on a MODULE-LEVEL `signal()` is fine. Existing code full of `x.value = …` writes: install `@cascivo/eslint-config` (spread `...cascivo` LAST) or set `'react-hooks/immutability': 'off'`, and keep it out of the Compiler. See /docs/using-with-strict-eslint.md.
  ⚠ FLAT CONFIG ENTRY POINT: the plugin exports BOTH `configs['recommended-latest']` (legacy eslintrc) and `configs.flat['recommended-latest']`. In an `eslint.config.js` you MUST use `reactHooks.configs.flat['recommended-latest']` — the other one is accepted silently and applies no rules at all, so lint passes while checking nothing.
  ⚠ VENDORED-SOURCE GLOB: `...cascivo` scopes its vendored-source rules to `src/components/ui/**`. If your `outputDir` differs, call `cascivoVendoredSource('<your-outputDir>/**')` instead — with the default glob every rule it scopes off silently stays on. cascivo runs real ESLint over every file `cascivo add` copies in CI (scripts/checks/host-lint/eslint), so the published config is executed, not asserted.
- Controlled/uncontrolled prop bridged to a signal -> `useControllableSignal({ value, defaultValue, onChange })`.
- Side effects (DOM, listeners) -> `useSignalEffect(fn)`, never `useEffect`.
- Shared/app-wide state -> a module-level signal, imported anywhere. No React context needed.
- Per-route / per-tenant effect disposal -> `useScope()` / `createScope()` (disposes on unmount; prevents signal leaks across navigation).
- Genuine internal state machine -> `createMachine` / `useMachine`.
- Forms -> `createForm` / `useForm` / `<Form>` / `field()` (`@cascivo/react`): a signal-backed store with sync/async + Standard Schema (zod/valibot) validation and optional `validateOnChange` — keystroke validation, zero re-renders.
- Theming -> `<ThemeProvider>` + `useTheme()` / `setTheme()` + `themePreloadScript()` — import from **`@cascivo/core`** on BOTH install paths (`@cascivo/react` re-exports the same names; before 0.17.0 it shipped only from `@cascivo/react`, which told copy-paste adopters to install all 197 components to get a theme signal): persists the choice and drives `data-theme`, SSR no-FOUC. `useTheme()` returns a TUPLE `[string, setTheme]` — the first element is the current theme **name** (a plain string; the component re-renders on change, no signal handling). Do NOT destructure `{ theme, setTheme }` (that is next-themes’ shape). Signal-native code (computed/effect/Preact) can grab the underlying signal via `themeSignal()`. ThemeProvider warns in dev if it sets a `data-theme` for which no `--cascivo-color-*` token resolves (you forgot the `@cascivo/themes` CSS import → grayscale app). `setTheme()` writes the SIGNAL; the mounted `<ThemeProvider>` writes the `data-theme` attribute — with no provider mounted the signal updates, `useTheme()` reports the new value, and nothing restyles (dev warns). Outside React (imperative shell, pre-hydration script) use `applyTheme(theme, target?)`, which writes the attribute directly and keeps the signal in sync. CSS bundles: `@cascivo/themes/light-dark.css` = light + dark (the common case); `@cascivo/themes/all.css` = all twelve themes; `@cascivo/themes/<name>.css` = one theme. Initial-theme precedence: persisted > `defaultTheme` (if passed) > OS `prefers-color-scheme` > light; pass `defaultTheme` to override the OS. Controlled `<ThemeProvider value=…>` is SSR-safe by itself (emits an inline attribute setter); for the persisted flow add `suppressHydrationWarning` to the `<html>` the preload script writes to. Never write a `useEffect` that toggles a `.dark` class.
- Token names in TypeScript -> `import type { CascivoToken, CascivoColorToken } from '@cascivo/tokens/tokens'` (generated union of every `--cascivo-*` property — no CSS-file lookup).
- Router links in config-driven navs (SideNav/ShellHeader/Breadcrumb/Dock/…) -> `setLinkComponent(YourLink)` once at startup. Import it (and the `LinkComponentProps` contract type) from `@cascivo/react` (re-exported there, so prebuilt-package users need NOT add `@cascivo/core`); copied source can import from `@cascivo/core`. Adapter: `setLinkComponent(({ href, ...rest }: LinkComponentProps) => <Link to={href} {...rest} />)` — spread the bag; the link stays a real `<a>` so middle-click/new-tab work.
- Event-handler naming (predict the prop from what it receives): a **value** -> `onValueChange(value)` (Tabs, SegmentedControl, Combobox, MultiSelect, Toggle, Search, NumberInput, DatePicker, …); a raw DOM `ChangeEvent` -> `onChange(event)` (Checkbox, NativeSelect, PasswordInput, **Select**, **Slider** — these two wrap a real element and have NO `onValueChange`); activating an item -> `onSelect(value)` (Dropdown, OverflowMenu, chart points; on `Menu`/`ContextMenu` the `onSelect` lives on the *Item*, not the root). A few components keep a deprecated value-carrying `onChange` alias — prefer `onValueChange`.
- Data/shape prop vocabulary (the other half of handler naming — nine wrong guesses in one 2026-08-08 dashboard, two more on 2026-08-22): a config-driven collection (nav, list, menu) -> **`items`** (20: Breadcrumb, ChainOfThought, DataList, Dock, Dropdown, MenuButton, NavigationMenu, OverflowMenu, PromptSuggestions, ShareMenu, SideNav, Sources, StructuredList, Switcher, Timeline, Toc, ToggleGroup, TreeView, VirtualList, FeatureGrid); the choices on a form control -> **`options`** (7: Combobox, Filter, MultiSelect, NativeSelect, SegmentedControl, Select, WheelPicker); a chart's data points -> **`data`** (11: CalendarHeatmap, Candlestick, Funnel, Heatmap, Histogram, PieChart, Polar, RadialBar, Sparkline, Sunburst, Treemap). Exceptions, named in full because they are where the guesses go wrong: `DataTable.rows` (it renders a real <table>, where "rows" is the domain word); `Textarea.rows` (the HTML `rows` attribute, not a collection); `CommandMenu.groups` (its items are nested inside labelled groups); `ProgressIndicator.steps` (the domain word for a stepper); `Steps.steps` (the domain word for a stepper; also accepts `items`). A visual style enum -> **`variant`**, never `shape`/`kind`/`type`; a discriminated-union tag -> **`kind`**, never `type` (e.g. annotations: [{ kind: 'line' }]); a rich replaceable slot -> **`actions`** as ReactNode (Notification, CardHeader, PageHeader — only `Alert.action` is the {label,onClick} shorthand); body text on a feedback component -> **`description`**, NOT children (Notification renders nothing for children).
- Near-miss prop names (each one a real adopter's wrong guess): `<Text tone=…>` -> **`muted`** (a boolean; `tone` is the SEVERITY vocabulary on Status/Badge/Timeline/SideNav, not text emphasis); `gap="4"` -> **`gap={4}`** (numeric SpaceStep); `<Flex justify=…>` with no `direction` is already VERTICAL (the default, unlike CSS/Chakra/MUI/Radix); `const { theme } = useTheme()` -> a TUPLE `const [theme, setTheme]`; `DataList orientation="vertical"` moves the VALUE under its label, it does not stack the items (they stack either way); `<DataListItem>` is an INTERFACE, not a component (`DataList` takes `items`). Three former near-misses are now accepted both ways and cost nothing: `import { Switch }` (= `Toggle`), `<OverflowMenu label=…>` (= `ariaLabel`), `<Field hint=…>` (= `description`).
- ⚠ `gap` takes a NUMBER: `gap={4}`, not `gap="4"`. Every other size-ish prop is a string union (`size="sm"`, `padding="md"`), but the space scale is a numeric `SpaceStep` (1|2|3|4|5|6|8|10|12) — this applies to Flex/Grid/AutoGrid `gap` and `AppShell.padding`. One adopter wrote `gap="4"` and got 20 type errors in a single run.
- Items-prop-driven vs children-driven: `DataList`/`StructuredList`/`Timeline`/`Steps` take an `items` ARRAY; `ListItem`/`ContainedListItem`/`MenuItem`/`TabsTrigger` are composed as children. `DataListItem` is an INTERFACE, not a component — write <DataList items={[{ label, value }]} />, not <DataList><DataListItem/></DataList>. DataList items are { label, value } (NOT { term, description }, despite rendering a <dl>).

Full behavior/headless catalog: https://github.com/cascivo/cascivo/blob/main/docs/HEADLESS.md. Enterprise friction -> primitive map: https://github.com/cascivo/cascivo/blob/main/docs/ENTERPRISE-READINESS.md.

## Versioning & compatibility

Packages version independently (changesets) — a low number on one package does not mean the
whole system is behind. The compatibility truth is per-entry: every registry entry carries a
`peerVersions` floor (e.g. `{ "@cascivo/i18n": ">=0.2.1" }`) for the packages its copied source
needs. Pin exact versions, and after adding components run `cascivo doctor --drift` to catch an
installed peer that is older than a copied component needs. Watch https://cascivo.com/breaking-changes.json
(major + minor releases per package) to detect API drift before upgrading.

## Guides

All guides are fetchable as plain markdown at https://cascivo.com/docs/<slug>.md (no browser needed):

- Getting started (install, themes, SSR): https://cascivo.com/docs/getting-started.md
- Reactivity & headless behavior primitives: https://cascivo.com/docs/headless.md
- Enterprise readiness (friction -> primitive map: state, layout, theming, forms, tokens): https://cascivo.com/docs/enterprise-readiness.md
- Using cascivo with a router (React Router / TanStack Router / Next.js): https://cascivo.com/docs/using-with-a-router.md
- Theming & branding: https://cascivo.com/docs/theming.md
- Using cascivo with Preact: https://cascivo.com/docs/using-with-preact.md
- Using cascivo with Next.js (App Router / RSC): https://cascivo.com/docs/using-with-nextjs.md
- Using cascivo with Vite SSR / TanStack Start: https://cascivo.com/docs/using-with-vite-ssr.md
- Using cascivo with Tailwind v4 (@layer order + dark bridge): https://cascivo.com/docs/using-with-tailwind.md
- Strict host ESLint (scope stylistic rules off your components dir): https://cascivo.com/docs/using-with-strict-eslint.md
- Transactional & newsletter email (@cascivo/email): https://cascivo.com/docs/recipe-email.md
- Payments, billing and email on Cloudflare (Stripe, Amazon SES, @cascivo/app): https://cascivo.com/docs/recipe-payments.md
- Sign-in, connected accounts and social posting (OAuth, Bluesky, Mastodon, LinkedIn, Threads, Buffer, ShareMenu): https://cascivo.com/docs/recipe-social.md
- Every @cascivo/email component, with props and examples: https://cascivo.com/docs/email-primitives.md
- Email client support matrix (what the conformance lint enforces): https://cascivo.com/docs/email-client-support.md
- Compatibility & support matrix: https://cascivo.com/docs/compatibility.md
- Migrating from shadcn/ui: https://cascivo.com/docs/migrating-from-shadcn.md
- Token reference: https://cascivo.com/docs/tokens.md
- Troubleshooting: https://cascivo.com/docs/troubleshooting.md

## Reference apps (runnable, in-repo — copy these setups)

- Vite + React (CSR/SPA): https://github.com/cascivo/cascivo/tree/main/apps/examples/react-vite
- Vite SSR (TanStack Start / Remix / workerd — server-renders through the built dist with `cascivoSsr()`): https://github.com/cascivo/cascivo/tree/main/apps/examples/react-vite-ssr
- Next.js App Router (RSC): https://github.com/cascivo/cascivo/tree/main/apps/examples/react-next

## Frameworks & browsers (summary; full matrix in COMPATIBILITY.md)

- React 18/19, Next.js App Router (RSC), Vite (CSR), Astro islands, Preact 10 (preact/compat — verified).
- Vite SSR / TanStack Start / Remix / workerd: supported with ZERO Vite config on >= 0.10
  (import a theme once for color). Only on < 0.10 do you need `ssr.noExternal: [/^@cascivo\//]`
  or the `cascivoSsr()` plugin. See USING-WITH-VITE-SSR.md.
- Last 2 versions of Chrome/Firefox/Safari (requires @layer, @container, :has(), oklch()).
- CSS @function is opt-in (`import '@cascivo/tokens/functions.css'`); not auto-loaded, so
  lightningcss / Tailwind v4 pipelines work by default.

## MCP server (recommended for agents)

Point any MCP client at the cascivo server:

```json
{ "mcpServers": { "cascivo": { "command": "npx", "args": ["-y", "@cascivo/mcp"] } } }
```

Tools (every tool the server registers; `pnpm llms:check` fails when one is missing):
- Start an app: `compose_app` (whole app from a blueprint: each page renders a registry block), `list_blocks` (the blocks a blueprint page can render, one line each), `create_app` (whole app: shell, nav, theme, placeholder pages; cloudflare examples and sign-in), `list_templates` (whole-page templates), `get_template` (one template), `add_template` (install a template), `deploy_preview` (publish a cloudflare app with no account)
- Pick components: `list_components` (every component, by category/type), `search_components` (fuzzy search), `select_component` (rank by a natural-language need), `get_context` (intent and when (not) to use), `get_component` (manifest; `compact: true` for props + one example), `list_registries` (third-party registries), `add_to_project` (install several components in one call)
- Build a view: `get_view_grammar` (format rules + props/enums for the components you name), `scaffold_view` (starter ViewConfig from a description), `scaffold_flow` (starter <Flow> diagram), `scaffold_page` (deprecated; use scaffold_view)
- Verify: `validate_view` (ViewConfig check; `target: "tsx"` before `cascivo generate`), `render_view_as_markdown` (read back what a view says (needs @cascivo/render)), `validate_component` (hooks, breakpoints, fallbacks, tokens in your own component), `lint_email` (rendered email: unsupported features, dead links)
- Style: `get_tokens` (closed-set token catalog), `get_variant_matrix` (intent → exact token, resolved per theme), `search_icons` (icon by intent or foreign name (LayoutDashboard→Dashboard)), `create_theme` (theme CSS from three colors)
- Read: `list_guides` (concept guides), `get_guide` (one guide)

Two MCP servers, two jobs — run both if your client allows it:
- `@cascivo/mcp` (above) serves the **registry**: pick a component, read its manifest, install it.
- `npx docspack mcp` (with `@cascivo/docspack` installed) serves the **prose**: ask a question,
  get the passages that answer it. Use it for "how do I…" and "which layer does X go in".

To pick a component without MCP, read the intent summaries below (grouped by need) or
fetch https://cascivo.com/context/<name>.md for the full when-to-use / when-not-to-use of each.

## Component authoring rules (for cascivo-extend / custom components)

These constrain code you write INSIDE a component you author or copy-paste-and-edit — not the app
code that merely renders cascivo components (that code uses React normally).

- Signals only: `useSignal`, `useComputed`, `useSignalEffect` from `@cascivo/core`
- No `useState`, `useEffect`, `useContext`, `useLayoutEffect`, `useReducer`
- DOM side effects via `useSignalEffect`, not `useEffect`
- `useRef` only for DOM element references
- CSS custom properties only — no Tailwind, no inline styles, no CSS-in-JS
- Visual states (hover/focus/active) via CSS pseudo-classes — not JS
- `data-state` attributes only for states CSS cannot express (e.g. loading, error)
- FSM (`useMachine`) only when the component itself drives transitions
- CSS logical properties throughout (RTL-safe): `margin-inline-start`, etc.
- User-visible strings via `@cascivo/i18n` — no hardcoded English fallbacks
- WCAG 2.2 AA minimum — keyboard navigable, screen-reader tested

## High-throughput / streaming data

For live logs, build output, market ticks, or streamed tokens, do NOT rebuild an array per
event (`arr = [...arr.slice(1), line]` is O(n) per line and thrashes rendering). Use the
built-in primitives, which coalesce bursts to one render per frame:

- `useStreamBuffer` / `createStreamBuffer` (`@cascivo/core`) — fixed-capacity O(1) ring buffer,
  rAF-coalesced; a burst within one frame is a single signal write.
- `useStreamSeries` / `bindStream` (`@cascivo/charts`) — feed a live source into a chart with
  optional LTTB/min-max decimation so a fast stream never blows the rendered point count.
- `LogViewer` (`@cascivo/react`) — virtualized console for high-frequency logs (100k-line buffer
  stays responsive), ANSI parsing, auto-follow tail. Pairs with `createStreamBuffer`.

## Feedback signals for agents

cascivo ships no runtime telemetry (copy-paste model — you own the code; no phone-home). To
see how components behave without adding tracking, read these machine-readable CI outputs:

- Breaking/feature changes per package: https://cascivo.com/breaking-changes.json
- Benchmark results (runtime, bundle, render counts vs Carbon/shadcn): https://github.com/cascivo/cascivo/blob/main/apps/bench/results/results.json
- Accessibility conformance (axe sweep, AT matrix): https://github.com/cascivo/cascivo/tree/main/docs/specs

## Component index (226 entries — 214 components + 12 page blocks)

Not all ship in `@cascivo/react`: 25 in @cascivo/charts, 10 in @cascivo/flow, 2 in @cascivo/editor — those are separate installs (see Quick Setup). Blocks are copy-paste only. Each entry below is tagged with its channel.

Naming note: `Stack` overlaps children into a card-pile (z-axis), NOT vertical spacing — for a vertical/horizontal spacing layout use `Flex` (`layout/flex`; the aliases `vstack`/`hstack` resolve to it).

### auth

- [block/auth-login](https://cascivo.com/llms/block/auth-login.md) — Email + password login with remember-me checkbox and forgot-password link. _(copy-paste)_
- [block/auth-signup](https://cascivo.com/llms/block/auth-signup.md) — Full-name, email, password, confirm-password sign-up form with terms checkbox. _(copy-paste)_

### chart

- [chart/area-chart](https://cascivo.com/llms/chart/area-chart.md) — Area chart with optional stacking, multi-series support, and hover tooltip. _(npm @cascivo/charts)_
- [chart/bar-chart](https://cascivo.com/llms/chart/bar-chart.md) — Bar chart with vertical/horizontal orientation, grouped or stacked modes, and multi-series support. _(npm @cascivo/charts)_
- [chart/boxplot](https://cascivo.com/llms/chart/boxplot.md) — Box-and-whisker plot with five-number summary and outlier dots per series. _(npm @cascivo/charts)_
- [chart/bubble-chart](https://cascivo.com/llms/chart/bubble-chart.md) — Bubble chart mapping x, y, and size dimensions; radius is area-proportional via sqrt scale. _(npm @cascivo/charts)_
- [chart/bullet](https://cascivo.com/llms/chart/bullet.md) — Bullet chart with background range bands, measure bar, and target tick. _(npm @cascivo/charts)_
- [chart/calendar](https://cascivo.com/llms/chart/calendar.md) — Calendar heatmap — a week-column grid of day cells colored by value (GitHub-style). _(npm @cascivo/charts)_
- [chart/candlestick](https://cascivo.com/llms/chart/candlestick.md) — OHLC financial chart — each period a high–low wick and an open↔close body, coloured up/down. _(npm @cascivo/charts)_
- [chart/combo-chart](https://cascivo.com/llms/chart/combo-chart.md) — Combination bar + line chart on shared or dual y-axes. _(npm @cascivo/charts)_
- [chart/funnel](https://cascivo.com/llms/chart/funnel.md) — Vertical conversion funnel — each stage is a trapezoid narrowing toward the next, with optional conversion labels. _(npm @cascivo/charts)_
- [chart/gauge](https://cascivo.com/llms/chart/gauge.md) — A speedometer gauge — a value arc over a min–max sweep with threshold zones, ticks, and a needle. _(npm @cascivo/charts)_
- [chart/heatmap](https://cascivo.com/llms/chart/heatmap.md) — Two-dimensional heatmap with band scales and color-mix cell interpolation. _(npm @cascivo/charts)_
- [chart/histogram](https://cascivo.com/llms/chart/histogram.md) — Frequency histogram using Freedman–Diaconis binning with hover tooltips. _(npm @cascivo/charts)_
- [chart/kpi](https://cascivo.com/llms/chart/kpi.md) — KPI card showing a primary metric with optional delta indicator, icon, and sparkline. _(npm @cascivo/charts)_
- [chart/line-chart](https://cascivo.com/llms/chart/line-chart.md) — Time-series or numeric line chart with multi-series support, hover tooltip, and legend. _(npm @cascivo/charts)_
- [chart/meter](https://cascivo.com/llms/chart/meter.md) — Progress meter in bar or gauge variant with threshold coloring. _(npm @cascivo/charts)_
- [chart/pie-chart](https://cascivo.com/llms/chart/pie-chart.md) — Pie or donut chart with hover segments and optional legend. _(npm @cascivo/charts)_
- [chart/polar](https://cascivo.com/llms/chart/polar.md) — A polar coordinate plot — categories around the circle, value as radius. Bars (a rose), or a polar line/area. _(npm @cascivo/charts)_
- [chart/radar](https://cascivo.com/llms/chart/radar.md) — Radar / spider chart with polar grid rings, spokes, and multi-series polygon overlays. _(npm @cascivo/charts)_
- [chart/radial-bar](https://cascivo.com/llms/chart/radial-bar.md) — Concentric radial bars (a circular gauge family) — each datum is a ring whose sweep is proportional to its value. _(npm @cascivo/charts)_
- [chart/sankey](https://cascivo.com/llms/chart/sankey.md) — Flow diagram — ranked nodes connected by throughput-sized link ribbons. _(npm @cascivo/charts)_
- [chart/scatter-chart](https://cascivo.com/llms/chart/scatter-chart.md) — Scatter plot with variable point radius, multi-series, and hover tooltip. _(npm @cascivo/charts)_
- [chart/sparkline](https://cascivo.com/llms/chart/sparkline.md) — Compact inline sparkline for embedding trend data in dashboards or KPI cards. _(npm @cascivo/charts)_
- [chart/stream](https://cascivo.com/llms/chart/stream.md) — Streamgraph — stacked areas on a centered (silhouette) flowing baseline. _(npm @cascivo/charts)_
- [chart/sunburst](https://cascivo.com/llms/chart/sunburst.md) — Radial hierarchy — concentric rings where each node is an annular segment sized by value. _(npm @cascivo/charts)_
- [chart/treemap](https://cascivo.com/llms/chart/treemap.md) — Squarified treemap for visualizing part-to-whole hierarchical data. _(npm @cascivo/charts)_

### dashboard

- [block/dashboard-overview](https://cascivo.com/llms/block/dashboard-overview.md) — Welcome header with four KPI stat cards (revenue, users, orders, conversion). _(copy-paste)_
- [block/dashboard-table](https://cascivo.com/llms/block/dashboard-table.md) — Searchable, sortable, paginated data table with export button. _(copy-paste)_

### display

- [ai-badge](https://cascivo.com/llms/ai-badge.md) — Small "AI" marker for AI-generated content; with children it opens a toggletip explaining how AI was involved _(npm @cascivo/react · or copy-paste)_
- [alert](https://cascivo.com/llms/alert.md) — Highlights a short, important message inline _(npm @cascivo/react · or copy-paste)_
- [avatar](https://cascivo.com/llms/avatar.md) — Displays a user image with initials fallback _(npm @cascivo/react · or copy-paste)_
- [avatar-group](https://cascivo.com/llms/avatar-group.md) — Overlapping stack of avatars with a max cap and an i18n-labelled +N overflow chip _(npm @cascivo/react · or copy-paste)_
- [badge](https://cascivo.com/llms/badge.md) — Small status label or category indicator _(npm @cascivo/react · or copy-paste)_
- [block/console-app](https://cascivo.com/llms/block/console-app.md) — Carbon-parity console shell: ShellHeader + icon-rail SideNav + HeaderPanel notifications/switcher + collapsible aside + main content. _(copy-paste)_
- [block/dashboard-charts](https://cascivo.com/llms/block/dashboard-charts.md) — Dashboard layout with KPI tiles, line chart, bar chart, and pie chart. _(copy-paste)_
- [block/empty-dashboard](https://cascivo.com/llms/block/empty-dashboard.md) — Dashboard page showing an empty state with a call-to-action button. _(copy-paste)_
- [block/login-page](https://cascivo.com/llms/block/login-page.md) — Authentication login page with email and password form. _(copy-paste)_
- [block/notification-center](https://cascivo.com/llms/block/notification-center.md) — A list of notification alerts with a mark-all-read action. _(copy-paste)_
- [block/page-with-breadcrumb](https://cascivo.com/llms/block/page-with-breadcrumb.md) — A centered content page with a breadcrumb navigation and page header. _(copy-paste)_
- [block/settings-form-page](https://cascivo.com/llms/block/settings-form-page.md) — Settings page with profile form inside a two-column settings layout. _(copy-paste)_
- [block/sidebar-app](https://cascivo.com/llms/block/sidebar-app.md) — Full app shell with collapsible side navigation and top header. _(copy-paste)_
- [block/stats-cards](https://cascivo.com/llms/block/stats-cards.md) — Grid of KPI stat cards with trend badges. _(copy-paste)_
- [block/users-table-page](https://cascivo.com/llms/block/users-table-page.md) — Full users management page with table, search, and invite action. _(copy-paste)_
- [blockquote](https://cascivo.com/llms/blockquote.md) — Quoted passage with optional attribution footer _(npm @cascivo/react · or copy-paste)_
- [brand/logo](https://cascivo.com/llms/brand/logo.md) — The cascivo mark and its sanctioned lockups, as inline SVG _(npm @cascivo/react · or copy-paste)_
- [card](https://cascivo.com/llms/card.md) — Container for grouping related content _(npm @cascivo/react · or copy-paste)_
- [carousel](https://cascivo.com/llms/carousel.md) — Scroll-snap slide deck with previous/next controls and dot indicators _(npm @cascivo/react · or copy-paste)_
- [chain-of-thought](https://cascivo.com/llms/chain-of-thought.md) — The steps an AI agent takes — searching, reading, calling tools — each with its status, and optional collapsible detail _(npm @cascivo/react · or copy-paste)_
- [chat-bubble](https://cascivo.com/llms/chat-bubble.md) — Message bubble for chat and messaging UIs with avatar, name, and timestamp support _(npm @cascivo/react · or copy-paste)_
- [code](https://cascivo.com/llms/code.md) — Inline code span for identifiers, commands, and short snippets _(npm @cascivo/react · or copy-paste)_
- [code-snippet](https://cascivo.com/llms/code-snippet.md) — 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 _(npm @cascivo/react · or copy-paste)_
- [collapsible](https://cascivo.com/llms/collapsible.md) — A single disclosure region toggled open and closed by its trigger _(npm @cascivo/react · or copy-paste)_
- [comparison](https://cascivo.com/llms/comparison.md) — Reveals the difference between two layers with a draggable divider _(npm @cascivo/react · or copy-paste)_
- [contained-list](https://cascivo.com/llms/contained-list.md) — Labelled list of rows inside a bordered container _(npm @cascivo/react · or copy-paste)_
- [data-list](https://cascivo.com/llms/data-list.md) — Key-value pairs rendered as a description list _(npm @cascivo/react · or copy-paste)_
- [data-table](https://cascivo.com/llms/data-table.md) — Signal-driven data table with client/server sort, filter, pagination, multi-selection, expandable rows, and CSS content-visibility row containment for large datasets _(npm @cascivo/react · or copy-paste)_
- [editor/highlight](https://cascivo.com/llms/editor/highlight.md) — Read-only syntax-highlighted code block — the same owned tokenizer as CodeEditor, without the textarea. _(npm @cascivo/editor)_
- [empty-state](https://cascivo.com/llms/empty-state.md) — Placeholder for views that have no data to display _(npm @cascivo/react · or copy-paste)_
- [flow/flow](https://cascivo.com/llms/flow/flow.md) — The declarative, AI-first flow surface — render a node/edge graph from plain serializable data. _(npm @cascivo/flow)_
- [flow/flow-background](https://cascivo.com/llms/flow/flow-background.md) — Decorative dots / grid / cross canvas background, drawn purely in CSS gradients. _(npm @cascivo/flow)_
- [flow/flow-canvas](https://cascivo.com/llms/flow/flow-canvas.md) — The pan/zoom canvas pane — a single CSS-transformed layer driven by the viewport signal. _(npm @cascivo/flow)_
- [flow/flow-controls](https://cascivo.com/llms/flow/flow-controls.md) — Zoom in / out / fit-view controls for a flow canvas — real, i18n-labeled buttons. _(npm @cascivo/flow)_
- [flow/flow-edge](https://cascivo.com/llms/flow/flow-edge.md) — An SVG edge with bezier/straight/smoothstep paths, an arrowhead, an optional label, and animation. _(npm @cascivo/flow)_
- [flow/flow-handle](https://cascivo.com/llms/flow/flow-handle.md) — A connection port on a node edge — where edges attach and interactive connect starts. _(npm @cascivo/flow)_
- [flow/flow-minimap](https://cascivo.com/llms/flow/flow-minimap.md) — A scaled SVG overview of the graph with a draggable viewport rectangle. _(npm @cascivo/flow)_
- [flow/flow-node](https://cascivo.com/llms/flow/flow-node.md) — An HTML node box positioned in the viewport pane — draggable, selectable, with arbitrary children. _(npm @cascivo/flow)_
- [flow/flow-panel](https://cascivo.com/llms/flow/flow-panel.md) — An absolutely-positioned slot for custom flow-canvas UI (legend, toolbar). _(npm @cascivo/flow)_
- [flow/flow-story](https://cascivo.com/llms/flow/flow-story.md) — A scripted, sequenced, looping flow animation — walks a graph step by step with fade-in captions. _(npm @cascivo/flow)_
- [heading](https://cascivo.com/llms/heading.md) — Section heading with semantic level decoupled from visual size _(npm @cascivo/react · or copy-paste)_
- [image](https://cascivo.com/llms/image.md) — Image with load state, blur-up placeholder, graceful fallback, and optional zoom _(npm @cascivo/react · or copy-paste)_
- [inline-citation](https://cascivo.com/llms/inline-citation.md) — A numbered citation marker inside AI-generated text that links to its source and previews it in a hover card _(npm @cascivo/react · or copy-paste)_
- [item](https://cascivo.com/llms/item.md) — Generic content row primitive with media, content, and action regions _(npm @cascivo/react · or copy-paste)_
- [kbd](https://cascivo.com/llms/kbd.md) — Displays a keyboard key or shortcut _(npm @cascivo/react · or copy-paste)_
- [list](https://cascivo.com/llms/list.md) — Styled unordered or ordered list with ListItem _(npm @cascivo/react · or copy-paste)_
- [log-viewer](https://cascivo.com/llms/log-viewer.md) — Virtualized monospace console for high-frequency log and stream output _(npm @cascivo/react · or copy-paste)_
- [prose](https://cascivo.com/llms/prose.md) — Wrapper that styles raw descendant HTML — headings, lists, code, quotes, tables _(npm @cascivo/react · or copy-paste)_
- [qr-code](https://cascivo.com/llms/qr-code.md) — Encodes a URL or short text into a scannable SVG QR code _(npm @cascivo/react · or copy-paste)_
- [reasoning](https://cascivo.com/llms/reasoning.md) — Collapsible panel for a model’s reasoning — opens and shimmers "Thinking…" while it streams, then settles to "Thought for N seconds" _(npm @cascivo/react · or copy-paste)_
- [relative-time](https://cascivo.com/llms/relative-time.md) — Displays a date as a localized phrase relative to now, auto-updating _(npm @cascivo/react · or copy-paste)_
- [separator](https://cascivo.com/llms/separator.md) — Visual or semantic divider between content _(npm @cascivo/react · or copy-paste)_
- [skeleton](https://cascivo.com/llms/skeleton.md) — Animated loading placeholder that mirrors the shape of pending content _(npm @cascivo/react · or copy-paste)_
- [sources](https://cascivo.com/llms/sources.md) — Collapsible, numbered list of the sources an AI answer drew on — "Used 3 sources" — whose numbers match InlineCitation _(npm @cascivo/react · or copy-paste)_
- [stat](https://cascivo.com/llms/stat.md) — Displays a key metric with optional delta, trend direction and help text _(npm @cascivo/react · or copy-paste)_
- [status](https://cascivo.com/llms/status.md) — Colored dot with a label communicating the state of a system or entity _(npm @cascivo/react · or copy-paste)_
- [streaming-text](https://cascivo.com/llms/streaming-text.md) — Reveals text character by character with a blinking cursor, catching up as a streamed reply grows _(npm @cascivo/react · or copy-paste)_
- [structured-list](https://cascivo.com/llms/structured-list.md) — Tabular row list for scannable data, optionally single-selectable _(npm @cascivo/react · or copy-paste)_
- [swipe-item](https://cascivo.com/llms/swipe-item.md) — List row whose leading/trailing actions are revealed by a horizontal swipe, with keyboard parity _(npm @cascivo/react · or copy-paste)_
- [tag](https://cascivo.com/llms/tag.md) — Compact chip for labeling, categorizing, or filtering content _(npm @cascivo/react · or copy-paste)_
- [terminal](https://cascivo.com/llms/terminal.md) — An animated terminal that types out a script of commands and output — for demos, onboarding and agent transcripts _(npm @cascivo/react · or copy-paste)_
- [text](https://cascivo.com/llms/text.md) — Body text with size, weight, and muted variants _(npm @cascivo/react · or copy-paste)_
- [timeline](https://cascivo.com/llms/timeline.md) — Ordered sequence of events with status markers and a connector line _(npm @cascivo/react · or copy-paste)_
- [tool-call](https://cascivo.com/llms/tool-call.md) — Card for one AI tool invocation — the tool name, its lifecycle status, collapsible input/output, and approval actions _(npm @cascivo/react · or copy-paste)_
- [tree-view](https://cascivo.com/llms/tree-view.md) — Hierarchical, expandable tree of nodes with keyboard navigation and selection _(npm @cascivo/react · or copy-paste)_
- [user](https://cascivo.com/llms/user.md) — Identity composite: an avatar with a name, description, and optional action slot _(npm @cascivo/react · or copy-paste)_
- [virtual-list](https://cascivo.com/llms/virtual-list.md) — Renders only the rows inside the viewport, so list length costs no extra DOM _(npm @cascivo/react · or copy-paste)_
- [visually-hidden](https://cascivo.com/llms/visually-hidden.md) — Hides content visually while keeping it available to screen readers _(npm @cascivo/react · or copy-paste)_

### feedback

- [ai-disclaimer](https://cascivo.com/llms/ai-disclaimer.md) — A short, quiet note that AI-generated content may be wrong — "AI-generated content may be incorrect" _(npm @cascivo/react · or copy-paste)_
- [ai-status](https://cascivo.com/llms/ai-status.md) — Announces what an AI is doing — thinking, generating, done, failed or stopped — with a shimmering label and an optional Stop button _(npm @cascivo/react · or copy-paste)_
- [context-meter](https://cascivo.com/llms/context-meter.md) — How much of a model’s context window a conversation has used — "12K / 200K" with a bar that warns as it fills _(npm @cascivo/react · or copy-paste)_
- [infinite-scroll](https://cascivo.com/llms/infinite-scroll.md) — Loads the next page when the end of a list scrolls into view _(npm @cascivo/react · or copy-paste)_
- [inline-loading](https://cascivo.com/llms/inline-loading.md) — Compact inline status indicator that pairs a label with a loading, success, or error state _(npm @cascivo/react · or copy-paste)_
- [notification](https://cascivo.com/llms/notification.md) — Inline, actionable notification banner that surfaces a titled message with an optional recovery action _(npm @cascivo/react · or copy-paste)_
- [progress](https://cascivo.com/llms/progress.md) — Horizontal bar showing the completion progress of a tracked operation _(npm @cascivo/react · or copy-paste)_
- [progress-bar](https://cascivo.com/llms/progress-bar.md) — Shows determinate or indeterminate progress of a task _(npm @cascivo/react · or copy-paste)_
- [progress-circle](https://cascivo.com/llms/progress-circle.md) — Circular determinate progress indicator rendered as an SVG arc _(npm @cascivo/react · or copy-paste)_
- [pull-to-refresh](https://cascivo.com/llms/pull-to-refresh.md) — Wraps a scrollable region and triggers a refresh when pulled down past a threshold at the top _(npm @cascivo/react · or copy-paste)_
- [radial-progress](https://cascivo.com/llms/radial-progress.md) — Circular progress indicator using conic-gradient, with percentage label and variant colors _(npm @cascivo/react · or copy-paste)_
- [shimmer-text](https://cascivo.com/llms/shimmer-text.md) — Text with a bright band sweeping through it — the "Thinking…" look for a label that marks work in progress _(npm @cascivo/react · or copy-paste)_
- [spinner](https://cascivo.com/llms/spinner.md) — Indeterminate loading indicator _(npm @cascivo/react · or copy-paste)_
- [typing-indicator](https://cascivo.com/llms/typing-indicator.md) — Three bouncing dots that hold a chat message slot while an assistant (or a person) is composing a reply _(npm @cascivo/react · or copy-paste)_

### inputs

- [button](https://cascivo.com/llms/button.md) — Triggers an action or event _(npm @cascivo/react · or copy-paste)_
- [button-group](https://cascivo.com/llms/button-group.md) — Visually joins a set of related buttons into a single segmented control _(npm @cascivo/react · or copy-paste)_
- [calendar](https://cascivo.com/llms/calendar.md) — An accessible standalone month-grid date picker. _(npm @cascivo/react · or copy-paste)_
- [checkbox](https://cascivo.com/llms/checkbox.md) — Binary toggle for forms, with indeterminate support _(npm @cascivo/react · or copy-paste)_
- [checkbox-card](https://cascivo.com/llms/checkbox-card.md) — Multi-selectable card backed by a native checkbox. Use multiple independent CheckboxCards for multi-select scenarios. _(npm @cascivo/react · or copy-paste)_
- [color-picker](https://cascivo.com/llms/color-picker.md) — Interactive color selection widget with saturation/lightness area, hue and alpha sliders _(npm @cascivo/react · or copy-paste)_
- [combobox](https://cascivo.com/llms/combobox.md) — Filterable single-select with an animated custom listbox, built on the dropdown open/close machine _(npm @cascivo/react · or copy-paste)_
- [copy-button](https://cascivo.com/llms/copy-button.md) — Icon button that copies a value to the clipboard with copied feedback _(npm @cascivo/react · or copy-paste)_
- [date-picker](https://cascivo.com/llms/date-picker.md) — An accessible date-picker with a calendar popover. _(npm @cascivo/react · or copy-paste)_
- [date-range-picker](https://cascivo.com/llms/date-range-picker.md) — A dual-calendar picker for selecting a contiguous date range. _(npm @cascivo/react · or copy-paste)_
- [editable](https://cascivo.com/llms/editable.md) — Inline click-to-edit text field _(npm @cascivo/react · or copy-paste)_
- [editor/code-editor](https://cascivo.com/llms/editor/code-editor.md) — Lightweight code editor — a native textarea overlaid on a syntax-highlighted layer, with line numbers and Tab indent. _(npm @cascivo/editor)_
- [fab](https://cascivo.com/llms/fab.md) — Floating action button anchored to a screen corner, with an optional speed-dial of secondary actions _(npm @cascivo/react · or copy-paste)_
- [field](https://cascivo.com/llms/field.md) — Form-field wrapper composing label, control, description, and error _(npm @cascivo/react · or copy-paste)_
- [file-uploader](https://cascivo.com/llms/file-uploader.md) — Drag-and-drop file upload zone with file list and status indicators. _(npm @cascivo/react · or copy-paste)_
- [filter](https://cascivo.com/llms/filter.md) — A group of toggleable pill or outline buttons for filtering content by category _(npm @cascivo/react · or copy-paste)_
- [form](https://cascivo.com/llms/form.md) — Typed signal-based form store (createForm/useForm) with sync/async validation and a thin Form element wrapper _(npm @cascivo/react · or copy-paste)_
- [icon-button](https://cascivo.com/llms/icon-button.md) — Square, icon-only button with a required accessible label _(npm @cascivo/react · or copy-paste)_
- [input](https://cascivo.com/llms/input.md) — Text input field with optional label, hint, and error state _(npm @cascivo/react · or copy-paste)_
- [input-group](https://cascivo.com/llms/input-group.md) — Prefix/suffix addon wrapper for Input; InputGroupAddon renders inline icons/units inside the field border; InputGroupButtons collapses adjacent button borders _(npm @cascivo/react · or copy-paste)_
- [label](https://cascivo.com/llms/label.md) — Accessible caption for a form control _(npm @cascivo/react · or copy-paste)_
- [message-actions](https://cascivo.com/llms/message-actions.md) — The action row under an AI reply — copy, good / bad feedback as toggle buttons, and regenerate _(npm @cascivo/react · or copy-paste)_
- [multi-select](https://cascivo.com/llms/multi-select.md) — Searchable multi-value select with a popover listbox, chips and grouping _(npm @cascivo/react · or copy-paste)_
- [native-select](https://cascivo.com/llms/native-select.md) — A styled native <select> that keeps platform form/keyboard behavior with a custom chevron and focus ring _(npm @cascivo/react · or copy-paste)_
- [number-input](https://cascivo.com/llms/number-input.md) — Numeric input with stepper buttons, clamping, precision, and locale formatting _(npm @cascivo/react · or copy-paste)_
- [otp-input](https://cascivo.com/llms/otp-input.md) — Segmented one-time code input _(npm @cascivo/react · or copy-paste)_
- [password-input](https://cascivo.com/llms/password-input.md) — Password input with reveal toggle and optional strength meter _(npm @cascivo/react · or copy-paste)_
- [prompt-suggestions](https://cascivo.com/llms/prompt-suggestions.md) — Starter prompts as a wrap of pill buttons — the "Try asking…" row of an empty AI chat _(npm @cascivo/react · or copy-paste)_
- [radio](https://cascivo.com/llms/radio.md) — Single choice from a set, grouped with RadioGroup _(npm @cascivo/react · or copy-paste)_
- [radio-card](https://cascivo.com/llms/radio-card.md) — Selectable card backed by a native radio input. Use RadioCardGroup for single-select groups. _(npm @cascivo/react · or copy-paste)_
- [rating-group](https://cascivo.com/llms/rating-group.md) — Star rating input with accessible radio group pattern _(npm @cascivo/react · or copy-paste)_
- [reorder-list](https://cascivo.com/llms/reorder-list.md) — List whose rows can be reordered by pointer drag or entirely by keyboard _(npm @cascivo/react · or copy-paste)_
- [search](https://cascivo.com/llms/search.md) — Search input with debounced search callback and clear button _(npm @cascivo/react · or copy-paste)_
- [segmented-control](https://cascivo.com/llms/segmented-control.md) — Mutually exclusive toggle group _(npm @cascivo/react · or copy-paste)_
- [select](https://cascivo.com/llms/select.md) — Native select menu styled to match the design system _(npm @cascivo/react · or copy-paste)_
- [slider](https://cascivo.com/llms/slider.md) — Range input for selecting a value within bounds _(npm @cascivo/react · or copy-paste)_
- [swap](https://cascivo.com/llms/swap.md) — Animated toggle between two icon/content states with rotate or flip transition _(npm @cascivo/react · or copy-paste)_
- [tags-input](https://cascivo.com/llms/tags-input.md) — Free-form multi-value chip input _(npm @cascivo/react · or copy-paste)_
- [textarea](https://cascivo.com/llms/textarea.md) — Multi-line text input with optional label, hint, and error state _(npm @cascivo/react · or copy-paste)_
- [tile](https://cascivo.com/llms/tile.md) — A selectable card with radio (single) or checkbox (multi) semantics, toggled by click or keyboard _(npm @cascivo/react · or copy-paste)_
- [time-picker](https://cascivo.com/llms/time-picker.md) — Native time input wrapper with label, hint, error, and size variants _(npm @cascivo/react · or copy-paste)_
- [toggle](https://cascivo.com/llms/toggle.md) — On/off switch built as an accessible button _(npm @cascivo/react · or copy-paste)_
- [toggle-group](https://cascivo.com/llms/toggle-group.md) — A set of toggle buttons for single or multiple selection _(npm @cascivo/react · or copy-paste)_
- [wheel-picker](https://cascivo.com/llms/wheel-picker.md) — iOS-style drum picker — a column of options that scrolls and snaps to a selection _(npm @cascivo/react · or copy-paste)_

### layout

- [app-shell](https://cascivo.com/llms/app-shell.md) — Sticky-header + full-height side-nav + single-scroll-container layout with an animated, accessible nav toggle. _(npm @cascivo/react · or copy-paste)_
- [aspect-ratio](https://cascivo.com/llms/aspect-ratio.md) — Constrains content to a fixed width-to-height ratio _(npm @cascivo/react · or copy-paste)_
- [indicator](https://cascivo.com/llms/indicator.md) — Positions an overlay element (badge, dot, count) at a corner of its child _(npm @cascivo/react · or copy-paste)_
- [join](https://cascivo.com/llms/join.md) — Groups adjacent children into a seamless joined element by removing interior borders and radii _(npm @cascivo/react · or copy-paste)_
- [layout/app-shell](https://cascivo.com/llms/layout/app-shell.md) — Full-page application shell with persisted collapsible sidebar. Includes a signal-driven top progress bar with determinate progress, error state, and dismissible error strip. _(copy-paste)_
- [layout/auth-layout](https://cascivo.com/llms/layout/auth-layout.md) — Centered card layout for authentication pages (login, register, forgot password). _(npm @cascivo/react · or copy-paste)_
- [layout/auto-grid](https://cascivo.com/llms/layout/auto-grid.md) — Media-query-free responsive grid — columns auto-fill based on available space. _(npm @cascivo/react · or copy-paste)_
- [layout/center](https://cascivo.com/llms/layout/center.md) — Horizontally centered container with a configurable max-width. _(npm @cascivo/react · or copy-paste)_
- [layout/columns](https://cascivo.com/llms/layout/columns.md) — Equal-width multi-column layout that collapses to single column on narrow viewports. _(npm @cascivo/react · or copy-paste)_
- [layout/dashboard-layout](https://cascivo.com/llms/layout/dashboard-layout.md) — Dashboard page layout with stats strip, main content area, and optional aside. _(npm @cascivo/react · or copy-paste)_
- [layout/flex](https://cascivo.com/llms/layout/flex.md) — Flex layout primitive for vertical or horizontal stacking with gap control. ⚠ Unlike CSS `flex-direction`, `direction` defaults to `vertical` — pass `direction="horizontal"` for a row. _(npm @cascivo/react · or copy-paste)_
- [layout/grid](https://cascivo.com/llms/layout/grid.md) — CSS grid layout primitive with responsive column collapsing. Establishes its own containment, so responsive `cols` adapt to the grid’s own slot width with no wrapper or container ancestor required. _(npm @cascivo/react · or copy-paste)_
- [layout/masonry](https://cascivo.com/llms/layout/masonry.md) — Masonry layout — native CSS masonry where supported, multi-column fallback elsewhere (fallback orders items top-to-bottom per column). _(copy-paste)_
- [layout/page-header](https://cascivo.com/llms/layout/page-header.md) — Page-level header with title, description, breadcrumb, and actions slots. _(npm @cascivo/react · or copy-paste)_
- [layout/section](https://cascivo.com/llms/layout/section.md) — Page-section shell with block padding, centered inner width, and stack gap. _(copy-paste)_
- [layout/settings-layout](https://cascivo.com/llms/layout/settings-layout.md) — Two-column settings page layout with a fixed-width menu and fluid content area. _(npm @cascivo/react · or copy-paste)_
- [layout/spacer](https://cascivo.com/llms/layout/spacer.md) — Fixed-height spacing block using design token steps. _(npm @cascivo/react · or copy-paste)_
- [layout/split-view](https://cascivo.com/llms/layout/split-view.md) — Resizable two-pane split layout with keyboard and pointer drag support. _(copy-paste)_
- [resizable](https://cascivo.com/llms/resizable.md) — Two-pane splitter whose divider can be dragged or keyboard-nudged to reallocate space _(npm @cascivo/react · or copy-paste)_
- [scroll-area](https://cascivo.com/llms/scroll-area.md) — A scroll container with styled, slim scrollbars and overflow shadows _(npm @cascivo/react · or copy-paste)_
- [section/cta](https://cascivo.com/llms/section/cta.md) — Call-to-action band — quiet hairline-bordered section with title, description, and centered actions. Replace demo content before shipping. _(copy-paste)_
- [section/feature-grid](https://cascivo.com/llms/section/feature-grid.md) — 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. _(copy-paste)_
- [section/hero](https://cascivo.com/llms/section/hero.md) — Page hero section — centered or split layout with eyebrow, title, description, actions and media slots. Replace demo content before shipping. _(copy-paste)_
- [section/media-masonry](https://cascivo.com/llms/section/media-masonry.md) — 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. _(copy-paste)_
- [section/page-footer](https://cascivo.com/llms/section/page-footer.md) — 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. _(copy-paste)_
- [section/stats-band](https://cascivo.com/llms/section/stats-band.md) — 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. _(copy-paste)_
- [stack](https://cascivo.com/llms/stack.md) — Overlaps children in a CSS grid stack with a configurable offset to create a card-pile effect _(npm @cascivo/react · or copy-paste)_

### marketing

- [block/faq](https://cascivo.com/llms/block/faq.md) — Frequently-asked-questions section composed from the Accordion component, with a centered, readable measure. _(copy-paste)_
- [block/marketing-features](https://cascivo.com/llms/block/marketing-features.md) — Three-column responsive feature grid with icon, title, and description per cell. _(copy-paste)_
- [block/marketing-hero](https://cascivo.com/llms/block/marketing-hero.md) — Full-width hero with headline, subtitle, CTA pair, and trust badges. _(copy-paste)_
- [block/pricing](https://cascivo.com/llms/block/pricing.md) — Responsive three-tier pricing section composed from Card, Badge, and Button, with a highlighted featured plan. _(copy-paste)_
- [block/site-footer](https://cascivo.com/llms/block/site-footer.md) — Multi-column site footer composed from Link and Separator, with a brand blurb, link columns, and a legal row. _(copy-paste)_
- [block/testimonials](https://cascivo.com/llms/block/testimonials.md) — Responsive testimonial grid composed from Card and Avatar, with a quote and attribution per card. _(copy-paste)_

### navigation

- [accordion](https://cascivo.com/llms/accordion.md) — Vertically stacked, collapsible content sections _(npm @cascivo/react · or copy-paste)_
- [breadcrumb](https://cascivo.com/llms/breadcrumb.md) — Shows the current page location within a navigation hierarchy _(npm @cascivo/react · or copy-paste)_
- [dock](https://cascivo.com/llms/dock.md) — Fixed bottom navigation bar for mobile app shells with up to 5 items _(npm @cascivo/react · or copy-paste)_
- [header](https://cascivo.com/llms/header.md) — App top bar with brand, primary navigation links, and an actions slot _(npm @cascivo/react · or copy-paste)_
- [header-panel](https://cascivo.com/llms/header-panel.md) — Non-modal panel anchored below the shell header at the inline-end edge — hosts notifications, app switcher, user settings _(npm @cascivo/react · or copy-paste)_
- [large-title-header](https://cascivo.com/llms/large-title-header.md) — Scrolling region whose large title collapses into a compact sticky bar as it scrolls _(npm @cascivo/react · or copy-paste)_
- [link](https://cascivo.com/llms/link.md) — Styled anchor for navigation, standalone or inline within prose _(npm @cascivo/react · or copy-paste)_
- [menu-button](https://cascivo.com/llms/menu-button.md) — A button that opens an anchored action menu of one-shot commands _(npm @cascivo/react · or copy-paste)_
- [menubar](https://cascivo.com/llms/menubar.md) — Horizontal application menu bar with keyboard-navigable dropdown menus _(npm @cascivo/react · or copy-paste)_
- [navigation-menu](https://cascivo.com/llms/navigation-menu.md) — Site navigation bar with links and dropdown flyout panels _(npm @cascivo/react · or copy-paste)_
- [pagination](https://cascivo.com/llms/pagination.md) — Controls for navigating paged data sets, with page size selection _(npm @cascivo/react · or copy-paste)_
- [progress-indicator](https://cascivo.com/llms/progress-indicator.md) — Shows progress through the steps of a multi-step flow _(npm @cascivo/react · or copy-paste)_
- [shell-header](https://cascivo.com/llms/shell-header.md) — Console application header: brand with prefix, dropdown nav menus, global icon actions, hamburger, skip-to-content _(npm @cascivo/react · or copy-paste)_
- [side-nav](https://cascivo.com/llms/side-nav.md) — Collapsible sidebar navigation with optional icons and one level of grouping _(npm @cascivo/react · or copy-paste)_
- [skip-nav](https://cascivo.com/llms/skip-nav.md) — Skip link that jumps keyboard users past the navigation to the main content _(npm @cascivo/react (SkipNavLink, SkipNavLinkProps, SkipNavTarget, SkipNavTargetProps) · the SkipNav component itself is copy-paste)_
- [steps](https://cascivo.com/llms/steps.md) — Visual progress indicator for multi-step flows with horizontal and vertical orientations _(npm @cascivo/react · or copy-paste)_
- [switcher](https://cascivo.com/llms/switcher.md) — Always-visible app/product switcher LIST — every entry is rendered at once, it does not collapse. Lives inside HeaderPanel; renders links with an active indicator and optional dividers. For a collapsed trigger with a menu, use Dropdown. _(npm @cascivo/react · or copy-paste)_
- [tabs](https://cascivo.com/llms/tabs.md) — Switch between related panels of content _(npm @cascivo/react · or copy-paste)_
- [toc](https://cascivo.com/llms/toc.md) — Table of contents with scroll-spy highlighting of the active section _(npm @cascivo/react · or copy-paste)_

### overlay

- [action-sheet](https://cascivo.com/llms/action-sheet.md) — Bottom-rising sheet of discrete actions (iOS action-sheet pattern) with a Cancel button _(npm @cascivo/react · or copy-paste)_
- [alert-dialog](https://cascivo.com/llms/alert-dialog.md) — Confirmation dialog requiring explicit user action; no light-dismiss _(npm @cascivo/react · or copy-paste)_
- [bottom-sheet](https://cascivo.com/llms/bottom-sheet.md) — Mobile bottom sheet with drag-to-resize detents, velocity-projected snapping, and drag-to-dismiss _(npm @cascivo/react · or copy-paste)_
- [command-menu](https://cascivo.com/llms/command-menu.md) — Cmd+K command palette with fuzzy search over grouped commands _(npm @cascivo/react · or copy-paste)_
- [context-menu](https://cascivo.com/llms/context-menu.md) — Right-click context menu anchored at pointer coordinates via CSS custom properties _(npm @cascivo/react · or copy-paste)_
- [drawer](https://cascivo.com/llms/drawer.md) — Edge-anchored dialog panel that slides in from a screen edge with CSS-only enter/exit motion _(npm @cascivo/react · or copy-paste)_
- [dropdown](https://cascivo.com/llms/dropdown.md) — Menu of actions revealed from a trigger _(npm @cascivo/react · or copy-paste)_
- [hover-card](https://cascivo.com/llms/hover-card.md) — Hover-triggered popover with configurable open/close delay _(npm @cascivo/react · or copy-paste)_
- [menu](https://cascivo.com/llms/menu.md) — Dropdown menu with keyboard navigation, built on usePopover _(npm @cascivo/react · or copy-paste)_
- [modal](https://cascivo.com/llms/modal.md) — Accessible dialog overlay using native <dialog> element _(npm @cascivo/react · or copy-paste)_
- [overflow-menu](https://cascivo.com/llms/overflow-menu.md) — Kebab icon button revealing a menu of row-level actions _(npm @cascivo/react · or copy-paste)_
- [popover](https://cascivo.com/llms/popover.md) — Anchored floating panel built on CSS Anchor Positioning + Popover API _(npm @cascivo/react · or copy-paste)_
- [share-menu](https://cascivo.com/llms/share-menu.md) — A Share button opening intent links for Bluesky, Mastodon, Threads, LinkedIn and X, plus copy link and the system share sheet _(npm @cascivo/react · or copy-paste)_
- [sheet](https://cascivo.com/llms/sheet.md) — Slide-in panel from any edge, using popover=manual and @starting-style animations _(npm @cascivo/react · or copy-paste)_
- [toast](https://cascivo.com/llms/toast.md) — Transient notification surfaced via the useToast hook _(npm @cascivo/react (ToastOptions, ToastProvider, ToastVariant, dismissAllToasts, useToast) · the Toast component itself is copy-paste)_
- [toggletip](https://cascivo.com/llms/toggletip.md) — A click-triggered info popover for supplementary, selectable content _(npm @cascivo/react · or copy-paste)_
- [tooltip](https://cascivo.com/llms/tooltip.md) — Contextual label shown on hover or focus _(npm @cascivo/react · or copy-paste)_

### shell

- [block/app-shell](https://cascivo.com/llms/block/app-shell.md) — Two-column layout with collapsible sidebar, nav links, and content area. _(copy-paste)_
- [block/settings-profile](https://cascivo.com/llms/block/settings-profile.md) — Two-section settings form: personal info fields + preference toggles. _(copy-paste)_

When-to-use / when-not-to-use for any entry: https://cascivo.com/context/<name>.md (all of them inline in llms-full.txt).

_Generated: 2026-10-09 from registry v1.9.0_

---

## Component intent summaries (use when…)

- [Accordion](https://cascivo.com/context/accordion.md) — Use when: Progressively disclosing sections of related content the user reads top to bottom
- [ActionSheet](https://cascivo.com/context/action-sheet.md) — Use when: A short list of discrete actions on a touch surface, rising from the bottom
- [AiBadge](https://cascivo.com/context/ai-badge.md) — Use when: Marking a field, card, table cell or message whose content an AI produced or suggested
- [AiDisclaimer](https://cascivo.com/context/ai-disclaimer.md) — Use when: Under an AI chat composer or answer, telling readers the output can be wrong
- [AiStatus](https://cascivo.com/context/ai-status.md) — Use when: Telling the reader an AI request is in flight, and which phase it is in (thinking before output, generating while it streams)
- [Alert](https://cascivo.com/context/alert.md) — Use when: Surfacing a persistent, contextual message inline within a view (warning, error, info, success)
- [AlertDialog](https://cascivo.com/context/alert-dialog.md) — Use when: Confirming a destructive or irreversible action (delete, overwrite, sign out) before it happens
- [AppShell](https://cascivo.com/context/app-shell.md) — Use when: Building an application screen with a persistent header and side navigation
- [AspectRatio](https://cascivo.com/context/aspect-ratio.md) — Use when: Reserving a stable box for media that loads asynchronously, avoiding layout shift
- [Avatar](https://cascivo.com/context/avatar.md) — Use when: Representing a person or entity with a thumbnail image and initials fallback
- [AvatarGroup](https://cascivo.com/context/avatar-group.md) — Use when: Showing several people compactly as an overlapping stack (collaborators, attendees, reviewers)
- [Badge](https://cascivo.com/context/badge.md) — Use when: Labeling an item with a short, static status or category (e.g. "New", "Beta")
- [App Shell](https://cascivo.com/context/block/app-shell.md) — Use when: Frame for an authenticated app: persistent sidebar nav on desktop, drawer nav on mobile
- [Login Form](https://cascivo.com/context/block/auth-login.md) — Use when: Sign-in page for returning users with email + password credentials
- [Sign Up Form](https://cascivo.com/context/block/auth-signup.md) — Use when: Registration page collecting name, email, and password with confirmation
- [ConsoleApp](https://cascivo.com/context/block/console-app.md) — Use when: A Carbon-parity console shell with icon-rail nav, header panels, and aside
- [DashboardCharts](https://cascivo.com/context/block/dashboard-charts.md) — Use when: A prebuilt dashboard with KPI tiles, line, bar, and pie charts
- [Dashboard Overview](https://cascivo.com/context/block/dashboard-overview.md) — Use when: Landing view of a dashboard summarizing headline KPIs (revenue, users, orders, conversion) at a glance
- [Dashboard Table](https://cascivo.com/context/block/dashboard-table.md) — Use when: Admin views listing records (customers, orders) with text search, column sorting, and pagination
- [EmptyDashboard](https://cascivo.com/context/block/empty-dashboard.md) — Use when: A first-run or zero-data dashboard with an empty state and primary CTA
- [FAQ Accordion](https://cascivo.com/context/block/faq.md) — Use when: Pre-sales or support question sections on marketing and pricing pages
- [LoginPage](https://cascivo.com/context/block/login-page.md) — Use when: A complete login page with email and password form
- [Feature Grid](https://cascivo.com/context/block/marketing-features.md) — Use when: Landing-page section detailing product capabilities right after the hero
- [Hero Section](https://cascivo.com/context/block/marketing-hero.md) — Use when: The opening section of a landing page: headline, supporting subtitle, and a primary/secondary CTA pair
- [NotificationCenter](https://cascivo.com/context/block/notification-center.md) — Use when: A list of notification alerts with a mark-all-read action
- [PageWithBreadcrumb](https://cascivo.com/context/block/page-with-breadcrumb.md) — Use when: A centered content page with breadcrumb navigation and a page header
- [Pricing Tiers](https://cascivo.com/context/block/pricing.md) — Use when: Subscription products with a small number of tiers, each with a price, feature list, and its own CTA
- [SettingsFormPage](https://cascivo.com/context/block/settings-form-page.md) — Use when: A settings page with a profile form inside a two-column settings layout
- [Settings — Profile](https://cascivo.com/context/block/settings-profile.md) — Use when: Account settings page combining editable profile fields (name, email, bio) with notification toggles
- [SidebarApp](https://cascivo.com/context/block/sidebar-app.md) — Use when: A ready-made app shell with opinionated collapsible sidebar and top header
- [Site Footer](https://cascivo.com/context/block/site-footer.md) — Use when: Global footer for a marketing or docs site with grouped secondary navigation columns
- [StatsCards](https://cascivo.com/context/block/stats-cards.md) — Use when: A grid of KPI stat cards with trend badges
- [Testimonials](https://cascivo.com/context/block/testimonials.md) — Use when: Social-proof section on a landing or pricing page with short customer quotes
- [UsersTablePage](https://cascivo.com/context/block/users-table-page.md) — Use when: A full user-management page with table, search, and invite action
- [Blockquote](https://cascivo.com/context/blockquote.md) — Use when: Setting off a quoted passage from another source with visual emphasis
- [BottomSheet](https://cascivo.com/context/bottom-sheet.md) — Use when: A mobile surface that rises from the bottom and can be resized between detents by dragging
- [Logo](https://cascivo.com/context/brand/logo.md) — Use when: Placing the cascivo logo in a header, footer, auth screen or splash
- [Breadcrumb](https://cascivo.com/context/breadcrumb.md) — Use when: Showing the user where the current page sits in a navigation hierarchy
- [Button](https://cascivo.com/context/button.md) — Use when: Triggering an action or navigation the user initiates by click/press
- [ButtonGroup](https://cascivo.com/context/button-group.md) — Use when: Presenting several related, independent actions that read as one control (e.g. an editor toolbar)
- [Calendar](https://cascivo.com/context/calendar.md) — Use when: Showing an always-visible month grid for picking a single date (inline, not a popover)
- [Card](https://cascivo.com/context/card.md) — Use when: Grouping related content into a visually distinct surface with border/shadow
- [Carousel](https://cascivo.com/context/carousel.md) — Use when: Presenting a sequence of media or cards the user pages through one at a time
- [ChainOfThought](https://cascivo.com/context/chain-of-thought.md) — Use when: Showing the discrete steps an AI agent is taking or took — searches, file reads, tool calls
- [AreaChart](https://cascivo.com/context/chart/area-chart.md) — Use when: Showing cumulative volume or magnitude of a trend over continuous time
- [BarChart](https://cascivo.com/context/chart/bar-chart.md) — Use when: Comparing discrete categorical values across groups
- [Boxplot](https://cascivo.com/context/chart/boxplot.md) — Use when: Comparing the distribution spread, median, and quartiles across groups
- [BubbleChart](https://cascivo.com/context/chart/bubble-chart.md) — Use when: Plotting three dimensions at once — x, y, and a size-encoded magnitude
- [Bullet](https://cascivo.com/context/chart/bullet.md) — Use when: Showing a single measure against a target with qualitative range bands
- [CalendarHeatmap](https://cascivo.com/context/chart/calendar.md) — Use when: Showing a daily value over weeks/months (activity, contributions)
- [Candlestick](https://cascivo.com/context/chart/candlestick.md) — Use when: Showing open/high/low/close price movement over time
- [ComboChart](https://cascivo.com/context/chart/combo-chart.md) — Use when: Overlaying two related metrics with different scales (e.g. volume bars + rate line)
- [Funnel](https://cascivo.com/context/chart/funnel.md) — Use when: Showing drop-off across the ordered stages of a process (signup, checkout)
- [Gauge](https://cascivo.com/context/chart/gauge.md) — Use when: A single value against a range with a needle and threshold zones
- [Heatmap](https://cascivo.com/context/chart/heatmap.md) — Use when: Showing magnitude across two categorical dimensions as a color-coded matrix
- [Histogram](https://cascivo.com/context/chart/histogram.md) — Use when: Showing the frequency distribution of a single continuous variable
- [Kpi](https://cascivo.com/context/chart/kpi.md) — Use when: Highlighting a single headline metric with an optional change delta
- [LineChart](https://cascivo.com/context/chart/line-chart.md) — Use when: Showing trends and precise values over continuous time or a numeric range
- [Meter](https://cascivo.com/context/chart/meter.md) — Use when: Showing a rated or gauged value within a known min/max range
- [PieChart](https://cascivo.com/context/chart/pie-chart.md) — Use when: Showing part-of-whole proportions with five or fewer slices
- [Polar](https://cascivo.com/context/chart/polar.md) — Use when: Cyclical/directional categories where the circle is meaningful (wind, hours, months)
- [Radar](https://cascivo.com/context/chart/radar.md) — Use when: Comparing several entities across the same set of quantitative dimensions
- [RadialBar](https://cascivo.com/context/chart/radial-bar.md) — Use when: Showing a few progress-to-goal values in a compact circular form
- [Sankey](https://cascivo.com/context/chart/sankey.md) — Use when: Showing flow/throughput between stages or categories
- [ScatterChart](https://cascivo.com/context/chart/scatter-chart.md) — Use when: Revealing correlation or clustering between two numeric variables
- [Sparkline](https://cascivo.com/context/chart/sparkline.md) — Use when: Embedding a compact micro-trend inline in text, tables, or KPI cards
- [Stream](https://cascivo.com/context/chart/stream.md) — Use when: Showing how several series ebb and flow over time as proportions of a whole
- [Sunburst](https://cascivo.com/context/chart/sunburst.md) — Use when: Showing a part-of-whole hierarchy across multiple levels
- [Treemap](https://cascivo.com/context/chart/treemap.md) — Use when: Showing part-to-whole proportions across many segments in a compact area
- [ChatBubble](https://cascivo.com/context/chat-bubble.md) — Use when: Chat UIs and messaging features showing conversation history
- [Checkbox](https://cascivo.com/context/checkbox.md) — Use when: Selecting zero or more options from a list where each choice is independent
- [CheckboxCard](https://cascivo.com/context/checkbox-card.md) — Use when: Multi-select where each option needs a title and supporting description (feature toggles, add-ons)
- [Code](https://cascivo.com/context/code.md) — Use when: Marking up an inline identifier, command, path, or token within prose
- [CodeSnippet](https://cascivo.com/context/code-snippet.md) — Use when: Showing a command, token, or path the user is expected to copy
- [Collapsible](https://cascivo.com/context/collapsible.md) — Use when: Hiding a single secondary block until the user asks for it
- [ColorPicker](https://cascivo.com/context/color-picker.md) — Use when: Letting a user choose an arbitrary color via a visual saturation/lightness area plus hue control
- [Combobox](https://cascivo.com/context/combobox.md) — Use when: Single-select from a long list where type-to-filter makes finding an option faster
- [CommandMenu](https://cascivo.com/context/command-menu.md) — Use when: Giving power users a global Cmd/Ctrl+K palette to search and run actions or navigate
- [Comparison](https://cascivo.com/context/comparison.md) — Use when: Showing the difference between two versions of similar content (before/after edits, original vs processed)
- [ContainedList](https://cascivo.com/context/contained-list.md) — Use when: Grouping a short set of related rows under a visible heading in a bordered surface
- [ContextMenu](https://cascivo.com/context/context-menu.md) — Use when: Offering actions contextual to an element via right-click (rename, delete, copy on a row or canvas item)
- [ContextMeter](https://cascivo.com/context/context-meter.md) — Use when: Showing how much of the model’s context window a conversation or document has used
- [CopyButton](https://cascivo.com/context/copy-button.md) — Use when: Letting users copy a short value to the clipboard — install commands, API keys, tokens, share links
- [DataList](https://cascivo.com/context/data-list.md) — Use when: Displaying read-only key-value metadata (profile fields, record summaries)
- [DataTable](https://cascivo.com/context/data-table.md) — Use when: Displaying tabular data with columns the user sorts, filters, or pages through
- [DatePicker](https://cascivo.com/context/date-picker.md) — Use when: Picking a single calendar date in a form where a visual month grid helps (due dates, bookings)
- [DateRangePicker](https://cascivo.com/context/date-range-picker.md) — Use when: Selecting a contiguous start–end date range (reporting windows, bookings, filters)
- [Dock](https://cascivo.com/context/dock.md) — Use when: Mobile app-shell navigation with 3–5 top-level destinations
- [Drawer](https://cascivo.com/context/drawer.md) — Use when: A side or edge panel for navigation, filters, or detail views that needs full-height space
- [Dropdown](https://cascivo.com/context/dropdown.md) — Use when: Revealing a short menu of actions from a trigger button (row actions, "More" overflow, account menu)
- [Editable](https://cascivo.com/context/editable.md) — Use when: Editing a single piece of text in place where the value is normally read-only — titles, names, labels
- [CodeEditor](https://cascivo.com/context/editor/code-editor.md) — Use when: Editing code or config inline — JSON, snippets, web languages — with line numbers and syntax colors
- [Highlight](https://cascivo.com/context/editor/highlight.md) — Use when: Displaying non-editable code or config with syntax colors — docs, snippets, examples
- [EmptyState](https://cascivo.com/context/empty-state.md) — Use when: Filling a view that has no data with guidance and a primary next step
- [Fab](https://cascivo.com/context/fab.md) — Use when: A single, high-emphasis primary action that floats above scrolling content (e.g. Compose, Add)
- [Field](https://cascivo.com/context/field.md) — Use when: Pairing a single control with its label, helper text, and validation message
- [FileUploader](https://cascivo.com/context/file-uploader.md) — Use when: Letting users attach one or more files via click-to-browse or drag-and-drop
- [Filter](https://cascivo.com/context/filter.md) — Use when: Tag or category filtering on listing pages where the active filters must remain visible
- [Flow](https://cascivo.com/context/flow/flow.md) — Use when: Rendering a graph from data — the common case and the agent-emittable surface
- [FlowBackground](https://cascivo.com/context/flow/flow-background.md) — Use when: Giving a flow canvas a sense of space and scale with a dotted or grid backdrop
- [FlowCanvas](https://cascivo.com/context/flow/flow-canvas.md) — Use when: Hosting a hand-composed flow from low-level FlowNode/FlowEdge primitives
- [FlowControls](https://cascivo.com/context/flow/flow-controls.md) — Use when: Giving users explicit zoom/fit controls on a flow canvas
- [FlowEdge](https://cascivo.com/context/flow/flow-edge.md) — Use when: Connecting two nodes with a directed path and arrowhead
- [FlowHandle](https://cascivo.com/context/flow/flow-handle.md) — Use when: Marking where edges connect to a node
- [FlowMiniMap](https://cascivo.com/context/flow/flow-minimap.md) — Use when: Orienting users in a large graph
- [FlowNode](https://cascivo.com/context/flow/flow-node.md) — Use when: Representing a unit in a graph that holds arbitrary themed content
- [FlowPanel](https://cascivo.com/context/flow/flow-panel.md) — Use when: Overlaying custom UI (a legend, a toolbar) on a flow canvas
- [FlowStory](https://cascivo.com/context/flow/flow-story.md) — Use when: Explaining how a flow works step by step, not just showing a static diagram
- [Form](https://cascivo.com/context/form.md) — Use when: Collecting and submitting a set of related field values together
- [Header](https://cascivo.com/context/header.md) — Use when: Providing a simple marketing or app top bar with brand, links, and actions
- [HeaderPanel](https://cascivo.com/context/header-panel.md) — Use when: Hosting a non-modal panel anchored under the shell header (notifications, switcher, settings)
- [Heading](https://cascivo.com/context/heading.md) — Use when: Titling a page or section as part of the document outline
- [HoverCard](https://cascivo.com/context/hover-card.md) — Use when: Showing a rich preview (avatar, summary, links) when a user hovers or focuses a trigger
- [IconButton](https://cascivo.com/context/icon-button.md) — Use when: A compact, recognizable action where an icon alone communicates intent (close, edit, more)
- [Image](https://cascivo.com/context/image.md) — Use when: Displaying a content image that should show a placeholder while loading and degrade gracefully on error
- [Indicator](https://cascivo.com/context/indicator.md) — Use when: Notification counts on icon buttons
- [InfiniteScroll](https://cascivo.com/context/infinite-scroll.md) — Use when: A long, page-fetched feed or list where the user should keep reading without a page break
- [InlineCitation](https://cascivo.com/context/inline-citation.md) — Use when: Attributing a claim in an AI answer to the source it came from, right where the claim is made
- [InlineLoading](https://cascivo.com/context/inline-loading.md) — Use when: Showing the progress of a single inline action — a Save button that becomes "Saving… / Saved / Failed"
- [Input](https://cascivo.com/context/input.md) — Use when: Collecting a single line of free-form text from the user
- [InputGroup](https://cascivo.com/context/input-group.md) — Use when: Attaching a prefix/suffix addon (protocol, currency, unit) to an Input so it reads as one field
- [Item](https://cascivo.com/context/item.md) — Use when: Composing a single content row with leading media, a text block, and trailing actions
- [Join](https://cascivo.com/context/join.md) — Use when: Input + button search groups where the two controls should appear as one unit
- [Kbd](https://cascivo.com/context/kbd.md) — Use when: Showing a keyboard key or shortcut the user should press
- [Label](https://cascivo.com/context/label.md) — Use when: Naming a single form control (input, select, checkbox) so clicking the text focuses it
- [LargeTitleHeader](https://cascivo.com/context/large-title-header.md) — Use when: A scrolling screen that should keep its title reachable after the heading scrolls away
- [AppFrame](https://cascivo.com/context/layout/app-shell.md) — Use when: A full-page application frame with header, collapsible sidebar, and content
- [AuthLayout](https://cascivo.com/context/layout/auth-layout.md) — Use when: Centered card layout for authentication pages — login, register, reset
- [AutoGrid](https://cascivo.com/context/layout/auto-grid.md) — Use when: Responsive card or tile grids that auto-fit columns to available width
- [Center](https://cascivo.com/context/layout/center.md) — Use when: Horizontally centering content within a configurable max-width
- [Columns](https://cascivo.com/context/layout/columns.md) — Use when: Equal-width multi-column content that collapses to one column when narrow
- [DashboardLayout](https://cascivo.com/context/layout/dashboard-layout.md) — Use when: A dashboard page with a stats strip, main content area, and optional aside
- [Flex](https://cascivo.com/context/layout/flex.md) — Use when: Arranging children vertically or horizontally with a consistent gap
- [Grid](https://cascivo.com/context/layout/grid.md) — Use when: Two-dimensional layouts with an explicit column count
- [Masonry](https://cascivo.com/context/layout/masonry.md) — Use when: Galleries of variable-height items packed into balanced columns
- [PageHeader](https://cascivo.com/context/layout/page-header.md) — Use when: A page-level header with title, description, breadcrumb, and action slots
- [Section](https://cascivo.com/context/layout/section.md) — Use when: Wrapping a page region with block padding and a centered inner width
- [SettingsLayout](https://cascivo.com/context/layout/settings-layout.md) — Use when: A two-column settings page with a fixed-width menu and fluid content
- [Spacer](https://cascivo.com/context/layout/spacer.md) — Use when: Inserting a fixed vertical gap between blocks using spacing token steps
- [SplitView](https://cascivo.com/context/layout/split-view.md) — Use when: Two side-by-side panes the user can resize via pointer or keyboard
- [Link](https://cascivo.com/context/link.md) — Use when: Navigating to another page, view, or resource via a real href
- [List](https://cascivo.com/context/list.md) — Use when: Presenting a set of related items as a bulleted or numbered list
- [LogViewer](https://cascivo.com/context/log-viewer.md) — Use when: Rendering continuous, high-volume log or stream output (build/deploy logs, server output)
- [Menu](https://cascivo.com/context/menu.md) — Use when: Presenting a list of actions or commands triggered from a button
- [MenuButton](https://cascivo.com/context/menu-button.md) — Use when: Exposing a small set of one-shot actions behind a single labeled button
- [Menubar](https://cascivo.com/context/menubar.md) — Use when: A persistent application-style command bar (File / Edit / View) where each top-level entry opens a menu of actions
- [MessageActions](https://cascivo.com/context/message-actions.md) — Use when: Under each assistant message: copy the reply, rate it, or ask for another attempt
- [Modal](https://cascivo.com/context/modal.md) — Use when: Presenting focused content or a task that must interrupt the current flow
- [MultiSelect](https://cascivo.com/context/multi-select.md) — Use when: Selecting several values at once from a known list of options
- [NativeSelect](https://cascivo.com/context/native-select.md) — Use when: A standard single-choice dropdown where native behavior and form integration matter most
- [NavigationMenu](https://cascivo.com/context/navigation-menu.md) — Use when: Primary site navigation where some destinations are plain links and others reveal a flyout of grouped links
- [Notification](https://cascivo.com/context/notification.md) — Use when: Surfacing a prominent, often actionable message in the page flow (sync result, failed upload, available update)
- [NumberInput](https://cascivo.com/context/number-input.md) — Use when: Collecting a bounded numeric value where increment/decrement by a known step is natural (quantity, opacity, count)
- [OtpInput](https://cascivo.com/context/otp-input.md) — Use when: Entering a fixed-length one-time code (2FA, SMS verification, email confirmation) split across per-character slots
- [OverflowMenu](https://cascivo.com/context/overflow-menu.md) — Use when: Collapsing secondary row-level or item-level actions behind a kebab trigger in dense layouts like tables and lists
- [Pagination](https://cascivo.com/context/pagination.md) — Use when: Navigating between pages of a paged dataset
- [PasswordInput](https://cascivo.com/context/password-input.md) — Use when: Collecting a secret credential that should be masked by default with an opt-in reveal toggle
- [Popover](https://cascivo.com/context/popover.md) — Use when: Showing rich, interactive content anchored to a trigger that the user must explicitly open by clicking
- [Progress](https://cascivo.com/context/progress.md) — Use when: Tracked operations with a known total (file uploads, multi-step imports)
- [ProgressBar](https://cascivo.com/context/progress-bar.md) — Use when: Showing linear determinate progress of a task with a known percentage (value)
- [ProgressCircle](https://cascivo.com/context/progress-circle.md) — Use when: Showing determinate progress compactly as a circular arc
- [ProgressIndicator](https://cascivo.com/context/progress-indicator.md) — Use when: Showing progress through the discrete steps of a multi-step flow (wizard, checkout)
- [PromptSuggestions](https://cascivo.com/context/prompt-suggestions.md) — Use when: An empty conversation: offer a few concrete things to ask
- [Prose](https://cascivo.com/context/prose.md) — Use when: Styling long-form authored content (articles, docs, CMS output)
- [PullToRefresh](https://cascivo.com/context/pull-to-refresh.md) — Use when: A scrollable list or feed on touch devices that the user refreshes by pulling down from the top
- [QrCode](https://cascivo.com/context/qr-code.md) — Use when: Letting users scan a URL, contact, or short token with a phone camera
- [RadialProgress](https://cascivo.com/context/radial-progress.md) — Use when: Dashboard KPI metrics showing completion percentage
- [Radio](https://cascivo.com/context/radio.md) — Use when: Choosing exactly one option from a small, mutually exclusive set (roughly 2–6) where all options should stay visible
- [RadioCard](https://cascivo.com/context/radio-card.md) — Use when: Single-select from a few options where each choice needs a title plus supporting description (plans, tiers, shipping methods)
- [RatingGroup](https://cascivo.com/context/rating-group.md) — Use when: Capturing a discrete subjective rating on a small fixed scale (e.g. 1–5 stars)
- [Reasoning](https://cascivo.com/context/reasoning.md) — Use when: Showing a model’s reasoning or thinking trace above its answer, collapsed once the answer arrives
- [RelativeTime](https://cascivo.com/context/relative-time.md) — Use when: Showing how long ago something happened in human terms ("3 minutes ago")
- [ReorderList](https://cascivo.com/context/reorder-list.md) — Use when: A short, user-owned ordering such as playlist tracks, form fields, or dashboard cards
- [Resizable](https://cascivo.com/context/resizable.md) — Use when: Letting users reallocate space between two adjacent regions, e.g. an editor and a preview
- [ScrollArea](https://cascivo.com/context/scroll-area.md) — Use when: Constraining a region to a fixed height/width with overflow scrolling
- [Search](https://cascivo.com/context/search.md) — Use when: A query field that filters or searches content, with a built-in clear button and debounced onSearch
- [Cta](https://cascivo.com/context/section/cta.md) — Use when: A call-to-action band with title, description, and centered actions
- [FeatureGrid](https://cascivo.com/context/section/feature-grid.md) — Use when: A feature section laying out items in an auto-fitting grid
- [Hero](https://cascivo.com/context/section/hero.md) — Use when: The primary page intro with eyebrow, title, description, actions, and media
- [MediaMasonry](https://cascivo.com/context/section/media-masonry.md) — Use when: A full-width media gallery section with masonry packing
- [PageFooter](https://cascivo.com/context/section/page-footer.md) — Use when: A site footer with grouped link columns and a brand/meta bottom row
- [StatsBand](https://cascivo.com/context/section/stats-band.md) — Use when: A horizontal KPI strip with optional deltas and inline sparkline trends
- [SegmentedControl](https://cascivo.com/context/segmented-control.md) — Use when: A compact inline single choice among a few mutually exclusive options (2–5) such as view modes or time ranges
- [Select](https://cascivo.com/context/select.md) — Use when: Choosing exactly one value from a known, finite list inside a form
- [Separator](https://cascivo.com/context/separator.md) — Use when: Dividing groups of content within a section or menu
- [ShareMenu](https://cascivo.com/context/share-menu.md) — Use when: Letting readers share a page to a social network without any account, token or API on your side
- [Sheet](https://cascivo.com/context/sheet.md) — Use when: Showing secondary content or a form in a panel that slides in from a screen edge
- [ShellHeader](https://cascivo.com/context/shell-header.md) — Use when: Building console/admin app chrome with brand, dropdown nav, and global icon actions
- [ShimmerText](https://cascivo.com/context/shimmer-text.md) — Use when: Styling a short label that names work in progress — "Thinking…", "Searching the docs…"
- [SideNav](https://cascivo.com/context/side-nav.md) — Use when: Persistent primary navigation along the side of an app shell
- [Skeleton](https://cascivo.com/context/skeleton.md) — Use when: Indicating loading by mirroring the shape of the content that will appear
- [SkipNav](https://cascivo.com/context/skip-nav.md) — Use when: Letting keyboard users jump past repeated navigation to the main content
- [Slider](https://cascivo.com/context/slider.md) — Use when: Selecting a value within a continuous or stepped numeric range where approximate adjustment is fine
- [Sources](https://cascivo.com/context/sources.md) — Use when: Listing what an AI answer was based on, below the answer
- [Spinner](https://cascivo.com/context/spinner.md) — Use when: Indicating indeterminate work where duration and progress are unknown
- [Stack](https://cascivo.com/context/stack.md) — Use when: Card pile UI where depth and layering should be visible
- [Stat](https://cascivo.com/context/stat.md) — Use when: Highlighting a single key metric with a clear label
- [Status](https://cascivo.com/context/status.md) — Use when: Communicating the live state of a system or entity (operational, deploying, down)
- [Steps](https://cascivo.com/context/steps.md) — Use when: Checkout flows where the user moves through a fixed sequence of screens
- [StreamingText](https://cascivo.com/context/streaming-text.md) — Use when: Rendering an assistant reply as it streams in, smoothing bursty token arrival into steady typing
- [StructuredList](https://cascivo.com/context/structured-list.md) — Use when: Presenting a set of related records in aligned columns the user scans top to bottom
- [Swap](https://cascivo.com/context/swap.md) — Use when: Theme toggles where an icon animates between two states (sun/moon)
- [SwipeItem](https://cascivo.com/context/swipe-item.md) — Use when: List rows on touch surfaces where secondary actions (archive, delete) should hide until swiped
- [Switcher](https://cascivo.com/context/switcher.md) — Use when: Listing sibling apps/products the user can switch between
- [Tabs](https://cascivo.com/context/tabs.md) — Use when: Switching between peer panels of related content in the same context
- [Tag](https://cascivo.com/context/tag.md) — Use when: Labeling, categorizing, or filtering content with a compact chip
- [TagsInput](https://cascivo.com/context/tags-input.md) — Use when: Collecting an open-ended set of free-text values the user types themselves (keywords, emails, labels)
- [Terminal](https://cascivo.com/context/terminal.md) — Use when: Demonstrating a CLI or agent run on a marketing or onboarding page
- [Text](https://cascivo.com/context/text.md) — Use when: Rendering body copy, paragraphs, and inline text in app UI
- [Textarea](https://cascivo.com/context/textarea.md) — Use when: Capturing multi-line free text such as messages, descriptions, or comments
- [Tile](https://cascivo.com/context/tile.md) — Use when: A visually rich, clickable choice card in a single- or multi-select group
- [TimePicker](https://cascivo.com/context/time-picker.md) — Use when: Capturing a time of day (HH:mm) in a form, such as a meeting or reminder time
- [Timeline](https://cascivo.com/context/timeline.md) — Use when: Showing an ordered sequence of events over time (activity feeds, order tracking)
- [Toast](https://cascivo.com/context/toast.md) — Use when: Confirming that a background or just-completed action succeeded or failed (e.g. "Saved")
- [Toc](https://cascivo.com/context/toc.md) — Use when: Long-form pages (docs, articles) that benefit from in-page jump links
- [Toggle](https://cascivo.com/context/toggle.md) — Use when: Flipping a single binary setting that takes effect immediately (e.g. notifications on/off)
- [ToggleGroup](https://cascivo.com/context/toggle-group.md) — Use when: Choosing one value from a small, mutually exclusive set that should stay visible (type="single")
- [Toggletip](https://cascivo.com/context/toggletip.md) — Use when: Revealing brief supplementary information on demand when the user clicks an info affordance
- [ToolCall](https://cascivo.com/context/tool-call.md) — Use when: Showing an AI tool or function call in a conversation, with what it was given and what it returned
- [Tooltip](https://cascivo.com/context/tooltip.md) — Use when: Labeling an icon-only control or clarifying a terse element on hover or focus
- [TreeView](https://cascivo.com/context/tree-view.md) — Use when: Showing nested, parent/child data the user expands and collapses (file trees, org charts, nav)
- [TypingIndicator](https://cascivo.com/context/typing-indicator.md) — Use when: Holding the place of an assistant reply between sending a prompt and the first token arriving
- [User](https://cascivo.com/context/user.md) — Use when: Showing a person with their name and a secondary line (email, role) next to an avatar
- [VirtualList](https://cascivo.com/context/virtual-list.md) — Use when: Lists long enough that rendering every row costs noticeable time or memory (roughly a thousand rows and up)
- [VisuallyHidden](https://cascivo.com/context/visually-hidden.md) — Use when: Giving an icon-only control an accessible name without showing text
- [WheelPicker](https://cascivo.com/context/wheel-picker.md) — Use when: Touch surfaces picking one value from a short, ordered, homogeneous range — an hour, a minute, a unit

---

# Full component reference (inlined)

Every entry below is the same content as the per-component `llms/<name>.md` files, inlined
here so no additional fetches are required.

---

# Accordion

Vertically stacked, collapsible content sections

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add accordion
```

Or use it from the prebuilt package without copying:

```tsx
import { Accordion } from '@cascivo/react'
```

## Category

`navigation`

## States

- `open`
- `closed`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `type` | `'single' \| 'multiple'` | no | `single` | Whether one or multiple sections can be open at once ('single' \| 'multiple'). |
| `defaultValue` | `string \| string[]` | no | — | The initial value when uncontrolled. |
| `value` | `string \| string[]` | no | — | The controlled value. |
| `onValueChange` | `(value: string \| string[]) => void` | no | — | Called with the new value when it changes. |

## Examples

### Single

```tsx
<Accordion type="single" defaultValue="a"><AccordionItem value="a"><AccordionTrigger>Section</AccordionTrigger><AccordionContent>…</AccordionContent></AccordionItem></Accordion>
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-color-border`
- `--cascivo-color-bg-subtle`
- `--cascivo-color-text`
- `--cascivo-radius-md`
- `--cascivo-focus-ring`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `button`
- **Keyboard:** Enter, Space

## Dependencies

- `@cascivo/core`

## Tags

navigation, collapse, disclosure

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# ActionSheet

Bottom-rising sheet of discrete actions (iOS action-sheet pattern) with a Cancel button

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add action-sheet
```

Or use it from the prebuilt package without copying:

```tsx
import { ActionSheet } from '@cascivo/react'
```

## Category

`overlay`

## States

- `open`
- `closed`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `open` | `boolean` | no | — | Whether the component is open (controlled). |
| `defaultOpen` | `boolean` | no | — | Whether the component is open on first render (uncontrolled). |
| `onOpenChange` | `(open: boolean) => void` | no | — | Called with the next open state when it changes. |
| `actions` | `ActionSheetAction[]` | yes | — | Choices, each with a label, onSelect, and optional destructive/disabled flags |
| `title` | `React.ReactNode` | no | — | Title text for the component. |
| `description` | `React.ReactNode` | no | — | Supporting description text. |
| `showCancel` | `boolean` | no | `true` | When true, shows a cancel button below the actions. |
| `labels` | `{ cancel?: string; label?: string }` | no | — | Overrides for the component’s user-visible strings (i18n). |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |

## Examples

### Basic

```tsx
<ActionSheet
  open={isOpen}
  onOpenChange={setIsOpen}
  title="Share photo"
  actions={[
    { label: 'Copy link', onSelect: copyLink },
    { label: 'Delete', onSelect: remove, destructive: true },
  ]}
/>
```

### Without cancel button

Escape and outside press still dismiss the sheet.

```tsx
<ActionSheet defaultOpen showCancel={false} actions={[{ label: "Archive", onSelect: archive }]} />
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-accent-text`
- `--cascivo-color-surface`
- `--cascivo-color-border`
- `--cascivo-color-destructive`
- `--cascivo-color-text`
- `--cascivo-color-text-subtle`
- `--cascivo-color-text-muted`
- `--cascivo-radius-overlay`
- `--cascivo-shadow-overlay`
- `--cascivo-motion-enter`
- `--cascivo-motion-exit`
- `--cascivo-z-overlay`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `menu`
- **Keyboard:** ArrowUp, ArrowDown, Home, End, Enter, Space, Escape

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

overlay, action-sheet, menu, mobile, sheet

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# AiBadge

Small "AI" marker for AI-generated content; with children it opens a toggletip explaining how AI was involved

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add ai-badge
```

Or use it from the prebuilt package without copying:

```tsx
import { AiBadge } from '@cascivo/react'
```

## Category

`display`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `children` | `ReactNode` | no | — | The explanation shown in the toggletip — model, sources, confidence. Omit for a static marker. |
| `edited` | `boolean` | no | `false` | The person has changed the AI’s output. The AI mark gives way to a revert button when `onRevert` is set, and to nothing otherwise — edited content is no longer AI-generated. |
| `onRevert` | `() => void` | no | — | Restores the AI version. Shown as an icon button (named by `labels.revert`) while `edited` is true. |
| `labels` | `{ text?: string; explain?: string; description?: string; revert?: string }` | no | — | Overrides for the component’s user-visible strings (i18n): `text` (the pill, "AI"), `explain` (appended to the trigger’s accessible name), `description` (what a screen reader hears for the static marker), `revert` (the revert button’s accessible name). |

## Examples

### Edited, with revert

```tsx
<AiBadge edited onRevert={() => {}} />
```

### Static marker

```tsx
<AiBadge />
```

### With explanation

```tsx
<AiBadge>This summary was generated by an AI model from the last 30 days of tickets. Check important details.</AiBadge>
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-color-ai`
- `--cascivo-color-ai-subtle`
- `--cascivo-color-ai-border`
- `--cascivo-color-text`
- `--cascivo-radius-indicator`
- `--cascivo-text-xs`
- `--cascivo-font-semibold`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `button`
- **Keyboard:** Enter, Space, Escape

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

ai, label, badge, provenance, explainability, generated

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# AiDisclaimer

A short, quiet note that AI-generated content may be wrong — "AI-generated content may be incorrect"

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add ai-disclaimer
```

Or use it from the prebuilt package without copying:

```tsx
import { AiDisclaimer } from '@cascivo/react'
```

## Category

`feedback`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `children` | `ReactNode` | no | — | Replaces the default text — e.g. naming the model or what to double-check. |
| `labels` | `{ text?: string }` | no | — | Overrides for the component’s user-visible strings (i18n). |

## Examples

### Default

```tsx
<AiDisclaimer />
```

### Specific

```tsx
<AiDisclaimer>Summaries are generated by AI. Check figures against the source report.</AiDisclaimer>
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-color-text-muted`
- `--cascivo-color-ai`
- `--cascivo-text-xs`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `paragraph`

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

ai, disclaimer, disclosure, notice, provenance, generated

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# AiStatus

Announces what an AI is doing — thinking, generating, done, failed or stopped — with a shimmering label and an optional Stop button

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add ai-status
```

Or use it from the prebuilt package without copying:

```tsx
import { AiStatus } from '@cascivo/react'
```

## Category

`feedback`

## States

- `thinking`
- `generating`
- `complete`
- `error`
- `stopped`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `status` | `'thinking' \| 'generating' \| 'complete' \| 'error' \| 'stopped'` | yes | — | The phase: `thinking` (working, nothing produced yet), `generating` (output is streaming), `complete`, `error`, or `stopped` (the reader pressed Stop). |
| `label` | `ReactNode` | no | — | Replaces the default text for the current status, e.g. "Searching 12 documents…". Rendered on screen. |
| `labels` | `{ thinking?: string; generating?: string; complete?: string; error?: string; stopped?: string; stop?: string }` | no | — | Overrides for the component’s user-visible strings (i18n). |
| `onStop` | `() => void` | no | — | Called when the reader presses Stop. When set, a Stop button renders while the status is `thinking` or `generating`. |

## Examples

### Thinking

```tsx
<AiStatus status="thinking" />
```

### Generating, with Stop

```tsx
<AiStatus status="generating" onStop={() => {}} />
```

### Custom label

```tsx
<AiStatus status="thinking" label="Searching 12 documents…" />
```

### Complete

```tsx
<AiStatus status="complete" />
```

### Error

```tsx
<AiStatus status="error" />
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-color-ai`
- `--cascivo-color-text`
- `--cascivo-color-text-muted`
- `--cascivo-color-success`
- `--cascivo-color-destructive`
- `--cascivo-duration-loop-slow`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `status`
- **Keyboard:** Tab, Enter, Space

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

ai, status, loading, thinking, generating, progress, stop

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Alert

Highlights a short, important message inline

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add alert
```

Or use it from the prebuilt package without copying:

```tsx
import { Alert } from '@cascivo/react'
```

## Category

`display`

## Variants

- `default`
- `info`
- `success`
- `warning`
- `destructive`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `variant` | `'default' \| 'info' \| 'success' \| 'warning' \| 'destructive'` | no | `default` | Severity tone: `default` (neutral), `info`, `success`, `warning` or `destructive`. Sets the icon and the accent colour. Unlike Badge/Tag/Notification this is a private union, not `ToneInput` — the canonical `danger`/`neutral` spellings are not accepted here. |
| `title` | `string` | no | — | Title text for the component. |
| `icon` | `ReactNode` | no | — | Icon element rendered in the component. |
| `dismissible` | `boolean` | no | `false` | When true, shows a control to dismiss the component. |
| `onDismiss` | `() => void` | no | — | Called when the component is dismissed. |
| `action` | `{ label: string; onClick: () => void }` | no | — | Primary action shown in the component. |

## Examples

### Info

```tsx
<Alert variant="info" title="Heads up">Your trial ends soon.</Alert>
```

### Dismissible

```tsx
<Alert variant="success" dismissible title="Saved">Changes saved.</Alert>
```

### Actionable

```tsx
<Alert variant="warning" title="Update available" action={{ label: 'Update now', onClick: update }}>A new version is ready.</Alert>
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-color-info`
- `--cascivo-color-success`
- `--cascivo-color-warning`
- `--cascivo-color-destructive`
- `--cascivo-color-border`
- `--cascivo-radius-md`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `alert`

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

notification, message, feedback

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# AlertDialog

Confirmation dialog requiring explicit user action; no light-dismiss

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add alert-dialog
```

Or use it from the prebuilt package without copying:

```tsx
import { AlertDialog } from '@cascivo/react'
```

## Category

`overlay`

## Variants

- `default`
- `destructive`

## States

- `open`
- `closed`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `open` | `boolean` | yes | — | Whether the component is open (controlled). |
| `title` | `string` | yes | — | Title text for the component. |
| `description` | `string` | yes | — | Supporting description text. |
| `onConfirm` | `() => void` | yes | — | Called when the confirm button is activated. |
| `onCancel` | `() => void` | yes | — | Called when the cancel button is activated. |
| `labels` | `AlertDialogLabels` | no | — | Overrides for the component’s user-visible strings (i18n). |
| `variant` | `'destructive' \| 'default'` | no | `default` | `destructive` styles the confirm button as a danger action; `default` styles it as the primary action. Use `destructive` for anything that deletes. |

## Examples

### Destructive confirm

```tsx
<AlertDialog
  open={isOpen}
  variant="destructive"
  title="Delete project?"
  description="This permanently removes the project and cannot be undone."
  onConfirm={remove}
  onCancel={() => setIsOpen(false)}
/>
```

### Custom action labels

```tsx
<AlertDialog
  open={isOpen}
  title="Sign out?"
  description="Unsaved changes will be lost."
  labels={{ confirm: 'Sign out', cancel: 'Stay' }}
  onConfirm={signOut}
  onCancel={() => setIsOpen(false)}
/>
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-surface`
- `--cascivo-color-border`
- `--cascivo-radius-lg`
- `--cascivo-shadow-xl`
- `--cascivo-motion-enter`
- `--cascivo-motion-exit`
- `--cascivo-color-accent`
- `--cascivo-color-destructive`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `alertdialog`
- **Keyboard:** Tab, Shift+Tab, Enter, Space

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

overlay, dialog, confirm, destructive

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# AppShell

Sticky-header + full-height side-nav + single-scroll-container layout with an animated, accessible nav toggle.

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add app-shell
```

Or use it from the prebuilt package without copying:

```tsx
import { AppShell } from '@cascivo/react'
```

## Category

`layout`

## States

- `open`
- `closed`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `header` | `ReactNode` | yes | — | Top bar (typically a ShellHeader). If a React element, its onMenuClick/menuExpanded are bound to the nav toggle. |
| `nav` | `ReactNode` | no | — | Side navigation (typically a SideNav). Fills full height and scrolls internally. |
| `children` | `ReactNode` | yes | — | Main content, rendered inside the single scroll container. |
| `footer` | `ReactNode` | no | — | Optional footer pinned below the content area. |
| `open` | `boolean` | no | — | Controlled nav open/visible state. Omit for uncontrolled. |
| `defaultOpen` | `boolean` | no | — | Initial open state when uncontrolled. Defaults open on desktop, closed on small screens. |
| `onOpenChange` | `(open: boolean) => void` | no | — | Fired when the nav requests open/close (burger, Escape, scrim). |
| `padding` | `SpaceStep \| 'none'` | no | `6` | Inset around the main content area, as a space-scale step. Defaults to 6 — `<main>` shipped unpadded for three releases and every adopter wrote the same wrapper div. Pass 'none' for a full-bleed layout that owns its own insets. |

## Examples

### Header + SideNav + content

The burger in ShellHeader toggles the SideNav automatically.

```tsx
<AppShell
  header={<ShellHeader brand={{ name: 'Acme' }} />}
  nav={<SideNav items={items} />}
>
  <h1>Dashboard</h1>
</AppShell>
```

### Controlled open

```tsx
const [open, setOpen] = useSignalState(false)

<AppShell header={header} nav={nav} open={open.value} onOpenChange={setOpen}>
  …
</AppShell>
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-shell-aside-inline-size`
- `--cascivo-shell-panel-inline-size`
- `--cascivo-motion-emphasis`
- `--cascivo-z-raised`
- `--cascivo-z-overlay`
- `--cascivo-color-foreground`
- `--cascivo-color-background`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `none`
- **Keyboard:** Escape

## Dependencies

- `@cascivo/core`

## Tags

shell, layout, sidebar, navigation, drawer, responsive, sticky

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# AspectRatio

Constrains content to a fixed width-to-height ratio

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add aspect-ratio
```

Or use it from the prebuilt package without copying:

```tsx
import { AspectRatio } from '@cascivo/react'
```

## Category

`layout`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `ratio` | `number` | no | `16 / 9` | Width-to-height ratio applied via the CSS aspect-ratio property |
| `children` | `ReactNode` | no | — | Content to fill the ratio box (typically an image, video, or iframe) |

## Examples

### Image at 16:9

```tsx
<AspectRatio ratio={16 / 9}>
  <img src="/cover.jpg" alt="Cover" />
</AspectRatio>
```

### Square

```tsx
<AspectRatio ratio={1}>
  <img src="/avatar.jpg" alt="Avatar" />
</AspectRatio>
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-aspect-ratio`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `none`

## Dependencies

- `@cascivo/core`

## Tags

layout, ratio, image, video, responsive

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Avatar

Displays a user image with initials fallback

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add avatar
```

Or use it from the prebuilt package without copying:

```tsx
import { Avatar } from '@cascivo/react'
```

## Category

`display`

## Sizes

- `xs`
- `sm`
- `md`
- `lg`
- `xl`

## States

- `loading`
- `loaded`
- `error`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `src` | `string` | no | — | Image source URL. |
| `alt` | `string` | no | `` | Alternative text describing the image. |
| `name` | `string` | no | — | Full name — used to derive initials for the fallback and as the accessible label. |
| `fallback` | `string` | no | — | Explicit fallback text (initials/glyph); overrides initials derived from name. |
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | no | `md` | Visual size of the component (e.g. 'sm', 'md', 'lg'). |
| `status` | `'online' \| 'offline' \| 'busy'` | no | — | Status state. |

## Examples

### Image

```tsx
<Avatar src="/jane.jpg" alt="Jane Doe" />
```

### Initials from name

Derives initials automatically; also sets the accessible label.

```tsx
<Avatar name="Ada Lovelace" /> // renders "AL"
```

### Explicit fallback

```tsx
<Avatar fallback="JD" alt="Jane Doe" />
```

### With status

```tsx
<Avatar name="Jane Doe" status="online" />
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-color-accent-subtle`
- `--cascivo-color-success`
- `--cascivo-color-destructive`
- `--cascivo-radius-full`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `img`

## Dependencies

- `@cascivo/core`

## Tags

user, profile, image

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# AvatarGroup

Overlapping stack of avatars with a max cap and an i18n-labelled +N overflow chip

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add avatar-group
```

Or use it from the prebuilt package without copying:

```tsx
import { AvatarGroup } from '@cascivo/react'
```

## Category

`display`

## States

- `default`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `max` | `number` | no | — | Cap the number of visible avatars |
| `total` | `number` | no | — | Override the total count used for the +N chip |
| `spacing` | `'sm' \| 'md' \| 'lg'` | no | `md` | Spacing between items. |
| `isGrid` | `boolean` | no | `false` | When true, lays the avatars out in a grid instead of an overlapping stack. |
| `labels` | `AvatarGroupLabels` | no | — | Overrides for the component’s user-visible strings (i18n). |

## Examples

### Basic

```tsx
<AvatarGroup><Avatar fallback="A" /><Avatar fallback="B" /><Avatar fallback="C" /></AvatarGroup>
```

### With max

```tsx
<AvatarGroup max={3}>{users.map((u) => <Avatar key={u.id} src={u.src} alt={u.name} />)}</AvatarGroup>
```

### Grid

```tsx
<AvatarGroup isGrid max={8}>{avatars}</AvatarGroup>
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-color-surface`
- `--cascivo-color-text-muted`
- `--cascivo-space-2`
- `--cascivo-text-xs`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `group`

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

avatar, group, stack, overflow, display

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Badge

Small status label or category indicator

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add badge
```

Or use it from the prebuilt package without copying:

```tsx
import { Badge } from '@cascivo/react'
```

## Category

`display`

## Variants

- `default`
- `secondary`
- `success`
- `warning`
- `destructive`
- `outline`

## Sizes

- `sm`
- `md`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `variant` | `'default' \| 'secondary' \| 'success' \| 'warning' \| 'destructive' \| 'outline'` | no | `default` | Severity tone. Accepts the catalog-wide `Tone` vocabulary (`neutral \| info \| success \| warning \| danger`) plus Badge's historical spellings (`default` → neutral, `error`/`destructive` → danger), and two values that carry no tone at all: `secondary` (muted fill) and `outline` (border only). |
| `size` | `'sm' \| 'md'` | no | `md` | Visual size of the component (e.g. 'sm', 'md', 'lg'). |

## Examples

### Default

```tsx
<Badge>New</Badge>
```

### Success

```tsx
<Badge variant="success">Active</Badge>
```

### Destructive

```tsx
<Badge variant="destructive">Deprecated</Badge>
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-font-sans`
- `--cascivo-font-medium`
- `--cascivo-radius-badge`
- `--cascivo-space-1`
- `--cascivo-space-2`
- `--cascivo-space-3`
- `--cascivo-text-xs`
- `--cascivo-leading-normal`
- `--cascivo-color-accent`
- `--cascivo-color-text-on-accent`
- `--cascivo-color-bg-subtle`
- `--cascivo-color-text`
- `--cascivo-color-border`
- `--cascivo-color-border-strong`
- `--cascivo-color-success-subtle`
- `--cascivo-color-success-foreground`
- `--cascivo-color-warning-subtle`
- `--cascivo-color-warning-foreground`
- `--cascivo-color-destructive-subtle`
- `--cascivo-color-destructive-foreground`
- `--cascivo-color-primary`
- `--cascivo-color-primary-content`
- `--cascivo-color-info`
- `--cascivo-color-info-content`
- `--cascivo-color-error`
- `--cascivo-color-error-content`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `status`

## Dependencies

- `@cascivo/core`

## Tags

label, status, tag

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# App Shell

Two-column layout with collapsible sidebar, nav links, and content area.

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add block/app-shell
```

_Copy-paste only — `App Shell` is not exported from `@cascivo/react`. Run the command above to own the source, or compose it from the exported primitives (`Flex`, `Grid`, `Heading`, …)._

## Category

`shell`

## Props

_No props._

## Dependencies

- `@cascivo/react`

## Tags

shell, layout, sidebar, navigation, responsive

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Login Form

Email + password login with remember-me checkbox and forgot-password link.

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add block/auth-login
```

_Copy-paste only — `Login Form` is not exported from `@cascivo/react`. Run the command above to own the source, or compose it from the exported primitives (`Flex`, `Grid`, `Heading`, …)._

## Category

`auth`

## Props

_No props._

## Dependencies

- `@cascivo/react`

## Tags

auth, login, form, email, password

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Sign Up Form

Full-name, email, password, confirm-password sign-up form with terms checkbox.

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add block/auth-signup
```

_Copy-paste only — `Sign Up Form` is not exported from `@cascivo/react`. Run the command above to own the source, or compose it from the exported primitives (`Flex`, `Grid`, `Heading`, …)._

## Category

`auth`

## Props

_No props._

## Dependencies

- `@cascivo/react`

## Tags

auth, signup, register, form

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# ConsoleApp

Carbon-parity console shell: ShellHeader + icon-rail SideNav + HeaderPanel notifications/switcher + collapsible aside + main content.

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add block/console-app
```

_Copy-paste only — `ConsoleApp` is not exported from `@cascivo/react`. Run the command above to own the source, or compose it from the exported primitives (`Flex`, `Grid`, `Heading`, …)._

## Category

`display`

## Props

_No props._

## Examples

### Default

Full console shell demo

```tsx
<ConsoleApp />
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-shell-header-block-size`
- `--cascivo-shell-panel-inline-size`
- `--cascivo-shell-aside-inline-size`
- `--cascivo-color-border`
- `--cascivo-color-surface`
- `--cascivo-color-scrim`
- `--cascivo-motion-enter`
- `--cascivo-motion-exit`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `generic`
- **Keyboard:** Escape, Tab

## Dependencies

- `@cascivo/react`
- `@cascivo/icons`

## Tags

block, console, shell, navigation, carbon-parity

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# DashboardCharts

Dashboard layout with KPI tiles, line chart, bar chart, and pie chart.

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add block/dashboard-charts
```

_Copy-paste only — `DashboardCharts` is not exported from `@cascivo/react`. Run the command above to own the source, or compose it from the exported primitives (`Flex`, `Grid`, `Heading`, …)._

## Category

`display`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `className` | `string` | no | — | Additional CSS class names merged onto the root DashboardLayout element. |

## Examples

### Default

Charts dashboard demo

```tsx
<DashboardCharts />
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `generic`

## Dependencies

- `@cascivo/charts`
- `@cascivo/react`

## Tags

block, dashboard, charts, kpi

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Dashboard Overview

Welcome header with four KPI stat cards (revenue, users, orders, conversion).

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add block/dashboard-overview
```

_Copy-paste only — `Dashboard Overview` is not exported from `@cascivo/react`. Run the command above to own the source, or compose it from the exported primitives (`Flex`, `Grid`, `Heading`, …)._

## Category

`dashboard`

## Props

_No props._

## Dependencies

- `@cascivo/react`

## Tags

dashboard, stats, kpi, cards, overview

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Dashboard Table

Searchable, sortable, paginated data table with export button.

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add block/dashboard-table
```

_Copy-paste only — `Dashboard Table` is not exported from `@cascivo/react`. Run the command above to own the source, or compose it from the exported primitives (`Flex`, `Grid`, `Heading`, …)._

## Category

`dashboard`

## Props

_No props._

## Dependencies

- `@cascivo/react`

## Tags

dashboard, table, data, search, sort, pagination

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# EmptyDashboard

Dashboard page showing an empty state with a call-to-action button.

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add block/empty-dashboard
```

_Copy-paste only — `EmptyDashboard` is not exported from `@cascivo/react`. Run the command above to own the source, or compose it from the exported primitives (`Flex`, `Grid`, `Heading`, …)._

## Category

`display`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `onCreateItem` | `() => void` | no | — | Create item button handler |

## Examples

### Default

Empty dashboard

```tsx
<EmptyDashboard />
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `generic`

## Dependencies

- `@cascivo/react`

## Tags

block, dashboard, empty-state, page

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# FAQ Accordion

Frequently-asked-questions section composed from the Accordion component, with a centered, readable measure.

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add block/faq
```

_Copy-paste only — `FAQ Accordion` is not exported from `@cascivo/react`. Run the command above to own the source, or compose it from the exported primitives (`Flex`, `Grid`, `Heading`, …)._

## Category

`marketing`

## Props

_No props._

## Dependencies

- `@cascivo/react`

## Tags

marketing, faq, accordion, questions

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# LoginPage

Authentication login page with email and password form.

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add block/login-page
```

_Copy-paste only — `LoginPage` is not exported from `@cascivo/react`. Run the command above to own the source, or compose it from the exported primitives (`Flex`, `Grid`, `Heading`, …)._

## Category

`display`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `onSubmit` | `(values: LoginValues) => void` | no | — | Called with valid form values on submit |

## Examples

### Default

Login page

```tsx
<LoginPage />
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `generic`

## Dependencies

- `@cascivo/react`

## Tags

block, login, auth, form, page

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Feature Grid

Three-column responsive feature grid with icon, title, and description per cell.

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add block/marketing-features
```

_Copy-paste only — `Feature Grid` is not exported from `@cascivo/react`. Run the command above to own the source, or compose it from the exported primitives (`Flex`, `Grid`, `Heading`, …)._

## Category

`marketing`

## Props

_No props._

## Dependencies

- `@cascivo/react`

## Tags

marketing, features, grid, icons

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Hero Section

Full-width hero with headline, subtitle, CTA pair, and trust badges.

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add block/marketing-hero
```

_Copy-paste only — `Hero Section` is not exported from `@cascivo/react`. Run the command above to own the source, or compose it from the exported primitives (`Flex`, `Grid`, `Heading`, …)._

## Category

`marketing`

## Props

_No props._

## Dependencies

- `@cascivo/react`

## Tags

marketing, hero, landing, cta

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# NotificationCenter

A list of notification alerts with a mark-all-read action.

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add block/notification-center
```

_Copy-paste only — `NotificationCenter` is not exported from `@cascivo/react`. Run the command above to own the source, or compose it from the exported primitives (`Flex`, `Grid`, `Heading`, …)._

## Category

`display`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `notifications` | `Notification[]` | no | `demoNotifications` | Notification items to display |
| `onMarkAllRead` | `() => void` | no | — | Mark all read button handler |

## Examples

### Default

Notification center

```tsx
<NotificationCenter />
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `generic`

## Dependencies

- `@cascivo/react`

## Tags

block, notifications, alerts

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# PageWithBreadcrumb

A centered content page with a breadcrumb navigation and page header.

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add block/page-with-breadcrumb
```

_Copy-paste only — `PageWithBreadcrumb` is not exported from `@cascivo/react`. Run the command above to own the source, or compose it from the exported primitives (`Flex`, `Grid`, `Heading`, …)._

## Category

`display`

## Props

_No props._

## Examples

### Default

Page with breadcrumb

```tsx
<PageWithBreadcrumb />
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `generic`

## Dependencies

- `@cascivo/react`

## Tags

block, breadcrumb, page, navigation

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Pricing Tiers

Responsive three-tier pricing section composed from Card, Badge, and Button, with a highlighted featured plan.

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add block/pricing
```

_Copy-paste only — `Pricing Tiers` is not exported from `@cascivo/react`. Run the command above to own the source, or compose it from the exported primitives (`Flex`, `Grid`, `Heading`, …)._

## Category

`marketing`

## Props

_No props._

## Dependencies

- `@cascivo/react`

## Tags

marketing, pricing, plans, cards

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# SettingsFormPage

Settings page with profile form inside a two-column settings layout.

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add block/settings-form-page
```

_Copy-paste only — `SettingsFormPage` is not exported from `@cascivo/react`. Run the command above to own the source, or compose it from the exported primitives (`Flex`, `Grid`, `Heading`, …)._

## Category

`display`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `onSave` | `(values: SettingsValues) => void` | no | — | Called with valid form values on submit |

## Examples

### Default

Settings form page

```tsx
<SettingsFormPage />
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `generic`

## Dependencies

- `@cascivo/react`

## Tags

block, settings, form, page

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Settings — Profile

Two-section settings form: personal info fields + preference toggles.

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add block/settings-profile
```

_Copy-paste only — `Settings — Profile` is not exported from `@cascivo/react`. Run the command above to own the source, or compose it from the exported primitives (`Flex`, `Grid`, `Heading`, …)._

## Category

`shell`

## Props

_No props._

## Dependencies

- `@cascivo/react`

## Tags

settings, profile, form, toggles, preferences

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# SidebarApp

Full app shell with collapsible side navigation and top header.

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add block/sidebar-app
```

_Copy-paste only — `SidebarApp` is not exported from `@cascivo/react`. Run the command above to own the source, or compose it from the exported primitives (`Flex`, `Grid`, `Heading`, …)._

## Category

`display`

## Props

_No props._

## Examples

### Default

App with sidebar navigation

```tsx
<SidebarApp />
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `generic`

## Dependencies

- `@cascivo/react`

## Tags

block, sidebar, navigation, app-shell

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Site Footer

Multi-column site footer composed from Link and Separator, with a brand blurb, link columns, and a legal row.

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add block/site-footer
```

_Copy-paste only — `Site Footer` is not exported from `@cascivo/react`. Run the command above to own the source, or compose it from the exported primitives (`Flex`, `Grid`, `Heading`, …)._

## Category

`marketing`

## Props

_No props._

## Dependencies

- `@cascivo/react`

## Tags

marketing, footer, navigation, links

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# StatsCards

Grid of KPI stat cards with trend badges.

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add block/stats-cards
```

_Copy-paste only — `StatsCards` is not exported from `@cascivo/react`. Run the command above to own the source, or compose it from the exported primitives (`Flex`, `Grid`, `Heading`, …)._

## Category

`display`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `stats` | `Stat[]` | no | `demoStats` | KPI stat data |

## Examples

### Default

Demo KPI stats

```tsx
<StatsCards />
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `generic`

## Dependencies

- `@cascivo/react`

## Tags

block, stats, kpi, cards

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Testimonials

Responsive testimonial grid composed from Card and Avatar, with a quote and attribution per card.

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add block/testimonials
```

_Copy-paste only — `Testimonials` is not exported from `@cascivo/react`. Run the command above to own the source, or compose it from the exported primitives (`Flex`, `Grid`, `Heading`, …)._

## Category

`marketing`

## Props

_No props._

## Dependencies

- `@cascivo/react`

## Tags

marketing, testimonials, social-proof, cards

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# UsersTablePage

Full users management page with table, search, and invite action.

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add block/users-table-page
```

_Copy-paste only — `UsersTablePage` is not exported from `@cascivo/react`. Run the command above to own the source, or compose it from the exported primitives (`Flex`, `Grid`, `Heading`, …)._

## Category

`display`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `users` | `User[]` | no | `demoUsers` | User data |
| `onInvite` | `() => void` | no | — | Invite button handler |

## Examples

### Default

Demo users table

```tsx
<UsersTablePage />
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `generic`

## Dependencies

- `@cascivo/react`

## Tags

block, users, table, page

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Blockquote

Quoted passage with optional attribution footer

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add blockquote
```

Or use it from the prebuilt package without copying:

```tsx
import { Blockquote } from '@cascivo/react'
```

## Category

`display`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `cite` | `string` | no | `undefined` | URL of the quote’s source (sets the HTML cite attribute). |

## Examples

### Default

```tsx
<Blockquote>Less, but better.</Blockquote>
```

### With attribution

Attribution renders as <footer><cite>

```tsx
<Blockquote cite="Dieter Rams">Less, but better.</Blockquote>
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-color-border-strong`
- `--cascivo-color-text`
- `--cascivo-color-text-subtle`
- `--cascivo-font-sans`
- `--cascivo-font-medium`
- `--cascivo-leading-relaxed`
- `--cascivo-text-sm`
- `--cascivo-text-base`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `blockquote`

## Dependencies

- `@cascivo/core`

## Tags

typography, quote, blockquote, citation

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# BottomSheet

Mobile bottom sheet with drag-to-resize detents, velocity-projected snapping, and drag-to-dismiss

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add bottom-sheet
```

Or use it from the prebuilt package without copying:

```tsx
import { BottomSheet } from '@cascivo/react'
```

## Category

`overlay`

## States

- `open`
- `closed`
- `dragging`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `open` | `boolean` | no | — | Whether the component is open (controlled). |
| `defaultOpen` | `boolean` | no | — | Whether the component is open on first render (uncontrolled). |
| `onOpenChange` | `(open: boolean) => void` | no | — | Called with the next open state when it changes. |
| `snapPoints` | `number[]` | no | `[0.5, 0.92]` | Detent heights as ascending fractions of the viewport (0–1) |
| `activeSnap` | `number` | no | — | The controlled snap-point index. |
| `defaultSnap` | `number` | no | `0` | The initial snap-point index when uncontrolled. |
| `onSnapChange` | `(index: number) => void` | no | — | Called with the new snap-point index when it changes. |
| `title` | `React.ReactNode` | no | — | Title text for the component. |
| `description` | `React.ReactNode` | no | — | Supporting description text. |
| `children` | `React.ReactNode` | no | — | Content rendered inside the component. |
| `labels` | `{ close?: string; handle?: string }` | no | — | Overrides for the component’s user-visible strings (i18n). |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |

## Examples

### Basic

```tsx
<BottomSheet open={isOpen} onOpenChange={setIsOpen} title="Filters">
  <FilterForm />
</BottomSheet>
```

### Custom detents

Snaps between three detents by dragging the handle; opens at half height.

```tsx
<BottomSheet defaultOpen snapPoints={[0.25, 0.5, 0.9]} defaultSnap={1} title="Nearby">
  <PlacesList />
</BottomSheet>
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-surface`
- `--cascivo-color-border`
- `--cascivo-radius-overlay`
- `--cascivo-shadow-overlay`
- `--cascivo-motion-enter`
- `--cascivo-motion-exit`
- `--cascivo-target-min-coarse`
- `--cascivo-z-overlay`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `dialog`
- **Keyboard:** Escape, Tab, Shift+Tab

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

overlay, sheet, bottom-sheet, mobile, drag, detent, gesture

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Logo

The cascivo mark and its sanctioned lockups, as inline SVG

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add brand/logo
```

Or use it from the prebuilt package without copying:

```tsx
import { Logo } from '@cascivo/react'
```

## Category

`display`

## Variants

- `mark`
- `mark-accent`
- `horizontal`
- `stacked`
- `nav`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `variant` | `'mark' \| 'mark-accent' \| 'horizontal' \| 'stacked' \| 'nav'` | no | `mark` | `mark` and `mark-accent` render the square alone; `horizontal`, `stacked` and `nav` add the wordmark. `nav` is the only lockup permitted below 24px. |
| `size` | `number` | no | `18 for `nav`, 32 otherwise` | Mark height in px. Clamped to a 16px floor — below that the notch closes optically. |

## Examples

### Mark

```tsx
<Logo />
```

### Two colour

The accent fills the notch. Decoration — the mark is complete without it.

```tsx
<Logo variant="mark-accent" />
```

### Horizontal lockup

```tsx
<Logo variant="horizontal" />
```

### Nav lockup

18px mark, 16px wordmark, 10px gap — the only lockup allowed below 24px.

```tsx
<Logo variant="nav" />
```

### Stacked

```tsx
<Logo variant="stacked" size={48} />
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-color-accent`
- `--cascivo-font-display`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `img`

## Dependencies

- `@cascivo/core`

## Tags

logo, brand, mark, wordmark, lockup, identity

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Breadcrumb

Shows the current page location within a navigation hierarchy

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add breadcrumb
```

Or use it from the prebuilt package without copying:

```tsx
import { Breadcrumb } from '@cascivo/react'
```

## Category

`navigation`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `items` | `{ label: string; href?: string }[]` | yes | — | The items to render. |
| `maxVisible` | `number` | no | — | When items exceed this count, collapse to the first item, an ellipsis, and the trailing items |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |
| `label` | `string` | no | — | Alias of `ariaLabel` — the same invisible accessible name under the other spelling. Neither is deprecated. Not rendered — screen readers only. |
| `ariaLabel` | `string` | no | `Breadcrumb` | Accessible label for the component. Not rendered — screen readers only. |

## Examples

### Basic

```tsx
<Breadcrumb items={[{ label: 'Home', href: '/' }, { label: 'Docs', href: '/docs' }, { label: 'Breadcrumb' }]} />
```

### Collapsed

Long trails collapse to the first item, an ellipsis, and the trailing items.

```tsx
<Breadcrumb maxVisible={3} items={[{ label: 'Home', href: '/' }, { label: 'Docs', href: '/docs' }, { label: 'Components', href: '/docs/components' }, { label: 'Breadcrumb' }]} />
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-color-text`
- `--cascivo-color-text-muted`
- `--cascivo-color-text-subtle`
- `--cascivo-radius-sm`
- `--cascivo-focus-ring`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `navigation`
- **Keyboard:** Tab, Enter

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

breadcrumb, navigation, hierarchy

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Button

Triggers an action or event

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add button
```

Or use it from the prebuilt package without copying:

```tsx
import { Button } from '@cascivo/react'
```

## Category

`inputs`

## Variants

- `primary`
- `secondary`
- `ghost`
- `destructive`

## Sizes

- `sm`
- `md`
- `lg`

## States

- `idle`
- `loading`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `variant` | `'primary' \| 'secondary' \| 'ghost' \| 'destructive'` | no | `primary` | `primary` for the main action, `secondary` for a supporting one, `ghost` for a borderless action in dense UI, `destructive` for anything that deletes. |
| `size` | `'sm' \| 'md' \| 'lg'` | no | `md` | Visual size of the component (e.g. 'sm', 'md', 'lg'). |
| `loading` | `boolean` | no | `false` | When true, shows a loading state. |
| `disabled` | `boolean` | no | `false` | When true, disables the control and removes it from the tab order. |
| `asChild` | `boolean` | no | `false` | When true, renders the child element as the root via Slot, merging props (polymorphic rendering). |
| `onClick` | `React.MouseEventHandler<HTMLButtonElement>` | no | — | Called when the element is clicked. |

## Examples

### Primary

```tsx
<Button>Click me</Button>
```

### Loading

```tsx
<Button loading>Saving…</Button>
```

### Destructive

```tsx
<Button variant="destructive">Delete</Button>
```

### As link

Render button styling on a real anchor (keeps middle-click / open-in-new-tab).

```tsx
<Button asChild><a href="/pricing">View pricing</a></Button>
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-button-primary-bg`
- `--cascivo-button-primary-bg-hover`
- `--cascivo-button-primary-bg-active`
- `--cascivo-button-secondary-bg`
- `--cascivo-button-secondary-bg-hover`
- `--cascivo-button-ghost-bg`
- `--cascivo-button-ghost-bg-hover`
- `--cascivo-button-destructive-bg`
- `--cascivo-button-destructive-bg-hover`
- `--cascivo-button-radius`
- `--cascivo-color-accent`
- `--cascivo-color-accent-hover`
- `--cascivo-color-accent-active`
- `--cascivo-color-text-on-accent`
- `--cascivo-color-destructive`
- `--cascivo-radius-button`
- `--cascivo-focus-ring`
- `--cascivo-disabled-opacity`
- `--cascivo-text-ui`
- `--cascivo-text-body`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `button`
- **Keyboard:** Enter, Space

## Dependencies

- `@cascivo/core`

## Tags

action, form, interactive

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# ButtonGroup

Visually joins a set of related buttons into a single segmented control

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add button-group
```

Or use it from the prebuilt package without copying:

```tsx
import { ButtonGroup } from '@cascivo/react'
```

## Category

`inputs`

## Sizes

- `sm`
- `md`
- `lg`

## States

- `idle`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `orientation` | `'horizontal' \| 'vertical'` | no | `horizontal` | Axis the buttons flow along: `horizontal` puts them in a row, `vertical` stacks them in a column. The seams between them are collapsed either way. |
| `size` | `'sm' \| 'md' \| 'lg'` | no | `md` | Visual size of the component (e.g. 'sm', 'md', 'lg'). |
| `roving` | `boolean` | no | `false` | When true, uses roving tabindex so arrow keys move focus between buttons. |
| `loop` | `boolean` | no | `false` | When true, navigation wraps around from end to start. |
| `aria-label` | `string` | no | — | Accessible label used when no visible label is present. |
| `aria-labelledby` | `string` | no | — | Id of the element that labels this component. |

## Examples

### Joined actions

```tsx
<ButtonGroup aria-label="Text alignment"><Button>Left</Button><Button>Center</Button><Button>Right</Button></ButtonGroup>
```

### Vertical with roving focus

```tsx
<ButtonGroup orientation="vertical" roving aria-label="View"><Button>List</Button><Button>Grid</Button></ButtonGroup>
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-button-radius`
- `--cascivo-radius-control`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `group`
- **Keyboard:** ArrowRight, ArrowLeft, ArrowUp, ArrowDown, Home, End

## Dependencies

- `@cascivo/core`

## Tags

action, segmented, toolbar, layout

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Calendar

An accessible standalone month-grid date picker.

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add calendar
```

Or use it from the prebuilt package without copying:

```tsx
import { Calendar } from '@cascivo/react'
```

## Category

`inputs`

## Sizes

- `sm`
- `md`
- `lg`

## States

- `default`
- `selected`
- `today`
- `disabled`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `isInRange` | `(date: Date) => boolean` | no | — | Highlight predicate for range previews (used by DateRangePicker). |
| `isRangeStart` | `(date: Date) => boolean` | no | — | Predicate marking the range's start date for styling. |
| `isRangeEnd` | `(date: Date) => boolean` | no | — | Predicate marking the range's end date for styling. |
| `onDayHover` | `(date: Date \| null) => void` | no | — | Called with the hovered day (or null on leave) to drive range previews. |
| `value` | `Date \| null` | no | — | Controlled selected date |
| `defaultValue` | `Date` | no | — | Uncontrolled initial selected date |
| `onValueChange` | `(date: Date) => void` | no | — | Called when a day is selected |
| `min` | `Date` | no | — | Earliest selectable date |
| `max` | `Date` | no | — | Latest selectable date |
| `disabled` | `(date: Date) => boolean` | no | — | Predicate to disable individual days |
| `locale` | `string` | no | — | BCP-47 locale; defaults to the current i18n locale |
| `size` | `'sm' \| 'md' \| 'lg'` | no | `md` | Grid cell size |
| `labels` | `CalendarLabels` | no | — | i18n label overrides for the nav buttons |
| `month` | `number` | no | — | Controlled view month (0-11) |
| `year` | `number` | no | — | Controlled view year |
| `onViewChange` | `(view: { month: number; year: number }) => void` | no | — | Called when the visible month changes |
| `hideNav` | `boolean` | no | `false` | Hides the prev/next nav so a parent can drive navigation |
| `showToday` | `boolean` | no | `false` | When true, shows a button that jumps the view to the current month and focuses today. |
| `showWeekNumbers` | `boolean` | no | `false` | When true, prefixes each row with its ISO-8601 week number. |
| `ariaLabel` | `string` | no | — | Accessible name for the grid. Defaults to the visible month label. Calendar has no visible label slot — the month heading is its own — so `label` and `ariaLabel` are aliases for the same invisible name. Not rendered — screen readers only. |
| `label` | `string` | no | — | Alias for `ariaLabel`; both set the grid’s invisible accessible name. Not rendered — screen readers only. |

## Examples

### Basic

Uncontrolled calendar

```tsx
<Calendar defaultValue={new Date(Date.UTC(2024, 5, 15))} />
```

### Constrained

Limits the selectable range

```tsx
<Calendar min={new Date(Date.UTC(2024, 5, 1))} max={new Date(Date.UTC(2024, 5, 30))} />
```

### Disabled weekends

Predicate disables individual days

```tsx
<Calendar disabled={(d) => [0, 6].includes(d.getUTCDay())} />
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-accent-text`
- `--cascivo-calendar-bg`
- `--cascivo-calendar-radius`
- `--cascivo-calendar-cell-size`
- `--cascivo-calendar-day-selected-bg`
- `--cascivo-calendar-day-selected-fg`
- `--cascivo-calendar-day-today-color`
- `--cascivo-calendar-range-bg`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `grid`
- **Keyboard:** ArrowLeft, ArrowRight, ArrowUp, ArrowDown, Home, End, PageUp, PageDown, Enter, Space

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

calendar, date, month, grid, picker, input

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Card

Container for grouping related content

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add card
```

Or use it from the prebuilt package without copying:

```tsx
import { Card } from '@cascivo/react'
```

## Category

`display`

## Variants

- `default`
- `outlined`
- `elevated`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `actions` | `ReactNode` | no | — | CardHeader only — trailing content pinned to the inline-end (overflow menu, badge, link). The header is a column by default, so `justify-content: space-between` alone does nothing; this is how you get the title-left / action-right dashboard card. |
| `variant` | `'default' \| 'outlined' \| 'elevated'` | no | `default` | `default` draws a 1px border, `outlined` a heavier one, `elevated` drops the border for a shadow. |
| `padding` | `'none' \| 'sm' \| 'md' \| 'lg'` | no | `md` | Inner padding of the CARD BOX. ⚠ `padding="none"` deliberately does NOT strip the padding from CardHeader/CardContent/CardFooter — those keep their own. It means "let a flush child (a LogViewer, an image, an edge-to-edge table) reach the card's edge"; zeroing both put the title flush against the border and made the mode unusable with the composition it exists for. For an edge-to-edge table, skip CardContent and pass the table as a direct child. |
| `ai` | `boolean \| 'generating'` | no | `false` | AI presence: `true` gives the surface an AI-tinted edge and a soft aura, marking AI-generated content; `'generating'` adds a pulsing inner glow while AI is still producing it (stops under reduced motion). Visual only — pair it with an AiBadge so the provenance is also text. |

## Examples

### Basic card

```tsx
<Card>
  <CardHeader><CardTitle>Title</CardTitle></CardHeader>
  <CardContent>Content here</CardContent>
</Card>
```

### AI-generated content

```tsx
<Card ai>
  <CardHeader actions={<AiBadge />}><CardTitle>Summary</CardTitle></CardHeader>
  <CardContent>Revenue grew 12% quarter over quarter.</CardContent>
</Card>
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-color-surface`
- `--cascivo-color-border`
- `--cascivo-radius-card`
- `--cascivo-shadow-md`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `region`

## Dependencies

- `@cascivo/core`

## Tags

container, layout, surface, ai

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Carousel

Scroll-snap slide deck with previous/next controls and dot indicators

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add carousel
```

Or use it from the prebuilt package without copying:

```tsx
import { Carousel } from '@cascivo/react'
```

## Category

`display`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `labels` | `CarouselLabels` | no | — | Overrides for the component’s user-visible strings (i18n). |
| `children` | `ReactNode` | no | — | Slides as children |
| `slides` | `ReactNode[]` | no | — | Slides as an array |
| `index` | `number` | no | — | Controlled active index |
| `defaultIndex` | `number` | no | `0` | The initial slide index when uncontrolled. |
| `onIndexChange` | `(index: number) => void` | no | — | Called with the new slide index when it changes. |
| `loop` | `boolean` | no | `false` | When true, navigation wraps around from end to start. |
| `autoplay` | `number` | no | — | Milliseconds between automatic advances. Omit or set 0 to leave rotation off. Pauses on hover, on focus within, while the tab is hidden and under prefers-reduced-motion, and always renders a play/pause control. |

## Examples

### Basic

```tsx
<Carousel>
  <img src="/1.jpg" alt="" />
  <img src="/2.jpg" alt="" />
</Carousel>
```

### Looping with array

```tsx
<Carousel loop slides={[<Slide1 />, <Slide2 />, <Slide3 />]} />
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-color-accent`
- `--cascivo-color-surface`
- `--cascivo-color-border`
- `--cascivo-color-border-strong`
- `--cascivo-radius-md`
- `--cascivo-radius-full`
- `--cascivo-focus-ring`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `group`
- **Keyboard:** ArrowLeft, ArrowRight, Home, End

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

slider, gallery, slideshow, deck, scroll-snap

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# ChainOfThought

The steps an AI agent takes — searching, reading, calling tools — each with its status, and optional collapsible detail

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add chain-of-thought
```

Or use it from the prebuilt package without copying:

```tsx
import { ChainOfThought } from '@cascivo/react'
```

## Category

`display`

## States

- `pending`
- `active`
- `complete`
- `error`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `items` | `ChainOfThoughtItem[]` | yes | — | The steps, in order. Each has `id`, `title`, optional `description`, `status` (`pending \| active \| complete \| error`, plus the `current` / `upcoming` aliases), optional `detail` (collapsible content that turns the title into a toggle) and optional `icon`. |
| `labels` | `{ pending?: string; active?: string; complete?: string; error?: string }` | no | — | Overrides for the component’s user-visible strings (i18n) — the status text a screen reader hears after each step title. |

## Object types

### `ChainOfThoughtItem`

One step in the chain.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | `string` | yes | Stable key for the step. |
| `title` | `ReactNode` | yes | What the step does. |
| `description` | `ReactNode` | no | A secondary line under the title. |
| `status` | `ProgressInput` | no | `pending \| active \| complete \| error` (plus `current` / `upcoming`). Defaults to `pending`. |
| `detail` | `ReactNode` | no | Collapsible content; makes the title a disclosure toggle. |
| `icon` | `ReactNode` | no | Replaces the status glyph in the marker. |

## Examples

### Agent steps

```tsx
<ChainOfThought
  items={[
    { id: 'search', title: 'Searched the docs for "refund policy"', status: 'complete' },
    { id: 'read', title: 'Reading 3 pages', status: 'active' },
    { id: 'answer', title: 'Write the answer', status: 'pending' },
  ]}
/>
```

### With collapsible detail

```tsx
<ChainOfThought
  items={[
    {
      id: 'search',
      title: 'Searched the web',
      status: 'complete',
      detail: 'cascivo.com/docs · github.com/cascivo/cascivo · npmjs.com/package/@cascivo/react',
    },
    { id: 'fail', title: 'Fetch pricing page', description: 'The page returned 404.', status: 'error' },
  ]}
/>
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-color-ai`
- `--cascivo-color-text`
- `--cascivo-color-text-muted`
- `--cascivo-color-border`
- `--cascivo-color-success`
- `--cascivo-color-destructive`
- `--cascivo-focus-ring`
- `--cascivo-duration-loop-slow`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `list`
- **Keyboard:** Tab, Enter, Space

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

ai, agent, steps, chain-of-thought, reasoning, progress, tools

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# AreaChart

Area chart with optional stacking, multi-series support, and hover tooltip.

## Install

Ships in the `@cascivo/charts` package — install it (no copy-paste):

```sh
pnpm add @cascivo/charts
```

```tsx
import { AreaChart } from '@cascivo/charts'
import '@cascivo/charts/styles.css' // bundler: automatic. Needed only for no-bundler / SSR-externalised builds, where skipping it renders the screen-reader data-table fallback visibly
```

## Category

`chart`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `series` | `AreaChartSeries<Datum>[]` | yes | — | Array of data series |
| `x` | `(d: Datum) => number \| Date` | yes | — | X-value accessor. Return a number for a numeric axis or a Date for a time axis (ticks format as dates, parity with LineChart). This is a continuous scale — unlike BarChart, whose `x` returns a category `string` (band scale). For discrete categories, use BarChart. |
| `y` | `(d: Datum) => number` | yes | — | Y-value accessor, applied to every series unless a series sets its own `y`. One x-domain per chart, so `x` is chart-level only; give each series a `y` to plot different fields from one shared data row. |
| `title` | `string` | yes | — | Title text for the component. |
| `description` | `string` | no | — | Supporting description text. |
| `stacked` | `boolean` | no | — | Stack series areas |
| `curve` | `'linear' \| 'monotone' \| 'step' \| 'stepBefore' \| 'stepAfter' \| 'natural' \| 'basis' \| 'cardinal' \| 'catmullRom'` | no | `monotone` | Line/area interpolation curve. |
| `fill` | `'solid' \| 'gradient' \| 'pattern'` | no | `gradient for one non-stacked series, solid otherwise` | Area fill style — solid, a top→bottom gradient, or a pattern. A single non-stacked series defaults to `gradient` (a lone solid area reads as a heavy block); stacked and overlapping series default to `solid`. |
| `patternKind` | `'dots' \| 'lines' \| 'cross'` | no | — | Pattern motif when fill="pattern". |
| `width` | `number` | no | — | Fixed SVG width in px. ⚠ **Omit for a responsive chart** — the chart fills and tracks its container via a ResizeObserver; there is no correct pixel number in a responsive grid. A fixed width is clamped to the container (max-inline-size: 100%) so it can never overflow its card, but it also stops the chart growing. `useChartSize` is NOT needed for this — charts call it internally. |
| `height` | `number` | no | `300` | SVG height in px. Unlike `width`, height does NOT track the container — this is the knob you set to change the chart's aspect. |
| `xTicks` | `number` | no | `5` | Approximate number of ticks on the x-axis. |
| `yTicks` | `number` | no | `5` | Approximate number of ticks on the y-axis. |
| `legend` | `boolean` | no | — | Whether to show the legend. |
| `tooltip` | `boolean` | no | — | Enable hover/keyboard tooltip |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |
| `plain` | `boolean` | no | `false` | Marks only — no axes, grid lines, or legend. For micro/inline charts. |
| `annotations` | `Annotation[]` | no | — | Reference lines, shaded bands, and markers drawn over the plot (e.g. a target/threshold line). |
| `labels` | `boolean \| { format?: (v: number) => string; position?: string }` | no | — | Print each value as a label on the mark (collision-aware, decorative/aria-hidden). |
| `onSelect` | `(point: ChartPoint) => void` | no | — | Fired when a point is clicked or activated (Enter/Space) — for drill-down. |
| `brush` | `boolean` | no | `false` | Show a keyboard-operable Brush below the plot to subset the series to a window. |
| `dataZoom` | `boolean` | no | `false` | Show a DataZoom slider below the plot — a Brush whose body also pans the window. |
| `zoom` | `boolean` | no | `false` | Enable in-plot wheel/drag/keyboard zoom-pan (+/-/0) over the series index window, with a reset control and re-ticked axes. |
| `syncId` | `string` | no | — | Connect this chart to others sharing the same id — they mirror the zoom window and hovered x. |
| `tooltipMode` | `'item' \| 'axis'` | no | `item` | Tooltip trigger — item (nearest point) or axis (a crosshair + a shared tooltip listing every series at the hovered x). |
| `decimate` | `boolean \| { method?: 'lttb' \| 'minmax'; threshold?: number }` | no | — | Downsample dense non-stacked series before drawing (LTTB or min-max). Visual only — the fallback table keeps the full data. |
| `toolbox` | `boolean \| ToolboxOptions` | no | — | Render a keyboard-reachable toolbox — PNG/SVG export, a data-view table toggle, and restore (reset zoom). |
| `format` | `(value: number \| string \| Date) => string` | no | — | Format each X-axis tick label. |
| `secondAxis` | `{ label?: string; format?: (value: number) => string }` | no | — | Add a right-hand y-axis for series with `axis: 'right'` (non-stacked only). |

## Object types

### `AreaChartSeries`

One series. Pass via the `series` prop; set `type: 'line'` to draw it unfilled.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | `string` | yes | — |
| `label` | `string` | yes | — |
| `data` | `readonly Datum[]` | yes | — |
| `color` | `string` | no | Series colour. |
| `axis` | `'left' \| 'right'` | no | Which y-axis this series is measured against (ignored when `stacked`). |
| `y` | `(d: Datum) => number` | no | Per-series Y accessor. |

## Examples

### Basic area chart

```tsx
import { AreaChart } from '@cascivo/charts'

const series = [{ id: 'a', label: 'Revenue', data: [{x:1,y:10},{x:2,y:20}] }]
<AreaChart series={series} x={d => d.x} y={d => d.y} title="Revenue" />
```

### Multiple fields from one row (per-series y)

The chart-level x/y apply to every series. To plot two fields from the same rows, give each series its own y — no need to reshape the data into separate {x,y} arrays.

```tsx
import { AreaChart } from '@cascivo/charts'

const rows = [{ t: 0, requests: 100, errors: 5 }, { t: 1, requests: 120, errors: 9 }]
<AreaChart
  title="Traffic"
  series={[
    { id: 'req', label: 'Requests', data: rows, y: d => d.requests },
    { id: 'err', label: 'Errors', data: rows, y: d => d.errors },
  ]}
  x={d => d.t}
  y={d => d.requests}
/>
```

### Time axis (Date x)

Return a Date from x for a time axis — ticks render as dates (e.g. "Jul 10"), no need to encode day-of-month as an integer.

```tsx
import { AreaChart } from '@cascivo/charts'

const data = [
  { day: new Date('2026-07-10'), y: 120 },
  { day: new Date('2026-07-20'), y: 180 },
  { day: new Date('2026-07-30'), y: 150 },
]
<AreaChart
  title="Daily signups"
  series={[{ id: 's', label: 'Signups', data }]}
  x={d => d.day}
  y={d => d.y}
/>
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-chart-1`
- `--cascivo-chart-2`
- `--cascivo-chart-3`
- `--cascivo-chart-4`
- `--cascivo-chart-5`
- `--cascivo-chart-6`
- `--cascivo-chart-7`
- `--cascivo-chart-8`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `img`
- **Keyboard:** Tab (focus chart), ArrowLeft/ArrowRight (navigate points), Home/End (first/last point), Escape (clear focus)

## Dependencies

- `@cascivo/charts`

## Tags

chart, area, data-viz

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# BarChart

Bar chart with vertical/horizontal orientation, grouped or stacked modes, and multi-series support.

## Install

Ships in the `@cascivo/charts` package — install it (no copy-paste):

```sh
pnpm add @cascivo/charts
```

```tsx
import { BarChart } from '@cascivo/charts'
import '@cascivo/charts/styles.css' // bundler: automatic. Needed only for no-bundler / SSR-externalised builds, where skipping it renders the screen-reader data-table fallback visibly
```

## Category

`chart`

## Variants

- `grouped`
- `stacked`
- `percent`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `series` | `BarChartSeries<Datum>[]` | yes | — | Series array. Each series accepts an optional `color` (any CSS color) overriding the positional palette for that series/stacked layer. |
| `x` | `(d: Datum) => string` | yes | — | Accessor returning the **category label** for a datum. BarChart uses a categorical **band** scale, so `x` returns a `string` — this differs from LineChart/AreaChart, whose `x` returns `number \| Date` for a continuous/time scale. For a time-based bar chart, format the date to a label in the accessor (e.g. `x={(d) => d.day.toLocaleDateString()}`). For continuous or time-series data, prefer LineChart/AreaChart. |
| `y` | `(d: Datum) => number` | yes | — | Accessor returning the numeric value for a datum, applied to every series unless a series sets its own `y`. One category (x) domain per chart; give each series a `y` to plot different fields from one shared data row. |
| `title` | `string` | yes | — | Title text for the component. |
| `description` | `string` | no | — | Supporting description text. |
| `orientation` | `'vertical' \| 'horizontal'` | no | `vertical` | Direction the bars grow. `vertical` puts the categories on the x-axis and grows bars upward (columns); `horizontal` puts them on the y-axis and grows bars rightward — the better choice for long category names. |
| `mode` | `'grouped' \| 'stacked' \| 'percent'` | no | `grouped` | 'percent' stacks each category and normalizes it to 100%. |
| `width` | `number` | no | — | Fixed SVG width in px. ⚠ **Omit for a responsive chart** — the chart fills and tracks its container via a ResizeObserver; there is no correct pixel number in a responsive grid. A fixed width is clamped to the container (max-inline-size: 100%) so it can never overflow its card, but it also stops the chart growing. `useChartSize` is NOT needed for this — charts call it internally. |
| `height` | `number` | no | `300` | SVG height in px. Unlike `width`, height does NOT track the container — this is the knob you set to change the chart's aspect. |
| `valueAxisTicks` | `number` | no | `5` | Approximate number of ticks on the VALUE axis, on both orientations. Prefer this over xTicks/yTicks, which are named for where the axis is drawn and therefore swap meaning when orientation="horizontal". |
| `categoryAxisTicks` | `number` | no | `5` | Approximate number of ticks on the CATEGORY axis, on both orientations. Role-named twin of valueAxisTicks. |
| `categoryLabelEvery` | `number` | no | — | Show every Nth category label (always the last) to thin a crowded axis. Role-named twin of xLabelEvery; always strides the category axis on both orientations. |
| `xLabelEvery` | `number` | no | — | Show every Nth category label (always the last) to thin a crowded axis. Unlike xTicks/yTicks this does NOT swap with orientation — it always strides the category axis. categoryLabelEvery is the unambiguous name. |
| `legend` | `boolean` | no | — | Whether to show the legend. |
| `tooltip` | `boolean` | no | — | Whether to show tooltips on hover. |
| `tooltipFormat` | `(p: ChartPoint) => string` | no | — | Custom tooltip formatter. The stacked default lists "label · total" + each non-zero layer in its color. |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |
| `plain` | `boolean` | no | `false` | Marks only — no axes, grid lines, or legend. For micro/inline charts. |
| `annotations` | `Annotation[]` | no | — | Reference lines, shaded bands, and markers drawn over the plot (e.g. a target/threshold line). |
| `labels` | `boolean \| { format?: (v: number) => string; position?: string }` | no | — | Print each value as a label on the mark (collision-aware, decorative/aria-hidden). |
| `onSelect` | `(point: ChartPoint) => void` | no | — | Fired when a point is clicked or activated (Enter/Space) — for drill-down. |
| `fill` | `'solid' \| 'gradient' \| 'pattern'` | no | `solid` | Bar fill style — solid, a gradient, or a pattern. |
| `patternKind` | `'dots' \| 'lines' \| 'cross'` | no | — | Pattern motif when fill="pattern". |
| `format` | `(value: number \| string \| Date) => string` | no | — | Format each category/x-axis tick label. |

## Object types

### `BarChartSeries<Datum>`

One series (a set of bars). Pass an array via the `series` prop.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | `string` | yes | Stable series identity. |
| `label` | `string` | yes | Legend + tooltip label. |
| `data` | `readonly Datum[]` | yes | Row data read by the `x`/`y` accessors. |
| `color` | `string \| ((datum: Datum, index: number) => string)` | no | Any CSS color overriding the positional palette (--cascivo-chart-N) for this series / stacked layer. Pass a FUNCTION to color each bar from its own datum — the single-series categorical case (incidents by severity, where SEV1 reads as danger regardless of which bar is tallest). Each bar is also stamped with data-x for CSS targeting. |

### `StackedRow`

Row-oriented input to the `toStackedSeries(rows)` pivot helper.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `label` | `string` | yes | Category (one bar). |
| `segments` | `StackedSegment[]` | yes | Per-layer values: { key, value, color? }. First non-undefined color per key wins. |

### `StackedSegment`

One layer of a stacked bar within a StackedRow.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `key` | `string` | yes | Layer key — becomes the series id/label (e.g. "Done"). |
| `value` | `number` | yes | — |
| `color` | `string` | no | Optional CSS color for this layer. |

### `ChartPoint`

Argument passed to the `tooltipFormat` callback.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `label` | `string` | yes | Category label. |
| `value` | `number \| string` | yes | — |
| `color` | `string` | no | Resolved mark color (the default tooltip tints its text with this). |
| `segments` | `readonly { label: string; value: number; color?: string }[]` | no | Per-layer breakdown for a stacked category; the default stacked tooltip lists these. |

## Examples

### Basic bar chart

```tsx
import { BarChart } from '@cascivo/charts'

const series = [{ id: 'a', label: 'Sales', data: [{x:'Jan',y:100},{x:'Feb',y:150}] }]
<BarChart series={series} x={d => d.x} y={d => d.y} title="Sales" />
```

### Date-based categories (format the Date in the accessor)

BarChart's x is a category string, not a Date. When your data is date-keyed, format the Date to a label string inside the x accessor — do NOT return the Date itself (that is a type error; only LineChart/AreaChart take a Date x).

```tsx
import { BarChart } from '@cascivo/charts'

const series = [{ id: 'signups', label: 'Signups', data: [
  { day: new Date('2026-07-01'), count: 12 },
  { day: new Date('2026-07-02'), count: 18 },
] }]
<BarChart
  series={series}
  x={(d) => d.day.toLocaleDateString(undefined, { month: 'short', day: 'numeric' })}
  y={(d) => d.count}
  xLabelEvery={2}
  title="Daily signups"
/>
```

### Stacked bar from row-oriented data

```tsx
import { BarChart, toStackedSeries } from '@cascivo/charts'

// Pivot { label, segments[] } rows into series + x/y. Per-segment color is preserved.
const rows = [
  { label: 'Mon', segments: [
    { key: 'Done', value: 5, color: 'var(--cascivo-color-success)' },
    { key: 'Blocked', value: 2, color: 'var(--cascivo-color-destructive)' },
  ] },
  { label: 'Tue', segments: [
    { key: 'Done', value: 8, color: 'var(--cascivo-color-success)' },
    { key: 'Blocked', value: 1, color: 'var(--cascivo-color-destructive)' },
  ] },
]
// Tooltip shows "Mon · 7" then each non-zero layer in its color.
<BarChart mode="stacked" tooltip {...toStackedSeries(rows)} title="Throughput" />
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-chart-1`
- `--cascivo-chart-2`
- `--cascivo-chart-3`
- `--cascivo-chart-4`
- `--cascivo-chart-5`
- `--cascivo-chart-6`
- `--cascivo-chart-7`
- `--cascivo-chart-8`
- `--cascivo-chart-bar-radius`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `img`

## Dependencies

- `@cascivo/charts`

## Tags

chart, bar, data-viz

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Boxplot

Box-and-whisker plot with five-number summary and outlier dots per series.

## Install

Ships in the `@cascivo/charts` package — install it (no copy-paste):

```sh
pnpm add @cascivo/charts
```

```tsx
import { Boxplot } from '@cascivo/charts'
import '@cascivo/charts/styles.css' // bundler: automatic. Needed only for no-bundler / SSR-externalised builds, where skipping it renders the screen-reader data-table fallback visibly
```

## Category

`chart`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `series` | `{ id: string; label: string; values: number[] }[]` | yes | — | Array of series each with raw numeric values |
| `title` | `string` | yes | — | Title text for the component. |
| `description` | `string` | no | — | Supporting description text. |
| `width` | `number` | no | — | Fixed SVG width in px. ⚠ **Omit for a responsive chart** — the chart fills and tracks its container via a ResizeObserver; there is no correct pixel number in a responsive grid. A fixed width is clamped to the container (max-inline-size: 100%) so it can never overflow its card, but it also stops the chart growing. `useChartSize` is NOT needed for this — charts call it internally. |
| `height` | `number` | no | `320` | SVG height in px. Unlike `width`, height does NOT track the container — this is the knob you set to change the chart's aspect. |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |
| `plain` | `boolean` | no | `false` | Marks only — no axes, grid lines, or legend. For micro/inline charts. |
| `format` | `(value: number \| string \| Date) => string` | no | — | Format each category/x-axis tick label. |

## Object types

### `BoxplotSeries`

Shape of the `series` prop.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | `string` | yes | — |
| `label` | `string` | yes | — |
| `values` | `number[]` | yes | — |

## Examples

### Basic boxplot

```tsx
import { Boxplot } from '@cascivo/charts'

const series = [
  { id: 'a', label: 'Group A', values: [1,2,3,4,5,6,7,8,9,10] },
  { id: 'b', label: 'Group B', values: [3,5,6,7,8,8,9,9,10,15] },
]
<Boxplot series={series} title="Comparison" />
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-chart-1`
- `--cascivo-chart-2`
- `--cascivo-chart-3`
- `--cascivo-chart-4`
- `--cascivo-chart-5`
- `--cascivo-chart-6`
- `--cascivo-chart-7`
- `--cascivo-chart-8`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `img`

## Dependencies

- `@cascivo/charts`

## Tags

chart, boxplot, box-whisker, statistics, data-viz

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# BubbleChart

Bubble chart mapping x, y, and size dimensions; radius is area-proportional via sqrt scale.

## Install

Ships in the `@cascivo/charts` package — install it (no copy-paste):

```sh
pnpm add @cascivo/charts
```

```tsx
import { BubbleChart } from '@cascivo/charts'
import '@cascivo/charts/styles.css' // bundler: automatic. Needed only for no-bundler / SSR-externalised builds, where skipping it renders the screen-reader data-table fallback visibly
```

## Category

`chart`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `series` | `{ name: string; data: { x: number; y: number; size: number }[] }[]` | yes | — | The data series to plot. |
| `title` | `string` | yes | — | Title text for the component. |
| `description` | `string` | no | — | Supporting description text. |
| `width` | `number` | no | — | Fixed SVG width in px. ⚠ **Omit for a responsive chart** — the chart fills and tracks its container via a ResizeObserver; there is no correct pixel number in a responsive grid. A fixed width is clamped to the container (max-inline-size: 100%) so it can never overflow its card, but it also stops the chart growing. `useChartSize` is NOT needed for this — charts call it internally. |
| `height` | `number` | no | `320` | SVG height in px. Unlike `width`, height does NOT track the container — this is the knob you set to change the chart's aspect. |
| `tooltip` | `boolean` | no | — | Enable hover/keyboard tooltip |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |
| `plain` | `boolean` | no | `false` | Marks only — no axes, grid lines, or legend. For micro/inline charts. |
| `glyph` | `GlyphShape \| ((d, seriesId) => GlyphShape)` | no | — | Point glyph shape (circle/square/diamond/triangle/cross/star) — a fixed shape or a function to encode a category by shape. |
| `format` | `(value: number \| string \| Date) => string` | no | — | Format each X-axis tick label. |

## Object types

### `BubbleSeries`

Shape of the `series` prop.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | `string` | yes | — |
| `data` | `BubbleDatum[]` | yes | — |

## Examples

### Basic bubble chart

```tsx
import { BubbleChart } from '@cascivo/charts'

const series = [{ name: 'Group A', data: [{x:1,y:2,size:10},{x:3,y:4,size:30}] }]
<BubbleChart series={series} title="Bubble" />
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-chart-1`
- `--cascivo-chart-2`
- `--cascivo-chart-3`
- `--cascivo-chart-4`
- `--cascivo-chart-5`
- `--cascivo-chart-6`
- `--cascivo-chart-7`
- `--cascivo-chart-8`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `img`
- **Keyboard:** Tab (focus chart), ArrowLeft/ArrowRight (navigate points), Home/End (first/last point), Escape (clear focus)

## Dependencies

- `@cascivo/charts`

## Tags

chart, bubble, scatter, three-dimensional, data-viz

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Bullet

Bullet chart with background range bands, measure bar, and target tick.

## Install

Ships in the `@cascivo/charts` package — install it (no copy-paste):

```sh
pnpm add @cascivo/charts
```

```tsx
import { Bullet } from '@cascivo/charts'
import '@cascivo/charts/styles.css' // bundler: automatic. Needed only for no-bundler / SSR-externalised builds, where skipping it renders the screen-reader data-table fallback visibly
```

## Category

`chart`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `value` | `number` | yes | — | Current measure value |
| `target` | `number` | yes | — | Target marker value |
| `ranges` | `number[]` | yes | — | Qualitative range breakpoints (sorted ascending) |
| `label` | `string` | yes | — | Text label for the control. Rendered on screen. |
| `min` | `number` | no | `0` | Minimum allowed value. |
| `max` | `number` | no | — | Domain maximum (defaults to last range) |
| `width` | `number` | no | `300` | SVG width in px. **This chart is fixed-width by default** — it is a compact, inline chart meant to sit in a table cell or beside a label, so omitting `width` gives you 300px rather than a container-filling chart. Pass a number to change it. The catalogue-wide "omit for a responsive chart" note does not apply to this chart. |
| `height` | `number` | no | `40` | SVG height in px. Unlike `width`, height does NOT track the container — this is the knob you set to change the chart's aspect. |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |

## Examples

### Basic bullet chart

```tsx
import { Bullet } from '@cascivo/charts'

<Bullet value={72} target={80} ranges={[40, 70, 100]} label="Revenue %" />
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-chart-1`
- `--cascivo-gray-200`
- `--cascivo-gray-300`
- `--cascivo-gray-400`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `img`

## Dependencies

- `@cascivo/charts`

## Tags

chart, bullet, kpi, progress, data-viz

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# CalendarHeatmap

Calendar heatmap — a week-column grid of day cells colored by value (GitHub-style).

## Install

Ships in the `@cascivo/charts` package — install it (no copy-paste):

```sh
pnpm add @cascivo/charts
```

```tsx
import { CalendarHeatmap } from '@cascivo/charts'
import '@cascivo/charts/styles.css' // bundler: automatic. Needed only for no-bundler / SSR-externalised builds, where skipping it renders the screen-reader data-table fallback visibly
```

## Category

`chart`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `data` | `CalendarHeatmapDatum[]` | yes | — | Days: { day: string \| Date, value }. |
| `title` | `string` | yes | — | Title text for the component. |
| `description` | `string` | no | — | Supporting description text. |
| `from` | `string \| Date` | no | — | Range start (defaults to min day). |
| `to` | `string \| Date` | no | — | Range end (defaults to max day). |
| `width` | `number` | no | — | Fixed SVG width in px. ⚠ **Omit for a responsive chart** — the chart fills and tracks its container via a ResizeObserver; there is no correct pixel number in a responsive grid. A fixed width is clamped to the container (max-inline-size: 100%) so it can never overflow its card, but it also stops the chart growing. `useChartSize` is NOT needed for this — charts call it internally. |
| `height` | `number` | no | `160` | SVG height in px. Unlike `width`, height does NOT track the container — this is the knob you set to change the chart's aspect. It is a **cap on the drawn grid, never a crop**: cell size is clamped so all seven weekday rows fit inside it. |
| `maxCellSize` | `number` | no | — | Optional ceiling on a cell's edge, in px. Cells are already clamped to fit `height`; set this only to keep them small in a short, wide range (GitHub's calendar uses ~11). Omitted by default so the height budget alone decides. |
| `tooltip` | `boolean` | no | — | Whether to show tooltips on hover. |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |
| `plain` | `boolean` | no | `false` | When true, renders a minimal variant without chart chrome. |
| `visualMap` | `VisualMapOptions` | no | — | Map day value → CVD-safe colour (continuous or piecewise) via a keyboard-operable legend that filters the visible range. |

## Object types

### `CalendarHeatmapDatum`

Shape of the `data` prop.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `day` | `string \| Date` | yes | — |
| `value` | `number` | yes | — |

### `VisualMapOptions`

Shape of the `visualMap` prop.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `min` | `number` | yes | Domain minimum (value mapped to ramp t=0). |
| `max` | `number` | yes | Domain maximum (value mapped to ramp t=1). |
| `mode` | `VisualMode` | no | `continuous` ramp (default) or `piecewise` buckets. |
| `channel` | `VisualChannel` | no | Which visual channel(s) the value drives. |
| `ramp` | `RampKind` | no | Ramp family — CVD-safe `sequential` (default) or `diverging`. |
| `pieces` | `number` | no | Bucket count for `piecewise` (default 5). |
| `sizeRange` | `[number, number]` | no | [min, max] mark radius in px for the `size` channel (default [3, 14]). |

## Examples

### Contribution calendar

```tsx
import { CalendarHeatmap } from '@cascivo/charts'

<CalendarHeatmap
  title="Activity"
  data={[{ day: '2026-01-01', value: 3 }, { day: '2026-01-02', value: 7 }]}
/>
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-chart-2`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `img`
- **Keyboard:** Tab (focus chart), ArrowLeft/ArrowRight (navigate days), Escape (clear focus)

## Dependencies

- `@cascivo/charts`

## Tags

chart, calendar, heatmap, time, data-viz

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Candlestick

OHLC financial chart — each period a high–low wick and an open↔close body, coloured up/down.

## Install

Ships in the `@cascivo/charts` package — install it (no copy-paste):

```sh
pnpm add @cascivo/charts
```

```tsx
import { Candlestick } from '@cascivo/charts'
import '@cascivo/charts/styles.css' // bundler: automatic. Needed only for no-bundler / SSR-externalised builds, where skipping it renders the screen-reader data-table fallback visibly
```

## Category

`chart`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `data` | `CandlestickDatum[]` | yes | — | One candle per period: { t, open, high, low, close, volume? }. |
| `title` | `string` | yes | — | Chart title (also aria-label). |
| `description` | `string` | no | — | Supporting description text. |
| `width` | `number` | no | — | Fixed SVG width in px. ⚠ **Omit for a responsive chart** — the chart fills and tracks its container via a ResizeObserver; there is no correct pixel number in a responsive grid. A fixed width is clamped to the container (max-inline-size: 100%) so it can never overflow its card, but it also stops the chart growing. `useChartSize` is NOT needed for this — charts call it internally. |
| `height` | `number` | no | `320` | SVG height in px. Unlike `width`, height does NOT track the container — this is the knob you set to change the chart's aspect. |
| `yTicks` | `number` | no | `5` | Approximate number of ticks on the y-axis. |
| `upColor` | `string` | no | `'var(--cascivo-chart-2)'` | Colour for up candles (close ≥ open). |
| `downColor` | `string` | no | `'var(--cascivo-chart-4)'` | Colour for down candles (close < open). |
| `volume` | `boolean` | no | `false` | Render volume bars beneath the candles. |
| `tooltip` | `boolean` | no | — | Enable hover tooltip (OHLC). |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |
| `plain` | `boolean` | no | `false` | Marks only — no axes. For micro/inline charts. |
| `annotations` | `Annotation[]` | no | — | Reference lines/bands/markers over the plot (e.g. a last-price rule). |
| `brush` | `boolean` | no | — | Keyboard-operable Brush below the plot to subset the candles to a window. |
| `dataZoom` | `boolean` | no | — | DataZoom slider below the plot — a Brush whose body also pans the window. |
| `zoom` | `boolean` | no | — | In-plot wheel/drag/keyboard zoom-pan (+/-/0) over the candle index window. |
| `syncId` | `string` | no | — | Connect charts sharing this id — they mirror the zoom window. |
| `tooltipMode` | `'item' \| 'axis'` | no | `item` | item (nearest candle) or axis (crosshair + OHLC at the hovered x). |
| `format` | `(value: number \| string \| Date) => string` | no | — | Format each X-axis tick label. |

## Object types

### `CandlestickDatum`

Shape of the `data` prop.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `t` | `string` | yes | Period label (date string or index). |
| `open` | `number` | yes | — |
| `high` | `number` | yes | — |
| `low` | `number` | yes | — |
| `close` | `number` | yes | — |
| `volume` | `number` | no | Render volume bars beneath the candles. |

## Examples

### OHLC price series

```tsx
import { Candlestick } from '@cascivo/charts'

<Candlestick
  title="ACME daily"
  tooltip
  data={[
    { t: 'Mon', open: 10, high: 14, low: 9, close: 13 },
    { t: 'Tue', open: 13, high: 15, low: 11, close: 11 },
    { t: 'Wed', open: 11, high: 12, low: 8, close: 9 },
  ]}
/>
```

### Zoomable with a last-price rule

```tsx
<Candlestick
  title="ACME daily"
  data={candles}
  volume
  zoom
  dataZoom
  tooltipMode="axis"
  annotations={[{ kind: 'line', axis: 'y', value: lastClose, label: '42.77' }]}
/>
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-chart-2`
- `--cascivo-chart-4`
- `--cascivo-chart-grid`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `img`
- **Keyboard:** Tab (focus chart), ArrowLeft/ArrowRight (navigate candles), +/- (zoom), 0 (reset) when zoom enabled, Escape (clear focus)

## Dependencies

- `@cascivo/charts`

## Tags

chart, candlestick, ohlc, financial, data-viz

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# ComboChart

Combination bar + line chart on shared or dual y-axes.

## Install

Ships in the `@cascivo/charts` package — install it (no copy-paste):

```sh
pnpm add @cascivo/charts
```

```tsx
import { ComboChart } from '@cascivo/charts'
import '@cascivo/charts/styles.css' // bundler: automatic. Needed only for no-bundler / SSR-externalised builds, where skipping it renders the screen-reader data-table fallback visibly
```

## Category

`chart`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `bars` | `{ label: string; value: number }[]` | yes | — | Bar series data |
| `line` | `{ x: number; y: number }[]` | yes | — | Line series data points |
| `title` | `string` | yes | — | Title text for the component. |
| `description` | `string` | no | — | Supporting description text. |
| `secondAxis` | `boolean` | no | `false` | Render line on a secondary right y-axis |
| `width` | `number` | no | — | Fixed SVG width in px. ⚠ **Omit for a responsive chart** — the chart fills and tracks its container via a ResizeObserver; there is no correct pixel number in a responsive grid. A fixed width is clamped to the container (max-inline-size: 100%) so it can never overflow its card, but it also stops the chart growing. `useChartSize` is NOT needed for this — charts call it internally. |
| `height` | `number` | no | `320` | SVG height in px. Unlike `width`, height does NOT track the container — this is the knob you set to change the chart's aspect. |
| `tooltip` | `boolean` | no | — | Enable hover/keyboard tooltip |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |
| `plain` | `boolean` | no | `false` | Marks only — no axes, grid lines, or legend. For micro/inline charts. |
| `annotations` | `Annotation[]` | no | — | Reference lines, shaded bands, and markers drawn over the plot (e.g. a target/threshold line). |
| `barsLabel` | `string` | no | `'Bars'` | Legend label for the bar series. |
| `format` | `(value: number \| string \| Date) => string` | no | — | Format each X-axis tick label. |
| `legend` | `boolean` | no | — | Show the legend. |
| `lineLabel` | `string` | no | `'Line'` | Legend label for the line series. |
| `xLabelEvery` | `number` | no | — | Render every Nth category label. |

## Object types

### `ComboChartBar`

Shape of the `bars` prop.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `label` | `string` | yes | — |
| `value` | `number` | yes | — |

### `ComboChartPoint`

Shape of the `line` prop.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `x` | `number` | yes | Index into `bars` — point `i` is drawn at the centre of bar `i`. |
| `y` | `number` | yes | — |

## Examples

### Basic combo chart

```tsx
import { ComboChart } from '@cascivo/charts'

const bars = [{label:'Jan',value:100},{label:'Feb',value:120},{label:'Mar',value:90}]
const line = [{x:0,y:50},{x:1,y:70},{x:2,y:60}]
<ComboChart bars={bars} line={line} title="Sales vs Target" />
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-chart-1`
- `--cascivo-chart-2`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `img`
- **Keyboard:** Tab (focus chart), ArrowLeft/ArrowRight (navigate points), Home/End (first/last point), Escape (clear focus)

## Dependencies

- `@cascivo/charts`

## Tags

chart, combo, bar, line, dual-axis, data-viz

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Funnel

Vertical conversion funnel — each stage is a trapezoid narrowing toward the next, with optional conversion labels.

## Install

Ships in the `@cascivo/charts` package — install it (no copy-paste):

```sh
pnpm add @cascivo/charts
```

```tsx
import { Funnel } from '@cascivo/charts'
import '@cascivo/charts/styles.css' // bundler: automatic. Needed only for no-bundler / SSR-externalised builds, where skipping it renders the screen-reader data-table fallback visibly
```

## Category

`chart`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `data` | `FunnelStage[]` | yes | — | Ordered stages (descending): { id, label, value, color? }. |
| `title` | `string` | yes | — | Chart title (also used as aria-label). |
| `description` | `string` | no | — | Subtitle below the title. |
| `width` | `number` | no | — | Fixed SVG width in px. ⚠ **Omit for a responsive chart** — the chart fills and tracks its container via a ResizeObserver; there is no correct pixel number in a responsive grid. A fixed width is clamped to the container (max-inline-size: 100%) so it can never overflow its card, but it also stops the chart growing. `useChartSize` is NOT needed for this — charts call it internally. |
| `height` | `number` | no | `320` | SVG height in px. Unlike `width`, height does NOT track the container — this is the knob you set to change the chart's aspect. |
| `showConversion` | `boolean` | no | `false` | Append each stage’s % of the first stage to its label. |
| `tooltip` | `boolean` | no | — | Enable hover tooltip. |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |
| `plain` | `boolean` | no | `false` | Marks only — no labels. For micro/inline charts. |

## Object types

### `FunnelStage`

Shape of the `data` prop.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | `string` | yes | — |
| `label` | `string` | yes | — |
| `value` | `number` | yes | — |
| `color` | `string` | no | CSS color overriding the positional palette for this stage. |

## Examples

### Signup conversion funnel

```tsx
import { Funnel } from '@cascivo/charts'

<Funnel
  title="Signup funnel"
  showConversion
  data={[
    { id: 'visit', label: 'Visited', value: 8200 },
    { id: 'signup', label: 'Signed up', value: 3100 },
    { id: 'active', label: 'Activated', value: 1400 },
    { id: 'paid', label: 'Paid', value: 520 },
  ]}
/>
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-chart-1`
- `--cascivo-chart-2`
- `--cascivo-chart-3`
- `--cascivo-chart-4`
- `--cascivo-chart-5`
- `--cascivo-chart-6`
- `--cascivo-chart-7`
- `--cascivo-chart-8`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `img`
- **Keyboard:** Tab (focus chart), ArrowLeft/ArrowRight (navigate stages), Escape (clear focus)

## Dependencies

- `@cascivo/charts`

## Tags

chart, funnel, conversion, flow, data-viz

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Gauge

A speedometer gauge — a value arc over a min–max sweep with threshold zones, ticks, and a needle.

## Install

Ships in the `@cascivo/charts` package — install it (no copy-paste):

```sh
pnpm add @cascivo/charts
```

```tsx
import { Gauge } from '@cascivo/charts'
import '@cascivo/charts/styles.css' // bundler: automatic. Needed only for no-bundler / SSR-externalised builds, where skipping it renders the screen-reader data-table fallback visibly
```

## Category

`chart`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `value` | `number` | yes | — | The value the needle points to. |
| `min` | `number` | no | `0` | Minimum allowed value. |
| `max` | `number` | no | `100` | Maximum allowed value. |
| `thresholds` | `{ upTo: number; color: string }[]` | no | — | Coloured zones from min upward; the last should reach max. |
| `unit` | `string` | no | `''` | Suffix after the centre value. |
| `sweep` | `number` | no | `270` | Total sweep angle in degrees (270 = a speedometer arc). |
| `ticks` | `number` | no | `5` | Major tick count. |
| `title` | `string` | yes | — | Chart title (also aria-label). |
| `description` | `string` | no | — | Supporting description text. |
| `width` | `number` | no | — | Fixed SVG width in px. ⚠ **Omit for a responsive chart** — the chart fills and tracks its container via a ResizeObserver; there is no correct pixel number in a responsive grid. A fixed width is clamped to the container (max-inline-size: 100%) so it can never overflow its card, but it also stops the chart growing. `useChartSize` is NOT needed for this — charts call it internally. |
| `height` | `number` | no | `240` | SVG height in px. Unlike `width`, height does NOT track the container — this is the knob you set to change the chart's aspect. |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |
| `plain` | `boolean` | no | `false` | Marks only — no ticks/labels. For micro/inline charts. |

## Object types

### `GaugeThreshold`

Shape of the `thresholds` prop.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `upTo` | `number` | yes | Upper bound of this coloured zone (in value units). |
| `color` | `string` | yes | — |

## Examples

### Speedometer with zones

```tsx
import { Gauge } from '@cascivo/charts'

<Gauge
  title="CPU load"
  value={72}
  unit="%"
  thresholds={[
    { upTo: 50, color: 'var(--cascivo-chart-2)' },
    { upTo: 80, color: 'var(--cascivo-chart-3)' },
    { upTo: 100, color: 'var(--cascivo-chart-4)' },
  ]}
/>
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-color-accent`
- `--cascivo-color-foreground`
- `--cascivo-chart-grid`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `img`
- **Keyboard:** Tab (focus chart)

## Dependencies

- `@cascivo/charts`

## Tags

chart, gauge, speedometer, kpi, data-viz

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Heatmap

Two-dimensional heatmap with band scales and color-mix cell interpolation.

## Install

Ships in the `@cascivo/charts` package — install it (no copy-paste):

```sh
pnpm add @cascivo/charts
```

```tsx
import { Heatmap } from '@cascivo/charts'
import '@cascivo/charts/styles.css' // bundler: automatic. Needed only for no-bundler / SSR-externalised builds, where skipping it renders the screen-reader data-table fallback visibly
```

## Category

`chart`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `data` | `{ x: string; y: string; value: number }[]` | yes | — | Array of x/y/value triples |
| `title` | `string` | yes | — | Title text for the component. |
| `description` | `string` | no | — | Supporting description text. |
| `width` | `number` | no | — | Fixed SVG width in px. ⚠ **Omit for a responsive chart** — the chart fills and tracks its container via a ResizeObserver; there is no correct pixel number in a responsive grid. A fixed width is clamped to the container (max-inline-size: 100%) so it can never overflow its card, but it also stops the chart growing. `useChartSize` is NOT needed for this — charts call it internally. |
| `height` | `number` | no | `320` | SVG height in px. Unlike `width`, height does NOT track the container — this is the knob you set to change the chart's aspect. |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |
| `plain` | `boolean` | no | `false` | Marks only — no axes, grid lines, or legend. For micro/inline charts. |
| `visualMap` | `VisualMapOptions` | no | — | Map cell value → CVD-safe colour (continuous or piecewise) via a keyboard-operable legend that filters the visible range. |
| `toolbox` | `boolean \| ToolboxOptions` | no | — | Render a keyboard-reachable toolbox — PNG/SVG export, a data-view table toggle, and restore (reset the visualMap filter). |
| `format` | `(value: number \| string \| Date) => string` | no | — | Format each category/x-axis tick label. |

## Object types

### `HeatmapDatum`

Shape of the `data` prop.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `x` | `string` | yes | — |
| `y` | `string` | yes | — |
| `value` | `number` | yes | — |

### `VisualMapOptions`

Shape of the `visualMap` prop.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `min` | `number` | yes | Domain minimum (value mapped to ramp t=0). |
| `max` | `number` | yes | Domain maximum (value mapped to ramp t=1). |
| `mode` | `VisualMode` | no | `continuous` ramp (default) or `piecewise` buckets. |
| `channel` | `VisualChannel` | no | Which visual channel(s) the value drives. |
| `ramp` | `RampKind` | no | Ramp family — CVD-safe `sequential` (default) or `diverging`. |
| `pieces` | `number` | no | Bucket count for `piecewise` (default 5). |
| `sizeRange` | `[number, number]` | no | [min, max] mark radius in px for the `size` channel (default [3, 14]). |

## Examples

### Basic heatmap

```tsx
import { Heatmap } from '@cascivo/charts'

const data = [
  {x:'Mon',y:'AM',value:10},{x:'Mon',y:'PM',value:20},
  {x:'Tue',y:'AM',value:15},{x:'Tue',y:'PM',value:5},
]
<Heatmap data={data} title="Activity" />
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-chart-1`
- `--cascivo-gray-100`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `img`

## Dependencies

- `@cascivo/charts`

## Tags

chart, heatmap, matrix, data-viz

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Histogram

Frequency histogram using Freedman–Diaconis binning with hover tooltips.

## Install

Ships in the `@cascivo/charts` package — install it (no copy-paste):

```sh
pnpm add @cascivo/charts
```

```tsx
import { Histogram } from '@cascivo/charts'
import '@cascivo/charts/styles.css' // bundler: automatic. Needed only for no-bundler / SSR-externalised builds, where skipping it renders the screen-reader data-table fallback visibly
```

## Category

`chart`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `data` | `number[]` | yes | — | Array of numeric values to bin |
| `bins` | `number` | no | — | Explicit bin count (defaults to Freedman–Diaconis) |
| `title` | `string` | yes | — | Title text for the component. |
| `label` | `string` | yes | — | X-axis label — rendered visibly beneath the axis. Rendered on screen. |
| `description` | `string` | no | — | Supporting description text. |
| `width` | `number` | no | — | Fixed SVG width in px. ⚠ **Omit for a responsive chart** — the chart fills and tracks its container via a ResizeObserver; there is no correct pixel number in a responsive grid. A fixed width is clamped to the container (max-inline-size: 100%) so it can never overflow its card, but it also stops the chart growing. `useChartSize` is NOT needed for this — charts call it internally. |
| `height` | `number` | no | `300` | SVG height in px. Unlike `width`, height does NOT track the container — this is the knob you set to change the chart's aspect. |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |
| `plain` | `boolean` | no | `false` | Marks only — no axes, grid lines, or legend. For micro/inline charts. |
| `format` | `(value: number \| string \| Date) => string` | no | — | Format each X-axis tick label. |

## Examples

### Basic histogram

```tsx
import { Histogram } from '@cascivo/charts'

const data = Array.from({length:100}, () => Math.random() * 100)
<Histogram data={data} title="Distribution" label="Value" />
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-chart-1`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `img`

## Dependencies

- `@cascivo/charts`

## Tags

chart, histogram, distribution, frequency, data-viz

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Kpi

KPI card showing a primary metric with optional delta indicator, icon, and sparkline.

## Install

Ships in the `@cascivo/charts` package — install it (no copy-paste):

```sh
pnpm add @cascivo/charts
```

```tsx
import { Kpi } from '@cascivo/charts'
import '@cascivo/charts/styles.css' // bundler: automatic. Needed only for no-bundler / SSR-externalised builds, where skipping it renders the screen-reader data-table fallback visibly
```

## Category

`chart`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `value` | `string \| number` | yes | — | Primary metric value |
| `label` | `string` | yes | — | Metric label — rendered visibly at the top of the tile. Rendered on screen. |
| `delta` | `number` | no | — | Change value (positive = up, negative = down) |
| `deltaFormat` | `'number' \| 'percent' \| ((delta: number) => string)` | no | `number` | How to render `delta`. `'percent'` treats it as percentage points and appends `%` (25.6 → +25.6%) — it does not multiply by 100. A function owns the whole string, sign included. |
| `goodDirection` | `'up' \| 'down' \| 'neutral'` | no | `up` | Which direction is *good* for this metric — the colour, independent of the arrow (which follows the sign of `delta`). 'up' (default) suits revenue; use 'down' for errors, latency, cost or churn, where a rise is bad news; 'neutral' keeps the arrow and drops the sentiment colour. |
| `deltaLabel` | `string` | no | — | Delta context label (e.g. "vs last week") |
| `icon` | `ReactNode` | no | — | Icon element rendered in the component. |
| `sparkline` | `number[]` | no | — | Trend data for embedded sparkline |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |

## Examples

### Basic KPI card

```tsx
import { Kpi } from '@cascivo/charts'

<Kpi value="$12,400" label="Monthly revenue" delta={8.2} deltaLabel="vs last month" />
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-chart-1`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `figure`

## Dependencies

- `@cascivo/charts`

## Tags

chart, kpi, metric, dashboard, data-viz

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# LineChart

Time-series or numeric line chart with multi-series support, hover tooltip, and legend.

## Install

Ships in the `@cascivo/charts` package — install it (no copy-paste):

```sh
pnpm add @cascivo/charts
```

```tsx
import { LineChart } from '@cascivo/charts'
import '@cascivo/charts/styles.css' // bundler: automatic. Needed only for no-bundler / SSR-externalised builds, where skipping it renders the screen-reader data-table fallback visibly
```

## Category

`chart`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `series` | `LineChartSeries<Datum>[]` | yes | — | Array of data series |
| `x` | `(d: Datum) => number \| Date` | yes | — | X-value accessor. Return a `number` for a numeric axis or a `Date` for a time axis (ticks format as dates). This is a continuous scale — unlike BarChart, whose `x` returns a category `string` (band scale). For discrete categories, use BarChart. |
| `y` | `(d: Datum) => number` | yes | — | Y-value accessor, applied to every series unless a series sets its own `y`. One x-domain per chart, so `x` is chart-level only; give each series a `y` to plot different fields from one shared data row. |
| `title` | `string` | yes | — | Chart title (also used as aria-label) |
| `description` | `string` | no | — | Subtitle shown below title |
| `curve` | `'linear' \| 'monotone' \| 'step' \| 'stepBefore' \| 'stepAfter' \| 'natural' \| 'basis' \| 'cardinal' \| 'catmullRom'` | no | `monotone` | Line interpolation curve |
| `width` | `number` | no | — | Fixed SVG width (defaults to container width) |
| `height` | `number` | no | `300` | SVG height in px |
| `xTicks` | `number` | no | `5` | Approximate number of X-axis ticks |
| `yTicks` | `number` | no | `5` | Approximate number of Y-axis ticks |
| `format` | `(value: number \| string \| Date) => string` | no | — | Format each X-axis tick label; receives the datum's raw x value (number \| string \| Date). Without it a numeric x renders raw — a Date.now()-scale value renders as 1,785,217,000,000 — and passing Date objects gives a fixed date format, so sub-day buckets all collapse to the same label. Mirrors secondAxis.format on the right. |
| `legend` | `boolean` | no | — | Show series legend |
| `tooltip` | `boolean` | no | — | Enable hover tooltip |
| `formatTooltip` | `(datum: Datum, series: LineChartSeries<Datum>) => string` | no | — | Custom tooltip formatter |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |
| `plain` | `boolean` | no | `false` | Marks only — no axes, grid lines, or legend. For micro/inline charts. |
| `annotations` | `Annotation[]` | no | — | Reference lines, shaded bands, and markers drawn over the plot (e.g. a target/threshold line). |
| `labels` | `boolean \| { format?: (v: number) => string; position?: string }` | no | — | Print each value as a label on the mark (collision-aware, decorative/aria-hidden). |
| `connectNulls` | `boolean` | no | `false` | Bridge non-finite y gaps instead of breaking the line at them. |
| `onSelect` | `(point: ChartPoint) => void` | no | — | Fired when a point is clicked or activated (Enter/Space) — for drill-down. |
| `brush` | `boolean` | no | `false` | Show a keyboard-operable Brush below the plot to subset (zoom) the series to a window. |
| `dataZoom` | `boolean` | no | `false` | Show a DataZoom slider below the plot — a Brush whose body also pans the window. |
| `zoom` | `boolean` | no | `false` | Enable in-plot wheel/drag/keyboard zoom-pan (+/-/0) over the series index window, with a reset control and re-ticked axes. |
| `syncId` | `string` | no | — | Connect this chart to others sharing the same id — they mirror the zoom window and hovered x. |
| `tooltipMode` | `'item' \| 'axis'` | no | `item` | Tooltip trigger — item (nearest point) or axis (a crosshair + a shared tooltip listing every series at the hovered x). |
| `decimate` | `boolean \| { method?: 'lttb' \| 'minmax'; threshold?: number }` | no | — | Downsample dense series before drawing (LTTB or min-max). Visual only — the fallback table keeps the full data. |
| `toolbox` | `boolean \| ToolboxOptions` | no | — | Render a keyboard-reachable toolbox — PNG/SVG export, a data-view table toggle, and restore (reset zoom). |
| `transition` | `boolean \| { duration?: number; easing?: string; properties?: string[] }` | no | — | Tune the reduced-motion-gated enter/update transitions (false disables). Always suppressed under prefers-reduced-motion. |
| `onBeforeDraw` | `(ctx: { width: number; height: number }) => ReactNode` | no | — | Render custom SVG behind the marks (watermark/region) — a lightweight extension seam. |
| `onAfterDraw` | `(ctx: { width: number; height: number }) => ReactNode` | no | — | Render custom SVG over the marks (overlay/extra series) — a lightweight extension seam. |
| `secondAxis` | `{ label?: string; format?: (value: number) => string }` | no | — | Add a right-hand y-axis for series with `axis: 'right'` (e.g. |

## Object types

### `LineChartSeries`

Shape of the `series` prop.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | `string` | yes | — |
| `label` | `string` | yes | — |
| `data` | `readonly Datum[]` | yes | — |
| `color` | `string` | no | Series colour. |
| `axis` | `'left' \| 'right'` | no | Which y-axis this series is measured against. |
| `y` | `(d: Datum) => number` | no | Per-series Y accessor. |

## Examples

### Basic line chart

```tsx
import { LineChart } from '@cascivo/charts'

const series = [{ id: 'a', label: 'Revenue', data: [{x:1,y:10},{x:2,y:20},{x:3,y:15}] }]
<LineChart series={series} x={d => d.x} y={d => d.y} title="Revenue" />
```

### With an SLO target line

```tsx
<LineChart
  series={series}
  x={d => d.x}
  y={d => d.y}
  title="Latency"
  annotations={[{ kind: 'line', axis: 'y', value: 200, label: 'SLO' }]}
/>
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-chart-1`
- `--cascivo-chart-2`
- `--cascivo-chart-3`
- `--cascivo-chart-4`
- `--cascivo-chart-5`
- `--cascivo-chart-6`
- `--cascivo-chart-7`
- `--cascivo-chart-8`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `img`
- **Keyboard:** Tab (focus chart), ArrowLeft/ArrowRight (navigate points), Home/End (first/last point), Escape (clear focus)

## Dependencies

- `@cascivo/charts`

## Tags

chart, line, time-series, data-viz

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Meter

Progress meter in bar or gauge variant with threshold coloring.

## Install

Ships in the `@cascivo/charts` package — install it (no copy-paste):

```sh
pnpm add @cascivo/charts
```

```tsx
import { Meter } from '@cascivo/charts'
import '@cascivo/charts/styles.css' // bundler: automatic. Needed only for no-bundler / SSR-externalised builds, where skipping it renders the screen-reader data-table fallback visibly
```

## Category

`chart`

## Variants

- `bar`
- `gauge`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `value` | `number` | yes | — | Current value |
| `label` | `string` | yes | — | Text label for the control. Rendered on screen. |
| `min` | `number` | no | `0` | Minimum allowed value. |
| `max` | `number` | no | `100` | Maximum allowed value. |
| `variant` | `'bar' \| 'gauge'` | no | `bar` | `bar` draws a straight horizontal track; `gauge` draws a half-donut dial. |
| `thresholds` | `MeterThresholds` | no | — | Color breakpoints |
| `width` | `number` | no | — | Fixed SVG width in px. ⚠ **Omit for a responsive chart** — the chart fills and tracks its container via a ResizeObserver; there is no correct pixel number in a responsive grid. A fixed width is clamped to the container (max-inline-size: 100%) so it can never overflow its card, but it also stops the chart growing. `useChartSize` is NOT needed for this — charts call it internally. |
| `height` | `number` | no | — | SVG height in px. Unlike `width`, height does NOT track the container — this is the knob you set to change the chart's aspect. |

## Object types

### `MeterThresholds`

Shape of the `thresholds` prop.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `warning` | `number` | no | — |
| `critical` | `number` | no | — |

## Examples

### Basic meter

```tsx
import { Meter } from '@cascivo/charts'

<Meter value={72} label="CPU usage" />
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-chart-1`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `meter`

## Dependencies

- `@cascivo/charts`

## Tags

chart, meter, gauge, progress, data-viz

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# PieChart

Pie or donut chart with hover segments and optional legend.

## Install

Ships in the `@cascivo/charts` package — install it (no copy-paste):

```sh
pnpm add @cascivo/charts
```

```tsx
import { PieChart } from '@cascivo/charts'
import '@cascivo/charts/styles.css' // bundler: automatic. Needed only for no-bundler / SSR-externalised builds, where skipping it renders the screen-reader data-table fallback visibly
```

## Category

`chart`

## Variants

- `pie`
- `donut`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `data` | `PieChartDatum[]` | yes | — | Array of { id, label, value, color? } datums. Optional per-datum `color` (any CSS color) overrides the positional palette for that slice. |
| `title` | `string` | yes | — | Title text for the component. |
| `description` | `string` | no | — | Supporting description text. |
| `donut` | `boolean` | no | `false` | Render as donut chart |
| `width` | `number` | no | — | Fixed SVG width in px. ⚠ **Omit for a responsive chart** — the chart fills and tracks its container via a ResizeObserver; there is no correct pixel number in a responsive grid. A fixed width is clamped to the container (max-inline-size: 100%) so it can never overflow its card, but it also stops the chart growing. `useChartSize` is NOT needed for this — charts call it internally. |
| `height` | `number` | no | `300` | SVG height in px. Unlike `width`, height does NOT track the container — this is the knob you set to change the chart's aspect. |
| `size` | `number` | no | — | Square shorthand: sets width === height. Explicit width/height win. |
| `thickness` | `number` | no | — | Ring width in px (donut only); defaults to 0.4 × radius. |
| `innerRadius` | `number` | no | — | Inner radius in px (donut only); takes precedence over thickness; clamped to [0, outerRadius). |
| `centerValue` | `string` | no | — | Center value text rendered in the donut hole (donut only). |
| `centerLabel` | `string` | no | — | Center label text rendered below the value (donut only). |
| `centerSlot` | `ReactNode` | no | — | Arbitrary content for the donut hole; takes precedence over centerValue/centerLabel. |
| `emptyLabel` | `string` | no | — | Visible placeholder text when data is empty. Defaults to the i18n "No data". |
| `tooltipFormat` | `(p: ChartPoint) => string` | no | — | Custom tooltip formatter. Defaults to "value (pct%)" in the slice color. |
| `legend` | `boolean` | no | — | Whether to show the legend. |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |
| `plain` | `boolean` | no | `false` | Marks only — no axes, grid lines, or legend. For micro/inline charts. |
| `labels` | `boolean \| { format?: (v: number) => string; position?: string }` | no | — | Print each value as a label on the mark (collision-aware, decorative/aria-hidden). |
| `onSelect` | `(point: ChartPoint) => void` | no | — | Fired when a point is clicked or activated (Enter/Space) — for drill-down. |
| `tooltip` | `boolean` | no | `true` | Show tooltips. Parity with Area/Bar/Line/Combo, which all take this. |

## Object types

### `PieChartDatum`

One slice. Pass via the `data` prop.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | `string` | yes | Stable identity (used for legend toggle state). |
| `label` | `string` | yes | — |
| `value` | `number` | yes | — |
| `color` | `string` | no | Any CSS color overriding the positional palette (--cascivo-chart-N) for this slice. |

### `ChartPoint`

Argument passed to the `tooltipFormat` callback.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `label` | `string` | yes | Slice label. |
| `value` | `number \| string` | yes | — |
| `percent` | `number` | no | Share of the whole, 0–100. Used by the default "value (pct%)" formatter. |
| `color` | `string` | no | Resolved slice color (the default tooltip tints its text with this). |

## Examples

### Basic pie chart

```tsx
import { PieChart } from '@cascivo/charts'

<PieChart data={[{id:'a',label:'A',value:60},{id:'b',label:'B',value:40}]} title="Market share" />
```

### Donut with center total and custom thickness

```tsx
import { PieChart } from '@cascivo/charts'

<PieChart
  donut
  size={220}
  thickness={28}
  centerValue="142"
  centerLabel="Total tasks"
  data={[
    { id: 'done', label: 'Done', value: 92, color: 'var(--cascivo-color-success)' },
    { id: 'wip', label: 'In progress', value: 34, color: 'var(--cascivo-color-warning)' },
    { id: 'blocked', label: 'Blocked', value: 16, color: 'var(--cascivo-color-destructive)' },
  ]}
  title="Task status"
/>
```

### Percentage tooltip + empty state

```tsx
import { PieChart } from '@cascivo/charts'

// Default tooltip shows "value (pct%)" in the slice color; pass tooltipFormat to override.
<PieChart data={[{id:'a',label:'A',value:60},{id:'b',label:'B',value:40}]} title="Share" />

// Empty data renders a visible "No data" placeholder (override via emptyLabel).
<PieChart data={[]} title="Share" emptyLabel="Nothing tracked yet" />
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-chart-1`
- `--cascivo-chart-2`
- `--cascivo-chart-3`
- `--cascivo-chart-4`
- `--cascivo-chart-5`
- `--cascivo-chart-6`
- `--cascivo-chart-7`
- `--cascivo-chart-8`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `img`

## Dependencies

- `@cascivo/charts`

## Tags

chart, pie, donut, data-viz

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Polar

A polar coordinate plot — categories around the circle, value as radius. Bars (a rose), or a polar line/area.

## Install

Ships in the `@cascivo/charts` package — install it (no copy-paste):

```sh
pnpm add @cascivo/charts
```

```tsx
import { Polar } from '@cascivo/charts'
import '@cascivo/charts/styles.css' // bundler: automatic. Needed only for no-bundler / SSR-externalised builds, where skipping it renders the screen-reader data-table fallback visibly
```

## Category

`chart`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `data` | `PolarDatum[]` | yes | — | One entry per category: { label, value, color? }. |
| `title` | `string` | yes | — | Chart title (also aria-label). |
| `description` | `string` | no | — | Supporting description text. |
| `mode` | `'bar' \| 'line' \| 'area'` | no | `bar` | Bars (rose), a polar line, or a filled polar area. |
| `width` | `number` | no | — | Fixed SVG width in px. ⚠ **Omit for a responsive chart** — the chart fills and tracks its container via a ResizeObserver; there is no correct pixel number in a responsive grid. A fixed width is clamped to the container (max-inline-size: 100%) so it can never overflow its card, but it also stops the chart growing. `useChartSize` is NOT needed for this — charts call it internally. |
| `height` | `number` | no | `320` | SVG height in px. Unlike `width`, height does NOT track the container — this is the knob you set to change the chart's aspect. |
| `rings` | `number` | no | `4` | Radial ring count. |
| `max` | `number` | no | — | Domain top (full radius). Defaults to the largest value. |
| `tooltip` | `boolean` | no | — | Enable hover tooltip. |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |
| `plain` | `boolean` | no | `false` | Marks only — no rings or labels. For micro/inline charts. |

## Object types

### `PolarDatum`

Shape of the `data` prop.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `label` | `string` | yes | — |
| `value` | `number` | yes | — |
| `color` | `string` | no | — |

## Examples

### Wind rose

```tsx
import { Polar } from '@cascivo/charts'

<Polar
  title="Wind by direction"
  mode="bar"
  tooltip
  data={[
    { label: 'N', value: 12 },
    { label: 'E', value: 8 },
    { label: 'S', value: 5 },
    { label: 'W', value: 15 },
  ]}
/>
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-chart-1`
- `--cascivo-chart-2`
- `--cascivo-chart-3`
- `--cascivo-chart-4`
- `--cascivo-chart-5`
- `--cascivo-chart-6`
- `--cascivo-chart-7`
- `--cascivo-chart-8`
- `--cascivo-chart-grid`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `img`
- **Keyboard:** Tab (focus chart), ArrowLeft/ArrowRight (navigate), Escape (clear focus)

## Dependencies

- `@cascivo/charts`

## Tags

chart, polar, rose, radial, data-viz

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Radar

Radar / spider chart with polar grid rings, spokes, and multi-series polygon overlays.

## Install

Ships in the `@cascivo/charts` package — install it (no copy-paste):

```sh
pnpm add @cascivo/charts
```

```tsx
import { Radar } from '@cascivo/charts'
import '@cascivo/charts/styles.css' // bundler: automatic. Needed only for no-bundler / SSR-externalised builds, where skipping it renders the screen-reader data-table fallback visibly
```

## Category

`chart`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `axes` | `string[]` | yes | — | Axis labels (one per dimension) |
| `series` | `{ id: string; label: string; values: number[] }[]` | yes | — | One value per axis per series |
| `max` | `number` | no | — | Maximum value (defaults to data max) |
| `title` | `string` | yes | — | Title text for the component. |
| `description` | `string` | no | — | Supporting description text. |
| `width` | `number` | no | — | Fixed SVG width in px. ⚠ **Omit for a responsive chart** — the chart fills and tracks its container via a ResizeObserver; there is no correct pixel number in a responsive grid. A fixed width is clamped to the container (max-inline-size: 100%) so it can never overflow its card, but it also stops the chart growing. `useChartSize` is NOT needed for this — charts call it internally. |
| `height` | `number` | no | `320` | SVG height in px. Unlike `width`, height does NOT track the container — this is the knob you set to change the chart's aspect. |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |
| `plain` | `boolean` | no | `false` | Marks only — no axes, grid lines, or legend. For micro/inline charts. |

## Object types

### `RadarSeries`

Shape of the `series` prop.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | `string` | yes | — |
| `label` | `string` | yes | — |
| `values` | `number[]` | yes | — |

## Examples

### Basic radar chart

```tsx
import { Radar } from '@cascivo/charts'

const axes = ['Speed','Power','Range','Efficiency','Cost']
const series = [{ id:'a', label:'Model A', values:[80,70,60,90,50] }]
<Radar axes={axes} series={series} title="Model comparison" />
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-chart-1`
- `--cascivo-chart-2`
- `--cascivo-chart-3`
- `--cascivo-chart-4`
- `--cascivo-chart-5`
- `--cascivo-chart-6`
- `--cascivo-chart-7`
- `--cascivo-chart-8`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `img`

## Dependencies

- `@cascivo/charts`

## Tags

chart, radar, spider, polar, data-viz

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# RadialBar

Concentric radial bars (a circular gauge family) — each datum is a ring whose sweep is proportional to its value.

## Install

Ships in the `@cascivo/charts` package — install it (no copy-paste):

```sh
pnpm add @cascivo/charts
```

```tsx
import { RadialBar } from '@cascivo/charts'
import '@cascivo/charts/styles.css' // bundler: automatic. Needed only for no-bundler / SSR-externalised builds, where skipping it renders the screen-reader data-table fallback visibly
```

## Category

`chart`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `data` | `RadialBarDatum[]` | yes | — | One ring per datum: { id, label, value, color? }. |
| `title` | `string` | yes | — | Chart title (also used as aria-label). |
| `description` | `string` | no | — | Subtitle below the title. |
| `size` | `number` | no | — | Square shorthand (width === height). Explicit width/height win. |
| `width` | `number` | no | — | Fixed SVG width in px. ⚠ **Omit for a responsive chart** — the chart fills and tracks its container via a ResizeObserver; there is no correct pixel number in a responsive grid. A fixed width is clamped to the container (max-inline-size: 100%) so it can never overflow its card, but it also stops the chart growing. `useChartSize` is NOT needed for this — charts call it internally. |
| `height` | `number` | no | `300` | SVG height in px. Unlike `width`, height does NOT track the container — this is the knob you set to change the chart's aspect. |
| `max` | `number` | no | — | Domain top — the value a full sweep represents. Defaults to the largest datum. |
| `sweep` | `number` | no | `270` | Sweep angle in degrees (270 = a gauge arc; 360 = a full ring). |
| `centerValue` | `string` | no | — | Text in the hole. |
| `centerLabel` | `string` | no | — | Caption below centerValue. |
| `centerSlot` | `ReactNode` | no | — | Arbitrary hole content; wins over centerValue/centerLabel. |
| `tooltip` | `boolean` | no | — | Enable hover tooltip. |
| `legend` | `boolean` | no | — | Show ring legend. |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |
| `plain` | `boolean` | no | `false` | Marks only — no legend. For micro/inline charts. |

## Object types

### `RadialBarDatum`

Shape of the `data` prop.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | `string` | yes | — |
| `label` | `string` | yes | — |
| `value` | `number` | yes | — |
| `color` | `string` | no | CSS color overriding the positional palette for this ring. |

## Examples

### Goal progress rings

```tsx
import { RadialBar } from '@cascivo/charts'

<RadialBar
  title="Quarterly goals"
  max={100}
  centerValue="72%"
  centerLabel="On track"
  data={[
    { id: 'rev', label: 'Revenue', value: 84 },
    { id: 'nps', label: 'NPS', value: 61 },
    { id: 'ret', label: 'Retention', value: 72 },
  ]}
/>
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-chart-1`
- `--cascivo-chart-2`
- `--cascivo-chart-3`
- `--cascivo-chart-4`
- `--cascivo-chart-5`
- `--cascivo-chart-6`
- `--cascivo-chart-7`
- `--cascivo-chart-8`
- `--cascivo-chart-grid`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `img`
- **Keyboard:** Tab (focus chart), ArrowLeft/ArrowRight (navigate rings), Escape (clear focus)

## Dependencies

- `@cascivo/charts`

## Tags

chart, radial, gauge, progress, data-viz

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Sankey

Flow diagram — ranked nodes connected by throughput-sized link ribbons.

## Install

Ships in the `@cascivo/charts` package — install it (no copy-paste):

```sh
pnpm add @cascivo/charts
```

```tsx
import { Sankey } from '@cascivo/charts'
import '@cascivo/charts/styles.css' // bundler: automatic. Needed only for no-bundler / SSR-externalised builds, where skipping it renders the screen-reader data-table fallback visibly
```

## Category

`chart`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `nodes` | `SankeyNode[]` | yes | — | Nodes: { id, label, color? }. |
| `links` | `SankeyLink[]` | yes | — | Links: { source, target, value }. |
| `title` | `string` | yes | — | Title text for the component. |
| `description` | `string` | no | — | Supporting description text. |
| `width` | `number` | no | — | Fixed SVG width in px. ⚠ **Omit for a responsive chart** — the chart fills and tracks its container via a ResizeObserver; there is no correct pixel number in a responsive grid. A fixed width is clamped to the container (max-inline-size: 100%) so it can never overflow its card, but it also stops the chart growing. `useChartSize` is NOT needed for this — charts call it internally. |
| `height` | `number` | no | `320` | SVG height in px. Unlike `width`, height does NOT track the container — this is the knob you set to change the chart's aspect. |
| `tooltip` | `boolean` | no | — | Whether to show tooltips on hover. |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |
| `plain` | `boolean` | no | `false` | When true, renders a minimal variant without chart chrome. |

## Object types

### `SankeyLink`

Shape of the `links` prop.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `source` | `string` | yes | — |
| `target` | `string` | yes | — |
| `value` | `number` | yes | — |

### `SankeyNode`

Shape of the `nodes` prop.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | `string` | yes | — |
| `label` | `string` | yes | — |
| `color` | `string` | no | — |

## Examples

### Sankey flow

```tsx
import { Sankey } from '@cascivo/charts'

<Sankey
  title="Traffic flow"
  nodes={[{ id: 'a', label: 'Search' }, { id: 'b', label: 'Home' }, { id: 'c', label: 'Signup' }]}
  links={[{ source: 'a', target: 'b', value: 30 }, { source: 'b', target: 'c', value: 12 }]}
/>
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-chart-1`
- `--cascivo-chart-2`
- `--cascivo-chart-3`
- `--cascivo-chart-4`
- `--cascivo-chart-5`
- `--cascivo-chart-6`
- `--cascivo-chart-7`
- `--cascivo-chart-8`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `img`
- **Keyboard:** Tab (focus chart), ArrowLeft/ArrowRight (navigate nodes), Escape (clear focus)

## Dependencies

- `@cascivo/charts`

## Tags

chart, sankey, flow, network, data-viz

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# ScatterChart

Scatter plot with variable point radius, multi-series, and hover tooltip.

## Install

Ships in the `@cascivo/charts` package — install it (no copy-paste):

```sh
pnpm add @cascivo/charts
```

```tsx
import { ScatterChart } from '@cascivo/charts'
import '@cascivo/charts/styles.css' // bundler: automatic. Needed only for no-bundler / SSR-externalised builds, where skipping it renders the screen-reader data-table fallback visibly
```

## Category

`chart`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `series` | `ScatterChartSeries[]` | yes | — | The data series to plot. |
| `title` | `string` | yes | — | Title text for the component. |
| `description` | `string` | no | — | Supporting description text. |
| `r` | `number \| ((d: ScatterDatum) => number)` | no | `4` | Point radius or accessor |
| `width` | `number` | no | — | Fixed SVG width in px. ⚠ **Omit for a responsive chart** — the chart fills and tracks its container via a ResizeObserver; there is no correct pixel number in a responsive grid. A fixed width is clamped to the container (max-inline-size: 100%) so it can never overflow its card, but it also stops the chart growing. `useChartSize` is NOT needed for this — charts call it internally. |
| `height` | `number` | no | `300` | SVG height in px. Unlike `width`, height does NOT track the container — this is the knob you set to change the chart's aspect. |
| `xTicks` | `number` | no | `5` | Approximate number of ticks on the x-axis. |
| `yTicks` | `number` | no | `5` | Approximate number of ticks on the y-axis. |
| `legend` | `boolean` | no | — | Whether to show the legend. |
| `tooltip` | `boolean` | no | — | Enable hover/keyboard tooltip |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |
| `plain` | `boolean` | no | `false` | Marks only — no axes, grid lines, or legend. For micro/inline charts. |
| `annotations` | `Annotation[]` | no | — | Reference lines, shaded bands, and markers drawn over the plot (e.g. a target/threshold line). |
| `onSelect` | `(point: ChartPoint) => void` | no | — | Fired when a point is clicked or activated (Enter/Space) — for drill-down. |
| `glyph` | `GlyphShape \| ((d, seriesId) => GlyphShape)` | no | — | Point glyph shape (circle/square/diamond/triangle/cross/star) — a fixed shape or a function to encode a category by shape. |
| `renderer` | `'svg' \| 'canvas' \| 'auto'` | no | `svg` | Renderer — svg (default), canvas (force), or auto (canvas past ~2000 points). Canvas keeps the full a11y fallback table + keyboard layer. |
| `visualMap` | `VisualMapOptions` | no | — | Map each point’s y → CVD-safe colour and/or size via a keyboard-operable legend that filters the visible range. |
| `toolbox` | `boolean \| ToolboxOptions` | no | — | Render a keyboard-reachable toolbox — PNG/SVG export, a data-view table toggle, and restore (reset the visualMap filter). |
| `format` | `(value: number \| string \| Date) => string` | no | — | Format each X-axis tick label. |

## Object types

### `ScatterChartSeries`

Shape of the `series` prop.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | `string` | yes | — |
| `label` | `string` | yes | — |
| `data` | `readonly ScatterDatum[]` | yes | — |
| `color` | `string` | no | — |

### `VisualMapOptions`

Shape of the `visualMap` prop.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `min` | `number` | yes | Domain minimum (value mapped to ramp t=0). |
| `max` | `number` | yes | Domain maximum (value mapped to ramp t=1). |
| `mode` | `VisualMode` | no | `continuous` ramp (default) or `piecewise` buckets. |
| `channel` | `VisualChannel` | no | Which visual channel(s) the value drives. |
| `ramp` | `RampKind` | no | Ramp family — CVD-safe `sequential` (default) or `diverging`. |
| `pieces` | `number` | no | Bucket count for `piecewise` (default 5). |
| `sizeRange` | `[number, number]` | no | [min, max] mark radius in px for the `size` channel (default [3, 14]). |

## Examples

### Basic scatter chart

```tsx
import { ScatterChart } from '@cascivo/charts'

const series = [{ id: 'a', label: 'Group A', data: [{x:1,y:2},{x:3,y:4}] }]
<ScatterChart series={series} title="Scatter" />
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-chart-1`
- `--cascivo-chart-2`
- `--cascivo-chart-3`
- `--cascivo-chart-4`
- `--cascivo-chart-5`
- `--cascivo-chart-6`
- `--cascivo-chart-7`
- `--cascivo-chart-8`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `img`
- **Keyboard:** Tab (focus chart), ArrowLeft/ArrowRight (navigate points), Home/End (first/last point), Escape (clear focus)

## Dependencies

- `@cascivo/charts`

## Tags

chart, scatter, plot, data-viz

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Sparkline

Compact inline sparkline for embedding trend data in dashboards or KPI cards.

## Install

Ships in the `@cascivo/charts` package — install it (no copy-paste):

```sh
pnpm add @cascivo/charts
```

```tsx
import { Sparkline } from '@cascivo/charts'
import '@cascivo/charts/styles.css' // bundler: automatic. Needed only for no-bundler / SSR-externalised builds, where skipping it renders the screen-reader data-table fallback visibly
```

## Category

`chart`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `data` | `number[]` | yes | — | Array of numeric values |
| `label` | `string` | no | — | Accessible name for the chart (invisible — rendered as the SVG `<title>`). Not rendered — screen readers only. |
| `ariaLabel` | `string` | no | — | Alias for `label` (the catalog convention for an invisible accessible name). Both work; pass exactly one. Not rendered — screen readers only. |
| `width` | `number` | no | `120` | SVG width in px. **This chart is fixed-width by default** — it is a compact, inline chart meant to sit in a table cell or beside a label, so omitting `width` gives you 120px rather than a container-filling chart. Pass a number to change it. The catalogue-wide "omit for a responsive chart" note does not apply to this chart. |
| `height` | `number` | no | `32` | SVG height in px. Unlike `width`, height does NOT track the container — this is the knob you set to change the chart's aspect. |
| `color` | `string` | no | `'var(--cascivo-chart-1)'` | Stroke color (CSS value) |
| `endDot` | `boolean` | no | `true` | Show dot at last data point |

## Examples

### Inline sparkline

```tsx
import { Sparkline } from '@cascivo/charts'

<Sparkline data={[10, 20, 15, 30, 25]} label="Trend" endDot />
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-chart-1`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `img`

## Dependencies

- `@cascivo/charts`

## Tags

chart, sparkline, inline, trend, data-viz

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Stream

Streamgraph — stacked areas on a centered (silhouette) flowing baseline.

## Install

Ships in the `@cascivo/charts` package — install it (no copy-paste):

```sh
pnpm add @cascivo/charts
```

```tsx
import { Stream } from '@cascivo/charts'
import '@cascivo/charts/styles.css' // bundler: automatic. Needed only for no-bundler / SSR-externalised builds, where skipping it renders the screen-reader data-table fallback visibly
```

## Category

`chart`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `series` | `StreamSeries[]` | yes | — | Series, each with values[] aligned to categories. |
| `categories` | `(string \| number)[]` | yes | — | X-axis labels aligned with each series values. |
| `title` | `string` | yes | — | Title text for the component. |
| `description` | `string` | no | — | Supporting description text. |
| `offset` | `'silhouette' \| 'zero'` | no | `silhouette` | silhouette centers the stack (streamgraph); zero is a baseline stack. |
| `curve` | `Curve` | no | `basis` | Interpolation curve. |
| `width` | `number` | no | — | Fixed SVG width in px. ⚠ **Omit for a responsive chart** — the chart fills and tracks its container via a ResizeObserver; there is no correct pixel number in a responsive grid. A fixed width is clamped to the container (max-inline-size: 100%) so it can never overflow its card, but it also stops the chart growing. `useChartSize` is NOT needed for this — charts call it internally. |
| `height` | `number` | no | `300` | SVG height in px. Unlike `width`, height does NOT track the container — this is the knob you set to change the chart's aspect. |
| `legend` | `boolean` | no | — | Whether to show the legend. |
| `tooltip` | `boolean` | no | — | Whether to show tooltips on hover. |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |
| `plain` | `boolean` | no | `false` | When true, renders a minimal variant without chart chrome. |
| `format` | `(value: number \| string \| Date) => string` | no | — | Format each category/x-axis tick label. |

## Object types

### `StreamSeries`

Shape of the `series` prop.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | `string` | yes | — |
| `label` | `string` | yes | — |
| `values` | `number[]` | yes | One value per category, aligned with `categories`. |
| `color` | `string` | no | — |

## Examples

### Streamgraph

```tsx
import { Stream } from '@cascivo/charts'

<Stream
  title="Topics over time"
  categories={['Jan','Feb','Mar','Apr']}
  series={[
    { id: 'a', label: 'A', values: [4, 6, 5, 8] },
    { id: 'b', label: 'B', values: [2, 3, 7, 4] },
  ]}
/>
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-chart-1`
- `--cascivo-chart-2`
- `--cascivo-chart-3`
- `--cascivo-chart-4`
- `--cascivo-chart-5`
- `--cascivo-chart-6`
- `--cascivo-chart-7`
- `--cascivo-chart-8`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `img`
- **Keyboard:** Tab (focus chart), ArrowLeft/ArrowRight (navigate), Escape (clear focus)

## Dependencies

- `@cascivo/charts`

## Tags

chart, stream, streamgraph, area, data-viz

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Sunburst

Radial hierarchy — concentric rings where each node is an annular segment sized by value.

## Install

Ships in the `@cascivo/charts` package — install it (no copy-paste):

```sh
pnpm add @cascivo/charts
```

```tsx
import { Sunburst } from '@cascivo/charts'
import '@cascivo/charts/styles.css' // bundler: automatic. Needed only for no-bundler / SSR-externalised builds, where skipping it renders the screen-reader data-table fallback visibly
```

## Category

`chart`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `data` | `HierNode` | yes | — | Root of the tree; leaves carry value, parents sum their children. |
| `title` | `string` | yes | — | Title text for the component. |
| `description` | `string` | no | — | Supporting description text. |
| `size` | `number` | no | — | Square shorthand (width === height). |
| `width` | `number` | no | — | Fixed SVG width in px. ⚠ **Omit for a responsive chart** — the chart fills and tracks its container via a ResizeObserver; there is no correct pixel number in a responsive grid. A fixed width is clamped to the container (max-inline-size: 100%) so it can never overflow its card, but it also stops the chart growing. `useChartSize` is NOT needed for this — charts call it internally. |
| `height` | `number` | no | `300` | SVG height in px. Unlike `width`, height does NOT track the container — this is the knob you set to change the chart's aspect. |
| `tooltip` | `boolean` | no | — | Whether to show tooltips on hover. |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |
| `plain` | `boolean` | no | `false` | When true, renders a minimal variant without chart chrome. |

## Object types

### `HierNode`

Shape of the `data` prop.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | `string` | no | — |
| `label` | `string` | yes | — |
| `value` | `number` | no | — |
| `color` | `string` | no | — |
| `children` | `HierNode[]` | no | — |

## Examples

### Sunburst

```tsx
import { Sunburst } from '@cascivo/charts'

<Sunburst
  title="Disk usage"
  data={{ label: 'root', children: [
    { label: 'src', children: [{ label: 'app', value: 40 }, { label: 'lib', value: 25 }] },
    { label: 'docs', value: 15 },
  ] }}
/>
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-chart-1`
- `--cascivo-chart-2`
- `--cascivo-chart-3`
- `--cascivo-chart-4`
- `--cascivo-chart-5`
- `--cascivo-chart-6`
- `--cascivo-chart-7`
- `--cascivo-chart-8`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `img`
- **Keyboard:** Tab (focus chart), ArrowLeft/ArrowRight (navigate nodes), Escape (clear focus)

## Dependencies

- `@cascivo/charts`

## Tags

chart, sunburst, hierarchy, radial, data-viz

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Treemap

Squarified treemap for visualizing part-to-whole hierarchical data.

## Install

Ships in the `@cascivo/charts` package — install it (no copy-paste):

```sh
pnpm add @cascivo/charts
```

```tsx
import { Treemap } from '@cascivo/charts'
import '@cascivo/charts/styles.css' // bundler: automatic. Needed only for no-bundler / SSR-externalised builds, where skipping it renders the screen-reader data-table fallback visibly
```

## Category

`chart`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `data` | `{ id: string; label: string; value: number }[]` | yes | — | The hierarchical data to render as nested rectangles. |
| `title` | `string` | yes | — | Title text for the component. |
| `description` | `string` | no | — | Supporting description text. |
| `width` | `number` | no | — | Fixed SVG width in px. ⚠ **Omit for a responsive chart** — the chart fills and tracks its container via a ResizeObserver; there is no correct pixel number in a responsive grid. A fixed width is clamped to the container (max-inline-size: 100%) so it can never overflow its card, but it also stops the chart growing. `useChartSize` is NOT needed for this — charts call it internally. |
| `height` | `number` | no | `320` | SVG height in px. Unlike `width`, height does NOT track the container — this is the knob you set to change the chart's aspect. |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |
| `plain` | `boolean` | no | `false` | Marks only — no axes, grid lines, or legend. For micro/inline charts. |

## Object types

### `TreemapDatum`

Shape of the `data` prop.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | `string` | yes | — |
| `label` | `string` | yes | — |
| `value` | `number` | yes | — |

## Examples

### Basic treemap

```tsx
import { Treemap } from '@cascivo/charts'

const data = [
  {id:'a',label:'Alpha',value:40},
  {id:'b',label:'Beta',value:25},
  {id:'c',label:'Gamma',value:20},
  {id:'d',label:'Delta',value:15},
]
<Treemap data={data} title="Market share" />
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-chart-1`
- `--cascivo-chart-2`
- `--cascivo-chart-3`
- `--cascivo-chart-4`
- `--cascivo-chart-5`
- `--cascivo-chart-6`
- `--cascivo-chart-7`
- `--cascivo-chart-8`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `img`

## Dependencies

- `@cascivo/charts`

## Tags

chart, treemap, hierarchy, part-to-whole, data-viz

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# ChatBubble

Message bubble for chat and messaging UIs with avatar, name, and timestamp support

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add chat-bubble
```

Or use it from the prebuilt package without copying:

```tsx
import { ChatBubble } from '@cascivo/react'
```

## Category

`display`

## Variants

- `start`
- `end`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `children` | `React.ReactNode` | yes | — | Content rendered inside the component. |
| `side` | `'start' \| 'end'` | no | `start` | Which side of the thread the bubble sits on: `start` for an incoming message (avatar first), `end` for an outgoing one (right-aligned, avatar last). |
| `avatar` | `React.ReactNode` | no | — | Avatar element shown beside the message. |
| `name` | `string` | no | — | Display name of the message sender. |
| `time` | `string` | no | — | Timestamp text shown with the message. |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |

## Examples

### Incoming message

Message from another user, aligned to the start

```tsx
<ChatBubble side="start" name="Alice" time="10:42 AM">Hey, how are you?</ChatBubble>
```

### Outgoing message

Current user message, aligned to the end with accent background

```tsx
<ChatBubble side="end" time="10:43 AM">Doing great, thanks!</ChatBubble>
```

### With avatar

Message with an avatar beside the bubble

```tsx
<ChatBubble side="start" avatar={<Avatar src="/alice.png" size="sm" />} name="Alice">See you tomorrow!</ChatBubble>
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-color-surface`
- `--cascivo-color-text`
- `--cascivo-color-text-muted`
- `--cascivo-color-text-subtle`
- `--cascivo-color-accent`
- `--cascivo-color-accent-content`
- `--cascivo-radius-overlay`
- `--cascivo-radius-indicator`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `none`

## Tags

chat, message, conversation, messaging

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Checkbox

Binary toggle for forms, with indeterminate support

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add checkbox
```

Or use it from the prebuilt package without copying:

```tsx
import { Checkbox } from '@cascivo/react'
```

## Category

`inputs`

## States

- `unchecked`
- `checked`
- `indeterminate`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `label` | `string` | no | — | Text label for the control. Rendered on screen. |
| `checked` | `boolean` | no | — | Whether the control is checked (controlled). |
| `indeterminate` | `boolean` | no | `false` | When true, renders the mixed/indeterminate state. |
| `disabled` | `boolean` | no | `false` | When true, disables the control and removes it from the tab order. |
| `onChange` | `React.ChangeEventHandler<HTMLInputElement>` | no | — | Called when the value changes. |
| `ariaLabel` | `string` | no | — | Invisible accessible name, for when a visible element outside this component already labels it and `label` would render that text a second time. ⚠ `label` on this component is **visible**; `IconButton.label`/`Sparkline.label` are invisible names, which is the prior that costs adopters a duplicated label. The raw DOM `aria-label` still wins over this. Not rendered — screen readers only. |

## Examples

### With label

```tsx
<Checkbox label="Accept terms" />
```

### Indeterminate

```tsx
<Checkbox label="Select all" indeterminate />
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-color-surface`
- `--cascivo-color-accent`
- `--cascivo-color-border-strong`
- `--cascivo-color-text-on-accent`
- `--cascivo-radius-sm`
- `--cascivo-focus-ring`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `checkbox`
- **Keyboard:** Space

## Dependencies

- `@cascivo/core`

## Tags

form, toggle, boolean

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# CheckboxCard

Multi-selectable card backed by a native checkbox. Use multiple independent CheckboxCards for multi-select scenarios.

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add checkbox-card
```

Or use it from the prebuilt package without copying:

```tsx
import { CheckboxCard } from '@cascivo/react'
```

## Category

`inputs`

## States

- `default`
- `checked`
- `disabled`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `title` | `ReactNode` | yes | — | Card title |
| `description` | `ReactNode` | no | — | Optional description |
| `checked` | `boolean` | no | — | Controlled checked state |
| `defaultChecked` | `boolean` | no | — | Uncontrolled default |
| `onCheckedChange` | `(checked: boolean) => void` | no | — | Change callback |
| `disabled` | `boolean` | no | — | Disables the card |

## Examples

### Feature toggles

Multi-select feature toggles

```tsx
<div style={{ display: 'grid', gap: 12 }}>
  <CheckboxCard title="Automated backups" description="Daily snapshots, 30-day retention" defaultChecked />
  <CheckboxCard title="Monitoring" description="Metrics + alerting" />
  <CheckboxCard title="Audit log" description="Requires Team plan" disabled />
</div>
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-color-accent`
- `--cascivo-color-border`
- `--cascivo-radius-surface`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `checkbox`
- **Keyboard:** Space

## Dependencies

- `@cascivo/core`

## Tags

checkbox, card, selectable, form

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Code

Inline code span for identifiers, commands, and short snippets

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add code
```

Or use it from the prebuilt package without copying:

```tsx
import { Code } from '@cascivo/react'
```

## Category

`display`

## Sizes

- `sm`
- `md`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `size` | `'sm' \| 'md'` | no | `md` | Visual size of the component (e.g. 'sm', 'md', 'lg'). |

## Examples

### Default

```tsx
<Code>npx cascivo add button</Code>
```

### In a sentence

Sits inline with surrounding text

```tsx
<Text>Run <Code>vp check</Code> before committing.</Text>
```

### Small

```tsx
<Code size="sm">--cascivo-color-accent</Code>
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-font-mono`
- `--cascivo-color-text`
- `--cascivo-color-surface`
- `--cascivo-color-border`
- `--cascivo-radius-indicator`
- `--cascivo-text-xs`
- `--cascivo-text-sm`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `code`

## Dependencies

- `@cascivo/core`

## Tags

typography, code, inline, mono

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# 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

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add code-snippet
```

Or use it from the prebuilt package without copying:

```tsx
import { CodeSnippet } from '@cascivo/react'
```

## Category

`display`

## Variants

- `inline`
- `single`
- `multi`

## States

- `idle`
- `copied`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `code` | `string` | no | — | The code to display (and copy). Equivalent to passing a plain string as `children`; `code` wins if both are given, and one of the two is required. A string rather than a ReactNode because the content is tokenized for highlighting and handed to the clipboard. |
| `children` | `string` | no | — | The code, as children — `<CodeSnippet>npm i foo</CodeSnippet>`. Must be a plain string (interpolation is fine, arbitrary elements are not). |
| `variant` | `'inline' \| 'single' \| 'multi'` | no | `single` | inline = a <code> span; single = one-line <pre>; multi = multi-line <pre>. |
| `language` | `'bash' \| 'css' \| 'js' \| 'ts'` | no | — | Enables built-in syntax highlighting for the block variants; inline is never highlighted. |
| `terminal` | `boolean` | no | `false` | Renders terminal-window chrome (title bar with dots). Block variants only. |
| `title` | `string` | no | — | Optional label shown in the terminal title bar. |
| `showLineNumbers` | `boolean` | no | — | Show line numbers (multi only; ignored when language is set). |
| `showCopyButton` | `boolean` | no | — | Show the copy-to-clipboard button. Defaults true for single/multi, false for inline. |
| `labels` | `{ copy?: string; copied?: string }` | no | — | Overrides for the component’s user-visible strings (i18n). |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |

## Examples

### Install command

```tsx
<CodeSnippet code="npx cascivo add button" language="bash" />
```

### Inline

```tsx
<p>Run <CodeSnippet variant="inline" code="pnpm build" /> first.</p>
```

### Terminal block

Multi-line shell transcript with terminal-window chrome.

```tsx
<CodeSnippet
  variant="multi"
  language="bash"
  terminal
  title="deploy.sh"
  code={'pnpm build\npnpm deploy'}
/>
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-font-mono`
- `--cascivo-color-text`
- `--cascivo-color-text-muted`
- `--cascivo-color-bg-subtle`
- `--cascivo-color-surface`
- `--cascivo-color-border`
- `--cascivo-radius-surface`
- `--cascivo-radius-control`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `group`
- **Keyboard:** Enter, Space

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

display, code, snippet, copy, pre, syntax-highlighting, terminal, bash, css, js, ts

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Collapsible

A single disclosure region toggled open and closed by its trigger

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add collapsible
```

Or use it from the prebuilt package without copying:

```tsx
import { Collapsible } from '@cascivo/react'
```

## Category

`display`

## States

- `open`
- `closed`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `open` | `boolean` | no | — | Controlled open state |
| `defaultOpen` | `boolean` | no | `false` | Initial open state for uncontrolled use |
| `onOpenChange` | `(open: boolean) => void` | no | — | Called whenever the open state should change |
| `trigger` | `ReactNode` | yes | — | Content rendered inside the built-in trigger button |
| `disabled` | `boolean` | no | `false` | Disables the trigger. Enforced in the enhancement layer — <details> has no native disabled state, so with JavaScript off a disabled Collapsible is still operable |
| `children` | `ReactNode` | no | — | Content of the collapsible region |

## Examples

### Uncontrolled

```tsx
<Collapsible trigger="Show details">
  <p>Hidden content revealed on toggle.</p>
</Collapsible>
```

### Open by default

```tsx
<Collapsible defaultOpen trigger="Details">
  <p>Visible initially.</p>
</Collapsible>
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-color-text`
- `--cascivo-color-text-subtle`
- `--cascivo-color-border`
- `--cascivo-color-bg-subtle`
- `--cascivo-radius-control`
- `--cascivo-focus-ring`
- `--cascivo-space-3`
- `--cascivo-duration-200`
- `--cascivo-ease-out`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `button`
- **Keyboard:** Enter, Space

## Dependencies

- `@cascivo/core`

## Tags

disclosure, collapse, expand, toggle, show-hide

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# ColorPicker

Interactive color selection widget with saturation/lightness area, hue and alpha sliders

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add color-picker
```

Or use it from the prebuilt package without copying:

```tsx
import { ColorPicker } from '@cascivo/react'
```

## Category

`inputs`

## Sizes

- `sm`
- `md`
- `lg`

## States

- `default`
- `disabled`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `labels` | `ColorPickerLabels` | no | — | Overrides for the component’s user-visible strings (i18n). |
| `value` | `string` | no | — | Controlled hex color value |
| `defaultValue` | `string` | no | `#3b82f6` | The initial value when uncontrolled. |
| `onValueChange` | `(value: string) => void` | no | — | Called with the new value when it changes. |
| `presets` | `string[]` | no | — | Preset swatch colors |
| `alpha` | `boolean` | no | `true` | When true, enables alpha (opacity) selection. |
| `format` | `'hex' \| 'rgb' \| 'hsl'` | no | `'hex'` | Notation for the emitted value. Alpha is included whenever alpha is on, so the emitted string has a stable width. |
| `name` | `string` | no | — | Submitted with a surrounding form — a hidden input carrying the current value. |
| `label` | `string` | no | — | Text label for the control. Rendered on screen. |
| `disabled` | `boolean` | no | `false` | When true, disables the control and removes it from the tab order. |
| `size` | `'sm' \| 'md' \| 'lg'` | no | `md` | Visual size of the component (e.g. 'sm', 'md', 'lg'). |
| `aria-labelledby` | `string` | no | — | Wired automatically by a wrapping `Field` — its label id, forwarded to the focusable control so the Field's label names it. |
| `aria-describedby` | `string` | no | — | Wired automatically by a wrapping `Field` — the ids of its hint/error text, forwarded to the focusable control so the supporting text is announced. |
| `aria-invalid` | `boolean` | no | — | Wired automatically by a wrapping `Field` when it is in an error state. |
| `id` | `string` | no | — | Id for the **focusable control** (not the wrapper), so a `<label for>` names what actually takes focus. `Field` supplies this automatically. |
| `ariaLabel` | `string` | no | — | Invisible accessible name, for when a visible element outside this component already labels it and `label` would render that text a second time. ⚠ `label` on this component is **visible**; `IconButton.label`/`Sparkline.label` are invisible names, which is the prior that costs adopters a duplicated label. The raw DOM `aria-label` still wins over this. Not rendered — screen readers only. |

## Examples

### Basic

```tsx
<ColorPicker defaultValue="#3b82f6" onValueChange={setColor} />
```

### With presets

```tsx
<ColorPicker presets={["#ef4444", "#3b82f6", "#10b981"]} alpha={false} />
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-accent`
- `--cascivo-color-surface`
- `--cascivo-color-border`
- `--cascivo-color-border-strong`
- `--cascivo-radius-md`
- `--cascivo-radius-full`
- `--cascivo-focus-ring`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `group`
- **Keyboard:** ArrowLeft, ArrowRight, ArrowUp, ArrowDown, Home, End, PageUp, PageDown, Enter, Escape

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

color, input, form, picker, hue, alpha

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Combobox

Filterable single-select with an animated custom listbox, built on the dropdown open/close machine

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add combobox
```

Or use it from the prebuilt package without copying:

```tsx
import { Combobox } from '@cascivo/react'
```

## Category

`inputs`

## Sizes

- `sm`
- `md`
- `lg`

## States

- `closed`
- `open`
- `error`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `id` | `string` | no | — | Base id for the input and its listbox/aria wiring; auto-generated when omitted. |
| `options` | `ComboboxOption[]` | yes | — | The selectable options. |
| `value` | `string` | no | — | The controlled value. |
| `defaultValue` | `string` | no | — | The initial value when uncontrolled. |
| `onValueChange` | `(value: string \| undefined) => void` | no | — | Called with the selected option value (or undefined when cleared). |
| `clearable` | `boolean` | no | `false` | When true, shows a control to clear the selected value. |
| `searchable` | `boolean` | no | `true` | When true the field is a text input that filters the list as the user types (the APG editable combobox). When false it is a button that opens the list, and type-to-select jumps to a matching option (the APG select-only combobox). |
| `loading` | `boolean` | no | `false` | When true, the list reports itself as busy and shows a loading row instead of the empty message. |
| `onSearchChange` | `(query: string) => void` | no | — | Called with the search text on every keystroke. Pair it with filter={() => true} for a server-driven list. |
| `filter` | `(option: ComboboxOption, query: string) => boolean` | no | — | Replaces the built-in diacritic-insensitive matcher. |
| `creatable` | `boolean` | no | `false` | When true, offers the current search text as a new option. |
| `onCreate` | `(label: string) => void` | no | — | Called with the typed label when the user picks the "create" row. |
| `name` | `string` | no | — | Submitted with a surrounding form — a hidden input carrying the selected value. |
| `required` | `boolean` | no | — | Marks the control as required for assistive technology. |
| `open` | `boolean` | no | — | Controlled open state of the listbox. |
| `defaultOpen` | `boolean` | no | `false` | The initial open state when uncontrolled. |
| `onOpenChange` | `(open: boolean) => void` | no | — | Called when the listbox opens or closes. |
| `label` | `string` | no | — | Text label for the control. Rendered on screen. |
| `hint` | `string` | no | — | Supplementary hint text shown with the control. |
| `error` | `string` | no | — | Error message shown when the value is invalid. |
| `size` | `'sm' \| 'md' \| 'lg'` | no | `'md'` | Visual size of the component (e.g. 'sm', 'md', 'lg'). |
| `disabled` | `boolean` | no | `false` | When true, disables the control and removes it from the tab order. |
| `labels` | `ComboboxLabels` | no | — | Overrides for the component’s user-visible strings (i18n). |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |
| `aria-labelledby` | `string` | no | — | Wired automatically by a wrapping `Field` — its label id, forwarded to the focusable control so the Field's label names it. |
| `aria-describedby` | `string` | no | — | Wired automatically by a wrapping `Field` — the ids of its hint/error text, forwarded to the focusable control so the supporting text is announced. |
| `aria-invalid` | `boolean` | no | — | Wired automatically by a wrapping `Field` when it is in an error state. |
| `ariaLabel` | `string` | no | — | Invisible accessible name, for when a visible element outside this component already labels it and `label` would render that text a second time. ⚠ `label` on this component is **visible**; `IconButton.label`/`Sparkline.label` are invisible names, which is the prior that costs adopters a duplicated label. The raw DOM `aria-label` still wins over this. Not rendered — screen readers only. |

## Examples

### Grouped options

Options carrying a group render under a labelled role="group" heading.

```tsx
<Combobox options={[{value:'de',label:'Germany',group:'Europe'},{value:'jp',label:'Japan',group:'Asia'}]} />
```

### Remote search

filter={() => true} hands filtering to the server; loading marks the list busy between keystroke and response.

```tsx
<Combobox options={results} loading={pending} onSearchChange={search} filter={() => true} />
```

### Select-only

A button rather than a text field; printable characters type-to-select, and Home/End jump the list.

```tsx
<Combobox options={options} searchable={false} />
```

### Basic combobox

```tsx
<Combobox
  label="Country"
  options={[
    { value: 'us', label: 'United States' },
    { value: 'de', label: 'Germany' },
    { value: 'fr', label: 'France' },
  ]}
  onValueChange={(value) => console.log(value)}
/>
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-accent-text`
- `--cascivo-color-surface`
- `--cascivo-color-surface-overlay`
- `--cascivo-color-bg-subtle`
- `--cascivo-color-border`
- `--cascivo-color-border-strong`
- `--cascivo-color-text`
- `--cascivo-color-text-muted`
- `--cascivo-color-text-subtle`
- `--cascivo-color-accent`
- `--cascivo-color-destructive`
- `--cascivo-font-medium`
- `--cascivo-font-bold`
- `--cascivo-radius-field`
- `--cascivo-radius-overlay`
- `--cascivo-radius-item`
- `--cascivo-radius-control`
- `--cascivo-shadow-overlay`
- `--cascivo-motion-enter`
- `--cascivo-z-dropdown`
- `--cascivo-target-min-coarse`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `combobox`
- **Keyboard:** ArrowDown, ArrowUp, Home, End, PageUp, PageDown, Enter, Space, Escape, Tab

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

select, combobox, dropdown, filter, search

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# CommandMenu

Cmd+K command palette with fuzzy search over grouped commands

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add command-menu
```

Or use it from the prebuilt package without copying:

```tsx
import { CommandMenu } from '@cascivo/react'
```

## Category

`overlay`

## States

- `closed`
- `open`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `open` | `boolean` | yes | — | Whether the component is open (controlled). |
| `onOpenChange` | `(open: boolean) => void` | yes | — | Called with the next open state when it changes. |
| `groups` | `CommandGroup[]` | yes | — | The grouped commands to display. |
| `placeholder` | `string` | no | `Type a command or search…` | Placeholder text shown when the field is empty. |
| `emptyLabel` | `string` | no | `No results found` | Text shown when no commands match the query. |
| `hotkey` | `boolean` | no | `true` | Global Cmd/Ctrl+K toggles the menu via onOpenChange |
| `ariaLabel` | `string` | no | — | Alias of `label` — the same invisible accessible name under the catalog spelling. Neither is deprecated. Not rendered — screen readers only. |
| `label` | `string` | no | `Command menu` | Accessible name for the command dialog. Not rendered — screen readers only. |
| `loading` | `boolean` | no | `false` | Shows a loading spinner in place of the empty state (for async items) |
| `onQueryChange` | `(query: string) => void` | no | — | Fires on every query keystroke — use to fetch async items |
| `scopes` | `CommandScope[]` | no | `[]` | Selectable filter scopes. Renders a scope bar + chip; a scope activates by clicking its pill, typing its prefix (c:/c ), or cycling with Tab, and filters to groups tagged with a matching scope (plus untagged groups). |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |

## Examples

### Basic command menu

```tsx
<CommandMenu
  open={open}
  onOpenChange={setOpen}
  groups={[
    {
      heading: 'Actions',
      items: [
        { id: 'new', label: 'New file', shortcut: ['⌘', 'N'], onSelect: createFile },
        { id: 'search', label: 'Search docs', keywords: ['find'], onSelect: openSearch },
      ],
    },
  ]}
/>
```

### Scoped search with rich rows and inline actions

A scope chip filters to Clusters, matched glyphs are highlighted, each row carries a mono metadata line + status pill, and the selected row reveals Open (↵) / New tab (⌘↵) inline actions.

```tsx
<CommandMenu
  open={open}
  onOpenChange={setOpen}
  scopes={[
    { id: 'clusters', label: 'Clusters', prefix: 'c' },
    { id: 'orgs', label: 'Orgs', prefix: 'o' },
    { id: 'commands', label: 'Commands', prefix: '>' },
  ]}
  groups={[
    {
      heading: 'Clusters',
      scope: 'clusters',
      items: [
        {
          id: 'prod-eu',
          label: 'prod-eu-central-1',
          description: 'eu-central-1 · Enterprise · c9f21a04',
          status: { label: 'Healthy', tone: 'healthy' },
          actions: [
            { id: 'open', label: 'Open', shortcut: ['↵'], onSelect: () => open('prod-eu') },
            { id: 'tab', label: 'New tab', shortcut: ['⌘', '↵'], onSelect: () => openInTab('prod-eu') },
          ],
        },
      ],
    },
  ]}
/>
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-surface-overlay`
- `--cascivo-color-border`
- `--cascivo-color-bg-subtle`
- `--cascivo-color-text`
- `--cascivo-color-text-muted`
- `--cascivo-color-text-subtle`
- `--cascivo-color-accent-content`
- `--cascivo-color-accent-muted`
- `--cascivo-color-accent-subtle`
- `--cascivo-color-success-subtle`
- `--cascivo-color-success-foreground`
- `--cascivo-color-warning-subtle`
- `--cascivo-color-warning-foreground`
- `--cascivo-font-mono`
- `--cascivo-radius-modal`
- `--cascivo-radius-sm`
- `--cascivo-shadow-xl`
- `--cascivo-motion-enter`
- `--cascivo-motion-exit`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `combobox`
- **Keyboard:** Cmd/Ctrl+K, ArrowDown, ArrowUp, Home, End, Enter, Cmd/Ctrl+Enter, Tab, Backspace, Escape

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

overlay, command, palette, search, cmdk, keyboard, scope, fuzzy

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Comparison

Reveals the difference between two layers with a draggable divider

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add comparison
```

Or use it from the prebuilt package without copying:

```tsx
import { Comparison } from '@cascivo/react'
```

## Category

`display`

## States

- `default`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `after` | `ReactNode` | yes | — | Base layer shown underneath |
| `before` | `ReactNode` | yes | — | Top layer revealed up to the divider |
| `position` | `number` | no | — | Divider position 0–100 (controlled) |
| `defaultPosition` | `number` | no | `50` | The initial divider position (0–100) when uncontrolled. |
| `onPositionChange` | `(position: number) => void` | no | — | Called with the new divider position when it changes. |
| `orientation` | `'horizontal' \| 'vertical'` | no | `horizontal` | Axis you drag along. `horizontal` splits the two images left and right with a vertical divider; `vertical` splits them top and bottom with a horizontal one. |
| `keyboardStep` | `number` | no | `5` | How far the divider moves per arrow-key press. |
| `ariaLabel` | `string` | no | — | Alias of `label` — the same invisible accessible name under the catalog spelling. Neither is deprecated. Not rendered — screen readers only. |
| `label` | `string` | no | — | Accessible name for the divider slider. Not rendered — screen readers only. |

## Examples

### Image before/after

```tsx
<Comparison before={<img src="/edited.jpg" alt="" />} after={<img src="/original.jpg" alt="Original" />} label="Reveal edited image" />
```

### Vertical

```tsx
<Comparison orientation="vertical" before={<Before />} after={<After />} />
```

### Controlled

```tsx
<Comparison position={position} onPositionChange={setPosition} before={<Before />} after={<After />} />
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-radius-md`
- `--cascivo-radius-full`
- `--cascivo-color-surface`
- `--cascivo-color-border`
- `--cascivo-color-focus-ring`
- `--cascivo-shadow-sm`
- `--cascivo-target-min-coarse`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `slider`
- **Keyboard:** ArrowLeft, ArrowRight, ArrowUp, ArrowDown, Home, End, PageUp, PageDown

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

comparison, before-after, image, slider, display

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# ContainedList

Labelled list of rows inside a bordered container

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add contained-list
```

Or use it from the prebuilt package without copying:

```tsx
import { ContainedList } from '@cascivo/react'
```

## Category

`display`

## Variants

- `on-page`
- `disclosed`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `label` | `ReactNode` | yes | — | Text label for the control. Rendered on screen. |
| `kind` | `'on-page' \| 'disclosed'` | no | `on-page` | Visual treatment — 'on-page' or 'disclosed'. |
| `action` | `ReactNode` | no | — | Primary action shown in the component. |

## Examples

### Basic contained list

```tsx
<ContainedList label="Members">
  <ContainedListItem>Ada Lovelace</ContainedListItem>
  <ContainedListItem>Alan Turing</ContainedListItem>
</ContainedList>
```

### Interactive rows

```tsx
<ContainedList label="Settings" kind="disclosed">
  <ContainedListItem asChild>
    <button type="button" onClick={open}>Profile</button>
  </ContainedListItem>
</ContainedList>
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-color-surface`
- `--cascivo-color-border`
- `--cascivo-color-bg-subtle`
- `--cascivo-radius-surface`
- `--cascivo-focus-ring`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `list`
- **Keyboard:** Tab, Enter, Space

## Dependencies

- `@cascivo/core`

## Tags

list, container, rows, group

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# ContextMenu

Right-click context menu anchored at pointer coordinates via CSS custom properties

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add context-menu
```

Or use it from the prebuilt package without copying:

```tsx
import { ContextMenu } from '@cascivo/react'
```

## Category

`overlay`

## States

- `open`
- `closed`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `children` | `React.ReactNode` | yes | — | The right-click target first, followed by ContextMenuItem children. |

## Examples

### Basic

```tsx
<ContextMenu>
  <div>Right-click me</div>
  <ContextMenuItem onSelect={rename}>Rename</ContextMenuItem>
  <ContextMenuItem onSelect={remove}>Delete</ContextMenuItem>
</ContextMenu>
```

### Disabled item

```tsx
<ContextMenu>
  <FileRow file={file} />
  <ContextMenuItem onSelect={copy}>Copy</ContextMenuItem>
  <ContextMenuItem onSelect={paste} disabled>Paste</ContextMenuItem>
</ContextMenu>
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-surface`
- `--cascivo-color-border`
- `--cascivo-radius-md`
- `--cascivo-shadow-md`
- `--cascivo-motion-enter`
- `--cascivo-motion-exit`
- `--cascivo-color-bg-subtle`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `menu`
- **Keyboard:** ArrowDown, ArrowUp, Home, End, Enter, Space, Escape

## Dependencies

- `@cascivo/core`

## Tags

overlay, menu, context, right-click

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# ContextMeter

How much of a model’s context window a conversation has used — "12K / 200K" with a bar that warns as it fills

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add context-meter
```

Or use it from the prebuilt package without copying:

```tsx
import { ContextMeter } from '@cascivo/react'
```

## Category

`feedback`

## States

- `normal`
- `high`
- `full`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `value` | `number` | yes | — | Tokens used so far. |
| `max` | `number` | yes | — | The context window size, in tokens. |
| `label` | `string` | no | `Context` | The meter’s name, shown above the bar. Rendered on screen. |
| `labels` | `{ usage?: string }` | no | — | Overrides for the component’s user-visible strings (i18n). `usage` is the spoken value and may contain `{used}`, `{max}` and `{percent}`. |

## Examples

### Plenty left

```tsx
<ContextMeter value={12400} max={200000} />
```

### Nearly full

```tsx
<ContextMeter value={192000} max={200000} />
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-color-ai`
- `--cascivo-color-warning`
- `--cascivo-color-destructive`
- `--cascivo-color-bg-subtle`
- `--cascivo-color-text`
- `--cascivo-color-text-muted`
- `--cascivo-radius-full`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `meter`

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

ai, context, tokens, usage, meter, quota

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# CopyButton

Icon button that copies a value to the clipboard with copied feedback

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add copy-button
```

Or use it from the prebuilt package without copying:

```tsx
import { CopyButton } from '@cascivo/react'
```

## Category

`inputs`

## Sizes

- `sm`
- `md`

## States

- `idle`
- `copied`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `value` | `string` | yes | — | The text written to the clipboard on click |
| `size` | `'sm' \| 'md'` | no | `md` | Visual size of the component (e.g. 'sm', 'md', 'lg'). |
| `labels` | `{ copy?: string; copied?: string }` | no | — | Overrides the built-in i18n labels per instance |

## Examples

### Default

```tsx
<CopyButton value="npx cascivo add button" />
```

### Small

```tsx
<CopyButton value="pnpm install" size="sm" />
```

### Custom labels

Override the built-in copy/copied strings per instance

```tsx
<CopyButton value="token" labels={{ copy: 'Copy token', copied: 'Token copied' }} />
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-surface`
- `--cascivo-color-text-subtle`
- `--cascivo-color-text`
- `--cascivo-color-border`
- `--cascivo-color-bg-subtle`
- `--cascivo-color-success`
- `--cascivo-radius-control`
- `--cascivo-focus-ring`
- `--cascivo-control-height-sm`
- `--cascivo-control-height-md`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `button`
- **Keyboard:** Enter, Space

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

clipboard, copy, button, snippet

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# DataList

Key-value pairs rendered as a description list

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add data-list
```

Or use it from the prebuilt package without copying:

```tsx
import { DataList } from '@cascivo/react'
```

## Category

`display`

## Variants

- `horizontal`
- `vertical`

## Sizes

- `sm`
- `md`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `items` | `DataListEntry[]` | no | — | The label/value pairs to render. Optional: pass `<DataListItem label="…">value</DataListItem>` children instead when a value needs surrounding JSX. |
| `orientation` | `'horizontal' \| 'vertical'` | no | `horizontal` | Where each value sits relative to its own label: 'horizontal' beside it, 'vertical' underneath. Items are stacked vertically in both modes — this does not change the list's own axis. |
| `dividers` | `boolean` | no | `false` | When true, shows dividers between items. |
| `size` | `'sm' \| 'md'` | no | `md` | Visual size of the component (e.g. 'sm', 'md', 'lg'). |
| `children` | `ReactNode` | no | — | `<DataListItem>` rows, as an alternative to `items`. |

## Examples

### Horizontal data list

```tsx
<DataList
  items={[
    { label: 'Name', value: 'Ada Lovelace' },
    { label: 'Role', value: 'Mathematician' },
  ]}
/>
```

### Vertical — value under its label, not "items stacked vertically"

Both modes stack the items vertically. `orientation` moves the VALUE: beside its label (horizontal) or under it (vertical).

```tsx
<DataList
  orientation="vertical"
  items={[
    { label: 'Region', value: 'fra1' },
    { label: 'Branch', value: 'main' },
  ]}
/>
```

### Vertical with dividers

```tsx
<DataList
  orientation="vertical"
  dividers
  items={[{ label: 'Email', value: 'ada@example.com' }]}
/>
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-color-text`
- `--cascivo-color-text-subtle`
- `--cascivo-color-border`
- `--cascivo-space-3`
- `--cascivo-space-4`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `none`

## Dependencies

- `@cascivo/core`

## Tags

key-value, description, metadata, details

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# DataTable

Signal-driven data table with client/server sort, filter, pagination, multi-selection, expandable rows, and CSS content-visibility row containment for large datasets

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add data-table
```

Or use it from the prebuilt package without copying:

```tsx
import { DataTable } from '@cascivo/react'
```

## Category

`display`

## Sizes

- `compact`
- `normal`
- `relaxed`

## States

- `default`
- `loading`
- `empty`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `virtualized` | `boolean` | no | `false` | Render only the visible row window for large datasets. |
| `rowHeight` | `number` | no | — | Row height in px for the virtualized window. Measured from the first rendered row when omitted, so the density presets stay correct; set it only for custom-sized rows. |
| `windowSize` | `number` | no | — | Rows rendered per window. Derived from the scroller height when omitted; set it only to render a fixed count regardless of height. |
| `overscan` | `number` | no | `3` | Extra rows rendered above/below the window to smooth scrolling. |
| `columns` | `Column<Row>[]` | yes | — | The column definitions describing each table column. |
| `rows` | `Row[]` | yes | — | The row objects to render — one table row per array element. |
| `getRowId` | `(row: Row) => string` | no | — | Returns a stable unique id for a row. |
| `sort` | `SortState` | no | — | The controlled sort state. |
| `defaultSort` | `SortState` | no | — | The initial sort state when uncontrolled. |
| `sortMode` | `'client' \| 'server'` | no | `'client'` | Whether sorting is handled client-side or by the server ('client' \| 'server'). |
| `onSortChange` | `(sort: SortState \| undefined) => void` | no | — | Called with the new sort state when it changes. |
| `searchable` | `boolean` | no | `false` | When true, shows a search/filter input. |
| `pagination` | `{ pageSize: number; pageSizeOptions?: number[]; page?: number; onPageChange?: (page: number) => void }` | no | — | Paging config: pageSize, optional pageSizeOptions, and page/onPageChange to control the current page. With `server`, it is the pager for server-side paging. |
| `selection` | `{ mode: 'single' \| 'multi'; selected?: string[]; onChange?: (ids: string[]) => void }` | no | — | Row-selection configuration (mode and selected ids). |
| `batchActions` | `{ label: string; onClick: (selectedIds: string[]) => void }[]` | no | — | Actions applied to the currently selected rows. |
| `filters` | `ColumnFilters` | no | — | Per-column filter values (controlled), keyed by column key. Columns opt in with `Column.filter`: `text` (substring), `select` (faceted checklist with counts), `range` (numeric min/max). |
| `defaultFilters` | `ColumnFilters` | no | — | Initial per-column filter values (uncontrolled). |
| `onFiltersChange` | `(filters: ColumnFilters) => void` | no | — | Called with the full filter map whenever any column filter changes. |
| `noResultsState` | `ReactNode` | no | — | Shown instead of emptyState when there are rows but the search or filters match none of them. |
| `toolbar` | `ReactNode` | no | — | Extra controls rendered in the toolbar next to the search box — exports, primary actions. |
| `rowActions` | `(row: Row) => RowAction<Row>[]` | no | — | Per-row actions. Returns the menu entries for a row; rendered as a trailing overflow-menu column. Each entry has id, label, onSelect(row), and optional destructive/disabled/icon. |
| `columnState` | `ColumnState` | no | — | User-adjustable column layout (controlled): `hidden` keys, display `order`, explicit `widths` in px, and `pinned` sides. One object, so it round-trips through storage or a URL as a unit. |
| `defaultColumnState` | `ColumnState` | no | — | Initial column layout (uncontrolled). |
| `onColumnStateChange` | `(state: ColumnState) => void` | no | — | Called with the full column layout whenever the user changes it. |
| `columnSettings` | `ColumnSettings` | no | — | Which column-layout controls to offer: `visibility` (a "Columns" menu in the toolbar), `resizable` (a drag handle per header; arrows nudge, Home resets), `reorderable` (Move left/right in the header menu), `pinnable` (Pin to start/end in the header menu). All off by default. |
| `server` | `DataTableServer` | no | — | Server-driven mode: rows are rendered as the current page verbatim and `onQueryChange({ sort, search, filters, page, pageSize })` fires whenever any of them changes (not on mount). `totalItems` drives the pager. One switch turns off client sort, search, filters and paging together. |
| `multiSort` | `boolean` | no | `false` | Allow sorting by more than one column: Shift-click a header adds it as a tie-breaker (`SortState.thenBy`); a plain click replaces the whole sort. Sorted headers show their level. |
| `stateKey` | `string` | no | — | Remember the user's column layout and sort across reloads, in local storage under this key. Applies to uncontrolled `columnState`/`sort`; controlled props still win. Tables sharing a key share the preference. |
| `keyboardNavigation` | `'row' \| 'grid'` | no | `row` | How the keyboard moves through the table. 'row' keeps every control in the Tab order with the arrows stepping between them. 'grid' is the APG data-grid pattern: one Tab stop, arrows move a focused cell, Home/End within the row, Ctrl+Home/End to the corners, PageUp/PageDown by a screenful, Enter/F2 enters the cell's control, Escape returns to the cell; rows outside the virtualized window are scrolled to. |
| `onCellEdit` | `(row: Row, key: string, value: string) => void` | no | — | Commits an inline edit with the row, the column key and the new text. Enables editing for every column marked `editable`; the table does not mutate `rows` itself. |
| `groupBy` | `string \| string[]` | no | — | Group the rows by one or more columns, in order. Each group is a collapsible row showing its value, its row count and every `aggregate` column's reduction; leaves keep the current sort inside their group. Groups appear in order of first occurrence — sort by the grouped column to order them. |
| `totals` | `boolean` | no | `false` | Show a totals row under the body with each `aggregate` column's reduction over every row passing the search and filters (not just the page). Sticks to the bottom of the scroller. |
| `pinnedRows` | `{ top?: Row[]; bottom?: Row[] }` | no | — | Rows kept in view outside sort, search, filters, paging and the virtual window: `top` rows sit under the header (stuck there with `stickyHeader`), `bottom` rows above the totals. |
| `columnGroups` | `ColumnGroup[]` | no | — | Bands of columns under a shared header, rendered as a row above the column headers. Keep a band's columns adjacent; reordering them apart splits the band. |
| `exportable` | `boolean \| { filename?: string }` | no | `false` | An "Export CSV" button in the toolbar: every row passing the search and filters (all pages; with `server`, the rows given), in the current sort, visible columns as headers, raw cell values as fields (RFC 4180, UTF-8 with BOM). Pass `{ filename }` to name the file; it defaults to the `title`. |
| `renderExpandedRow` | `(row: Row) => ReactNode` | no | — | Renders the expanded content for a row. |
| `density` | `'compact' \| 'normal' \| 'relaxed'` | no | `'normal'` | Row density — 'compact', 'normal', or 'relaxed'. ⚠ It sets a row **height floor**, so it is invisible whenever the cell content is already taller: a two-line cell or a Badge stack looks identical at every density. Reported as "barely distinguishable" — the prop works, the content is winning. Shrink the cell content, or set `--cascivo-data-table-cell-gap` to tighten the horizontal rhythm too. |
| `zebra` | `boolean` | no | `false` | When true, applies alternating row striping. |
| `stickyHeader` | `boolean` | no | `false` | When true, the header stays fixed while the body scrolls. |
| `loading` | `boolean` | no | `false` | When true, shows a loading state. |
| `emptyState` | `ReactNode` | no | — | Content shown when there are no rows. |
| `ariaLabel` | `string` | no | — | Invisible accessible name for the table, used when there is no visible `title`. A table with neither is an unnamed landmark; dev-warns. Not rendered — screen readers only. |
| `title` | `string` | no | — | Visible caption above the table; it also becomes the table's accessible name. |
| `description` | `string` | no | — | Supporting description text. |
| `labels` | `DataTableLabels` | no | — | Overrides for the component’s user-visible strings (i18n). |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |

## Object types

### `Column<Row>`

A single column definition. `render` is the escape hatch for custom cell content — return any ReactNode (a Badge, an icon + link, a formatted value); when omitted the cell shows `String(row[key])`.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `key` | `string` | yes | Row property this column reads, and the sort key. |
| `header` | `string` | yes | Column header label. |
| `sortable` | `boolean` | no | When true, the header toggles sort on this column. |
| `render` | `(row: Row) => ReactNode` | no | Custom cell renderer. Return a Badge, icon + link, or formatted value. Omit to render `String(row[key])`. |
| `align` | `'start' \| 'end'` | no | Cell/text alignment. Use 'end' for numbers and timestamps. |
| `filter` | `'text' \| 'select' \| 'range'` | no | Offer a per-column filter under the header: a substring input, a faceted checklist of distinct values with counts, or a numeric min/max pair. Values surface through the `filters` props. |
| `aggregate` | `'sum' \| 'avg' \| 'min' \| 'max' \| 'count' \| ((rows: Row[]) => ReactNode)` | no | What group rows and the `totals` row show for this column: a built-in reduction over the numeric cell values (`count` counts rows), or a function of the rows. |
| `editable` | `boolean` | no | Edit cells in place: each renders an Editable (click, Enter or F2 to start; Enter commits, Escape cancels) that commits through `onCellEdit`. Ignored with a custom `render` or without `onCellEdit`. |
| `minWidth` | `string` | no | Floor for the column width, any CSS length. |
| `width` | `string` | no | Preferred column width (any CSS length, e.g. `120px`), with an automatic content floor. ⚠ Sizing EVERY column switches the table to `table-layout: fixed`. ⚠ "Leave one unsized" is necessary but NOT sufficient: the leftover width is split by content weight, so if the sized columns nearly fill the table the remainder can be narrower than the content needs and long tokens wrap mid-word. Leave the widest free-form column unsized, keep sized columns to ~2/3 of the table, and give the free-form one a `minWidth` when the data has long unbreakable tokens. |

### `SortState`

Controlled/initial sort state, used by `sort`, `defaultSort`, `onSortChange`.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `key` | `string` | yes | The sorted column key. |
| `direction` | `'asc' \| 'desc'` | yes | Sort direction. |
| `thenBy` | `{ key: string; direction: "asc" \| "desc" }[]` | no | Secondary columns that break ties, in order (multi-sort). |

### `DataTableServer`

Server-driven mode. The table renders `rows` as the current page and reports every change to sort, search, filters, page or page size through `onQueryChange`; nothing runs on the client.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `totalItems` | `number` | no | Total rows across every page; drives the pager and the range label. |
| `onQueryChange` | `(query: TableQuery) => void` | yes | Called with the full query whenever it changes. Not called on mount — the rows passed initially are the first page. |

### `TableQuery`

What the server is asked to apply.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `sort` | `SortState \| undefined` | yes | Active sort. |
| `search` | `string` | yes | Trimmed global search text. |
| `filters` | `ColumnFilters` | yes | Per-column filter values keyed by column key. |
| `page` | `number` | yes | 1-based page. |
| `pageSize` | `number` | yes | Rows per page. |

### `ColumnState`

User-adjustable column layout, used by `columnState`, `defaultColumnState`, `onColumnStateChange`.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `hidden` | `string[]` | no | Keys of hidden columns. At least one column always stays visible. |
| `order` | `string[]` | no | Display order of column keys; keys not listed follow in definition order. |
| `widths` | `Record<string, number>` | no | Explicit widths in px by key — what the resize handle writes. Any set width switches the table to a fixed layout. |
| `pinned` | `Record<string, 'start' \| 'end'>` | no | Pinned columns by key. Pinned-start columns render first and stick to the leading edge; pinned-end last, to the trailing edge. |

### `ColumnGroup`

A band of columns under one shared header (`columnGroups`).

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `header` | `string` | yes | The band label. |
| `columns` | `string[]` | yes | Column keys in the band. Non-adjacent keys render as separate spans. |

### `ColumnSettings`

Which column-layout controls the table offers. All off by default.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `visibility` | `boolean` | no | A "Columns" menu in the toolbar that shows and hides columns. |
| `resizable` | `boolean` | no | A drag handle on each header; arrow keys nudge by 16px (Shift: 64px), Home returns to auto, double-click too. |
| `reorderable` | `boolean` | no | "Move left" / "Move right" in each column's header menu (within its pin group). |
| `pinnable` | `boolean` | no | "Pin to start" / "Pin to end" / "Unpin" in each column's header menu. |

### `RowAction<Row>`

One entry in a row actions menu.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | `string` | yes | Stable id (menu key). |
| `label` | `string` | yes | Menu entry text. |
| `onSelect` | `(row: Row) => void` | yes | Activation handler; receives the row the menu belongs to. |
| `destructive` | `boolean` | no | Style as a destructive action. |
| `disabled` | `boolean` | no | Disable the entry. |
| `icon` | `ReactNode` | no | Leading icon. |

## Examples

### Basic table

```tsx
<DataTable
  columns={[
    { key: 'name', header: 'Name', sortable: true },
    { key: 'role', header: 'Role' },
  ]}
  rows={[
    { name: 'Alice', role: 'Engineer' },
    { name: 'Bob', role: 'Designer' },
  ]}
  getRowId={(r) => r.name}
/>
```

### Custom cell content with Column.render

Use Column.render to return any ReactNode per cell — a Badge for status, an icon + link for a repo, a right-aligned timestamp. Columns without render fall back to String(row[key]).

```tsx
<DataTable
  columns={[
    { key: 'name', header: 'Project', sortable: true },
    {
      key: 'status',
      header: 'Status',
      render: (row) => (
        <Badge variant={row.status === 'ready' ? 'success' : 'warning'}>{row.status}</Badge>
      ),
    },
    {
      key: 'updated',
      header: 'Updated',
      align: 'end',
      render: (row) => new Date(row.updated).toLocaleDateString(),
    },
  ]}
  rows={rows}
  getRowId={(r) => r.name}
/>
```

### Full-featured: selection, pagination, search

```tsx
<DataTable
  columns={columns}
  rows={rows}
  getRowId={(r) => r.id}
  searchable
  pagination={{ pageSize: 10, pageSizeOptions: [10, 25, 50] }}
  selection={{ mode: 'multi', onChange: setSelected }}
  batchActions={[{ label: 'Delete', onClick: deleteRows }]}
  stickyHeader
  zebra
/>
```

### Filters, row actions and a columns menu

Per-column filters under the header (a text input, a faceted checklist with counts, a numeric range), a row actions menu, and a toolbar Columns menu to hide columns.

```tsx
<DataTable
  columns={[
    { key: 'name', header: 'Name', sortable: true, filter: 'text' },
    { key: 'status', header: 'Status', filter: 'select' },
    { key: 'amount', header: 'Amount', align: 'end', filter: 'range' },
  ]}
  rows={rows}
  getRowId={(r) => r.id}
  columnSettings={{ visibility: true, resizable: true, reorderable: true, pinnable: true }}
  defaultColumnState={{ pinned: { name: 'start' } }}
  rowActions={(row) => [
    { id: 'edit', label: 'Edit', onSelect: () => edit(row) },
    { id: 'delete', label: 'Delete', destructive: true, onSelect: () => remove(row) },
  ]}
  exportable={{ filename: 'invoices' }}
  ariaLabel="Invoices"
/>
```

### Grid keyboard mode with inline editing

One Tab stop; the arrows move a focused cell and Enter or F2 opens the cell for editing. Commit the edit into your own state — the table never mutates `rows`.

```tsx
<DataTable
  columns={[
    { key: 'name', header: 'Name', editable: true },
    { key: 'qty', header: 'Qty', editable: true, align: 'end' },
  ]}
  rows={items}
  getRowId={(r) => r.id}
  keyboardNavigation="grid"
  onCellEdit={(row, key, value) => update(row.id, { [key]: value })}
  ariaLabel="Line items"
/>
```

### Grouped, with totals and a column band

Rows grouped by region with a count and a sum on each group row, a sticky totals row over everything that passes the filters, and two columns under one "Order" header.

```tsx
<DataTable
  columns={[
    { key: 'region', header: 'Region', sortable: true },
    { key: 'status', header: 'Status', aggregate: 'count' },
    { key: 'amount', header: 'Amount', align: 'end', aggregate: 'sum' },
  ]}
  rows={orders}
  getRowId={(o) => o.id}
  groupBy="region"
  totals
  columnGroups={[{ header: 'Order', columns: ['status', 'amount'] }]}
  ariaLabel="Orders by region"
/>
```

### Server-driven

The server applies sort, search, filters and paging; the table renders the page it is given and reports the query whenever it changes.

```tsx
<DataTable
  columns={columns}
  rows={page.rows}
  getRowId={(r) => r.id}
  searchable
  pagination={{ pageSize: 50 }}
  server={{ totalItems: page.total, onQueryChange: load }}
  ariaLabel="Orders"
/>
```

### A million rows

Virtualized: only the visible rows are in the DOM, the scrollbar reaches the last row at any count, and search and sort stay usable. Row height and viewport are measured, so nothing else is needed.

```tsx
<DataTable
  columns={columns}
  rows={millionRows}
  getRowId={(r) => r.id}
  virtualized
  searchable
  ariaLabel="Events"
/>
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-surface`
- `--cascivo-color-bg-subtle`
- `--cascivo-color-border`
- `--cascivo-color-border-strong`
- `--cascivo-color-text`
- `--cascivo-color-text-muted`
- `--cascivo-color-accent`
- `--cascivo-font-sans`
- `--cascivo-text-sm`
- `--cascivo-text-xs`
- `--cascivo-font-semibold`
- `--cascivo-font-medium`
- `--cascivo-radius-lg`
- `--cascivo-radius-sm`
- `--cascivo-space-2`
- `--cascivo-space-3`
- `--cascivo-space-4`
- `--cascivo-data-table-max-height`
- `--cascivo-data-table-cell-gap`
- `--cascivo-duration-150`
- `--cascivo-duration-500`
- `--cascivo-ease-out`
- `--cascivo-ease-in-out`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `table`
- **Keyboard:** Tab, ArrowUp, ArrowDown, ArrowLeft, ArrowRight, Enter, Space, Home, End, PageUp, PageDown, F2, Escape

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

table, data, grid, sort, filter, pagination, selection

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# DatePicker

An accessible date-picker with a calendar popover.

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add date-picker
```

Or use it from the prebuilt package without copying:

```tsx
import { DatePicker } from '@cascivo/react'
```

## Category

`inputs`

## Sizes

- `sm`
- `md`
- `lg`

## States

- `default`
- `open`
- `error`
- `disabled`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `id` | `string` | no | — | Base id for the input and its popover/aria wiring; auto-generated when omitted. |
| `value` | `string` | no | — | Controlled ISO date value (YYYY-MM-DD) |
| `defaultValue` | `string` | no | — | Uncontrolled default value |
| `onValueChange` | `(value: string \| undefined) => void` | no | — | Called with the selected ISO date string (or undefined when cleared) |
| `min` | `string` | no | — | Minimum ISO date |
| `max` | `string` | no | — | Maximum ISO date |
| `clearable` | `boolean` | no | `false` | Shows a clear button |
| `typeable` | `boolean` | no | `true` | When true, the field accepts a typed date as well as one picked from the calendar. |
| `disabledDate` | `(date: Date) => boolean` | no | — | Rejects individual dates the bounds allow — holidays, weekends, taken slots. |
| `format` | `Intl.DateTimeFormatOptions` | no | — | Formatting options for the displayed date. Defaults to the locale's numeric form. |
| `showToday` | `boolean` | no | `false` | When true, the calendar offers a button that jumps to the current month. |
| `name` | `string` | no | — | Submitted with a surrounding form — a hidden input carrying the ISO value. |
| `required` | `boolean` | no | — | Marks the control as required for assistive technology. |
| `open` | `boolean` | no | — | Controlled open state of the calendar popup. |
| `onOpenChange` | `(open: boolean) => void` | no | — | Called when the popup opens or closes. |
| `label` | `string` | no | — | Visible field label rendered above the input; it also names the control. Rendered on screen. |
| `hint` | `string` | no | — | Hint text |
| `error` | `string` | no | — | Error message |
| `size` | `'sm' \| 'md' \| 'lg'` | no | `md` | Field size |
| `disabled` | `boolean` | no | `false` | Disables the picker |
| `labels` | `DatePickerLabels` | no | — | i18n label overrides |
| `aria-labelledby` | `string` | no | — | Wired automatically by a wrapping `Field` — its label id, forwarded to the focusable control so the Field's label names it. |
| `aria-describedby` | `string` | no | — | Wired automatically by a wrapping `Field` — the ids of its hint/error text, forwarded to the focusable control so the supporting text is announced. |
| `aria-invalid` | `boolean` | no | — | Wired automatically by a wrapping `Field` when it is in an error state. |
| `ariaLabel` | `string` | no | — | Invisible accessible name, for when a visible element outside this component already labels it and `label` would render that text a second time. ⚠ `label` on this component is **visible**; `IconButton.label`/`Sparkline.label` are invisible names, which is the prior that costs adopters a duplicated label. The raw DOM `aria-label` still wins over this. Not rendered — screen readers only. |

## Examples

### Basic

Uncontrolled date picker

```tsx
<DatePicker label="Date" />
```

### Clearable

With clear button

```tsx
<DatePicker label="Date" clearable />
```

### With constraints

Date range constraint

```tsx
<DatePicker min="2024-01-01" max="2024-12-31" />
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-accent-text`
- `--cascivo-color-surface`
- `--cascivo-color-surface-overlay`
- `--cascivo-color-border`
- `--cascivo-color-border-strong`
- `--cascivo-color-accent`
- `--cascivo-color-text-on-accent`
- `--cascivo-date-picker-day-today-color`
- `--cascivo-color-text`
- `--cascivo-color-text-muted`
- `--cascivo-color-text-subtle`
- `--cascivo-color-bg-subtle`
- `--cascivo-color-destructive`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `combobox`
- **Keyboard:** ArrowDown, ArrowUp, ArrowLeft, ArrowRight, Home, End, PageUp, PageDown, Enter, Space, Escape, Delete

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

date, calendar, picker, input, form

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# DateRangePicker

A dual-calendar picker for selecting a contiguous date range.

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add date-range-picker
```

Or use it from the prebuilt package without copying:

```tsx
import { DateRangePicker } from '@cascivo/react'
```

## Category

`inputs`

## Sizes

- `sm`
- `md`
- `lg`

## States

- `default`
- `open`
- `selecting`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `value` | `{ start: Date; end: Date } \| null` | no | — | Controlled selected range |
| `defaultValue` | `{ start: Date; end: Date }` | no | — | Uncontrolled initial range |
| `onValueChange` | `(range: { start: Date; end: Date }) => void` | no | — | Called when a complete range is selected |
| `min` | `Date` | no | — | Earliest selectable date |
| `max` | `Date` | no | — | Latest selectable date |
| `disabled` | `(date: Date) => boolean` | no | — | Predicate to disable individual days |
| `presets` | `{ label: string; range: { start: Date; end: Date } }[]` | no | — | Quick-select preset ranges shown in a side column |
| `locale` | `string` | no | — | BCP-47 locale; defaults to the current i18n locale |
| `placeholder` | `string` | no | — | Empty-state trigger text |
| `size` | `'sm' \| 'md' \| 'lg'` | no | `md` | Field/grid size |
| `labels` | `DateRangePickerLabels` | no | — | i18n label overrides |

## Examples

### Basic

Uncontrolled dual-calendar range picker

```tsx
<DateRangePicker />
```

### With presets

Quick-select common ranges

```tsx
<DateRangePicker presets={[{ label: "Last 7 days", range: last7 }]} />
```

### Constrained

Limits the selectable dates

```tsx
<DateRangePicker min={new Date(Date.UTC(2024, 0, 1))} max={new Date(Date.UTC(2024, 11, 31))} />
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-calendar-bg`
- `--cascivo-calendar-day-selected-bg`
- `--cascivo-calendar-day-selected-fg`
- `--cascivo-calendar-range-bg`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `combobox`
- **Keyboard:** Enter, Space, Escape, ArrowUp, ArrowDown, ArrowLeft, ArrowRight, Home, End, PageUp, PageDown

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

date, range, calendar, picker, input, form

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Dock

Fixed bottom navigation bar for mobile app shells with up to 5 items

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add dock
```

Or use it from the prebuilt package without copying:

```tsx
import { Dock } from '@cascivo/react'
```

## Category

`navigation`

## States

- `default`
- `active`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `label` | `string` | no | — | Alias of `ariaLabel` — the same invisible accessible name under the other spelling. Neither is deprecated. Not rendered — screen readers only. |
| `ariaLabel` | `string` | no | — | Accessible label for the dock navigation; defaults to the built-in i18n string. Not rendered — screen readers only. |
| `items` | `DockItem[]` | yes | — | Navigation items, each with a label, icon, and optional href or onClick |
| `activeIndex` | `number` | no | — | Index of the currently active item (0-based) |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |

## Examples

### Basic mobile dock

Fixed bottom navigation for a mobile app shell

```tsx
<Dock
  activeIndex={0}
  items={[
    { label: 'Home', icon: '🏠', onClick: () => navigate('/') },
    { label: 'Search', icon: '🔍', onClick: () => navigate('/search') },
    { label: 'Profile', icon: '👤', onClick: () => navigate('/profile') },
  ]}
/>
```

### With hrefs

Link-based dock items for standard navigation

```tsx
<Dock
  activeIndex={1}
  items={[
    { label: 'Feed', icon: '📰', href: '/feed' },
    { label: 'Explore', icon: '🌐', href: '/explore' },
    { label: 'Notifications', icon: '🔔', href: '/notifications' },
    { label: 'Profile', icon: '👤', href: '/profile' },
  ]}
/>
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-color-accent-text`
- `--cascivo-color-surface`
- `--cascivo-color-text-muted`
- `--cascivo-border-subtle`
- `--cascivo-ring-width`
- `--cascivo-ring-color`
- `--cascivo-ease-out`
- `--cascivo-target-min-coarse`
- `--cascivo-z-dock`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `navigation`
- **Keyboard:** Tab, Enter

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

dock, tab-bar, bottom-nav, mobile, navigation, app-shell

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Drawer

Edge-anchored dialog panel that slides in from a screen edge with CSS-only enter/exit motion

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add drawer
```

Or use it from the prebuilt package without copying:

```tsx
import { Drawer } from '@cascivo/react'
```

## Category

`overlay`

## States

- `open`
- `closed`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `open` | `boolean` | no | — | Whether the component is open (controlled). |
| `defaultOpen` | `boolean` | no | — | Whether the component is open on first render (uncontrolled). |
| `onOpenChange` | `(open: boolean) => void` | no | — | Called with the next open state when it changes. |
| `side` | `'start' \| 'end' \| 'top' \| 'bottom'` | no | `end` | Edge the panel is anchored to. Drives the slide direction. |
| `size` | `string` | no | — | Panel size along its cross axis (width for start/end, height for top/bottom). |
| `title` | `React.ReactNode` | no | — | Title text for the component. |
| `description` | `React.ReactNode` | no | — | Supporting description text. |
| `children` | `React.ReactNode` | no | — | Content rendered inside the component. |
| `labels` | `{ close?: string }` | no | — | Overrides for the component’s user-visible strings (i18n). |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |
| `swipeToDismiss` | `boolean` | no | `false` | Allow dragging the header toward its edge to dismiss (opt-in). |

## Examples

### Basic

```tsx
<Drawer open={isOpen} onOpenChange={setIsOpen} title="Settings">
  <SettingsForm />
</Drawer>
```

### Bottom drawer with swipe-to-dismiss

Dragging the header past a threshold toward the edge dismisses the panel.

```tsx
<Drawer defaultOpen side="bottom" size="20rem" swipeToDismiss title="Details">
  <OrderDetails />
</Drawer>
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-dialog-body-gap`
- `--cascivo-color-surface`
- `--cascivo-color-border`
- `--cascivo-radius-overlay`
- `--cascivo-shadow-overlay`
- `--cascivo-motion-enter`
- `--cascivo-motion-exit`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `dialog`
- **Keyboard:** Escape, Tab, Shift+Tab

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

overlay, drawer, panel, slide, dialog

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Dropdown

Menu of actions revealed from a trigger

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add dropdown
```

Or use it from the prebuilt package without copying:

```tsx
import { Dropdown } from '@cascivo/react'
```

## Category

`overlay`

## States

- `closed`
- `open`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `trigger` | `ReactElement` | yes | — | The element that opens the dropdown when activated. |
| `items` | `({ label: string; value: string; icon?: ReactNode; disabled?: boolean } \| { kind: 'separator' })[]` | yes | — | Menu entries. A selectable row is `{ label, value, icon?, disabled? }`; a rule between groups is `{ kind: 'separator' }`, which takes no label or value. The union is tagged on `kind`, so a separator cannot carry data that would be silently discarded. |
| `onSelect` | `(value: string) => void` | no | — | Called with the selected value. |
| `placement` | `'bottom-start' \| 'bottom-end'` | no | `bottom-start` | Which trigger edge the menu aligns to. `bottom-start` hangs it from the trigger's start edge, `bottom-end` from its end edge — use `bottom-end` for a trigger near the end of the viewport. |
| `open` | `boolean` | no | — | Whether the component is open (controlled). |
| `onOpenChange` | `(open: boolean) => void` | no | — | Called with the next open state when it changes. |

## Object types

### `DropdownMenuItem`

A selectable row in the menu.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `label` | `string` | yes | Visible item text. |
| `value` | `string` | yes | Passed to `onSelect`. |
| `icon` | `ReactNode` | no | Leading icon. |
| `disabled` | `boolean` | no | Skips the item in keyboard navigation and selection. |

### `DropdownSeparatorItem`

A rule between groups. Carries no data and is skipped by keyboard navigation.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `kind` | `'separator'` | yes | Discriminant. |

## Examples

### Basic

```tsx
<Dropdown trigger={<Button>Actions</Button>} items={[{ label: "Edit", value: "edit" }]} onSelect={handle} />
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-surface-overlay`
- `--cascivo-color-border`
- `--cascivo-color-bg-subtle`
- `--cascivo-radius-md`
- `--cascivo-z-dropdown`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `menu`
- **Keyboard:** ArrowDown, ArrowUp, Home, End, Enter, Space, Escape

## Dependencies

- `@cascivo/core`

## Tags

overlay, menu, actions

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Editable

Inline click-to-edit text field

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add editable
```

Or use it from the prebuilt package without copying:

```tsx
import { Editable } from '@cascivo/react'
```

## Category

`inputs`

## States

- `preview`
- `editing`
- `disabled`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `value` | `string` | yes | — | The controlled value. |
| `onValueChange` | `(v: string) => void` | yes | — | Called with the new value when it changes. |
| `placeholder` | `string` | no | — | Placeholder text shown when the field is empty. |
| `disabled` | `boolean` | no | `false` | When true, disables the control and removes it from the tab order. |
| `submitOnBlur` | `boolean` | no | `true` | When true, commits the edit when the field loses focus. |
| `onCancel` | `() => void` | no | — | Called when the edit is cancelled. |
| `id` | `string` | no | — | Id for the **focusable control** (not the wrapper), so a `<label for>` names what actually takes focus. `Field` supplies this automatically. |
| `aria-labelledby` | `string` | no | — | Wired automatically by a wrapping `Field` — its label id, forwarded to the focusable control so the Field's label names it. |
| `aria-describedby` | `string` | no | — | Wired automatically by a wrapping `Field` — the ids of its hint/error text, forwarded to the focusable control so the supporting text is announced. |
| `aria-invalid` | `boolean` | no | — | Wired automatically by a wrapping `Field` when it is in an error state. |

## Examples

### Basic

```tsx
<Editable value="Click to edit" onValueChange={() => {}} />
```

### With placeholder

```tsx
<Editable value="" onValueChange={() => {}} placeholder="Enter text" />
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-surface`
- `--cascivo-color-border`
- `--cascivo-color-accent`
- `--cascivo-color-text`
- `--cascivo-color-text-muted`
- `--cascivo-color-bg-subtle`
- `--cascivo-radius-sm`
- `--cascivo-focus-ring`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `button`
- **Keyboard:** Enter, Escape

## Dependencies

- `@cascivo/core`

## Tags

form, editable, inline, input, text

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# CodeEditor

Lightweight code editor — a native textarea overlaid on a syntax-highlighted layer, with line numbers and Tab indent.

## Install

Ships in the `@cascivo/editor` package — install it (no copy-paste):

```sh
pnpm add @cascivo/editor
```

```tsx
import { CodeEditor } from '@cascivo/editor'
import '@cascivo/editor/styles.css' // bundler: automatic. Needed only for no-bundler / SSR-externalised builds
```

## Category

`inputs`

## States

- `default`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `value` | `string` | no | — | Controlled value |
| `defaultValue` | `string` | no | — | Initial value for uncontrolled use |
| `onValueChange` | `(value: string) => void` | no | — | Called with the new text on every edit |
| `language` | `string` | no | `plaintext` | Grammar name (plaintext/json/javascript/typescript/css/html/markdown/bash) |
| `lineNumbers` | `boolean` | no | `true` | Show the line-number gutter |
| `tabSize` | `number` | no | `2` | Spaces per tab stop |
| `insertSpaces` | `boolean` | no | `true` | Insert spaces vs a literal tab on Tab |
| `wrap` | `boolean` | no | `false` | Soft-wrap long lines instead of scrolling horizontally |
| `readOnly` | `boolean` | no | `false` | When true, the value is shown but cannot be edited. |
| `disabled` | `boolean` | no | `false` | When true, disables the control and removes it from the tab order. |
| `placeholder` | `string` | no | — | Placeholder text shown when the field is empty. |
| `ariaLabel` | `string` | no | — | Alias of `label` — the same invisible accessible name under the catalog spelling. Neither is deprecated. Not rendered — screen readers only. |
| `label` | `string` | no | — | Accessible label (defaults to the i18n "Code editor"). Not rendered — screen readers only. |
| `onSave` | `(value: string) => void` | no | — | Called on Mod-S; the browser save dialog is suppressed |
| `bracketMatching` | `boolean` | no | `false` | Highlight the bracket matching the one adjacent to the caret |
| `theme` | `EditorTheme` | no | — | Per-instance --cascivo-editor-* overrides; swapping it re-themes live |
| `keymap` | `KeyMap` | no | — | Extra key bindings merged over the built-ins (user wins on a chord) |
| `decorations` | `Decoration[] \| ((value: string) => Decoration[])` | no | — | Extra offset-range → CSS class decorations |
| `commands` | `SlashCommand[]` | no | — | Slash-command entries; typing "/" opens a filtered menu. Omit to disable. |
| `ref` | `Ref<CodeEditorHandle>` | no | — | Imperative handle: applyEdit / getSelection / focus / undo / redo / openFind / openCommandMenu |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |
| `virtualize` | `boolean` | no | — | Render only the visible lines for large documents. |

## Object types

### `SlashCommand`

A slash-command entry.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | `string` | yes | Stable id (menu key). |
| `label` | `string` | yes | Shown in the menu and matched against the query. |
| `hint` | `string` | no | Optional right-aligned hint (e.g. |
| `keywords` | `readonly string[]` | no | Extra match terms beyond the label. |
| `insert` | `string` | no | Text inserted in place of the `/query` (an undoable edit). |
| `run` | `(editor: CodeEditorHandle) => void` | no | Side effect run after the `/query` is removed (receives the editor handle). |

## Examples

### Basic editor

```tsx
import { CodeEditor } from '@cascivo/editor'
import '@cascivo/editor/styles.css'

<CodeEditor language="typescript" lineNumbers defaultValue={'const x = 1\n'} />
```

### Controlled

```tsx
<CodeEditor language="json" value={value} onValueChange={setValue} />
```

### Notes editing — find, save, brackets

```tsx
<CodeEditor
  language="markdown"
  value={doc}
  onValueChange={setDoc}
  onSave={save} // Mod-S
  bracketMatching
/> // Mod-F to search
```

### Slash commands

Type "/" to open a filtered command menu; arrows + Enter insert.

```tsx
const commands = [
  { id: 'fence', label: 'Code block', keywords: ['code'], insert: '\u0060\u0060\u0060\n\n\u0060\u0060\u0060' },
  { id: 'todo', label: 'TODO', insert: '// TODO: ' },
  { id: 'date', label: 'Date', run: (e) => e.applyEdit(e.getSelection(), new Date().toISOString()) },
]

<CodeEditor language="markdown" commands={commands} />
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-editor-bg`
- `--cascivo-editor-fg`
- `--cascivo-editor-gutter-bg`
- `--cascivo-editor-gutter-fg`
- `--cascivo-editor-gutter-active`
- `--cascivo-editor-gutter-width`
- `--cascivo-editor-gutter-gap`
- `--cascivo-editor-current-line`
- `--cascivo-editor-selection`
- `--cascivo-editor-border`
- `--cascivo-editor-match`
- `--cascivo-editor-match-current`
- `--cascivo-editor-bracket`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `textbox`
- **Keyboard:** Tab (indent), Shift+Tab (dedent), Mod+Z / Mod+Shift+Z (undo / redo), Mod+F (find), Mod+Alt+F (replace), Mod+S (save), / (open slash-command menu when commands are provided), Up/Down + Enter/Tab (navigate + insert a command), Escape (dismiss), Standard textarea editing

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

editor, code, syntax-highlighting, textarea, inputs

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Highlight

Read-only syntax-highlighted code block — the same owned tokenizer as CodeEditor, without the textarea.

## Install

Ships in the `@cascivo/editor` package — install it (no copy-paste):

```sh
pnpm add @cascivo/editor
```

```tsx
import { Highlight } from '@cascivo/editor'
import '@cascivo/editor/styles.css' // bundler: automatic. Needed only for no-bundler / SSR-externalised builds
```

## Category

`display`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `value` | `string` | yes | — | Code to render |
| `language` | `string` | no | `plaintext` | Grammar name (plaintext/json/javascript/typescript/css/html/markdown/bash) |
| `lineNumbers` | `boolean` | no | `false` | Show the line-number gutter |
| `wrap` | `boolean` | no | `false` | Soft-wrap long lines |
| `tabSize` | `number` | no | `2` | Spaces per tab stop |
| `ariaLabel` | `string` | no | — | Alias of `label` — the same invisible accessible name under the catalog spelling. Neither is deprecated. Not rendered — screen readers only. |
| `label` | `string` | no | — | Accessible label for the code block. Not rendered — screen readers only. |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |
| `gutterRef` | `Ref<HTMLDivElement>` | no | — | Ref to the line-number gutter's backdrop strip. |
| `preRef` | `Ref<HTMLPreElement>` | no | — | Ref to the scrollable `<pre>` (used by `CodeEditor` for scroll-sync). |

## Examples

### Read-only snippet

```tsx
import { Highlight } from '@cascivo/editor'
import '@cascivo/editor/styles.css'

<Highlight language="json" value={'{ "ok": true }'} />
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-editor-bg`
- `--cascivo-editor-fg`
- `--cascivo-editor-gutter-bg`
- `--cascivo-editor-gutter-fg`
- `--cascivo-editor-gutter-width`
- `--cascivo-editor-gutter-gap`
- `--cascivo-editor-border`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `group`
- **Keyboard:** Scroll (no interactive controls)

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

editor, code, syntax-highlighting, display, read-only

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# EmptyState

Placeholder for views that have no data to display

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add empty-state
```

Or use it from the prebuilt package without copying:

```tsx
import { EmptyState } from '@cascivo/react'
```

## Category

`display`

## Sizes

- `md`
- `lg`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `icon` | `ReactNode` | no | — | Icon element rendered in the component. |
| `title` | `string` | yes | — | Title text for the component. |
| `description` | `string` | no | — | Supporting description text. |
| `action` | `ReactNode` | no | — | Primary action shown in the component. |
| `size` | `'md' \| 'lg'` | no | `md` | Visual size of the component (e.g. 'sm', 'md', 'lg'). |

## Examples

### Basic

```tsx
<EmptyState title="No results" description="Try adjusting your filters." />
```

### With action

```tsx
<EmptyState icon="📄" title="No documents yet" description="Create your first document to get started." action={<Button>New document</Button>} />
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-color-text`
- `--cascivo-color-text-subtle`
- `--cascivo-color-text-muted`
- `--cascivo-color-bg-subtle`
- `--cascivo-radius-full`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `none`

## Dependencies

- `@cascivo/core`

## Tags

empty, placeholder, zero-state, no-data

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Fab

Floating action button anchored to a screen corner, with an optional speed-dial of secondary actions

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add fab
```

Or use it from the prebuilt package without copying:

```tsx
import { Fab } from '@cascivo/react'
```

## Category

`inputs`

## States

- `default`
- `open`
- `closed`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `children` | `React.ReactNode` | yes | — | The main icon |
| `ariaLabel` | `string` | no | — | Alias of `label` — the same invisible accessible name under the catalog spelling. Neither is deprecated. Not rendered — screen readers only. |
| `label` | `string` | no | — | Accessible name for the main button (it is icon-only). Not rendered — screen readers only. Exactly one of `label` / `ariaLabel` is required; the type enforces it. |
| `onClick` | `() => void` | no | — | Called when the element is clicked. |
| `actions` | `FabAction[]` | no | — | Speed-dial actions; each has a label, icon, onSelect, and optional disabled |
| `position` | `'bottom-end' \| 'bottom-start'` | no | `bottom-end` | Screen corner the button is pinned to: `bottom-end` or `bottom-start`. Safe-area insets are honoured either way. |
| `open` | `boolean` | no | — | Whether the component is open (controlled). |
| `defaultOpen` | `boolean` | no | — | Whether the component is open on first render (uncontrolled). |
| `onOpenChange` | `(open: boolean) => void` | no | — | Called with the next open state when it changes. |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |

## Examples

### Single action

```tsx
<Fab label="Compose" onClick={compose}><PlusIcon /></Fab>
```

### Speed dial

The main button toggles a menu of secondary actions.

```tsx
<Fab
  label="Create"
  actions={[
    { label: 'New note', icon: <NoteIcon />, onSelect: newNote },
    { label: 'New folder', icon: <FolderIcon />, onSelect: newFolder },
  ]}
>
  <PlusIcon />
</Fab>
```

### Start corner

```tsx
<Fab label="Help" position="bottom-start" onClick={openHelp}><HelpIcon /></Fab>
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-accent-text`
- `--cascivo-color-accent`
- `--cascivo-color-accent-content`
- `--cascivo-color-accent-hover`
- `--cascivo-color-surface`
- `--cascivo-color-border`
- `--cascivo-radius-full`
- `--cascivo-shadow-overlay`
- `--cascivo-target-min-coarse`
- `--cascivo-motion-enter`
- `--cascivo-motion-exit`
- `--cascivo-z-dropdown`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `button`
- **Keyboard:** Enter, Space, ArrowUp, ArrowDown, Home, End, Escape

## Dependencies

- `@cascivo/core`

## Tags

inputs, fab, floating-action-button, mobile, speed-dial

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Field

Form-field wrapper composing label, control, description, and error

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add field
```

Or use it from the prebuilt package without copying:

```tsx
import { Field } from '@cascivo/react'
```

## Category

`inputs`

## States

- `default`
- `disabled`
- `invalid`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `label` | `ReactNode` | no | — | Text label for the control. Rendered on screen. |
| `hint` | `ReactNode` | no | — | Alias of `description` — the name the eight form controls use for the same supporting text. Neither is deprecated. |
| `description` | `ReactNode` | no | — | Supporting text under the control, wired via aria-describedby. `hint` is accepted as an alias. |
| `error` | `ReactNode` | no | — | Error message shown when the value is invalid. |
| `required` | `boolean` | no | `false` | When true, marks the field as required. |
| `disabled` | `boolean` | no | `false` | When true, disables the control and removes it from the tab order. |
| `id` | `string` | no | — | Id applied to the root element (auto-generated when omitted). |
| `children` | `ReactElement` | yes | — | Content rendered inside the component. |

## Examples

### Basic

```tsx
<Field label="Email"><Input type="email" /></Field>
```

### With description

```tsx
<Field label="Email" description="We never share it."><Input /></Field>
```

### With error

Sets aria-invalid on the control and announces the error via role="alert".

```tsx
<Field label="Email" error="Email is required" required><Input /></Field>
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-space-2`
- `--cascivo-font-sans`
- `--cascivo-text-sm`
- `--cascivo-leading-snug`
- `--cascivo-color-text-muted`
- `--cascivo-color-destructive`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `group`

## Dependencies

- `@cascivo/core`

## Tags

form, layout, validation, accessibility

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# FileUploader

Drag-and-drop file upload zone with file list and status indicators.

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add file-uploader
```

Or use it from the prebuilt package without copying:

```tsx
import { FileUploader } from '@cascivo/react'
```

## Category

`inputs`

## States

- `idle`
- `dragover`
- `uploading`
- `complete`
- `error`
- `disabled`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `files` | `UploaderFile[]` | no | `[]` | Controlled file list |
| `onFilesAdded` | `(files: File[]) => void` | no | — | Called with accepted files |
| `onRemove` | `(id: string) => void` | no | — | Called when a file is removed |
| `multiple` | `boolean` | no | `false` | Allow multiple files |
| `accept` | `string` | no | — | Accepted file types (MIME or extension) |
| `maxSize` | `number` | no | — | Maximum file size in bytes |
| `onRejected` | `(files: File[], reason: 'size' \| 'type') => void` | no | — | Called with rejected files |
| `label` | `string` | no | — | Visible field label rendered above the drop zone; it also names the control. Rendered on screen. |
| `hint` | `string` | no | — | Hint text below the drop zone |
| `labels` | `FileUploaderLabels` | no | — | i18n label overrides |
| `disabled` | `boolean` | no | `false` | Disables the upload zone |
| `ariaLabel` | `string` | no | — | Invisible accessible name, for when a visible element outside this component already labels it and `label` would render that text a second time. ⚠ `label` on this component is **visible**; `IconButton.label`/`Sparkline.label` are invisible names, which is the prior that costs adopters a duplicated label. The raw DOM `aria-label` still wins over this. Not rendered — screen readers only. |

## Examples

### Basic

Single file upload zone

```tsx
<FileUploader onFilesAdded={console.log} />
```

### Multiple

Accept multiple files

```tsx
<FileUploader multiple onFilesAdded={console.log} />
```

### With files

Shows file list

```tsx
<FileUploader files={[{ id:'1', name:'report.pdf', size:102400, status:'complete' }]} />
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-accent`
- `--cascivo-color-accent-subtle`
- `--cascivo-color-success-foreground`
- `--cascivo-color-destructive`
- `--cascivo-color-destructive-subtle`
- `--cascivo-target-min-coarse`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `button`
- **Keyboard:** Enter, Space

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

upload, file, drop, drag, input, form

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Filter

A group of toggleable pill or outline buttons for filtering content by category

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add filter
```

Or use it from the prebuilt package without copying:

```tsx
import { Filter } from '@cascivo/react'
```

## Category

`inputs`

## Variants

- `pill`
- `outline`

## States

- `default`
- `selected`
- `hover`
- `focus`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `label` | `string` | no | — | Alias of `ariaLabel` — the same invisible accessible name under the other spelling. Neither is deprecated. Not rendered — screen readers only. |
| `ariaLabel` | `string` | no | — | Invisible accessible name. The catalog convention; the DOM spelling `aria-label` is accepted as an alias so either guess compiles. Not rendered — screen readers only. |
| `aria-label` | `string` | no | — | Accessible label for the filter group. |
| `options` | `FilterOption[]` | yes | — | Array of { label, value } objects to render as filter buttons |
| `value` | `string[]` | no | — | Controlled selected values |
| `defaultValue` | `string[]` | no | `[]` | Initial selected values for uncontrolled use |
| `onValueChange` | `(selected: string[]) => void` | no | — | Called with the selected values whenever the selection changes. |
| `multi` | `boolean` | no | `false` | Allow multiple items to be selected simultaneously |
| `variant` | `'pill' \| 'outline'` | no | `pill` | `pill` fills the selected chip with the accent colour; `outline` marks it with an accent border and text instead, leaving the fill transparent. |
| `multiple` | `boolean` | no | — | Alias of `multi` — the HTML spelling (`<select multiple>`), accepted because it is the guess an adopter makes first. `multi` stays canonical. |

## Examples

### Single-select

```tsx
<Filter
  options={[
    { label: 'All', value: 'all' },
    { label: 'Active', value: 'active' },
    { label: 'Archived', value: 'archived' },
  ]}
  aria-label="Filter by status"
/>
```

### Multi-select

```tsx
<Filter
  multi
  options={[
    { label: 'Design', value: 'design' },
    { label: 'Engineering', value: 'engineering' },
    { label: 'Marketing', value: 'marketing' },
  ]}
  aria-label="Filter by team"
/>
```

### Outline variant

```tsx
<Filter
  variant="outline"
  options={[{ label: 'React', value: 'react' }, { label: 'Vue', value: 'vue' }]}
  aria-label="Filter by framework"
/>
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-accent-text`
- `--cascivo-radius-full`
- `--cascivo-border-default`
- `--cascivo-color-text-subtle`
- `--cascivo-color-text`
- `--cascivo-color-active-bg`
- `--cascivo-color-accent`
- `--cascivo-color-accent-content`
- `--cascivo-ring-width`
- `--cascivo-ring-color`
- `--cascivo-ease-out`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `group`
- **Keyboard:** Tab, Enter, Space

## Dependencies

- `@cascivo/core`

## Tags

filter, chip, tag, pill, facet, category

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Flow

The declarative, AI-first flow surface — render a node/edge graph from plain serializable data.

## Install

Ships in the `@cascivo/flow` package — install it (no copy-paste):

```sh
pnpm add @cascivo/flow
```

```tsx
import { Flow } from '@cascivo/flow'
import '@cascivo/flow/styles.css' // bundler: automatic. Needed only for no-bundler / SSR-externalised builds
```

## Category

`display`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `nodes` | `FlowNode[]` | yes | — | Initial nodes (serializable). |
| `edges` | `FlowEdge[]` | yes | — | Initial edges (serializable). |
| `onNodesChange` | `(nodes: FlowNode[]) => void` | no | — | Called with the next nodes when they change (drag, add, remove). |
| `onEdgesChange` | `(edges: FlowEdge[]) => void` | no | — | Called with the next edges when they change. |
| `onConnect` | `(connection: Connection) => void` | no | — | Called when two handles are connected to form a new edge. |
| `nodeTypes` | `Record<string, NodeRenderer>` | no | — | Custom node renderers keyed by node.type. |
| `fitView` | `boolean` | no | `true` | When true, fits the graph to the viewport on mount. |
| `background` | `boolean \| FlowBackgroundProps` | no | `false` | Background pattern — true for the default dots, or a config object. |
| `controls` | `boolean` | no | `false` | Whether to show the controls. |
| `minimap` | `boolean` | no | `false` | When true, shows the minimap overlay. |
| `layout` | `'grid' \| 'layered' \| ((nodes, edges) => FlowNode[])` | no | — | Optional dependency-free layout. |
| `interactive` | `boolean` | no | `true` | When false (view mode), nodes cannot be selected, dragged, or connected and handles are hidden; pan/zoom still work. |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |
| `activeDirection` | `'forward' \| 'reverse' \| undefined` | no | — | Direction the active edge's dash travels. |
| `activeEdgeId` | `string \| undefined` | no | — | Highlight + animate a single edge (used by FlowStory's active step). |
| `maxZoom` | `number` | no | — | Maximum zoom scale the viewport can reach. |
| `minZoom` | `number` | no | — | Minimum zoom scale the viewport can reach. |

## Object types

### `FlowNode`

A graph node. Positioned in flow coordinates; renders as themed HTML.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | `string` | yes | — |
| `position` | `XYPosition` | yes | — |
| `data` | `Data` | no | — |
| `type` | `string` | no | Custom renderer key resolved via `nodeTypes`. |
| `selected` | `boolean` | no | — |
| `width` | `number` | no | Explicit/measured size used for handle anchors + bounding boxes. |
| `height` | `number` | no | — |

### `FlowEdge`

A directed connection between two nodes' handles.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | `string` | yes | — |
| `source` | `string` | yes | — |
| `target` | `string` | yes | — |
| `sourceHandle` | `string` | no | — |
| `targetHandle` | `string` | no | — |
| `type` | `EdgePathType \| string` | no | Custom renderer key resolved via `edgeTypes`. |
| `animated` | `boolean` | no | — |
| `label` | `string` | no | — |
| `selected` | `boolean` | no | — |
| `markerStart` | `boolean` | no | Arrowhead at the source end (points back toward the source). Default false. |
| `markerEnd` | `boolean` | no | Arrowhead at the target end (points at the target). Default true. |

## Examples

### Declarative pipeline

A flow from plain serializable data, with background, controls, and an animated edge.

```tsx
() => (
  <Flow
    style={{ height: 280 }}
    background
    controls
    nodes={[
      { id: 'a', position: { x: 0, y: 60 }, data: { label: 'Client' } },
      { id: 'b', position: { x: 240, y: 60 }, data: { label: 'Gateway' } },
      { id: 'c', position: { x: 480, y: 60 }, data: { label: 'Service' } },
    ]}
    edges={[
      { id: 'ab', source: 'a', target: 'b', animated: true, label: 'request' },
      { id: 'bc', source: 'b', target: 'c' },
    ]}
  />
)
```

### Layered layout

Let the dependency-free layered layout arrange a small DAG.

```tsx
() => (
  <Flow
    style={{ height: 300 }}
    layout="layered"
    background
    minimap
    nodes={[
      { id: 'a', position: { x: 0, y: 0 }, data: { label: 'Ingest' } },
      { id: 'b', position: { x: 0, y: 0 }, data: { label: 'Transform' } },
      { id: 'c', position: { x: 0, y: 0 }, data: { label: 'Validate' } },
      { id: 'd', position: { x: 0, y: 0 }, data: { label: 'Load' } },
    ]}
    edges={[
      { id: 'ab', source: 'a', target: 'b' },
      { id: 'ac', source: 'a', target: 'c' },
      { id: 'bd', source: 'b', target: 'd' },
      { id: 'cd', source: 'c', target: 'd' },
    ]}
  />
)
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-bg`
- `--cascivo-color-surface`
- `--cascivo-color-accent`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `application`
- **Keyboard:** Tab (focus nodes), Enter/Space (select), Drag (pan/move), Wheel (zoom)

## Dependencies

- `@cascivo/core`

## Tags

flow, graph, declarative, diagram, ai-first

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# FlowBackground

Decorative dots / grid / cross canvas background, drawn purely in CSS gradients.

## Install

Ships in the `@cascivo/flow` package — install it (no copy-paste):

```sh
pnpm add @cascivo/flow
```

```tsx
import { FlowBackground } from '@cascivo/flow'
import '@cascivo/flow/styles.css' // bundler: automatic. Needed only for no-bundler / SSR-externalised builds
```

## Category

`display`

## Variants

- `dots`
- `grid`
- `cross`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `variant` | `'dots' \| 'grid' \| 'cross'` | no | `dots` | Pattern style. |
| `gap` | `number` | no | `20` | Cell spacing (px). |
| `size` | `number` | no | `1` | Dot radius / line thickness (px). |
| `color` | `string` | no | — | Pattern color (defaults to the border token). |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |

## Examples

### Dotted background

A dotted grid behind a flow canvas.

```tsx
() => (
  <div style={{ position: 'relative', height: 220, overflow: 'hidden' }}>
    <FlowBackground variant="dots" gap={24} />
  </div>
)
```

### Grid and cross

The grid and cross variants.

```tsx
() => (
  <div style={{ display: 'grid', gap: 16, gridTemplateColumns: '1fr 1fr' }}>
    <div style={{ position: 'relative', height: 180, overflow: 'hidden' }}>
      <FlowBackground variant="grid" gap={28} />
    </div>
    <div style={{ position: 'relative', height: 180, overflow: 'hidden' }}>
      <FlowBackground variant="cross" gap={28} size={4} />
    </div>
  </div>
)
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-color-border`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `presentation`

## Dependencies

- `@cascivo/core`

## Tags

flow, background, grid, dots, canvas

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# FlowCanvas

The pan/zoom canvas pane — a single CSS-transformed layer driven by the viewport signal.

## Install

Ships in the `@cascivo/flow` package — install it (no copy-paste):

```sh
pnpm add @cascivo/flow
```

```tsx
import { FlowCanvas } from '@cascivo/flow'
import '@cascivo/flow/styles.css' // bundler: automatic. Needed only for no-bundler / SSR-externalised builds
```

## Category

`display`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `children` | `ReactNode` | no | — | Background, nodes, edges. |
| `viewport` | `{ x: number; y: number; zoom: number }` | no | — | Controlled viewport. |
| `onViewportChange` | `(viewport: Viewport) => void` | no | — | Viewport change callback. |
| `minZoom` | `number` | no | `0.2` | Lower bound for the viewport zoom level. |
| `maxZoom` | `number` | no | `2` | Upper bound for the viewport zoom level. |
| `panOnDrag` | `boolean` | no | `true` | Drag the empty pane to pan the viewport. |
| `zoomOnScroll` | `boolean` | no | `true` | Wheel or pinch to zoom the viewport. |
| `fitView` | `boolean` | no | `false` | Frame the whole graph once on mount. |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |
| `chrome` | `ReactNode` | no | — | Screen-fixed overlay (controls, minimap, panels) — rendered outside the transformed pane. |
| `controller` | `UseViewportReturn` | no | — | Use a viewport controller owned by a parent (e.g. |
| `defaultViewport` | `Viewport` | no | — | Initial viewport (x, y, zoom) when uncontrolled. |
| `flow` | `FlowStore` | no | — | Share an external store (e.g. |

## Object types

### `UseViewportReturn`

Shape of the `controller` prop.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `containerRef` | `RefObject<HTMLDivElement \| null>` | yes | Outer clipping container — attach for wheel + size measurement. |
| `panHandleRef` | `RefObject<HTMLElement \| null>` | yes | Background drag-surface (behind nodes) — the pan handle. |
| `viewport` | `Signal<Viewport>` | yes | — |
| `pan` | `(dx: number, dy: number) => void` | yes | Translate the viewport by a screen-space delta. |
| `zoomTo` | `(zoom: number, center?: XYPosition) => void` | yes | Set zoom (clamped), optionally keeping `center` (container coords) fixed. |
| `zoomIn` | `() => void` | yes | — |
| `zoomOut` | `() => void` | yes | — |
| `fitView` | `(size?: Size) => void` | yes | Frame all nodes. |

### `Viewport`

The pan/zoom state of the canvas pane.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `x` | `number` | yes | — |
| `y` | `number` | yes | — |
| `zoom` | `number` | yes | — |

### `FlowStore`

Shape of the `flow` prop.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `nodes` | `Signal<FlowNode[]>` | yes | — |
| `edges` | `Signal<FlowEdge[]>` | yes | — |
| `viewport` | `Signal<Viewport>` | yes | — |
| `setNodes` | `(nodes: FlowNode[]) => void` | yes | — |
| `updateNode` | `(id: string, patch: Partial<FlowNode>) => void` | yes | — |
| `setEdges` | `(edges: FlowEdge[]) => void` | yes | — |
| `addEdge` | `(edge: FlowEdge) => void` | yes | — |
| `setViewport` | `(viewport: Viewport) => void` | yes | — |

## Examples

### Empty canvas with a background

```tsx
() => (
  <FlowCanvas style={{ height: 240 }}>
    <FlowBackground />
  </FlowCanvas>
)
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-bg`
- `--cascivo-radius-surface`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `application`
- **Keyboard:** Tab (focus), Drag (pan), Wheel (zoom)

## Dependencies

- `@cascivo/core`

## Tags

flow, canvas, viewport, pan, zoom

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# FlowControls

Zoom in / out / fit-view controls for a flow canvas — real, i18n-labeled buttons.

## Install

Ships in the `@cascivo/flow` package — install it (no copy-paste):

```sh
pnpm add @cascivo/flow
```

```tsx
import { FlowControls } from '@cascivo/flow'
import '@cascivo/flow/styles.css' // bundler: automatic. Needed only for no-bundler / SSR-externalised builds
```

## Category

`display`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `position` | `'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right'` | no | `bottom-left` | Canvas corner the control cluster is pinned to: `bottom-left`, `bottom-right`, `top-left` or `top-right`. |
| `showZoom` | `boolean` | no | `true` | When true, shows the zoom-in/zoom-out buttons. |
| `showFitView` | `boolean` | no | `true` | When true, shows the fit-to-view button. |
| `onZoomIn` | `() => void` | no | — | Called when the zoom-in control is activated. |
| `onZoomOut` | `() => void` | no | — | Called when the zoom-out control is activated. |
| `onFitView` | `() => void` | no | — | Called when the fit-to-view control is activated. |
| `labels` | `FlowControlsLabels` | no | — | Overrides for the component’s user-visible strings (i18n). |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |

## Examples

### Canvas controls

```tsx
() => (
  <div style={{ position: 'relative', height: 200, border: '1px solid var(--cascivo-color-border)' }}>
    <FlowControls onZoomIn={() => {}} onZoomOut={() => {}} onFitView={() => {}} />
  </div>
)
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-surface`
- `--cascivo-color-border`
- `--cascivo-target-min-coarse`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `group`
- **Keyboard:** Tab (focus), Enter/Space (activate)

## Dependencies

- `@cascivo/core`

## Tags

flow, controls, zoom, chrome

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# FlowEdge

An SVG edge with bezier/straight/smoothstep paths, an arrowhead, an optional label, and animation.

## Install

Ships in the `@cascivo/flow` package — install it (no copy-paste):

```sh
pnpm add @cascivo/flow
```

```tsx
import { FlowEdge } from '@cascivo/flow'
import '@cascivo/flow/styles.css' // bundler: automatic. Needed only for no-bundler / SSR-externalised builds
```

## Category

`display`

## Variants

- `bezier`
- `straight`
- `smoothstep`

## States

- `default`
- `selected`
- `animated`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `sourceX` | `number` | yes | — | Source anchor x (flow coords). |
| `sourceY` | `number` | yes | — | Y coordinate of the edge’s source point. |
| `targetX` | `number` | yes | — | X coordinate of the edge’s target point. |
| `targetY` | `number` | yes | — | Y coordinate of the edge’s target point. |
| `type` | `'bezier' \| 'straight' \| 'smoothstep'` | no | `bezier` | Edge path style ('bezier' \| 'straight' \| 'smoothstep'). |
| `animated` | `boolean` | no | `false` | When true, animates the edge path (dashed flow). |
| `label` | `ReactNode` | no | — | Text label for the control. Rendered on screen. |
| `selected` | `boolean` | no | `false` | Whether the edge is rendered as selected. |
| `markerStart` | `boolean` | no | `false` | Arrowhead at the source (points back toward the source) — set both for bidirectional. |
| `markerEnd` | `boolean` | no | `true` | Arrowhead at the target. Set false for an undirected line. |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |
| `active` | `boolean \| undefined` | no | — | Highlight the edge (used by FlowStory's active step). |
| `direction` | `'forward' \| 'reverse' \| undefined` | no | `'forward'` | Direction the dash travels when animated. |
| `id` | `string` | no | — | Edge identifier, used to target it via `activeEdgeId`. |
| `sourcePosition` | `HandlePosition \| undefined` | no | `'right'` | Handle side the edge leaves from. |
| `targetPosition` | `HandlePosition \| undefined` | no | `'left'` | Handle side the edge arrives at. |

## Examples

### Edge path types

Bezier, straight, smoothstep, and an animated edge.

```tsx
() => (
  <div style={{ position: 'relative', height: 220 }}>
    <FlowEdge sourceX={20} sourceY={30} targetX={260} targetY={30} type="bezier" label="bezier" />
    <FlowEdge sourceX={20} sourceY={90} targetX={260} targetY={90} type="smoothstep" label="step" />
    <FlowEdge sourceX={20} sourceY={150} targetX={260} targetY={150} animated label="animated" />
  </div>
)
```

### Arrow direction

Forward (default), backward, bidirectional, or undirected — via markerStart/markerEnd.

```tsx
() => (
  <div style={{ position: 'relative', height: 260 }}>
    <FlowEdge sourceX={20} sourceY={30} targetX={260} targetY={30} label="forward" />
    <FlowEdge sourceX={20} sourceY={90} targetX={260} targetY={90} markerEnd={false} markerStart label="backward" />
    <FlowEdge sourceX={20} sourceY={150} targetX={260} targetY={150} markerStart label="both" />
    <FlowEdge sourceX={20} sourceY={210} targetX={260} targetY={210} markerEnd={false} label="undirected" />
  </div>
)
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-color-border-strong`
- `--cascivo-color-accent`
- `--cascivo-color-surface`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `presentation`

## Dependencies

- `@cascivo/core`

## Tags

flow, edge, connector, animated, svg

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# FlowHandle

A connection port on a node edge — where edges attach and interactive connect starts.

## Install

Ships in the `@cascivo/flow` package — install it (no copy-paste):

```sh
pnpm add @cascivo/flow
```

```tsx
import { FlowHandle } from '@cascivo/flow'
import '@cascivo/flow/styles.css' // bundler: automatic. Needed only for no-bundler / SSR-externalised builds
```

## Category

`display`

## Variants

- `source`
- `target`

## States

- `default`
- `hover`
- `focus`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `type` | `'source' \| 'target'` | yes | — | Whether the handle is a connection source or target ('source' \| 'target'). |
| `position` | `'top' \| 'right' \| 'bottom' \| 'left'` | no | — | Edge of the node (defaults: source→right, target→left). |
| `id` | `string` | no | — | Handle id for multi-handle nodes. |
| `isConnectable` | `boolean` | no | `true` | Whether new connections can start or end at this handle. |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |

## Examples

### Source and target ports

```tsx
() => (
  <div style={{ position: 'relative', height: 160 }}>
    <FlowNode id="api" defaultPosition={{ x: 70, y: 55 }}>
      API
      <FlowHandle type="target" position="left" />
      <FlowHandle type="source" position="right" />
    </FlowNode>
  </div>
)
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-color-accent`
- `--cascivo-color-surface`
- `--cascivo-target-min-coarse`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `button`
- **Keyboard:** Tab (focus the port)

## Dependencies

- `@cascivo/core`

## Tags

flow, handle, port, connect

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# FlowMiniMap

A scaled SVG overview of the graph with a draggable viewport rectangle.

## Install

Ships in the `@cascivo/flow` package — install it (no copy-paste):

```sh
pnpm add @cascivo/flow
```

```tsx
import { FlowMiniMap } from '@cascivo/flow'
import '@cascivo/flow/styles.css' // bundler: automatic. Needed only for no-bundler / SSR-externalised builds
```

## Category

`display`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `nodes` | `FlowNode[]` | yes | — | The nodes to render. |
| `viewport` | `Viewport` | yes | — | The current pan/zoom viewport to reflect in the minimap. |
| `containerWidth` | `number` | no | — | Width of the flow container, used to scale the minimap. |
| `containerHeight` | `number` | no | — | Height of the flow container, used to scale the minimap. |
| `width` | `number` | no | `200` | Width in px. |
| `height` | `number` | no | `150` | Height in px. |
| `position` | `'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right'` | no | `bottom-right` | Canvas corner the minimap is pinned to: `bottom-right`, `bottom-left`, `top-left` or `top-right`. |
| `onViewportChange` | `(viewport: Viewport) => void` | no | — | Called with the new viewport when the minimap is dragged. |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |
| `ariaLabel` | `string` | no | — | Alias of `label` — the same invisible accessible name under the catalog spelling. Neither is deprecated. Not rendered — screen readers only. |
| `label` | `string \| undefined` | no | — | Accessible name for the minimap region. Not rendered — screen readers only. |
| `nodeColor` | `string \| undefined` | no | — | Fill colour for node rectangles in the minimap. |

## Object types

### `FlowNode`

A graph node.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | `string` | yes | — |
| `position` | `XYPosition` | yes | — |
| `data` | `Data` | no | — |
| `type` | `string` | no | Custom renderer key resolved via `nodeTypes`. |
| `selected` | `boolean` | no | — |
| `width` | `number` | no | Explicit/measured size used for handle anchors + bounding boxes. |
| `height` | `number` | no | — |

### `Viewport`

The pan/zoom state of the canvas pane.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `x` | `number` | yes | — |
| `y` | `number` | yes | — |
| `zoom` | `number` | yes | — |

## Examples

### Graph overview

```tsx
() => (
  <FlowMiniMap
    nodes={[
      { id: 'a', position: { x: 0, y: 0 } },
      { id: 'b', position: { x: 220, y: 120 } },
      { id: 'c', position: { x: 440, y: 0 } },
    ]}
    viewport={{ x: 0, y: 0, zoom: 1 }}
    containerWidth={400}
    containerHeight={300}
  />
)
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-surface`
- `--cascivo-color-border-strong`
- `--cascivo-color-accent`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `img`

## Dependencies

- `@cascivo/core`

## Tags

flow, minimap, overview, chrome

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# FlowNode

An HTML node box positioned in the viewport pane — draggable, selectable, with arbitrary children.

## Install

Ships in the `@cascivo/flow` package — install it (no copy-paste):

```sh
pnpm add @cascivo/flow
```

```tsx
import { FlowNode } from '@cascivo/flow'
import '@cascivo/flow/styles.css' // bundler: automatic. Needed only for no-bundler / SSR-externalised builds
```

## Category

`display`

## States

- `default`
- `dragging`
- `selected`
- `focus`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `id` | `string` | yes | — | Stable node id. |
| `position` | `{ x: number; y: number }` | no | — | Position in flow coords (controllable). |
| `defaultPosition` | `XYPosition` | no | — | Initial position for an uncontrolled node — the node then owns its own position as it is dragged. Pass `position` instead to control it. |
| `onPositionChange` | `(position: XYPosition) => void` | no | — | Fired while dragging. |
| `zoom` | `number` | no | `1` | Current zoom (drag deltas are divided by it). |
| `selected` | `boolean` | no | `false` | Whether the node is rendered as selected. |
| `draggable` | `boolean` | no | `true` | Whether the node can be dragged. |
| `interactive` | `boolean` | no | `true` | When false, the node is view-only: not draggable, selectable, or focusable. |
| `onSelect` | `(id: string) => void` | no | — | Called with the selected value. |
| `children` | `ReactNode` | no | — | Any cascivo content. |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |
| `onMeasure` | `(size: NodeSize) => void` | no | — | Reports the rendered box size so edges can anchor to the real node bounds. |

## Object types

### `XYPosition`

Shared geometry + graph types for the flow engine.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `x` | `number` | yes | — |
| `y` | `number` | yes | — |

## Examples

### A draggable node

```tsx
() => (
  <div style={{ position: 'relative', height: 160 }}>
    <FlowNode id="a" defaultPosition={{ x: 40, y: 50 }}>Service A</FlowNode>
  </div>
)
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-surface`
- `--cascivo-color-border`
- `--cascivo-color-accent`
- `--cascivo-radius-md`
- `--cascivo-shadow-sm`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `group`
- **Keyboard:** Tab (focus), Enter/Space (select)

## Dependencies

- `@cascivo/core`

## Tags

flow, node, draggable, graph

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# FlowPanel

An absolutely-positioned slot for custom flow-canvas UI (legend, toolbar).

## Install

Ships in the `@cascivo/flow` package — install it (no copy-paste):

```sh
pnpm add @cascivo/flow
```

```tsx
import { FlowPanel } from '@cascivo/flow'
import '@cascivo/flow/styles.css' // bundler: automatic. Needed only for no-bundler / SSR-externalised builds
```

## Category

`display`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `position` | `'top-left' \| 'top-center' \| 'top-right' \| 'bottom-left' \| 'bottom-center' \| 'bottom-right'` | no | `top-right` | Canvas edge slot the panel occupies: `top-right`, `top-center`, `top-left`, `bottom-left`, `bottom-center` or `bottom-right`. |
| `children` | `ReactNode` | no | — | Content rendered inside the component. |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |

## Examples

### A legend panel

```tsx
() => (
  <div style={{ position: 'relative', height: 160, border: '1px solid var(--cascivo-color-border)' }}>
    <FlowPanel position="top-right">Legend</FlowPanel>
  </div>
)
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-space-3`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `group`

## Dependencies

- `@cascivo/core`

## Tags

flow, panel, slot, chrome

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# FlowStory

A scripted, sequenced, looping flow animation — walks a graph step by step with fade-in captions.

## Install

Ships in the `@cascivo/flow` package — install it (no copy-paste):

```sh
pnpm add @cascivo/flow
```

```tsx
import { FlowStory } from '@cascivo/flow'
import '@cascivo/flow/styles.css' // bundler: automatic. Needed only for no-bundler / SSR-externalised builds
```

## Category

`display`

## States

- `playing`
- `paused`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `nodes` | `FlowNode[]` | yes | — | The nodes to render. |
| `edges` | `FlowEdge[]` | yes | — | The edges to render at each step. |
| `script` | `StoryStep[]` | yes | — | Ordered steps: { from, to, label? } or { edge, reverse? }. |
| `loop` | `boolean` | no | `true` | When true, navigation wraps around from end to start. |
| `stepDuration` | `number` | no | `1500` | How long (ms) each step is shown during playback. |
| `stepGap` | `number` | no | `0` | Extra pause after each step before advancing (ms) — makes the story easier to follow. |
| `playing` | `boolean` | no | — | Whether the story is currently playing (controlled). |
| `currentStep` | `number` | no | — | The controlled current step index. |
| `onStepChange` | `(step: number) => void` | no | — | Called with the new step index when it changes. |
| `controls` | `boolean` | no | `true` | Whether to show the controls. |
| `autoPlay` | `boolean` | no | `true` | When true, starts playback automatically on mount. |
| `interactive` | `boolean` | no | `false` | A storyline is a view by default — set true to allow selecting/dragging/connecting. |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |
| `background` | `boolean` | no | `true` | Render the dotted background pane behind the flow. |
| `clock` | `StoryClock` | no | — | Injectable clock for deterministic tests. |
| `labels` | `FlowStoryLabels` | no | — | Label overrides for the story playback controls. |

## Object types

### `StoryClock`

Shape of the `clock` prop.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `setTimeout` | `(callback: () => void, ms: number) => unknown` | yes | — |
| `clearTimeout` | `(handle: unknown) => void` | yes | — |

### `FlowNode`

A graph node.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | `string` | yes | — |
| `position` | `XYPosition` | yes | — |
| `data` | `Data` | no | — |
| `type` | `string` | no | Custom renderer key resolved via `nodeTypes`. |
| `selected` | `boolean` | no | — |
| `width` | `number` | no | Explicit/measured size used for handle anchors + bounding boxes. |
| `height` | `number` | no | — |

### `FlowEdge`

A directed connection between two nodes' handles.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | `string` | yes | — |
| `source` | `string` | yes | — |
| `target` | `string` | yes | — |
| `sourceHandle` | `string` | no | — |
| `targetHandle` | `string` | no | — |
| `type` | `EdgePathType \| string` | no | Custom renderer key resolved via `edgeTypes`. |
| `animated` | `boolean` | no | — |
| `label` | `string` | no | — |
| `selected` | `boolean` | no | — |
| `markerStart` | `boolean` | no | Arrowhead at the source end (points back toward the source). Default false. |
| `markerEnd` | `boolean` | no | Arrowhead at the target end (points at the target). Default true. |

## Examples

### A request/response storyboard

A<->B-->C: animate A→B, B→A, A→B, B→C, looping — each step fades in its caption.

```tsx
() => (
  <FlowStory
    style={{ height: 340 }}
    nodes={[
      { id: 'A', position: { x: 0, y: 100 }, data: { label: 'Client' } },
      { id: 'B', position: { x: 240, y: 100 }, data: { label: 'Gateway' } },
      { id: 'C', position: { x: 480, y: 100 }, data: { label: 'Service' } },
    ]}
    edges={[
      { id: 'ab', source: 'A', target: 'B' },
      { id: 'bc', source: 'B', target: 'C' },
    ]}
    script={[
      { from: 'A', to: 'B', label: 'Request sent' },
      { from: 'B', to: 'A', label: 'Acknowledged' },
      { from: 'A', to: 'B', label: 'Payload streamed' },
      { from: 'B', to: 'C', label: 'Forwarded to Service' },
    ]}
    loop
  />
)
```

### A linear pipeline

Each stage animates and is captioned in turn.

```tsx
() => (
  <FlowStory
    style={{ height: 320 }}
    nodes={[
      { id: 'ingest', position: { x: 0, y: 100 }, data: { label: 'Ingest' } },
      { id: 'transform', position: { x: 240, y: 100 }, data: { label: 'Transform' } },
      { id: 'load', position: { x: 480, y: 100 }, data: { label: 'Load' } },
    ]}
    edges={[
      { id: 'it', source: 'ingest', target: 'transform' },
      { id: 'tl', source: 'transform', target: 'load' },
    ]}
    script={[
      { from: 'ingest', to: 'transform', label: 'Records ingested', description: 'Raw events read from the source' },
      { from: 'transform', to: 'load', label: 'Transformed', description: 'Cleaned and enriched' },
    ]}
  />
)
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-surface`
- `--cascivo-color-accent`
- `--cascivo-color-text-muted`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `group`
- **Keyboard:** Tab (focus controls), Enter/Space (play/pause, prev, next)

## Dependencies

- `@cascivo/core`

## Tags

flow, animation, storyline, walkthrough, sequence

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Form

Typed signal-based form store (createForm/useForm) with sync/async validation and a thin Form element wrapper

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add form
```

Or use it from the prebuilt package without copying:

```tsx
import { Form } from '@cascivo/react'
```

## Category

`inputs`

## States

- `idle`
- `submitting`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `form` | `FormStore<T>` | yes | — | The form store holding values, validation, and submission state. |
| `onValid` | `(values: T) => void \| Promise<void>` | yes | — | Called with the values when the form passes validation. |
| `children` | `ReactNode` | yes | — | Content rendered inside the component. |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |

## Examples

### Basic form with validation

```tsx
function Demo() {
  const form = useForm({
    initialValues: { email: '' },
    validate: (v) => v.email.includes('@') ? {} : { email: 'Invalid email' },
  })
  const email = form.field('email')
  return (
    <Form form={form} onValid={console.log}>
      <Input
        label="Email"
        value={email.value}
        onChange={(e) => email.onChange(e.currentTarget.value)}
        onBlur={email.onBlur}
        error={email.error}
      />
      <Button type="submit">Save</Button>
    </Form>
  )
}
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-space-4`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `form`
- **Keyboard:** Tab, Enter

## Dependencies

- `@cascivo/core`

## Tags

form, validation, signals, input

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Header

App top bar with brand, primary navigation links, and an actions slot

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add header
```

Or use it from the prebuilt package without copying:

```tsx
import { Header } from '@cascivo/react'
```

## Category

`navigation`

## States

- `default`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `labels` | `HeaderLabels` | no | — | Overrides for the component’s user-visible strings (i18n). |
| `brand` | `React.ReactNode` | no | — | Product name or logo area, typically wraps a link |
| `links` | `{ label: string; href: string; active?: boolean }[]` | no | — | Primary navigation links; active link gets aria-current="page" |
| `actions` | `React.ReactNode` | no | — | Right-aligned slot for buttons or an avatar |
| `sticky` | `boolean` | no | `false` | When true, the header sticks to the top on scroll. |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |

## Examples

### Basic

```tsx
<Header brand="cascivo" links={[{ label: 'Docs', href: '/docs' }]} />
```

### With actions

```tsx
<Header brand="cascivo" actions={<Button size="sm">Sign in</Button>} />
```

### Sticky

```tsx
<Header sticky brand="cascivo" links={links} />
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-header-bg`
- `--cascivo-color-surface`
- `--cascivo-color-border`
- `--cascivo-color-text`
- `--cascivo-color-text-subtle`
- `--cascivo-color-bg-subtle`
- `--cascivo-focus-ring`
- `--cascivo-z-raised`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `banner`
- **Keyboard:** Tab

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

navigation, app-shell, top-bar, banner

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# HeaderPanel

Non-modal panel anchored below the shell header at the inline-end edge — hosts notifications, app switcher, user settings

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add header-panel
```

Or use it from the prebuilt package without copying:

```tsx
import { HeaderPanel } from '@cascivo/react'
```

## Category

`navigation`

## States

- `open`
- `closed`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `open` | `boolean` | yes | — | Controlled open state |
| `onClose` | `() => void` | yes | — | Called on close button click or light-dismiss |
| `label` | `string` | yes | — | Accessible label for the region (shown as header title). Rendered on screen. |
| `children` | `ReactNode` | yes | — | Content rendered inside the component. |
| `labels` | `HeaderPanelLabels` | no | — | i18n overrides |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |

## Examples

### Notification panel

Pair with a ShellHeader action: action active=open, onAction toggles open

```tsx
<HeaderPanel open={open} onClose={() => setOpen(false)} label="Notifications">
  <p>3 unread messages</p>
</HeaderPanel>
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-shell-header-block-size`
- `--cascivo-shell-panel-inline-size`
- `--cascivo-color-surface`
- `--cascivo-color-border`
- `--cascivo-shadow-md`
- `--cascivo-motion-enter`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `region`
- **Keyboard:** Escape, Tab

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

navigation, panel, shell, console, overlay, notifications

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Heading

Section heading with semantic level decoupled from visual size

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add heading
```

Or use it from the prebuilt package without copying:

```tsx
import { Heading } from '@cascivo/react'
```

## Category

`display`

## Sizes

- `sm`
- `md`
- `lg`
- `xl`
- `2xl`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `level` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | no | `2` | Heading level (1–6) mapping to h1–h6. |
| `size` | `'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'` | no | `derived from level (1→2xl, 2→xl, 3→lg, 4→md, 5→sm, 6→sm)` | Visual size of the component (e.g. 'sm', 'md', 'lg'). |

## Examples

### Default

```tsx
<Heading>Section title</Heading>
```

### Page title

```tsx
<Heading level={1}>Page title</Heading>
```

### Decoupled size

Keep the document outline correct while controlling the visual scale

```tsx
<Heading level={2} size="2xl">Visually large, semantically h2</Heading>
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-font-display`
- `--cascivo-font-semibold`
- `--cascivo-leading-tight`
- `--cascivo-tracking-tight`
- `--cascivo-color-text`
- `--cascivo-text-base`
- `--cascivo-text-lg`
- `--cascivo-text-xl`
- `--cascivo-text-2xl`
- `--cascivo-text-3xl`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `heading`

## Dependencies

- `@cascivo/core`

## Tags

typography, heading, title

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# HoverCard

Hover-triggered popover with configurable open/close delay

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add hover-card
```

Or use it from the prebuilt package without copying:

```tsx
import { HoverCard } from '@cascivo/react'
```

## Category

`overlay`

## States

- `open`
- `closed`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `children` | `React.ReactNode` | yes | — | A HoverCardTrigger and HoverCardContent pair. |
| `openDelay` | `number` | no | `300` | Delay (ms) before the card opens on hover/focus. |
| `closeDelay` | `number` | no | `100` | Delay (ms) before the card closes after hover/focus leaves. |

## Examples

### Profile preview

```tsx
<HoverCard>
  <HoverCardTrigger><a href="/users/ada">@ada</a></HoverCardTrigger>
  <HoverCardContent>
    <Avatar name="Ada Lovelace" />
    <p>Wrote the first program.</p>
  </HoverCardContent>
</HoverCard>
```

### Custom delays

```tsx
<HoverCard openDelay={500} closeDelay={200}>
  <HoverCardTrigger>Definition</HoverCardTrigger>
  <HoverCardContent>A longer explanation shown on hover or focus.</HoverCardContent>
</HoverCard>
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-surface`
- `--cascivo-color-border`
- `--cascivo-radius-md`
- `--cascivo-shadow-md`
- `--cascivo-motion-enter`
- `--cascivo-motion-exit`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `complementary`
- **Keyboard:** Tab, Escape

## Dependencies

- `@cascivo/core`

## Tags

overlay, hover, preview, floating

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# IconButton

Square, icon-only button with a required accessible label

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add icon-button
```

Or use it from the prebuilt package without copying:

```tsx
import { IconButton } from '@cascivo/react'
```

## Category

`inputs`

## Variants

- `ghost`
- `outline`
- `filled`

## Sizes

- `sm`
- `md`
- `lg`

## States

- `idle`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `label` | `string` | no | — | Accessible name for the icon-only button. Not rendered — screen readers only; `ariaLabel` is the same thing under the catalog name. Not rendered — screen readers only. |
| `ariaLabel` | `string` | no | — | Alias for `label` (the catalog convention for an invisible accessible name). Both work; pass exactly one. Not rendered — screen readers only. |
| `icon` | `React.ReactNode` | no | — | Icon element rendered in the component. |
| `variant` | `'ghost' \| 'outline' \| 'filled'` | no | `ghost` | `ghost` is transparent until hover, `outline` adds a border, `filled` gives the button a solid surface. |
| `size` | `'sm' \| 'md' \| 'lg'` | no | `md` | Visual size of the component (e.g. 'sm', 'md', 'lg'). |
| `asChild` | `boolean` | no | `false` | When true, renders the child element as the root via Slot, merging props (polymorphic rendering). |
| `disabled` | `boolean` | no | `false` | When true, disables the control and removes it from the tab order. |
| `onClick` | `React.MouseEventHandler<HTMLButtonElement>` | no | — | Called when the element is clicked. |

## Examples

### Ghost

```tsx
<IconButton label="Settings"><GearIcon /></IconButton>
```

### Filled

```tsx
<IconButton label="Add" variant="filled" icon={<PlusIcon />} />
```

### As link

```tsx
<IconButton label="Home" asChild><a href="/"><HomeIcon /></a></IconButton>
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-control-height-sm`
- `--cascivo-control-height-md`
- `--cascivo-control-height-lg`
- `--cascivo-button-radius`
- `--cascivo-radius-control`
- `--cascivo-color-primary`
- `--cascivo-color-primary-fg`
- `--cascivo-color-bg-subtle`
- `--cascivo-color-border`
- `--cascivo-color-surface`
- `--cascivo-focus-ring`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `button`
- **Keyboard:** Enter, Space

## Dependencies

- `@cascivo/core`

## Tags

action, icon, compact, toolbar

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Image

Image with load state, blur-up placeholder, graceful fallback, and optional zoom

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add image
```

Or use it from the prebuilt package without copying:

```tsx
import { Image } from '@cascivo/react'
```

## Category

`display`

## States

- `loading`
- `loaded`
- `error`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `src` | `string` | no | — | Image source URL. |
| `alt` | `string` | no | `` | Alternative text describing the image. |
| `fallbackSrc` | `string` | no | — | Image shown if src fails to load |
| `width` | `string \| number` | no | — | Intrinsic width in px, forwarded to the `<img>`. Set it together with `height` so the browser can reserve the box before the image loads (no layout shift). |
| `height` | `string \| number` | no | — | Intrinsic height in px, forwarded to the `<img>`. Pair with `width` to reserve the box and avoid layout shift. |
| `radius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'full'` | no | `md` | Corner radius of the image ('none' \| 'sm' \| 'md' \| 'lg' \| 'full'). |
| `zoom` | `boolean` | no | `false` | When true, zooms the image on hover. |
| `removeWrapper` | `boolean` | no | `false` | Render a bare <img> with no wrapper, placeholder, or zoom |
| `isBlurred` | `boolean` | no | `false` | When true, renders a blurred backdrop behind the image. |

## Examples

### Basic

```tsx
<Image src="/photo.jpg" alt="A photo" width={320} height={240} />
```

### With fallback

```tsx
<Image src="/broken.jpg" fallbackSrc="/placeholder.jpg" alt="A photo" />
```

### Blurred placeholder

```tsx
<Image src="/photo.jpg" alt="A photo" isBlurred />
```

### Hover zoom

```tsx
<Image src="/photo.jpg" alt="A photo" zoom />
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-radius-none`
- `--cascivo-radius-sm`
- `--cascivo-radius-md`
- `--cascivo-radius-lg`
- `--cascivo-radius-full`
- `--cascivo-color-bg-subtle`
- `--cascivo-color-border`
- `--cascivo-space-12`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `img`

## Dependencies

- `@cascivo/core`

## Tags

image, media, display, loading

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Indicator

Positions an overlay element (badge, dot, count) at a corner of its child

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add indicator
```

Or use it from the prebuilt package without copying:

```tsx
import { Indicator } from '@cascivo/react'
```

## Category

`layout`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `children` | `React.ReactNode` | yes | — | Content rendered inside the component. |
| `overlay` | `React.ReactNode` | yes | — | The element to display at the corner (badge, dot, count) |
| `placement` | `'top-start' \| 'top-end' \| 'bottom-start' \| 'bottom-end'` | no | `top-end` | Corner of the wrapped element the dot or count sits on: `top-end`, `top-start`, `bottom-start` or `bottom-end`. |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |

## Examples

### Notification count

Notification count badge on an icon button

```tsx
<Indicator overlay={<Badge>3</Badge>}><Button variant="ghost"><Icon name="bell" /></Button></Indicator>
```

### Online status

Online status dot on an avatar

```tsx
<Indicator overlay={<span className="status-dot" />} placement="bottom-end"><Avatar src="/user.jpg" /></Indicator>
```

### Bottom-start placement

Indicator positioned at the bottom-start corner

```tsx
<Indicator overlay={<Badge variant="destructive">!</Badge>} placement="bottom-start"><Card>Content</Card></Indicator>
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `none`

## Tags

badge, indicator, overlay, notification, layout

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# InfiniteScroll

Loads the next page when the end of a list scrolls into view

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add infinite-scroll
```

Or use it from the prebuilt package without copying:

```tsx
import { InfiniteScroll } from '@cascivo/react'
```

## Category

`feedback`

## States

- `idle`
- `loading`
- `disabled`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `onLoadMore` | `() => Promise<unknown> \| unknown` | yes | — | Called when the sentinel comes into view, or the button is activated; the spinner shows until it settles |
| `disabled` | `boolean` | no | `false` | When true, stops observing and renders nothing — there are no more pages. |
| `rootMargin` | `string` | no | `'200px'` | How far ahead of the end to start loading, as an IntersectionObserver root margin. |
| `labels` | `{ loadMore?: string; loading?: string }` | no | — | Overrides for the component’s user-visible strings (i18n). |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |

## Examples

### Basic

Place it as the last child of the scrolling region, after the list.

```tsx
<InfiniteScroll onLoadMore={loadNextPage} />
```

### Stopping at the last page

Renders nothing and stops observing once there is nothing left to load.

```tsx
<InfiniteScroll onLoadMore={loadNextPage} disabled={!hasMore} />
```

### Loading earlier

Starts the next page well before the user reaches the end.

```tsx
<InfiniteScroll onLoadMore={loadNextPage} rootMargin="600px" />
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-text-muted`
- `--cascivo-color-border`
- `--cascivo-color-surface-2`
- `--cascivo-color-foreground`
- `--cascivo-radius-md`
- `--cascivo-ring-width`
- `--cascivo-ring-color`
- `--cascivo-text-ui`
- `--cascivo-target-min-coarse`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `button`
- **Keyboard:** Enter, Space

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

feedback, infinite-scroll, pagination, list, scroll, mobile, lazy

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# InlineCitation

A numbered citation marker inside AI-generated text that links to its source and previews it in a hover card

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add inline-citation
```

Or use it from the prebuilt package without copying:

```tsx
import { InlineCitation } from '@cascivo/react'
```

## Category

`display`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `index` | `number` | yes | — | The visible citation number — the source’s position in the matching Sources list. |
| `source` | `AiSource` | yes | — | The cited source (`title`, `url`, optional `description`). Only absolute http(s) URLs become links. |
| `labels` | `{ source?: string }` | no | — | Overrides for the component’s user-visible strings (i18n). `source` may contain `{index}`; the accessible name is "<source>: <title>". |

## Object types

### `AiSource`

One source an answer cites (shared with Sources).

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `title` | `string` | yes | The source’s title. |
| `url` | `string` | yes | Treated as untrusted: only absolute http(s) URLs are linked. |
| `description` | `ReactNode` | no | An excerpt shown in the hover card. |

## Examples

### In a sentence

```tsx
<p>
  Refunds are available for 30 days.
  <InlineCitation index={1} source={{ title: 'Refund policy', url: 'https://example.com/refunds' }} />
</p>
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-color-ai-subtle`
- `--cascivo-color-ai-sheen`
- `--cascivo-color-text`
- `--cascivo-color-text-muted`
- `--cascivo-radius-full`
- `--cascivo-focus-ring`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `link`
- **Keyboard:** Tab, Enter

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

ai, citation, sources, footnote, references, provenance

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# InlineLoading

Compact inline status indicator that pairs a label with a loading, success, or error state

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add inline-loading
```

Or use it from the prebuilt package without copying:

```tsx
import { InlineLoading } from '@cascivo/react'
```

## Category

`feedback`

## States

- `inactive`
- `active`
- `finished`
- `error`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `status` | `'inactive' \| 'active' \| 'finished' \| 'error'` | yes | — | Status state. |
| `label` | `ReactNode` | no | — | Text label for the control. Rendered on screen. |
| `labels` | `{ active?: string; finished?: string; error?: string }` | no | — | Overrides for the component’s user-visible strings (i18n). |

## Examples

### Active

```tsx
<InlineLoading status="active" />
```

### Finished

```tsx
<InlineLoading status="finished" label="Saved" />
```

### Error

```tsx
<InlineLoading status="error" label="Save failed" />
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-color-text`
- `--cascivo-color-text-muted`
- `--cascivo-color-success`
- `--cascivo-color-destructive`
- `--cascivo-motion-enter`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `status`

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

loading, status, progress, feedback, spinner

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Input

Text input field with optional label, hint, and error state

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add input
```

Or use it from the prebuilt package without copying:

```tsx
import { Input } from '@cascivo/react'
```

## Category

`inputs`

## Sizes

- `sm`
- `md`
- `lg`

## States

- `idle`
- `focused`
- `error`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `label` | `string` | no | — | Text label for the control (standalone use). Omit it when wrapping the Input in a Field — the Field owns the label, and setting both double-labels the control. Rendered on screen. |
| `hint` | `string` | no | — | Supplementary hint text shown with the control. |
| `error` | `string` | no | — | Error message shown when the value is invalid. |
| `size` | `'sm' \| 'md' \| 'lg'` | no | `md` | Visual size of the component (e.g. 'sm', 'md', 'lg'). |
| `placeholder` | `string` | no | — | Placeholder text shown when the field is empty. |
| `disabled` | `boolean` | no | `false` | When true, disables the control and removes it from the tab order. |
| `ariaLabel` | `string` | no | — | Invisible accessible name, for when a visible element outside this component already labels it and `label` would render that text a second time. ⚠ `label` on this component is **visible**; `IconButton.label`/`Sparkline.label` are invisible names, which is the prior that costs adopters a duplicated label. The raw DOM `aria-label` still wins over this. Not rendered — screen readers only. |
| `ai` | `boolean` | no | `false` | AI presence: an AI-tinted border and a soft aura, marking a value AI produced or suggested. Visual only — put an AiBadge in the label so the provenance is also text, and clear `ai` once the person edits the value. |

## Examples

### With label

```tsx
<Input label="Email" placeholder="you@example.com" />
```

### With error

```tsx
<Input label="Email" error="Invalid email address" />
```

### AI-suggested value

```tsx
<Input label="Subject" ai defaultValue="Weekly report" />
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-color-surface`
- `--cascivo-color-border`
- `--cascivo-color-accent`
- `--cascivo-color-destructive`
- `--cascivo-radius-input`
- `--cascivo-focus-ring`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `textbox`
- **Keyboard:** Tab, Shift+Tab

## Dependencies

- `@cascivo/core`

## Tags

form, text, input, ai

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# InputGroup

Prefix/suffix addon wrapper for Input; InputGroupAddon renders inline icons/units inside the field border; InputGroupButtons collapses adjacent button borders

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add input-group
```

Or use it from the prebuilt package without copying:

```tsx
import { InputGroup } from '@cascivo/react'
```

## Category

`inputs`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `prefix` | `ReactNode` | no | — | Content rendered before the input (leading adornment). |
| `suffix` | `ReactNode` | no | — | Content rendered after the input (trailing adornment). |
| `children` | `ReactNode` | yes | — | Content rendered inside the component. |

## Examples

### With prefix

```tsx
<InputGroup prefix="https://"><Input placeholder="example.com" /></InputGroup>
```

### With leading icon addon

```tsx
<InputGroup><InputGroupAddon><svg viewBox="0 0 16 16" width="16" height="16"><circle cx="6" cy="6" r="4" fill="none" stroke="currentColor" strokeWidth="1.5"/><path d="M10 10l3 3" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round"/></svg></InputGroupAddon><Input placeholder="Search…" aria-label="Search" /></InputGroup>
```

### With trailing unit addon

```tsx
<InputGroup><Input placeholder="0.00" aria-label="Weight" /><InputGroupAddon align="inline-end">kg</InputGroupAddon></InputGroup>
```

### InputGroupButtons

```tsx
<InputGroupButtons><Button>Left</Button><Button>Right</Button></InputGroupButtons>
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-color-bg-subtle`
- `--cascivo-color-border`
- `--cascivo-color-text-subtle`
- `--cascivo-radius-input`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `generic`

## Dependencies

- `@cascivo/core`

## Tags

form, input, addon, group, layout

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Item

Generic content row primitive with media, content, and action regions

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add item
```

Or use it from the prebuilt package without copying:

```tsx
import { Item } from '@cascivo/react'
```

## Category

`display`

## Variants

- `default`
- `muted`

## Sizes

- `sm`
- `md`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `asChild` | `boolean` | no | `false` | When true, renders the child element as the root via Slot, merging props (polymorphic rendering). |
| `variant` | `'default' \| 'muted'` | no | `default` | `muted` gives the row a subtle background — for a selected or highlighted item; `default` leaves it transparent. |
| `size` | `'sm' \| 'md'` | no | `md` | Visual size of the component (e.g. 'sm', 'md', 'lg'). |

## Examples

### Item with media, content, and actions

```tsx
<Item>
  <ItemMedia><Avatar /></ItemMedia>
  <ItemContent>
    <ItemTitle>Ada Lovelace</ItemTitle>
    <ItemDescription>Mathematician</ItemDescription>
  </ItemContent>
  <ItemActions><Button size="sm">Edit</Button></ItemActions>
</Item>
```

### As a link via asChild

```tsx
<Item asChild>
  <a href="/profile">
    <ItemContent><ItemTitle>Profile</ItemTitle></ItemContent>
  </a>
</Item>
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-color-text`
- `--cascivo-color-text-subtle`
- `--cascivo-color-bg-subtle`
- `--cascivo-radius-item`
- `--cascivo-space-3`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `none`

## Dependencies

- `@cascivo/core`

## Tags

row, primitive, list-item, layout

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Join

Groups adjacent children into a seamless joined element by removing interior borders and radii

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add join
```

Or use it from the prebuilt package without copying:

```tsx
import { Join } from '@cascivo/react'
```

## Category

`layout`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `children` | `React.ReactNode` | yes | — | Content rendered inside the component. |
| `orientation` | `'horizontal' \| 'vertical'` | no | `horizontal` | Axis the joined children flow along: `horizontal` for a row, `vertical` for a column. Inner corners are squared off either way. |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |

## Examples

### Search group

Input and button joined into a single search control

```tsx
<Join><Input placeholder="Search…" /><Button>Go</Button></Join>
```

### Segmented buttons

Segmented button row with no gaps between items

```tsx
<Join><Button variant="secondary">Day</Button><Button variant="secondary">Week</Button><Button variant="secondary">Month</Button></Join>
```

### Vertical stack

Vertically joined button group

```tsx
<Join orientation="vertical"><Button>Top</Button><Button>Middle</Button><Button>Bottom</Button></Join>
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `none`

## Tags

group, join, segmented, layout

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Kbd

Displays a keyboard key or shortcut

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add kbd
```

Or use it from the prebuilt package without copying:

```tsx
import { Kbd } from '@cascivo/react'
```

## Category

`display`

## Sizes

- `sm`
- `md`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `size` | `'sm' \| 'md'` | no | `md` | Visual size of the component (e.g. 'sm', 'md', 'lg'). |

## Examples

### Single key

```tsx
<Kbd>⌘</Kbd>
```

### Shortcut

Compose multiple keys to show a shortcut

```tsx
<span><Kbd>⌘</Kbd> + <Kbd>K</Kbd></span>
```

### Small

```tsx
<Kbd size="sm">Esc</Kbd>
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-color-text-subtle`
- `--cascivo-color-surface-raised`
- `--cascivo-color-border`
- `--cascivo-color-border-strong`
- `--cascivo-radius-sm`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `kbd`

## Dependencies

- `@cascivo/core`

## Tags

keyboard, shortcut, hotkey

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Label

Accessible caption for a form control

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add label
```

Or use it from the prebuilt package without copying:

```tsx
import { Label } from '@cascivo/react'
```

## Category

`inputs`

## States

- `default`
- `disabled`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `htmlFor` | `string` | no | — | Id of the form control this label is associated with. |
| `asChild` | `boolean` | no | `false` | When true, renders the child element as the root via Slot, merging props (polymorphic rendering). |
| `required` | `boolean` | no | `false` | When true, marks the field as required. |
| `disabled` | `boolean` | no | `false` | When true, disables the control and removes it from the tab order. |
| `children` | `ReactNode` | yes | — | Content rendered inside the component. |
| `labels` | `{ required?: string }` | no | — | Overrides for the component’s user-visible strings (i18n). |

## Examples

### Basic

```tsx
<Label htmlFor="email">Email</Label>
```

### Required

```tsx
<Label htmlFor="email" required>Email</Label>
```

### asChild

Render the label semantics onto a custom element via Slot.

```tsx
<Label asChild htmlFor="email"><span>Email</span></Label>
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-space-1`
- `--cascivo-font-sans`
- `--cascivo-text-sm`
- `--cascivo-font-medium`
- `--cascivo-leading-snug`
- `--cascivo-leading-none`
- `--cascivo-color-text`
- `--cascivo-color-destructive`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `label`

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

form, caption, accessibility

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# LargeTitleHeader

Scrolling region whose large title collapses into a compact sticky bar as it scrolls

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add large-title-header
```

Or use it from the prebuilt package without copying:

```tsx
import { LargeTitleHeader } from '@cascivo/react'
```

## Category

`navigation`

## States

- `expanded`
- `collapsed`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `title` | `string` | yes | — | The page title, rendered as the large heading and mirrored in the compact bar |
| `children` | `React.ReactNode` | yes | — | Content rendered inside the component. |
| `leading` | `React.ReactNode` | no | — | Leading slot of the compact bar — typically a back control |
| `actions` | `React.ReactNode` | no | — | Trailing slot of the compact bar — typically icon buttons |
| `level` | `1 \| 2 \| 3` | no | `1` | Heading level for the title, mapping to h1–h3. |
| `collapseDistance` | `number` | no | `48` | Scroll distance (px) over which the large title collapses into the bar. |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |

## Examples

### Basic

The component owns the scroll container; give it a parent with a height.

```tsx
<LargeTitleHeader title="Library">
  <List>
    <ListItem>Recently Added</ListItem>
    <ListItem>Artists</ListItem>
    <ListItem>Albums</ListItem>
  </List>
</LargeTitleHeader>
```

### With a back control and actions

Both slots stay in the compact bar and never scroll away.

```tsx
<LargeTitleHeader
  title="Downloads"
  leading={<IconButton label="Back" onClick={goBack}>←</IconButton>}
  actions={<IconButton label="Sort">⇅</IconButton>}
>
  <FileList files={files} />
</LargeTitleHeader>
```

### Longer collapse

Stretches the reveal over more scroll distance.

```tsx
<LargeTitleHeader title="Recently Played" collapseDistance={96}>
  <TrackList tracks={tracks} />
</LargeTitleHeader>
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-color-surface`
- `--cascivo-color-foreground`
- `--cascivo-border-subtle`
- `--cascivo-text-ui`
- `--cascivo-text-heading-lg`
- `--cascivo-font-semibold`
- `--cascivo-font-bold`
- `--cascivo-leading-tight`
- `--cascivo-target-min-coarse`
- `--cascivo-z-raised`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `heading`

## Dependencies

- `@cascivo/core`

## Tags

navigation, header, title, mobile, scroll, sticky, ios

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# AppFrame

Full-page application shell with persisted collapsible sidebar. Includes a signal-driven top progress bar with determinate progress, error state, and dismissible error strip.

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add layout/app-shell
```

_Copy-paste only — `AppFrame` is not exported from `@cascivo/react`. Run the command above to own the source, or compose it from the exported primitives (`Flex`, `Grid`, `Heading`, …)._

## Category

`layout`

## States

- `expanded`
- `collapsed`
- `loading`
- `error`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `footer` | `ReactNode` | no | — | Optional sticky footer rendered below the content area. |
| `sideNavMode` | `'push' \| 'overlay'` | no | `push` | push (default): sidebar takes grid space; overlay: sidebar floats over content. |
| `header` | `ReactNode` | yes | — | Top header slot |
| `sideNav` | `ReactNode` | no | — | Side navigation slot |
| `aside` | `ReactNode` | no | — | Right aside slot |
| `children` | `ReactNode` | yes | — | Main content |
| `persistKey` | `string \| false` | no | `cascade.appshell` | localStorage key prefix. Pass false to disable persistence. |
| `state` | `ShellState` | no | — | External shell state from createShellState(). Created internally when omitted. |

## Examples

### Basic

App shell with collapsible nav

```tsx
<AppFrame header={<Header />} sideNav={<Nav />}>content</AppFrame>
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-space-3`
- `--cascivo-space-4`
- `--cascivo-space-6`
- `--cascivo-duration-200`
- `--cascivo-ease-out`
- `--cascivo-color-border`
- `--cascivo-color-surface`
- `--cascivo-text-xs`
- `--cascivo-color-accent`
- `--cascivo-color-destructive`
- `--cascivo-color-destructive-subtle`
- `--cascivo-focus-ring`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `generic`

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`
- `@cascivo/storage`

## Tags

layout, shell, sidebar, navigation

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# AuthLayout

Centered card layout for authentication pages (login, register, forgot password).

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add layout/auth-layout
```

Or use it from the prebuilt package without copying:

```tsx
import { AuthLayout } from '@cascivo/react'
```

## Category

`layout`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `children` | `ReactNode` | yes | — | Auth form content |
| `logo` | `ReactNode` | no | — | Optional logo displayed above the form |

## Examples

### Login

Centered auth card with logo

```tsx
<AuthLayout logo={<img src="/logo.svg" alt="Logo" />}><form>...</form></AuthLayout>
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-color-bg-subtle`
- `--cascivo-color-surface`
- `--cascivo-color-border`
- `--cascivo-radius-lg`
- `--cascivo-space-4`
- `--cascivo-space-6`
- `--cascivo-space-8`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `generic`

## Dependencies

- `@cascivo/core`

## Tags

layout, auth, login, page

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# AutoGrid

Media-query-free responsive grid — columns auto-fill based on available space.

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add layout/auto-grid
```

Or use it from the prebuilt package without copying:

```tsx
import { AutoGrid } from '@cascivo/react'
```

## Category

`layout`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `min` | `string` | no | `"16rem"` | Minimum track width before items wrap to fewer columns |
| `gap` | `1\|2\|3\|4\|5\|6\|8\|10\|12` | no | `4` | Spacing token step. Maps to the --cascivo-space-* scale, which intentionally skips 7/9/11 — use 6 or 8. |

## Examples

### Auto-filling grid

Items fill available space and wrap when narrower than 12rem

```tsx
<AutoGrid min="12rem" gap={4}><div>Card 1</div><div>Card 2</div><div>Card 3</div></AutoGrid>
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-space-*`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `generic`

## Dependencies

- `@cascivo/core`

## Tags

layout, grid, responsive

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Center

Horizontally centered container with a configurable max-width.

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add layout/center
```

Or use it from the prebuilt package without copying:

```tsx
import { Center } from '@cascivo/react'
```

## Category

`layout`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `maxWidth` | `string` | no | `48rem` | CSS max-width value |

## Examples

### Centered content

Centered container with custom max-width

```tsx
<Center maxWidth="60rem"><p>Content</p></Center>
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-space-4`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `generic`

## Dependencies

- `@cascivo/core`

## Tags

layout, center, wrapper

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Columns

Equal-width multi-column layout that collapses to single column on narrow viewports.

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add layout/columns
```

Or use it from the prebuilt package without copying:

```tsx
import { Columns } from '@cascivo/react'
```

## Category

`layout`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `count` | `2\|3\|4` | no | `2` | Number of equal columns |
| `gap` | `1\|2\|3\|4\|5\|6\|8\|10\|12` | no | `4` | Spacing token step |

## Examples

### Three columns

Three equal columns

```tsx
<Columns count={3}><div>A</div><div>B</div><div>C</div></Columns>
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-space-*`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `generic`

## Dependencies

- `@cascivo/core`

## Tags

layout, grid, columns

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# DashboardLayout

Dashboard page layout with stats strip, main content area, and optional aside.

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add layout/dashboard-layout
```

Or use it from the prebuilt package without copying:

```tsx
import { DashboardLayout } from '@cascivo/react'
```

## Category

`layout`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `stats` | `ReactNode` | no | — | Stats/KPI row (auto-fit grid) |
| `main` | `ReactNode` | yes | — | Main content area |
| `aside` | `ReactNode` | no | — | Optional aside panel (20rem) |

## Examples

### With stats

Stats + main layout

```tsx
<DashboardLayout stats={<div>KPIs</div>} main={<div>Content</div>} />
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-space-4`
- `--cascivo-space-6`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `generic`

## Dependencies

- `@cascivo/core`

## Tags

layout, dashboard, page

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Flex

Flex layout primitive for vertical or horizontal stacking with gap control. ⚠ Unlike CSS `flex-direction`, `direction` defaults to `vertical` — pass `direction="horizontal"` for a row.

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add layout/flex
```

Or use it from the prebuilt package without copying:

```tsx
import { Flex } from '@cascivo/react'
```

## Category

`layout`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `direction` | `'vertical' \| 'horizontal'` | no | `vertical` | Flex direction. ⚠ Defaults to `vertical`, unlike CSS `flex-direction` (and unlike Chakra/MUI/Radix `Flex`, which default to a row) — `<Flex justify="between">` alone produces a centered vertical stack. |
| `gap` | `1\|2\|3\|4\|5\|6\|8\|10\|12` | no | `4` | Spacing token step |
| `align` | `'start'\|'center'\|'end'\|'stretch'` | no | — | align-items |
| `justify` | `'start'\|'center'\|'end'\|'between'` | no | — | justify-content |
| `wrap` | `boolean` | no | `false` | Allow wrapping |
| `size` | `'auto' \| 'fixed' \| 'grow' \| 'shrink'` | no | `auto` | FlexItem: main-axis sizing. 'fixed' (flex: 0 0 auto) is what a fixed-width child like Sparkline needs; 'grow' takes the leftover width without shrinking; 'shrink' gives way but never grows. |
| `basis` | `string` | no | — | FlexItem: flex-basis — the child's size before free space is distributed. Any CSS length. |
| `truncate` | `boolean` | no | `false` | FlexItem: allow the child to shrink below its content width (releases the flex item's `min-width: auto` floor and ellipsizes). Without it a long unbreakable string pushes its siblings out of the row. |

## Examples

### Vertical

Default vertical stack

```tsx
<Flex gap={4}><div>A</div><div>B</div></Flex>
```

### Horizontal

Row layout

```tsx
<Flex direction="horizontal" gap={2}><div>A</div><div>B</div></Flex>
```

### Toolbar: one field absorbs the row, the rest keep their width

Without FlexItem the Search takes the whole row and pushes the Select onto the next line

```tsx
<Flex direction="horizontal" gap={2}>
  <FlexItem size="grow" basis="0"><Search ariaLabel="Filter deployments" /></FlexItem>
  <FlexItem size="fixed"><Select options={states} ariaLabel="State" /></FlexItem>
</Flex>
```

### Protecting a fixed-width child

Sparkline is fixed-width and will not shrink; `size="fixed"` keeps it out of flex sizing, `truncate` lets the URL beside it ellipsize instead of pushing it out

```tsx
<Flex direction="horizontal" gap={3} align="center">
  <FlexItem truncate>{deployment.url}</FlexItem>
  <FlexItem size="fixed"><Sparkline data={points} label="Requests" /></FlexItem>
</Flex>
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-space-*`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `generic`

## Dependencies

- `@cascivo/core`

## Tags

layout, flex, stack, spacing

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Grid

CSS grid layout primitive with responsive column collapsing. Establishes its own containment, so responsive `cols` adapt to the grid’s own slot width with no wrapper or container ancestor required.

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add layout/grid
```

Or use it from the prebuilt package without copying:

```tsx
import { Grid } from '@cascivo/react'
```

## Category

`layout`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `cols` | `number \| { base?: number; sm?: number; md?: number; lg?: number; xl?: number }` | no | `12` | Column count — a number, or a per-breakpoint object (base/sm/md/lg/xl) for responsive columns |
| `gap` | `1\|2\|3\|4\|5\|6\|8\|10\|12` | no | `4` | Spacing token step. Maps to the --cascivo-space-* scale, which intentionally skips 7/9/11 — use 6 or 8. |
| `align` | `'start' \| 'center' \| 'end' \| 'stretch'` | no | — | Block-axis alignment of items within their cells (align-items); default stretch |
| `justify` | `'start' \| 'center' \| 'end' \| 'stretch'` | no | — | Inline-axis alignment of items within their cells (justify-items); default stretch |
| `alignRows` | `boolean` | no | `false` | Align the internal bands of adjacent children via CSS subgrid — every CardHeader in a row shares one row track, every CardContent the next, every CardFooter the last. Where subgrid is unsupported the grid renders as it does without this prop. |
| `span` | `number \| { base?: number; sm?: number; md?: number; lg?: number; xl?: number }` | no | — | GridItem: column span — a number, or a per-breakpoint object |

## Examples

### Basic grid

3-column grid with spanning item

```tsx
<Grid cols={3} gap={4}><GridItem span={1}>A</GridItem><GridItem span={2}>B</GridItem></Grid>
```

### Row-aligned card grid

Both cards put their content band on the same row track, so the headers align even though one wraps

```tsx
<Grid cols={3} gap={4} alignRows><Card><CardHeader title="A" /><CardContent>Short</CardContent></Card><Card><CardHeader title="A much longer title that wraps" /><CardContent>Long</CardContent></Card></Grid>
```

### Responsive dashboard grid

1 column on mobile, 2 on tablet, 3 on desktop; the first item spans 2 on desktop

```tsx
<Grid cols={{ base: 1, md: 2, lg: 3 }} gap={4}><GridItem span={{ base: 1, lg: 2 }}>Wide</GridItem></Grid>
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-space-*`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `generic`

## Dependencies

- `@cascivo/core`

## Tags

layout, grid, columns

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Masonry

Masonry layout — native CSS masonry where supported, multi-column fallback elsewhere (fallback orders items top-to-bottom per column).

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add layout/masonry
```

_Copy-paste only — `Masonry` is not exported from `@cascivo/react`. Run the command above to own the source, or compose it from the exported primitives (`Flex`, `Grid`, `Heading`, …)._

## Category

`layout`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `cols` | `number` | no | `3` | Number of columns |
| `gap` | `1\|2\|3\|4\|5\|6\|8\|10\|12` | no | `4` | Spacing token step |

## Examples

### Masonry gallery

Variable-height cards laid out in a masonry pattern; falls back to CSS columns

```tsx
<Masonry cols={3} gap={4}>{items.map(item => <Card key={item.id}>{item.content}</Card>)}</Masonry>
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-space-*`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `generic`

## Dependencies

- `@cascivo/core`

## Tags

layout, masonry, gallery

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# PageHeader

Page-level header with title, description, breadcrumb, and actions slots.

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add layout/page-header
```

Or use it from the prebuilt package without copying:

```tsx
import { PageHeader } from '@cascivo/react'
```

## Category

`layout`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `title` | `ReactNode` | yes | — | Page title, rendered as the `<h1>`. Accepts nodes, not just a string, so you can put a status Badge or a linked domain beside the name — the canonical project-header shape. Keep it inline-level: it is an `<h1>`. |
| `description` | `ReactNode` | no | — | Supporting line under the title, rendered as a `<p>`. Accepts nodes. |
| `breadcrumb` | `ReactNode` | no | — | Breadcrumb slot |
| `actions` | `ReactNode` | no | — | Action buttons slot |
| `className` | `string` | no | — | Additional CSS class |

## Examples

### Basic

Title with description

```tsx
<PageHeader title="Dashboard" description="Welcome back" />
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-space-2`
- `--cascivo-space-4`
- `--cascivo-text-2xl`
- `--cascivo-font-bold`
- `--cascivo-color-text`
- `--cascivo-color-text-muted`
- `--cascivo-text-sm`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `banner`

## Dependencies

- `@cascivo/core`

## Tags

layout, header, page

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Section

Page-section shell with block padding, centered inner width, and stack gap.

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add layout/section
```

_Copy-paste only — `Section` is not exported from `@cascivo/react`. Run the command above to own the source, or compose it from the exported primitives (`Flex`, `Grid`, `Heading`, …)._

## Category

`layout`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `width` | `"content" \| "wide" \| "full"` | no | `"content"` | Max inline size: content=72rem, wide=90rem, full=none |
| `gap` | `1\|2\|3\|4\|5\|6\|8\|10\|12` | no | `8` | Stack gap between children (spacing token step) |

## Examples

### Content section

Centered 72rem content column with 2rem block padding

```tsx
<Section width="content" gap={8}><h2>Heading</h2><p>Body copy.</p></Section>
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-space-*`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `region`

## Dependencies

- `@cascivo/core`

## Tags

layout, section, page

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# SettingsLayout

Two-column settings page layout with a fixed-width menu and fluid content area.

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add layout/settings-layout
```

Or use it from the prebuilt package without copying:

```tsx
import { SettingsLayout } from '@cascivo/react'
```

## Category

`layout`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `menu` | `ReactNode` | yes | — | Side navigation menu |
| `children` | `ReactNode` | yes | — | Settings content area |

## Examples

### Basic

Menu + content layout

```tsx
<SettingsLayout menu={<nav>Menu</nav>}><div>Settings</div></SettingsLayout>
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-space-8`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `generic`

## Dependencies

- `@cascivo/core`

## Tags

layout, settings, page

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Spacer

Fixed-height spacing block using design token steps.

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add layout/spacer
```

Or use it from the prebuilt package without copying:

```tsx
import { Spacer } from '@cascivo/react'
```

## Category

`layout`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `size` | `1\|2\|3\|4\|5\|6\|8\|10\|12` | no | `4` | Spacing token step |

## Examples

### Spacer

Adds vertical space between elements

```tsx
<Spacer size={8} />
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-space-*`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `none`

## Dependencies

- `@cascivo/core`

## Tags

layout, spacer, spacing

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# SplitView

Resizable two-pane split layout with keyboard and pointer drag support.

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add layout/split-view
```

_Copy-paste only — `SplitView` is not exported from `@cascivo/react`. Run the command above to own the source, or compose it from the exported primitives (`Flex`, `Grid`, `Heading`, …)._

## Category

`layout`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `label` | `string` | no | — | Alias of `ariaLabel` — the same invisible accessible name under the other spelling. Neither is deprecated. Not rendered — screen readers only. |
| `ariaLabel` | `string` | no | — | Invisible accessible name. The catalog convention; `aria-label` is accepted as an alias for the DOM spelling. Not rendered — screen readers only. |
| `start` | `ReactNode` | yes | — | Left pane content |
| `end` | `ReactNode` | yes | — | Right pane content |
| `defaultRatio` | `number` | no | `0.3` | Initial split ratio (0–1) |
| `min` | `number` | no | `0.2` | Minimum ratio for start pane |
| `max` | `number` | no | `0.8` | Maximum ratio for start pane |
| `aria-label` | `string` | no | — | Label for the separator |

## Examples

### Basic

Two-pane split with draggable divider

```tsx
<SplitView start={<FileTree />} end={<Editor />} />
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-border`
- `--cascivo-color-accent`
- `--cascivo-duration-150`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `separator`
- **Keyboard:** ArrowLeft, ArrowRight

## Dependencies

- `@cascivo/core`

## Tags

layout, split, resizable, pane

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Link

Styled anchor for navigation, standalone or inline within prose

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add link
```

Or use it from the prebuilt package without copying:

```tsx
import { Link } from '@cascivo/react'
```

## Category

`navigation`

## Variants

- `standalone`
- `inline`

## Sizes

- `sm`
- `md`
- `lg`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `variant` | `'standalone' \| 'inline'` | no | `standalone` | `standalone` uses the system's own type and underlines on hover — for a link that stands on its own. `inline` inherits the surrounding prose font and stays underlined — for a link inside a paragraph. |
| `size` | `'sm' \| 'md' \| 'lg'` | no | `md` | Visual size of the component (e.g. 'sm', 'md', 'lg'). |
| `external` | `boolean` | no | `false` | When true, treats the link as external (opens in a new tab with rel safety). |
| `href` | `string` | no | — | The destination URL. |
| `asChild` | `boolean` | no | `false` | Render the single child element instead of cascivo's own `<a>`, so the link styling lands on your router's Link. ⚠ This — not `setLinkComponent` — is how you style an in-content link in a routed app; `setLinkComponent` only covers the config-driven navs. See https://cascivo.com/docs/using-with-a-router.md. |

## Examples

### Standalone

```tsx
<Link href="/docs">View documentation</Link>
```

### Inline

Inline links inherit the surrounding font size and stay underlined.

```tsx
<p>Read the <Link variant="inline" href="/guide">guide</Link> first.</p>
```

### External

Opens in a new tab with rel="noreferrer" and a visual indicator.

```tsx
<Link external href="https://example.com">Example</Link>
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-color-accent-text`
- `--cascivo-color-accent-text-hover`
- `--cascivo-link-color`
- `--cascivo-radius-sm`
- `--cascivo-focus-ring`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `link`
- **Keyboard:** Enter

## Dependencies

- `@cascivo/core`

## Tags

link, anchor, navigation

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# List

Styled unordered or ordered list with ListItem

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add list
```

Or use it from the prebuilt package without copying:

```tsx
import { List } from '@cascivo/react'
```

## Category

`display`

## Variants

- `disc`
- `decimal`
- `none`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `as` | `'ul' \| 'ol'` | no | `ul` | `ul` for an unordered list, `ol` for a numbered one. Changes the element and its marker, not the styling. |
| `marker` | `'disc' \| 'decimal' \| 'none'` | no | `derived from as (ul→disc, ol→decimal)` | List marker style ('disc' \| 'decimal' \| 'none'). |

## Examples

### Unordered

```tsx
<List><ListItem>Tokens</ListItem><ListItem>Themes</ListItem></List>
```

### Ordered

```tsx
<List as="ol"><ListItem>Init</ListItem><ListItem>Add</ListItem></List>
```

### Unmarked

Keeps list semantics without visual markers

```tsx
<List marker="none"><ListItem>Clean row</ListItem></List>
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-font-sans`
- `--cascivo-leading-normal`
- `--cascivo-color-text`
- `--cascivo-text-base`
- `--cascivo-space-1`
- `--cascivo-space-6`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `list`

## Dependencies

- `@cascivo/core`

## Tags

typography, list, ul, ol

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# LogViewer

Virtualized monospace console for high-frequency log and stream output

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add log-viewer
```

Or use it from the prebuilt package without copying:

```tsx
import { LogViewer } from '@cascivo/react'
```

## Category

`display`

## States

- `following`
- `paused`
- `empty`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `lines` | `ReadonlySignal<readonly LogLine[]> \| readonly LogLine[]` | yes | — | The log lines to display (a signal or array). |
| `rowHeight` | `number` | no | `20` | Height of each row in pixels, used for virtualization. |
| `overscan` | `number` | no | `8` | Number of extra rows rendered above and below the viewport. |
| `follow` | `boolean` | no | — | Whether the view auto-scrolls to follow new lines (controlled). |
| `onFollowChange` | `(follow: boolean) => void` | no | — | Called with the new follow state when it changes. |
| `ansi` | `boolean` | no | `false` | When true, parses ANSI color escape codes into colored spans. |
| `search` | `string` | no | — | Query used to filter and highlight matching lines. |
| `maxHeight` | `string` | no | `'24rem'` | Maximum height of the scroll viewport (CSS length). |
| `timestampWidth` | `string` | no | `'6.5rem'` | Width of the `LogLine.timestamp` gutter (CSS length). Widen it for an ISO stamp, narrow it for a relative offset. |
| `labels` | `LogViewerLabels` | no | — | Overrides for the component’s user-visible strings (i18n). |

## Examples

### Streaming build log

Backed by createStreamBuffer; auto-follows the tail

```tsx
const logs = useStreamBuffer<LogLine>({ capacity: 1000 })
// socket.onmessage = (e) => logs.append({ id: seq++, text: e.data })
<LogViewer lines={logs.signal} />
```

### Static log with levels

```tsx
<LogViewer lines={[{ id: 1, text: "Build started", level: "info" }, { id: 2, text: "Type error", level: "error" }]} />
```

### ANSI colored output

```tsx
<LogViewer ansi lines={ansiLines} maxHeight="32rem" />
```

### Timestamped build log

Pass the clock as `timestamp`, not prefixed into `text` — the gutter is dimmed, column-aligned, and excluded from search and copy

```tsx
<LogViewer lines={[{ id: 1, timestamp: "08:59:12", text: "Build started" }, { id: 2, timestamp: "08:59:41", text: "Type error", level: "error" }]} />
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-accent-text`
- `--cascivo-font-mono`
- `--cascivo-color-text`
- `--cascivo-color-text-muted`
- `--cascivo-color-surface`
- `--cascivo-color-surface-raised`
- `--cascivo-color-border`
- `--cascivo-color-error`
- `--cascivo-color-warning`
- `--cascivo-color-success`
- `--cascivo-color-info`
- `--cascivo-color-accent`
- `--cascivo-target-min-coarse`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `log`
- **Keyboard:** Tab, ArrowUp, ArrowDown, PageUp, PageDown

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

log, stream, virtual, console, terminal, monospace

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Menu

Dropdown menu with keyboard navigation, built on usePopover

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add menu
```

Or use it from the prebuilt package without copying:

```tsx
import { Menu } from '@cascivo/react'
```

## Category

`overlay`

## States

- `open`
- `closed`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `children` | `React.ReactNode` | yes | — | The MenuTrigger first, followed by MenuItem/MenuSeparator children. |

## Examples

### Basic

```tsx
<Menu>
  <MenuTrigger>Options</MenuTrigger>
  <MenuItem onSelect={rename}>Rename</MenuItem>
  <MenuItem onSelect={duplicate}>Duplicate</MenuItem>
</Menu>
```

### With separator and disabled item

```tsx
<Menu>
  <MenuTrigger aria-label="More actions">…</MenuTrigger>
  <MenuItem onSelect={share}>Share</MenuItem>
  <MenuSeparator />
  <MenuItem onSelect={remove} disabled>Delete</MenuItem>
</Menu>
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-surface`
- `--cascivo-color-border`
- `--cascivo-radius-md`
- `--cascivo-shadow-md`
- `--cascivo-motion-enter`
- `--cascivo-motion-exit`
- `--cascivo-color-bg-subtle`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `menu`
- **Keyboard:** ArrowDown, ArrowUp, Enter, Space, Escape

## Dependencies

- `@cascivo/core`

## Tags

overlay, menu, dropdown, floating

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# MenuButton

A button that opens an anchored action menu of one-shot commands

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add menu-button
```

Or use it from the prebuilt package without copying:

```tsx
import { MenuButton } from '@cascivo/react'
```

## Category

`navigation`

## Variants

- `primary`
- `secondary`
- `ghost`

## Sizes

- `sm`
- `md`
- `lg`

## States

- `open`
- `closed`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `label` | `ReactNode` | yes | — | Visible content rendered inside the trigger button. Rendered on screen. |
| `items` | `MenuButtonItem[]` | yes | — | Action items: { id, label, onSelect?, disabled? } |
| `variant` | `'primary' \| 'secondary' \| 'ghost'` | no | `'secondary'` | Trigger visual variant |
| `size` | `'sm' \| 'md' \| 'lg'` | no | `'md'` | Trigger size |
| `disabled` | `boolean` | no | `false` | Disables the trigger |
| `align` | `'start' \| 'end'` | no | `'start'` | Aligns the menu to the start or end edge of the trigger |
| `labels` | `{ open?: string }` | no | — | Override the trigger accessible name |

## Examples

### Basic action menu

A secondary button that opens a list of actions

```tsx
<MenuButton
  label="Actions"
  items={[
    { id: 'edit', label: 'Edit', onSelect: () => edit() },
    { id: 'duplicate', label: 'Duplicate', onSelect: () => duplicate() },
    { id: 'delete', label: 'Delete', onSelect: () => remove(), disabled: !canDelete },
  ]}
/>
```

### End-aligned, primary

Aligns the menu to the trigger end edge

```tsx
<MenuButton
  label="Create"
  variant="primary"
  align="end"
  items={[
    { id: 'doc', label: 'New document', onSelect: createDoc },
    { id: 'folder', label: 'New folder', onSelect: createFolder },
  ]}
/>
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-primary`
- `--cascivo-color-primary-fg`
- `--cascivo-color-primary-hover`
- `--cascivo-color-surface`
- `--cascivo-color-border`
- `--cascivo-color-text`
- `--cascivo-color-bg-subtle`
- `--cascivo-radius-control`
- `--cascivo-radius-overlay`
- `--cascivo-radius-item`
- `--cascivo-shadow-md`
- `--cascivo-focus-ring`
- `--cascivo-motion-enter`
- `--cascivo-z-dropdown`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `menu`
- **Keyboard:** ArrowDown, ArrowUp, Enter, Space, Escape, Tab

## Dependencies

- `@cascivo/core`

## Tags

navigation, menu, actions, dropdown, floating

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Menubar

Horizontal application menu bar with keyboard-navigable dropdown menus

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add menubar
```

Or use it from the prebuilt package without copying:

```tsx
import { Menubar } from '@cascivo/react'
```

## Category

`navigation`

## States

- `closed`
- `open`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `ariaLabel` | `string` | no | — | Invisible accessible name for the menubar landmark. The catalog convention; `aria-label` is accepted as an alias for the DOM spelling. Exactly one of the two is required — a menubar with no accessible name is a bug, so the type enforces it. Not rendered — screen readers only. |
| `menus` | `MenubarMenu[]` | yes | — | The top-level menus to render. |
| `aria-label` | `string` | no | — | Accessible label used when no visible label is present. |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |

## Examples

### Basic

```tsx
<Menubar aria-label="Main" menus={[{ id: "file", label: "File", items: [{ id: "new", label: "New", onSelect: () => {} }] }]} />
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-surface`
- `--cascivo-color-bg-subtle`
- `--cascivo-color-text`
- `--cascivo-color-border`
- `--cascivo-focus-ring`
- `--cascivo-motion-enter`
- `--cascivo-motion-exit`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `menubar`
- **Keyboard:** ArrowLeft, ArrowRight, ArrowDown, ArrowUp, Home, End, Enter, Escape

## Dependencies

- `@cascivo/core`

## Tags

navigation, menubar, menu, application

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# MessageActions

The action row under an AI reply — copy, good / bad feedback as toggle buttons, and regenerate

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add message-actions
```

Or use it from the prebuilt package without copying:

```tsx
import { MessageActions } from '@cascivo/react'
```

## Category

`inputs`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `copyValue` | `string` | no | — | The text the Copy button copies. Omit to hide Copy. |
| `feedback` | `'good' \| 'bad' \| null` | no | — | Controlled rating: `good`, `bad` or `null`. Pressing the active rating again clears it. |
| `defaultFeedback` | `'good' \| 'bad' \| null` | no | `null` | Initial rating when uncontrolled. |
| `onFeedbackChange` | `(feedback: 'good' \| 'bad' \| null) => void` | no | — | Called with the new rating (or `null` when cleared). The rating buttons render when this or `feedback` is set; a rating also announces "Thanks for your feedback". |
| `onRegenerate` | `() => void` | no | — | Called by the Regenerate button. Omit to hide it. |
| `labels` | `{ group?: string; good?: string; bad?: string; regenerate?: string; recorded?: string }` | no | — | Overrides for the component’s user-visible strings (i18n). |

## Examples

### Copy, rate and regenerate

```tsx
<MessageActions copyValue="Refunds are available for 30 days." onFeedbackChange={() => {}} onRegenerate={() => {}} />
```

### Copy only

```tsx
<MessageActions copyValue="Hello" />
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-text-muted`
- `--cascivo-color-ai`
- `--cascivo-color-ai-subtle`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `group`
- **Keyboard:** Tab, Enter, Space

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

ai, chat, feedback, copy, regenerate, thumbs, actions

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Modal

Accessible dialog overlay using native <dialog> element

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add modal
```

Or use it from the prebuilt package without copying:

```tsx
import { Modal } from '@cascivo/react'
```

## Category

`overlay`

## Sizes

- `sm`
- `md`
- `lg`

## States

- `closed`
- `open`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `open` | `boolean` | no | `false` | Whether the component is open (controlled). |
| `onClose` | `() => void` | no | — | Called when the component is closed. |
| `title` | `string` | no | — | Title text for the component. |
| `description` | `string` | no | — | Supporting description text. |
| `size` | `'sm' \| 'md' \| 'lg'` | no | `md` | Visual size of the component (e.g. 'sm', 'md', 'lg'). |
| `footer` | `ReactNode` | no | — | Dialog actions, rendered in a right-aligned row below the body and separated by a divider. |
| `draggable` | `boolean` | no | `false` | Allow dragging the dialog by its header |
| `ai` | `boolean \| 'generating'` | no | `false` | AI presence: `true` gives the surface an AI-tinted edge and a soft aura, marking AI-generated content; `'generating'` adds a pulsing inner glow while AI is still producing it (stops under reduced motion). Visual only — pair it with an AiBadge so the provenance is also text. |

## Examples

### Basic modal

```tsx
<Modal open={isOpen} onClose={() => setIsOpen(false)} title="Confirm action">
  <p>Are you sure?</p>
</Modal>
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-surface-overlay`
- `--cascivo-color-border`
- `--cascivo-radius-modal`
- `--cascivo-shadow-xl`
- `--cascivo-focus-ring`
- `--cascivo-dialog-body-gap`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `dialog`
- **Keyboard:** Escape, Tab, Shift+Tab

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

overlay, dialog, popup, ai

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# MultiSelect

Searchable multi-value select with a popover listbox, chips and grouping

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add multi-select
```

Or use it from the prebuilt package without copying:

```tsx
import { MultiSelect } from '@cascivo/react'
```

## Category

`inputs`

## Sizes

- `sm`
- `md`
- `lg`

## States

- `closed`
- `open`
- `error`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `options` | `MultiSelectOption[]` | yes | — | The selectable options. |
| `value` | `string[]` | no | — | The controlled value. Omit it and pass defaultValue to let the component own the selection. |
| `defaultValue` | `string[]` | no | `[]` | The initial value when uncontrolled. |
| `onValueChange` | `(value: string[]) => void` | no | — | Called with the new value when it changes. |
| `placeholder` | `string` | no | — | Placeholder text shown when the field is empty. |
| `label` | `string` | no | — | Visible field label, rendered above the trigger. Rendered on screen. |
| `ariaLabel` | `string` | no | — | Invisible accessible name, for when a visible element outside this component already labels it and `label` would render that text a second time. ⚠ `label` on this component is **visible**; `IconButton.label`/`Sparkline.label` are invisible names, which is the prior that costs adopters a duplicated label. Not rendered — screen readers only. |
| `aria-labelledby` | `string` | no | — | Wired automatically by a wrapping `Field` — its label id, forwarded to the focusable control so the Field's label names it. |
| `aria-describedby` | `string` | no | — | Wired automatically by a wrapping `Field` — the ids of its hint/error text, forwarded to the focusable control so the supporting text is announced. |
| `aria-invalid` | `boolean` | no | — | Wired automatically by a wrapping `Field` when it is in an error state. |
| `hint` | `string` | no | — | Helper text below the field. |
| `error` | `string` | no | — | Error text below the field; also marks the control invalid. |
| `display` | `'count' \| 'chips'` | no | `'count'` | How the trigger summarises the selection: a count, or one removable chip per value. |
| `disabled` | `boolean` | no | `false` | When true, disables the control and removes it from the tab order. |
| `clearable` | `boolean` | no | `false` | When true, shows a control that clears every selected value. |
| `selectAll` | `boolean` | no | `false` | When true, shows a row that selects or clears every enabled option at once. |
| `max` | `number` | no | — | Maximum number of values that may be selected. Further options become unselectable once reached. |
| `creatable` | `boolean` | no | `false` | When true, offers the current search text as a new option. |
| `onCreate` | `(label: string) => void` | no | — | Called with the typed label when the user picks the "create" row. |
| `loading` | `boolean` | no | `false` | When true, the list reports itself as busy and shows a loading row instead of the no-results message. |
| `onSearchChange` | `(query: string) => void` | no | — | Called with the search text on every keystroke. Pair it with filter={() => true} for a server-driven list. |
| `filter` | `(option: MultiSelectOption, query: string) => boolean` | no | — | Replaces the built-in diacritic-insensitive matcher. |
| `searchable` | `boolean` | no | `true` | When true, shows the search field. The list is keyboard-navigable either way. |
| `size` | `'sm' \| 'md' \| 'lg'` | no | `'md'` | Field height. |
| `name` | `string` | no | — | Submitted with a surrounding form — one hidden input per selected value. |
| `labels` | `MultiSelectLabels` | no | — | Overrides for the component’s user-visible strings (i18n). |
| `id` | `string` | no | — | Id for the trigger control. |

## Examples

### Basic

```tsx
<MultiSelect options={[{label:'One',value:'1'},{label:'Two',value:'2'}]} defaultValue={[]} />
```

### Chips with a clear control

Each selection renders as a chip with its own remove button.

```tsx
<MultiSelect options={options} display="chips" clearable defaultValue={['1']} />
```

### Grouped options

Options carrying a group render under a labelled role="group" heading.

```tsx
<MultiSelect options={[{label:'Apple',value:'a',group:'Pome'},{label:'Cherry',value:'c',group:'Stone'}]} />
```

### Remote search

filter={() => true} hands filtering to the server; loading marks the list busy between keystroke and response.

```tsx
<MultiSelect options={results} loading={pending} onSearchChange={search} filter={() => true} />
```

### Bounded selection

Options past the limit report aria-disabled; select-all stops at the limit.

```tsx
<MultiSelect options={options} max={3} selectAll />
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-surface`
- `--cascivo-color-bg-subtle`
- `--cascivo-color-border`
- `--cascivo-color-border-strong`
- `--cascivo-color-text`
- `--cascivo-color-text-muted`
- `--cascivo-color-accent`
- `--cascivo-color-destructive`
- `--cascivo-font-medium`
- `--cascivo-font-bold`
- `--cascivo-radius-field`
- `--cascivo-radius-overlay`
- `--cascivo-radius-item`
- `--cascivo-radius-indicator`
- `--cascivo-shadow-md`
- `--cascivo-focus-ring`
- `--cascivo-motion-enter`
- `--cascivo-target-min-coarse`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `listbox`
- **Keyboard:** ArrowDown, ArrowUp, Home, End, PageUp, PageDown, Enter, Space, Escape, Backspace

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

form, select, multi, input, popover, combobox, tags

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# NativeSelect

A styled native <select> that keeps platform form/keyboard behavior with a custom chevron and focus ring

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add native-select
```

Or use it from the prebuilt package without copying:

```tsx
import { NativeSelect } from '@cascivo/react'
```

## Category

`inputs`

## Sizes

- `sm`
- `md`
- `lg`

## States

- `default`
- `focus`
- `disabled`
- `invalid`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `options` | `NativeSelectOption[]` | no | — | Options to render. Alternatively pass <option> children. |
| `children` | `React.ReactNode` | no | — | Raw <option> children (used when options is not provided). |
| `size` | `'sm' \| 'md' \| 'lg'` | no | `md` | Visual size of the component (e.g. 'sm', 'md', 'lg'). |
| `invalid` | `boolean` | no | — | Marks the control as invalid for error styling and a11y. |
| `placeholder` | `string` | no | — | Placeholder rendered as a disabled, hidden first option. |
| `value` | `string` | no | — | The controlled value. |
| `defaultValue` | `string` | no | — | The initial value when uncontrolled. |
| `onChange` | `React.ChangeEventHandler<HTMLSelectElement>` | no | — | Called when the selected value changes. |
| `disabled` | `boolean` | no | — | When true, disables the control and removes it from the tab order. |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |

## Examples

### Basic

```tsx
<NativeSelect
  aria-label="Country"
  placeholder="Choose a country"
  options={[
    { value: 'us', label: 'United States' },
    { value: 'de', label: 'Germany' },
  ]}
  onChange={(e) => setCountry(e.target.value)}
/>
```

### Option children

```tsx
<NativeSelect size="sm" defaultValue="light" aria-label="Theme">
  <option value="light">Light</option>
  <option value="dark">Dark</option>
</NativeSelect>
```

### Invalid

```tsx
<NativeSelect invalid placeholder="Required" options={countries} />
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-color-surface`
- `--cascivo-color-border`
- `--cascivo-color-border-strong`
- `--cascivo-color-accent`
- `--cascivo-color-destructive`
- `--cascivo-color-text`
- `--cascivo-color-text-muted`
- `--cascivo-color-bg-subtle`
- `--cascivo-radius-field`
- `--cascivo-radius-overlay`
- `--cascivo-radius-item`
- `--cascivo-shadow-md`
- `--cascivo-motion-enter`
- `--cascivo-motion-exit`
- `--cascivo-focus-ring`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `combobox`
- **Keyboard:** ArrowUp, ArrowDown, Enter, Space, Home, End

## Dependencies

- `@cascivo/core`

## Tags

inputs, select, native, form, dropdown

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# NavigationMenu

Site navigation bar with links and dropdown flyout panels

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add navigation-menu
```

Or use it from the prebuilt package without copying:

```tsx
import { NavigationMenu } from '@cascivo/react'
```

## Category

`navigation`

## States

- `closed`
- `open`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `label` | `string` | no | — | Alias of `ariaLabel` — the same invisible accessible name under the other spelling. Neither is deprecated. Not rendered — screen readers only. |
| `ariaLabel` | `string` | no | — | Invisible accessible name. The catalog convention; `aria-label` is accepted as an alias for the DOM spelling. Not rendered — screen readers only. |
| `items` | `NavigationMenuItem[]` | yes | — | The items to render. |
| `aria-label` | `string` | no | — | Accessible label used when no visible label is present. |
| `orientation` | `'horizontal' \| 'vertical' \| 'both'` | no | `horizontal` | Which arrow keys move focus, and the axis the items lay out on: `horizontal` (Left/Right), `vertical` (Up/Down), or `both` (all four). |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |

## Examples

### Basic

```tsx
<NavigationMenu aria-label="Main" items={[{ id: "home", label: "Home", href: "/" }, { id: "products", label: "Products", content: <ul>…</ul> }]} />
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-color-surface`
- `--cascivo-color-bg-subtle`
- `--cascivo-color-text`
- `--cascivo-color-border`
- `--cascivo-focus-ring`
- `--cascivo-motion-enter`
- `--cascivo-motion-exit`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `navigation`
- **Keyboard:** ArrowLeft, ArrowRight, Home, End, Enter, Space, Escape

## Dependencies

- `@cascivo/core`

## Tags

navigation, menu, flyout, site-nav

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Notification

Inline, actionable notification banner that surfaces a titled message with an optional recovery action

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add notification
```

Or use it from the prebuilt package without copying:

```tsx
import { Notification } from '@cascivo/react'
```

## Category

`feedback`

## Variants

- `info`
- `success`
- `warning`
- `error`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `title` | `ReactNode` | yes | — | Title text for the component. |
| `description` | `ReactNode` | no | — | Supporting description text. |
| `variant` | `'info' \| 'success' \| 'warning' \| 'error'` | no | `info` | Severity tone. Accepts the catalog-wide `Tone` vocabulary (`neutral \| info \| success \| warning \| danger`) plus Notification's historical spellings (`error`, `destructive` → danger). |
| `dismissible` | `boolean` | no | `false` | When true, shows a control to dismiss the component. |
| `onDismiss` | `() => void` | no | — | Called when the component is dismissed. |
| `actions` | `ReactNode` | no | — | Action elements shown in the notification. |
| `icon` | `ReactNode` | no | — | Icon element rendered in the component. |
| `labels` | `{ dismiss?: string }` | no | — | Overrides for the component’s user-visible strings (i18n). |

## Examples

### Info

```tsx
<Notification variant="info" title="Sync complete" description="Your files are up to date." />
```

### Dismissible

```tsx
<Notification variant="success" title="Saved" dismissible onDismiss={handleDismiss} />
```

### Actionable

```tsx
<Notification variant="error" title="Upload failed" description="The connection dropped." actions={<Button onClick={retry}>Retry</Button>} />
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-color-info`
- `--cascivo-color-success`
- `--cascivo-color-warning`
- `--cascivo-color-destructive`
- `--cascivo-color-border`
- `--cascivo-color-surface`
- `--cascivo-radius-surface`
- `--cascivo-motion-enter`
- `--cascivo-motion-exit`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `alert`

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

notification, banner, message, feedback, actionable

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# NumberInput

Numeric input with stepper buttons, clamping, precision, and locale formatting

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add number-input
```

Or use it from the prebuilt package without copying:

```tsx
import { NumberInput } from '@cascivo/react'
```

## Category

`inputs`

## Sizes

- `sm`
- `md`
- `lg`

## States

- `idle`
- `focused`
- `error`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `value` | `number \| null` | no | — | The controlled value. |
| `defaultValue` | `number` | no | — | The initial value when uncontrolled. |
| `onValueChange` | `(value: number \| null) => void` | no | — | Fired on commit (blur, Enter, stepping); null when empty or unparseable |
| `min` | `number` | no | — | Minimum allowed value. |
| `max` | `number` | no | — | Maximum allowed value. |
| `step` | `number` | no | `1` | Increment between allowed values. |
| `precision` | `number` | no | — | Decimal places applied on commit |
| `formatOptions` | `Intl.NumberFormatOptions` | no | — | Display formatting applied on blur; raw editable string while focused |
| `label` | `string` | no | — | Text label for the control. Rendered on screen. |
| `hint` | `string` | no | — | Supplementary hint text shown with the control. |
| `error` | `string` | no | — | Error message shown when the value is invalid. |
| `size` | `'sm' \| 'md' \| 'lg'` | no | `md` | Visual size of the component (e.g. 'sm', 'md', 'lg'). |
| `disabled` | `boolean` | no | `false` | When true, disables the control and removes it from the tab order. |
| `incrementLabel` | `string` | no | `Increment` | Accessible label for the increment button. |
| `decrementLabel` | `string` | no | `Decrement` | Accessible label for the decrement button. |
| `ariaLabel` | `string` | no | — | Invisible accessible name, for when a visible element outside this component already labels it and `label` would render that text a second time. ⚠ `label` on this component is **visible**; `IconButton.label`/`Sparkline.label` are invisible names, which is the prior that costs adopters a duplicated label. The raw DOM `aria-label` still wins over this. Not rendered — screen readers only. |

## Examples

### Basic

```tsx
<NumberInput label="Quantity" defaultValue={1} min={0} max={99} />
```

### Currency

```tsx
<NumberInput label="Price" precision={2} formatOptions={{ style: "currency", currency: "USD" }} />
```

### Stepped

```tsx
<NumberInput label="Opacity" min={0} max={1} step={0.1} />
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-color-surface`
- `--cascivo-color-border`
- `--cascivo-color-accent`
- `--cascivo-color-destructive`
- `--cascivo-color-bg-subtle`
- `--cascivo-color-text-subtle`
- `--cascivo-radius-input`
- `--cascivo-focus-ring`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `spinbutton`
- **Keyboard:** ArrowUp, ArrowDown, Enter, Tab

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

form, number, input, spinbutton, stepper

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# OtpInput

Segmented one-time code input

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add otp-input
```

Or use it from the prebuilt package without copying:

```tsx
import { OtpInput } from '@cascivo/react'
```

## Category

`inputs`

## States

- `idle`
- `focused`
- `filled`
- `disabled`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `length` | `number` | no | `6` | Number of input cells. |
| `value` | `string` | yes | — | The controlled value. |
| `onValueChange` | `(v: string) => void` | yes | — | Called with the new value when it changes. |
| `disabled` | `boolean` | no | `false` | When true, disables the control and removes it from the tab order. |
| `type` | `'numeric' \| 'alphanumeric'` | no | `numeric` | Accepted characters ('numeric' \| 'alphanumeric'). |

## Examples

### Basic

```tsx
<OtpInput value="" onValueChange={() => {}} />
```

### 4-digit

```tsx
<OtpInput length={4} value="" onValueChange={() => {}} />
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-color-surface`
- `--cascivo-color-border`
- `--cascivo-color-accent`
- `--cascivo-color-bg-subtle`
- `--cascivo-radius-input`
- `--cascivo-focus-ring`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `group`
- **Keyboard:** ArrowLeft, ArrowRight, Backspace

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

form, otp, code, input, verification

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# OverflowMenu

Kebab icon button revealing a menu of row-level actions

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add overflow-menu
```

Or use it from the prebuilt package without copying:

```tsx
import { OverflowMenu } from '@cascivo/react'
```

## Category

`overlay`

## Sizes

- `sm`
- `md`

## States

- `closed`
- `open`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `items` | `{ label: string; value: string; icon?: ReactNode; disabled?: boolean; destructive?: boolean }[]` | yes | — | The items to render. |
| `onSelect` | `(value: string) => void` | no | — | Called with the selected value. |
| `placement` | `'bottom-start' \| 'bottom-end'` | no | `bottom-end` | Which trigger edge the menu aligns to. `bottom-end` hangs it from the trigger's end edge (right in LTR), `bottom-start` from its start edge. |
| `label` | `string` | no | — | Alias of `ariaLabel` — the same invisible accessible name under the other spelling. Neither is deprecated. Not rendered — screen readers only. |
| `ariaLabel` | `string` | no | `More actions` | Accessible label for the component. Not rendered — screen readers only. |
| `size` | `'sm' \| 'md'` | no | `md` | Visual size of the component (e.g. 'sm', 'md', 'lg'). |
| `disabled` | `boolean` | no | `false` | When true, disables the control and removes it from the tab order. |
| `tabIndex` | `number` | no | — | Tab-order position of the trigger. Composite widgets that manage their own focus (a DataTable in grid keyboard mode) pass -1 so the menu is reachable by Enter on its cell without being an extra Tab stop. |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |

## Examples

### Row actions

```tsx
<OverflowMenu items={[{ label: "Edit", value: "edit" }, { label: "Delete", value: "delete", destructive: true }]} onSelect={handle} />
```

### Small, start-aligned

```tsx
<OverflowMenu size="sm" placement="bottom-start" items={items} />
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-text`
- `--cascivo-color-text-muted`
- `--cascivo-color-bg-subtle`
- `--cascivo-color-destructive`
- `--cascivo-color-destructive-subtle`
- `--cascivo-radius-button`
- `--cascivo-focus-ring`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `menu`
- **Keyboard:** ArrowDown, ArrowUp, Home, End, Enter, Space, Escape

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

overlay, menu, actions, kebab, table

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Pagination

Controls for navigating paged data sets, with page size selection

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add pagination
```

Or use it from the prebuilt package without copying:

```tsx
import { Pagination } from '@cascivo/react'
```

## Category

`navigation`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `page` | `number` | yes | — | Current page (1-based) |
| `pageSize` | `number` | yes | — | Items per page |
| `totalItems` | `number` | yes | — | Total number of items |
| `onPageChange` | `(page: number) => void` | yes | — | Called with the new page number when it changes. |
| `onPageSizeChange` | `(size: number) => void` | no | — | Called with the new page size when it changes. |
| `pageSizeOptions` | `number[]` | no | `[10, 25, 50, 100]` | Options for the page size select |
| `labels` | `PaginationLabels` | no | — | Overridable English strings for all visible and accessible text |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |

## Examples

### Basic

```tsx
<Pagination page={1} pageSize={25} totalItems={103} onPageChange={setPage} />
```

### With page size select

```tsx
<Pagination page={page} pageSize={size} totalItems={103} onPageChange={setPage} onPageSizeChange={setSize} />
```

### Custom labels

```tsx
<Pagination page={1} pageSize={10} totalItems={42} onPageChange={setPage} labels={{ previous: 'Zurück', next: 'Weiter' }} />
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-text`
- `--cascivo-color-text-muted`
- `--cascivo-color-surface`
- `--cascivo-color-border`
- `--cascivo-color-border-strong`
- `--cascivo-color-bg-subtle`
- `--cascivo-color-accent`
- `--cascivo-color-accent-subtle`
- `--cascivo-radius-input`
- `--cascivo-radius-button`
- `--cascivo-focus-ring`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `navigation`
- **Keyboard:** Tab, Enter, Space, ArrowUp, ArrowDown

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

pagination, navigation, table, data, pages

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# PasswordInput

Password input with reveal toggle and optional strength meter

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add password-input
```

Or use it from the prebuilt package without copying:

```tsx
import { PasswordInput } from '@cascivo/react'
```

## Category

`inputs`

## Sizes

- `sm`
- `md`
- `lg`

## States

- `idle`
- `revealed`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `showStrengthMeter` | `boolean` | no | `false` | When true, shows a password-strength meter. |
| `size` | `'sm' \| 'md' \| 'lg'` | no | `md` | Visual size of the component (e.g. 'sm', 'md', 'lg'). |
| `labels` | `PasswordInputLabels` | no | — | Overrides for the component’s user-visible strings (i18n). |
| `disabled` | `boolean` | no | `false` | When true, disables the control and removes it from the tab order. |
| `placeholder` | `string` | no | — | Placeholder text shown when the field is empty. |
| `value` | `string` | no | — | The controlled value. |
| `onChange` | `(e: React.ChangeEvent<HTMLInputElement>) => void` | no | — | Called when the value changes. |

## Examples

### Basic

```tsx
<PasswordInput placeholder="Enter password" />
```

### With strength meter

```tsx
<PasswordInput showStrengthMeter placeholder="Create password" />
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-color-surface`
- `--cascivo-color-border`
- `--cascivo-color-accent`
- `--cascivo-color-destructive`
- `--cascivo-color-warning`
- `--cascivo-color-success`
- `--cascivo-radius-input`
- `--cascivo-focus-ring`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `textbox`
- **Keyboard:** Tab, Shift+Tab

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

form, password, input, security

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Popover

Anchored floating panel built on CSS Anchor Positioning + Popover API

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add popover
```

Or use it from the prebuilt package without copying:

```tsx
import { Popover } from '@cascivo/react'
```

## Category

`overlay`

## States

- `open`
- `closed`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `children` | `React.ReactNode` | yes | — | A PopoverTrigger and PopoverContent pair. |
| `open` | `boolean` | no | — | Whether the component is open (controlled). |
| `onOpenChange` | `(open: boolean) => void` | no | — | Called with the next open state when it changes. |
| `placement` | `'top' \| 'bottom' \| 'left' \| 'right'` | no | `bottom` | Side of the trigger the panel opens on: `bottom`, `top`, `left` or `right`. |
| `offset` | `number` | no | `4` | Distance (px) between the trigger and the panel. |

## Examples

### Basic

```tsx
<Popover>
  <PopoverTrigger>Open settings</PopoverTrigger>
  <PopoverContent>
    <form>…</form>
  </PopoverContent>
</Popover>
```

### Controlled with placement

```tsx
<Popover open={isOpen} onOpenChange={setIsOpen} placement="top">
  <PopoverTrigger>Filters</PopoverTrigger>
  <PopoverContent><FilterForm /></PopoverContent>
</Popover>
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-surface`
- `--cascivo-color-border`
- `--cascivo-radius-md`
- `--cascivo-shadow-md`
- `--cascivo-motion-enter`
- `--cascivo-motion-exit`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `dialog`
- **Keyboard:** Escape

## Dependencies

- `@cascivo/core`

## Tags

overlay, floating, anchor, popover

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Progress

Horizontal bar showing the completion progress of a tracked operation

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add progress
```

Or use it from the prebuilt package without copying:

```tsx
import { Progress } from '@cascivo/react'
```

## Category

`feedback`

## Variants

- `primary`
- `info`
- `success`
- `warning`
- `error`

## Sizes

- `sm`
- `md`
- `lg`

## States

- `determinate`
- `indeterminate`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `label` | `string` | no | — | Alias of `ariaLabel` — the same invisible accessible name under the other spelling. Neither is deprecated. Not rendered — screen readers only. |
| `ariaLabel` | `string` | no | — | Invisible accessible name. The catalog convention; the DOM spelling `aria-label` is accepted as an alias so either guess compiles. Not rendered — screen readers only. |
| `aria-label` | `string` | no | — | Accessible label when no visible label is present. |
| `aria-describedby` | `string` | no | — | Id of an element describing the progress bar. |
| `value` | `number` | no | — | 0–100. Omit for indeterminate state. |
| `variant` | `'primary' \| 'info' \| 'success' \| 'warning' \| 'error'` | no | `primary` | Colour of the fill: `primary` (the accent) or a severity tone — `info`, `success`, `warning`, `error`. |
| `size` | `'sm' \| 'md' \| 'lg'` | no | `md` | Visual size of the component (e.g. 'sm', 'md', 'lg'). |

## Examples

### Determinate

```tsx
<Progress value={65} />
```

### Indeterminate

```tsx
<Progress aria-label="Loading…" />
```

### Success variant

```tsx
<Progress value={100} variant="success" />
```

### Small

```tsx
<Progress value={40} size="sm" />
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-color-surface-2`
- `--cascivo-color-primary`
- `--cascivo-color-info`
- `--cascivo-color-success`
- `--cascivo-color-warning`
- `--cascivo-color-error`
- `--cascivo-color-accent`
- `--cascivo-radius-full`
- `--cascivo-ease-out`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `progressbar`

## Tags

progress, loading, upload, bar

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# ProgressBar

Shows determinate or indeterminate progress of a task

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add progress-bar
```

Or use it from the prebuilt package without copying:

```tsx
import { ProgressBar } from '@cascivo/react'
```

## Category

`feedback`

## Variants

- `active`
- `success`
- `error`

## Sizes

- `sm`
- `md`

## States

- `determinate`
- `indeterminate`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `value` | `number` | no | — | Current value from 0 to max; omit for an indeterminate bar |
| `max` | `number` | no | `100` | Maximum allowed value. |
| `label` | `string` | no | — | Visible label above the track, wired via aria-labelledby. Rendered on screen. |
| `helperText` | `string` | no | — | Supplementary text shown with the progress bar. |
| `size` | `'sm' \| 'md'` | no | `md` | Visual size of the component (e.g. 'sm', 'md', 'lg'). |
| `status` | `'active' \| 'success' \| 'error'` | no | `active` | success/error tint the fill and show a glyph next to the label |

## Examples

### Determinate

```tsx
<ProgressBar value={60} label="Uploading" />
```

### Indeterminate

```tsx
<ProgressBar label="Processing" />
```

### Success

```tsx
<ProgressBar value={100} status="success" label="Upload complete" />
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-color-accent`
- `--cascivo-color-success`
- `--cascivo-color-destructive`
- `--cascivo-color-border`
- `--cascivo-color-text`
- `--cascivo-color-text-subtle`
- `--cascivo-radius-full`
- `--cascivo-motion-enter`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `progressbar`

## Dependencies

- `@cascivo/core`

## Tags

progress, loading, status, feedback

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# ProgressCircle

Circular determinate progress indicator rendered as an SVG arc

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add progress-circle
```

Or use it from the prebuilt package without copying:

```tsx
import { ProgressCircle } from '@cascivo/react'
```

## Category

`feedback`

## Sizes

- `sm`
- `md`
- `lg`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `value` | `number` | yes | — | Current value from 0 to max — clamped |
| `max` | `number` | no | `100` | Maximum allowed value. |
| `size` | `'sm' \| 'md' \| 'lg'` | no | `md` | Visual size of the component (e.g. 'sm', 'md', 'lg'). |
| `showValue` | `boolean` | no | `false` | Renders the rounded percentage in the center — pairs best with md and lg |
| `ariaLabel` | `string` | no | — | Alias of `label` — the same invisible accessible name under the catalog spelling. Neither is deprecated. Not rendered — screen readers only. |
| `label` | `string` | no | — | Accessible name announced by screen readers. Not rendered — screen readers only. |

## Examples

### Default

```tsx
<ProgressCircle value={40} label="Loading" />
```

### With value

```tsx
<ProgressCircle value={72} showValue size="lg" label="Upload progress" />
```

### Custom max

```tsx
<ProgressCircle value={3} max={8} label="Steps completed" />
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-color-border`
- `--cascivo-color-accent`
- `--cascivo-color-text`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `progressbar`

## Dependencies

- `@cascivo/core`

## Tags

progress, loading, circle, feedback

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# ProgressIndicator

Shows progress through the steps of a multi-step flow

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add progress-indicator
```

Or use it from the prebuilt package without copying:

```tsx
import { ProgressIndicator } from '@cascivo/react'
```

## Category

`navigation`

## Variants

- `horizontal`
- `vertical`

## States

- `complete`
- `current`
- `incomplete`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `steps` | `{ label: string; description?: string }[]` | yes | — | Ordered list of steps |
| `currentIndex` | `number` | yes | — | Index of the current step (0-based) |
| `vertical` | `boolean` | no | `false` | When true, lays the steps out vertically. |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |

## Examples

### Horizontal

```tsx
<ProgressIndicator steps={[{ label: 'Cart' }, { label: 'Shipping' }, { label: 'Payment' }]} currentIndex={1} />
```

### Vertical with descriptions

```tsx
<ProgressIndicator vertical steps={[{ label: 'Account', description: 'Your details' }, { label: 'Confirm' }]} currentIndex={0} />
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-color-accent-text`
- `--cascivo-color-accent`
- `--cascivo-color-accent-subtle`
- `--cascivo-color-text`
- `--cascivo-color-text-muted`
- `--cascivo-color-text-subtle`
- `--cascivo-color-text-on-accent`
- `--cascivo-color-border`
- `--cascivo-color-surface`
- `--cascivo-radius-full`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `list`

## Dependencies

- `@cascivo/core`

## Tags

steps, wizard, stepper, progress, navigation

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# PromptSuggestions

Starter prompts as a wrap of pill buttons — the "Try asking…" row of an empty AI chat

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add prompt-suggestions
```

Or use it from the prebuilt package without copying:

```tsx
import { PromptSuggestions } from '@cascivo/react'
```

## Category

`inputs`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `items` | `string[]` | yes | — | The prompts, as the exact text each one sends. |
| `onSelect` | `(value: string) => void` | yes | — | Called with the chosen prompt — send it, or put it in the composer. |
| `labels` | `{ group?: string }` | no | — | Overrides for the component’s user-visible strings (i18n) — `group` names the group for screen readers. |

## Examples

### Starter prompts

```tsx
<PromptSuggestions
  items={['Summarise this week’s tickets', 'Draft a release note', 'What changed in v2?']}
  onSelect={() => {}}
/>
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-border`
- `--cascivo-color-surface`
- `--cascivo-color-ai-border`
- `--cascivo-color-ai-subtle`
- `--cascivo-radius-full`
- `--cascivo-focus-ring`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `group`
- **Keyboard:** Tab, Enter, Space

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

ai, chat, prompts, suggestions, starters, chips

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Prose

Wrapper that styles raw descendant HTML — headings, lists, code, quotes, tables

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add prose
```

Or use it from the prebuilt package without copying:

```tsx
import { Prose } from '@cascivo/react'
```

## Category

`display`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `children` | `React.ReactNode` | no | — | Authored flow content (headings, paragraphs, lists, code, tables) to style. |
| `dangerouslySetInnerHTML` | `{ __html: string }` | no | — | Rendered HTML you do not control (CMS, markdown pipelines). Sanitize first. |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |

## Examples

### Authored content

```tsx
<Prose><h2>Install</h2><p>Run <code>npx cascivo init</code>.</p></Prose>
```

### Rendered markdown

The use case: HTML you do not control (CMS, markdown pipelines)

```tsx
<Prose dangerouslySetInnerHTML={{ __html: html }} />
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-color-accent-text`
- `--cascivo-color-accent-text-hover`
- `--cascivo-font-sans`
- `--cascivo-font-mono`
- `--cascivo-font-semibold`
- `--cascivo-leading-tight`
- `--cascivo-leading-relaxed`
- `--cascivo-tracking-tight`
- `--cascivo-color-text`
- `--cascivo-color-text-subtle`
- `--cascivo-color-surface`
- `--cascivo-color-border`
- `--cascivo-color-border-strong`
- `--cascivo-radius-indicator`
- `--cascivo-radius-surface`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `generic`

## Dependencies

- `@cascivo/core`

## Tags

typography, prose, content, markdown, article

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# PullToRefresh

Wraps a scrollable region and triggers a refresh when pulled down past a threshold at the top

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add pull-to-refresh
```

Or use it from the prebuilt package without copying:

```tsx
import { PullToRefresh } from '@cascivo/react'
```

## Category

`feedback`

## States

- `idle`
- `pulling`
- `ready`
- `refreshing`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `onRefresh` | `() => Promise<unknown> \| unknown` | yes | — | Called when the pull passes the threshold; the spinner shows until it settles |
| `children` | `React.ReactNode` | yes | — | Content rendered inside the component. |
| `threshold` | `number` | no | `64` | Pull distance (px) required to trigger a refresh. |
| `disabled` | `boolean` | no | `false` | When true, disables the control and removes it from the tab order. |
| `labels` | `{ pull?: string; release?: string; refreshing?: string }` | no | — | Overrides for the component’s user-visible strings (i18n). |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |

## Examples

### Basic

The spinner shows until the returned promise settles.

```tsx
<PullToRefresh onRefresh={() => refetch()}>
  <FeedList items={items} />
</PullToRefresh>
```

### Custom threshold

Requires a longer pull before a refresh is triggered.

```tsx
<PullToRefresh onRefresh={loadLatest} threshold={96}>
  <MessageList />
</PullToRefresh>
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-text-muted`
- `--cascivo-motion-enter`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `status`

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

feedback, pull-to-refresh, mobile, gesture, scroll, refresh

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# QrCode

Encodes a URL or short text into a scannable SVG QR code

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add qr-code
```

Or use it from the prebuilt package without copying:

```tsx
import { QrCode } from '@cascivo/react'
```

## Category

`display`

## States

- `default`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `value` | `string` | yes | — | Text or URL to encode |
| `size` | `number` | no | `128` | Visual size of the component (e.g. 'sm', 'md', 'lg'). |
| `errorCorrection` | `'L' \| 'M' \| 'Q' \| 'H'` | no | `M` | Higher levels tolerate more damage but hold less data |
| `radius` | `string` | no | — | CSS length rounding the corners |
| `fill` | `string` | no | `currentColor` | Foreground color of the QR modules. |
| `background` | `string` | no | `transparent` | Background color behind the QR code. |
| `ariaLabel` | `string` | no | — | Alias of `label` — the same invisible accessible name under the catalog spelling. Neither is deprecated. Not rendered — screen readers only. |
| `label` | `string` | no | — | Accessible name for the QR image. Not rendered — screen readers only. |

## Examples

### URL

```tsx
<QrCode value="https://cascivo.dev" />
```

### High error correction

```tsx
<QrCode value="https://cascivo.dev" errorCorrection="H" size={200} />
```

### Custom colors

```tsx
<QrCode value="cascivo" fill="var(--cascivo-color-accent)" background="var(--cascivo-color-surface)" />
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-color-text`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `img`

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

qr, qr-code, barcode, encode, display

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# RadialProgress

Circular progress indicator using conic-gradient, with percentage label and variant colors

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add radial-progress
```

Or use it from the prebuilt package without copying:

```tsx
import { RadialProgress } from '@cascivo/react'
```

## Category

`feedback`

## Variants

- `primary`
- `info`
- `success`
- `warning`
- `error`

## Sizes

- `sm`
- `md`
- `lg`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `label` | `string` | no | — | Alias of `ariaLabel` — the same invisible accessible name under the other spelling. Neither is deprecated. Not rendered — screen readers only. |
| `ariaLabel` | `string` | no | — | Invisible accessible name. The catalog convention; `aria-label` is accepted as an alias for the DOM spelling. Not rendered — screen readers only. |
| `value` | `number` | yes | — | The controlled value. |
| `size` | `'sm' \| 'md' \| 'lg'` | no | `md` | Visual size of the component (e.g. 'sm', 'md', 'lg'). |
| `variant` | `'primary' \| 'info' \| 'success' \| 'warning' \| 'error'` | no | `primary` | Colour of the ring: `primary` (the accent) or a severity tone — `info`, `success`, `warning`, `error`. |
| `children` | `React.ReactNode` | no | — | Content rendered inside the component. |
| `aria-label` | `string` | no | — | Accessible label used when no visible label is present. |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |

## Examples

### Default

Primary color, md size, auto percentage label

```tsx
<RadialProgress value={72} />
```

### Success large

Completed state with success color at large size

```tsx
<RadialProgress value={100} size="lg" variant="success" />
```

### Custom label

Override the default percentage label with custom content

```tsx
<RadialProgress value={45} variant="warning">45 GB</RadialProgress>
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-color-primary`
- `--cascivo-color-info`
- `--cascivo-color-success`
- `--cascivo-color-warning`
- `--cascivo-color-error`
- `--cascivo-color-surface`
- `--cascivo-color-surface-2`
- `--cascivo-color-text`
- `--cascivo-radius-full`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `progressbar`

## Tags

progress, circular, gauge, meter, kpi, dashboard

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Radio

Single choice from a set, grouped with RadioGroup

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add radio
```

Or use it from the prebuilt package without copying:

```tsx
import { Radio } from '@cascivo/react'
```

## Category

`inputs`

## States

- `unchecked`
- `checked`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `label` | `string` | no | — | Text label for the control. Rendered on screen. |
| `value` | `string` | yes | — | The controlled value. |
| `disabled` | `boolean` | no | `false` | When true, disables the control and removes it from the tab order. |
| `name` | `string` | no | — | Form field name shared by the radio group. |
| `ariaLabel` | `string` | no | — | Invisible accessible name, for when a visible element outside this component already labels it and `label` would render that text a second time. ⚠ `label` on this component is **visible**; `IconButton.label`/`Sparkline.label` are invisible names, which is the prior that costs adopters a duplicated label. The raw DOM `aria-label` still wins over this. Not rendered — screen readers only. |

## Examples

### Group

```tsx
<RadioGroup name="plan" defaultValue="pro"><Radio value="pro" label="Pro" /><Radio value="team" label="Team" /></RadioGroup>
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-color-surface`
- `--cascivo-color-accent`
- `--cascivo-color-border-strong`
- `--cascivo-color-text-on-accent`
- `--cascivo-radius-full`
- `--cascivo-focus-ring`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `radio`
- **Keyboard:** ArrowUp, ArrowDown, ArrowLeft, ArrowRight, Space

## Dependencies

- `@cascivo/core`

## Tags

form, choice, group

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# RadioCard

Selectable card backed by a native radio input. Use RadioCardGroup for single-select groups.

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add radio-card
```

Or use it from the prebuilt package without copying:

```tsx
import { RadioCard } from '@cascivo/react'
```

## Category

`inputs`

## States

- `default`
- `checked`
- `disabled`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `hideIndicator` | `boolean` | no | — | Hide the radio indicator glyph, showing only the card content. |
| `value` | `string` | yes | — | Radio value |
| `title` | `ReactNode` | yes | — | Card title |
| `description` | `ReactNode` | no | — | Optional description |
| `disabled` | `boolean` | no | — | Disables the card |

## Examples

### Plan selector

Single-select plan picker

```tsx
<RadioCardGroup name="plan" defaultValue="pro" label="Plan">
  <RadioCard value="free" title="Free" description="For hobbyists" />
  <RadioCard value="pro" title="Pro" description="For professionals" />
  <RadioCard value="team" title="Team" description="For teams" />
</RadioCardGroup>
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-color-accent`
- `--cascivo-color-border`
- `--cascivo-radius-surface`
- `--cascivo-color-active-bg`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `radiogroup`
- **Keyboard:** ArrowDown, ArrowUp, Space

## Dependencies

- `@cascivo/core`

## Tags

radio, card, selectable, form

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# RatingGroup

Star rating input with accessible radio group pattern

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add rating-group
```

Or use it from the prebuilt package without copying:

```tsx
import { RatingGroup } from '@cascivo/react'
```

## Category

`inputs`

## Sizes

- `sm`
- `md`
- `lg`

## States

- `idle`
- `disabled`
- `readOnly`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `value` | `number` | yes | — | The controlled value. |
| `onValueChange` | `(v: number) => void` | no | — | Called with the new value when it changes. |
| `max` | `number` | no | `5` | Maximum allowed value. |
| `size` | `'sm' \| 'md' \| 'lg'` | no | `md` | Visual size of the component (e.g. 'sm', 'md', 'lg'). |
| `disabled` | `boolean` | no | `false` | When true, disables the control and removes it from the tab order. |
| `readOnly` | `boolean` | no | `false` | When true, the value is shown but cannot be edited. |
| `labels` | `RatingGroupLabels` | no | — | Overrides for the component’s user-visible strings (i18n). |

## Examples

### Basic

```tsx
<RatingGroup value={3} onValueChange={() => {}} />
```

### Read only

```tsx
<RatingGroup value={4} readOnly />
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-warning`
- `--cascivo-color-border-strong`
- `--cascivo-color-accent`
- `--cascivo-radius-sm`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `radiogroup`
- **Keyboard:** Tab, Space, Enter

## Dependencies

- `@cascivo/core`

## Tags

form, rating, stars, input, feedback

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Reasoning

Collapsible panel for a model’s reasoning — opens and shimmers "Thinking…" while it streams, then settles to "Thought for N seconds"

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add reasoning
```

Or use it from the prebuilt package without copying:

```tsx
import { Reasoning } from '@cascivo/react'
```

## Category

`display`

## States

- `streaming`
- `settled`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `children` | `ReactNode` | yes | — | The reasoning text or steps. |
| `streaming` | `boolean` | no | `false` | True while reasoning is still arriving: the panel opens, the trigger shimmers "Thinking…" and the content is aria-busy. Turning it off closes the panel. |
| `duration` | `number` | no | — | Seconds spent reasoning. Once streaming ends the trigger reads "Thought for {duration} seconds"; without it, "Reasoning". The caller owns the clock. |
| `label` | `ReactNode` | no | — | Replaces the trigger text in every state. Rendered on screen. |
| `labels` | `{ thinking?: string; thoughtFor?: string; label?: string }` | no | — | Overrides for the component’s user-visible strings (i18n). `thoughtFor` may contain `{count}`. |

## Examples

### Streaming

```tsx
<Reasoning streaming>The user wants a summary, so I will start with the totals…</Reasoning>
```

### Settled

```tsx
<Reasoning duration={12}>The user wants a summary, so I started with the totals and then compared regions.</Reasoning>
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-color-ai`
- `--cascivo-color-ai-border`
- `--cascivo-color-text`
- `--cascivo-color-text-muted`
- `--cascivo-focus-ring`
- `--cascivo-duration-200`
- `--cascivo-duration-loop-slow`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `button`
- **Keyboard:** Enter, Space

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

ai, reasoning, thinking, chain-of-thought, disclosure, collapsible

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# RelativeTime

Displays a date as a localized phrase relative to now, auto-updating

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add relative-time
```

Or use it from the prebuilt package without copying:

```tsx
import { RelativeTime } from '@cascivo/react'
```

## Category

`display`

## States

- `default`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `date` | `Date \| number \| string` | yes | — | The date to render relative to now. |
| `sync` | `boolean` | no | `true` | When true, updates the relative time as it elapses. |
| `now` | `number` | no | — | Override "now" (ms); disables the interval. Pass a serialized server timestamp under SSR for a byte-deterministic render. |
| `format` | `Intl.RelativeTimeFormatOptions` | no | — | Intl.RelativeTimeFormat options controlling the output. |

## Examples

### Basic

```tsx
<RelativeTime date={post.createdAt} />
```

### Natural language

```tsx
<RelativeTime date={date} format={{ numeric: "auto" }} />
```

### Static (no ticking)

```tsx
<RelativeTime date={date} sync={false} />
```

### SSR deterministic

Relative text is clock-dependent, so it is hydration-safe by default (the server text is kept and corrected on the client). Pass a serialized server timestamp via `now` when you need identical server/client output with no post-hydration correction.

```tsx
<RelativeTime date={date} now={serverNow} />
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `time`

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

time, date, relative, i18n, display

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# ReorderList

List whose rows can be reordered by pointer drag or entirely by keyboard

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add reorder-list
```

Or use it from the prebuilt package without copying:

```tsx
import { ReorderList } from '@cascivo/react'
```

## Category

`inputs`

## States

- `idle`
- `grabbed`
- `disabled`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `value` | `ReorderItem[]` | yes | — | The ordered items; the component is controlled |
| `onValueChange` | `(value: ReorderItem[]) => void` | yes | — | Called with the new order whenever a row moves |
| `disabled` | `boolean` | no | `false` | When true, disables the control and removes it from the tab order. |
| `labels` | `{ handle?: string; grabbed?: string; moved?: string; dropped?: string; cancelled?: string }` | no | — | Overrides for the component’s user-visible strings (i18n). |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |

## Object types

### `ReorderItem`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | `string` | yes | Stable identity for the row |
| `label` | `React.ReactNode` | yes | Row content |
| `name` | `string` | no | Plain-text name used in announcements when label is not a string |

## Examples

### Basic

Controlled — the caller owns the order.

```tsx
<ReorderList
  value={items}
  onValueChange={setItems}
/>
```

### Locked

Handles are disabled and drop out of the tab order.

```tsx
<ReorderList value={items} onValueChange={setItems} disabled />
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-accent-text`
- `--cascivo-color-surface`
- `--cascivo-color-surface-2`
- `--cascivo-color-foreground`
- `--cascivo-color-text-muted`
- `--cascivo-border-subtle`
- `--cascivo-radius-sm`
- `--cascivo-ring-width`
- `--cascivo-ring-color`
- `--cascivo-disabled-opacity`
- `--cascivo-target-min-coarse`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `list`
- **Keyboard:** Space, Enter, ArrowUp, ArrowDown, Escape, Tab

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

inputs, reorder, sortable, drag, list, mobile, keyboard

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Resizable

Two-pane splitter whose divider can be dragged or keyboard-nudged to reallocate space

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add resizable
```

Or use it from the prebuilt package without copying:

```tsx
import { Resizable } from '@cascivo/react'
```

## Category

`layout`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `ariaLabel` | `string` | no | — | Alias of `label` — the same invisible accessible name under the catalog spelling. Neither is deprecated. Not rendered — screen readers only. |
| `label` | `string` | no | — | Accessible label for the resize handle. Not rendered — screen readers only. |
| `children` | `ReactNode` | yes | — | Exactly two panes |
| `orientation` | `'horizontal' \| 'vertical'` | no | `horizontal` | Axis the panes are split along. `horizontal` puts them side by side with a handle you drag left and right; `vertical` stacks them with a handle you drag up and down. |
| `defaultRatio` | `number` | no | `0.5` | The initial split ratio when uncontrolled. |
| `ratio` | `number` | no | — | Controlled ratio (0–1) |
| `minRatio` | `number` | no | `0.1` | Minimum allowed split ratio. |
| `maxRatio` | `number` | no | `0.9` | Maximum allowed split ratio. |
| `onRatioChange` | `(ratio: number) => void` | no | — | Called with the new split ratio when it changes. |

## Examples

### Horizontal split

```tsx
<Resizable>
  <Editor />
  <Preview />
</Resizable>
```

### Vertical with bounds

```tsx
<Resizable orientation="vertical" defaultRatio={0.3} minRatio={0.2} maxRatio={0.8}>
  <Toolbar />
  <Canvas />
</Resizable>
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-border`
- `--cascivo-color-border-strong`
- `--cascivo-radius-full`
- `--cascivo-focus-ring`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `separator`
- **Keyboard:** ArrowLeft, ArrowRight, ArrowUp, ArrowDown, Home, End

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

splitter, panes, layout, resize, divider

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# ScrollArea

A scroll container with styled, slim scrollbars and overflow shadows

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add scroll-area
```

Or use it from the prebuilt package without copying:

```tsx
import { ScrollArea } from '@cascivo/react'
```

## Category

`layout`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `height` | `string` | no | — | Max block size of the container (any CSS length) |
| `width` | `string` | no | — | Max inline size of the container (any CSS length) |
| `orientation` | `'vertical' \| 'horizontal' \| 'both'` | no | `vertical` | Which axes may scroll |
| `edges` | `'shadow' \| 'mask' \| 'none'` | no | `shadow` | Edge affordance: box-shadow, a mask-image fade, or none |
| `children` | `ReactNode` | no | — | Scrollable content |

## Examples

### Vertical scroll

```tsx
<ScrollArea height="12rem">
  <p>Long content…</p>
</ScrollArea>
```

### Both axes

```tsx
<ScrollArea height="12rem" width="20rem" orientation="both">
  <table>…</table>
</ScrollArea>
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-color-border`
- `--cascivo-color-surface`
- `--cascivo-color-text`
- `--cascivo-color-text-subtle`
- `--cascivo-radius-control`
- `--cascivo-scroll-area-height`
- `--cascivo-scroll-area-width`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `none`
- **Keyboard:** ArrowUp, ArrowDown, PageUp, PageDown, Home, End

## Dependencies

- `@cascivo/core`

## Tags

scroll, overflow, scrollbar, container, layout

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Search

Search input with debounced search callback and clear button

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add search
```

Or use it from the prebuilt package without copying:

```tsx
import { Search } from '@cascivo/react'
```

## Category

`inputs`

## Sizes

- `sm`
- `md`
- `lg`

## States

- `empty`
- `filled`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `value` | `string` | no | — | The controlled value. |
| `defaultValue` | `string` | no | `''` | The initial value when uncontrolled. |
| `onValueChange` | `(value: string) => void` | no | — | Called with the current text on every keystroke. |
| `onSearch` | `(value: string) => void` | no | — | Called with the query, debounced, as the user types. |
| `debounceMs` | `number` | no | `300` | Debounce delay (ms) before onSearch fires. |
| `placeholder` | `string` | no | `Search` | Placeholder text shown when the field is empty. |
| `size` | `'sm' \| 'md' \| 'lg'` | no | `md` | Visual size of the component (e.g. 'sm', 'md', 'lg'). |
| `label` | `string` | no | `Search` | Accessible name for the control. Rendered as a real `<label>` that is **visually hidden** by design — it changes the accessible name, not the visible UI. If you can see it, the component stylesheet did not load (import `@cascivo/react/styles.css` or the per-component CSS). Rendered on screen. |
| `disabled` | `boolean` | no | `false` | When true, disables the control and removes it from the tab order. |
| `clearLabel` | `string` | no | `Clear search` | Accessible label for the clear button. |
| `id` | `string` | no | — | Id for the input, wired to the label. Auto-generated with useId when omitted — SSR-safe and stable across hydration. |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |
| `aria-labelledby` | `string` | no | — | Wired automatically by a wrapping `Field` — its label id, forwarded to the focusable control so the Field's label names it. |
| `aria-describedby` | `string` | no | — | Wired automatically by a wrapping `Field` — the ids of its hint/error text, forwarded to the focusable control so the supporting text is announced. |
| `aria-invalid` | `boolean` | no | — | Wired automatically by a wrapping `Field` when it is in an error state. |
| `ariaLabel` | `string` | no | — | Accessible name set through `aria-label` instead of a rendered `<label>` element. ⚠ On Search **both** props give an invisible name — `label` renders a real `<label>` the stylesheet visually hides. They differ in mechanism, not in what you see: use `ariaLabel` when a visible element outside the component already names the field, `label` otherwise. The raw DOM `aria-label` still wins over this. Not rendered — screen readers only. |

## Examples

### Basic

```tsx
<Search onSearch={(q) => runQuery(q)} />
```

### Controlled

```tsx
<Search value={query} onValueChange={setQuery} onSearch={runQuery} debounceMs={500} />
```

### Large

```tsx
<Search size="lg" placeholder="Search products…" />
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-color-surface`
- `--cascivo-color-border`
- `--cascivo-color-border-strong`
- `--cascivo-color-accent`
- `--cascivo-color-text`
- `--cascivo-color-text-muted`
- `--cascivo-color-bg-subtle`
- `--cascivo-radius-input`
- `--cascivo-focus-ring`
- `--cascivo-search-width`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `searchbox`
- **Keyboard:** Enter

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

search, input, filter, form

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Cta

Call-to-action band — quiet hairline-bordered section with title, description, and centered actions. Replace demo content before shipping.

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add section/cta
```

_Copy-paste only — `Cta` is not exported from `@cascivo/react`. Run the command above to own the source, or compose it from the exported primitives (`Flex`, `Grid`, `Heading`, …)._

## Category

`layout`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `title` | `ReactNode` | yes | — | Primary heading of the CTA band |
| `description` | `ReactNode` | no | — | Supporting text below the title |
| `actions` | `ReactNode` | no | — | Buttons or links centered below the description |
| `headingLevel` | `1 \| 2 \| 3` | no | `2` | HTML heading level for document outline control |

## Examples

### CTA band

Quiet bordered band with centered heading, description, and action buttons

```tsx
<Cta title="Ready to ship?" description="Add Cascade to your project in minutes." actions={<><Button>Get started</Button><Button variant="ghost">View on GitHub</Button></>} />
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-color-border`
- `--cascivo-color-bg-subtle`
- `--cascivo-text-2xl`
- `--cascivo-text-base`
- `--cascivo-font-bold`
- `--cascivo-color-text-subtle`
- `--cascivo-space-*`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `region`

## Dependencies

- `@cascivo/core`

## Tags

section, cta, marketing

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# 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.

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add section/feature-grid
```

_Copy-paste only — `FeatureGrid` is not exported from `@cascivo/react`. Run the command above to own the source, or compose it from the exported primitives (`Flex`, `Grid`, `Heading`, …)._

## Category

`layout`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `items` | `FeatureItem[]` | yes | — | Array of feature items with title, optional description, icon, and href |
| `title` | `ReactNode` | no | — | Section heading above the grid |
| `description` | `ReactNode` | no | — | Subheading below the section title |
| `headingLevel` | `1 \| 2 \| 3` | no | `2` | Heading level for the section title (items use headingLevel + 1) |
| `min` | `string` | no | `"16rem"` | Minimum track width forwarded to AutoGrid |

## Examples

### Feature grid (text-only)

Four-item text-only feature grid with section heading

```tsx
<FeatureGrid
  title="Built for production"
  description="Everything you need to ship a polished product."
  items={[
    { title: 'Zero config', description: 'Copy a component and it works — no providers, no wrappers.' },
    { title: 'Token-first', description: 'Every color, size and radius is a CSS custom property you own.' },
    { title: 'Signal-driven', description: 'Fine-grained reactivity with @preact/signals-react — zero re-renders.' },
    { title: 'Accessible by default', description: 'WCAG 2.1 AA, keyboard navigable, logical CSS properties for RTL.' },
  ]}
/>
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-text-2xl`
- `--cascivo-text-base`
- `--cascivo-text-sm`
- `--cascivo-font-bold`
- `--cascivo-font-semibold`
- `--cascivo-color-text-subtle`
- `--cascivo-color-border`
- `--cascivo-color-bg-subtle`
- `--cascivo-space-*`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `region`

## Dependencies

- `@cascivo/core`

## Tags

section, features, grid

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Hero

Page hero section — centered or split layout with eyebrow, title, description, actions and media slots. Replace demo content before shipping.

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add section/hero
```

_Copy-paste only — `Hero` is not exported from `@cascivo/react`. Run the command above to own the source, or compose it from the exported primitives (`Flex`, `Grid`, `Heading`, …)._

## Category

`layout`

## Variants

- `centered`
- `split`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `variant` | `"centered" \| "split"` | no | `"centered"` | Layout variant: centered (single column) or split (two columns) |
| `title` | `ReactNode` | yes | — | Primary heading content |
| `eyebrow` | `ReactNode` | no | — | Small monospace label above the title |
| `description` | `ReactNode` | no | — | Supporting paragraph below the title |
| `actions` | `ReactNode` | no | — | Buttons or links rendered in a row below the description |
| `media` | `ReactNode` | no | — | Right-hand slot in the split variant (image, demo, code block) |
| `headingLevel` | `1 \| 2 \| 3` | no | `1` | HTML heading level for document outline control |

## Examples

### Centered hero

Single-column hero with eyebrow, headline, description, and CTA buttons

```tsx
<Hero eyebrow="v8 — Assembly Included" title="Ship the dashboard your ops team deserves" description="Cascade gives you charts, layouts and sections — fully composed, copy-paste ready." actions={<><Button>Get started</Button><Button variant="ghost">View docs</Button></>} />
```

### Split hero

Two-column layout with copy on the left and media on the right

```tsx
<Hero variant="split" title="Signal-driven, CSS-native" description="Fine-grained reactivity with zero re-renders. Beautiful by default." actions={<Button>Start building</Button>} media={<img src="/preview.png" alt="Dashboard preview" />} />
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-text-4xl`
- `--cascivo-text-lg`
- `--cascivo-text-sm`
- `--cascivo-font-mono`
- `--cascivo-font-bold`
- `--cascivo-color-text-subtle`
- `--cascivo-space-*`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `region`

## Dependencies

- `@cascivo/core`

## Tags

section, hero, marketing

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# 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.

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add section/media-masonry
```

_Copy-paste only — `MediaMasonry` is not exported from `@cascivo/react`. Run the command above to own the source, or compose it from the exported primitives (`Flex`, `Grid`, `Heading`, …)._

## Category

`layout`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `children` | `ReactNode` | yes | — | Tile elements (images, cards, quotes) — consumer-provided and self-styled |
| `title` | `ReactNode` | no | — | Section heading above the gallery |
| `description` | `ReactNode` | no | — | Subheading below the section title |
| `headingLevel` | `1 \| 2 \| 3` | no | `2` | HTML heading level for the section title |
| `cols` | `number` | no | `3` | Number of masonry columns |
| `gap` | `1\|2\|3\|4\|5\|6\|8\|10\|12` | no | `4` | Gap between tiles (spacing token step) |

## Examples

### Media gallery

Masonry gallery with three image tiles; falls back to CSS columns in unsupported browsers

```tsx
<MediaMasonry title="Customer stories" cols={3} gap={4}><img src="/photo-1.jpg" alt="Team at desk" /><img src="/photo-2.jpg" alt="Product screenshot" /><img src="/photo-3.jpg" alt="Dashboard view" /></MediaMasonry>
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-text-2xl`
- `--cascivo-text-base`
- `--cascivo-font-bold`
- `--cascivo-color-text-subtle`
- `--cascivo-space-*`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `region`

## Dependencies

- `@cascivo/core`

## Tags

section, gallery, masonry

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# 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.

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add section/page-footer
```

_Copy-paste only — `PageFooter` is not exported from `@cascivo/react`. Run the command above to own the source, or compose it from the exported primitives (`Flex`, `Grid`, `Heading`, …)._

## Category

`layout`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `groups` | `FooterGroup[]` | yes | — | Array of link groups, each with a title and array of {label, href} links |
| `brand` | `ReactNode` | no | — | Brand name or logo shown in the bottom row |
| `meta` | `ReactNode` | no | — | Meta line in the bottom row (license, copyright, etc.) |

## Examples

### Site footer

Three-column footer with brand and license meta

```tsx
<PageFooter
  brand="Cascade"
  meta="MIT licensed. Built with care."
  groups={[
    { title: 'Product', links: [{ label: 'Components', href: '/components' }, { label: 'Charts', href: '/charts' }, { label: 'Layouts', href: '/layouts' }] },
    { title: 'Developers', links: [{ label: 'Docs', href: '/docs' }, { label: 'GitHub', href: 'https://github.com/cascivo/cascivo' }, { label: 'Changelog', href: '/changelog' }] },
    { title: 'Resources', links: [{ label: 'Figma kit', href: '/figma' }, { label: 'Storybook', href: '/storybook' }] },
  ]}
/>
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-text-sm`
- `--cascivo-font-mono`
- `--cascivo-font-semibold`
- `--cascivo-color-text`
- `--cascivo-color-text-subtle`
- `--cascivo-color-border`
- `--cascivo-color-accent`
- `--cascivo-space-*`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `contentinfo`

## Dependencies

- `@cascivo/core`

## Tags

section, footer, navigation

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# 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.

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add section/stats-band
```

_Copy-paste only — `StatsBand` is not exported from `@cascivo/react`. Run the command above to own the source, or compose it from the exported primitives (`Flex`, `Grid`, `Heading`, …)._

## Category

`layout`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `label` | `string` | no | — | Alias of `ariaLabel` — the same invisible accessible name under the other spelling. Neither is deprecated. Not rendered — screen readers only. |
| `ariaLabel` | `string` | no | — | Invisible accessible name. The catalog convention; `aria-label` is accepted as an alias for the DOM spelling. Not rendered — screen readers only. |
| `stats` | `StatItem[]` | yes | — | Array of stat items: label, value, optional delta (e.g. "+3.2%"), optional trend numbers for sparkline |
| `aria-label` | `string` | no | `"Key metrics"` | Accessible label for the stats region |

## Examples

### KPI band with trends

Four KPI cells — three with sparkline trends and signed deltas

```tsx
<StatsBand
  aria-label="Performance metrics"
  stats={[
    { label: 'p99 latency', value: '184 ms', delta: '-12 ms', trend: [210, 205, 198, 192, 184] },
    { label: 'Error rate', value: '0.12%', delta: '-0.03%', trend: [0.18, 0.16, 0.15, 0.14, 0.12] },
    { label: 'Uptime', value: '99.98%', trend: [99.95, 99.97, 99.98, 99.99, 99.98] },
    { label: 'Deploys today', value: '7' },
  ]}
/>
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-text-2xl`
- `--cascivo-text-sm`
- `--cascivo-font-bold`
- `--cascivo-font-mono`
- `--cascivo-color-text-subtle`
- `--cascivo-color-border`
- `--cascivo-color-bg-subtle`
- `--cascivo-space-*`

## Accessibility

- **WCAG level:** 2.1-AA
- **ARIA role:** `region`

## Dependencies

- `@cascivo/core`
- `@cascivo/charts`

## Tags

section, stats, kpi, charts

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# SegmentedControl

Mutually exclusive toggle group

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add segmented-control
```

Or use it from the prebuilt package without copying:

```tsx
import { SegmentedControl } from '@cascivo/react'
```

## Category

`inputs`

## Sizes

- `sm`
- `md`
- `lg`

## States

- `idle`
- `selected`
- `disabled`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `options` | `SegmentedControlOption[]` | yes | — | The selectable options. |
| `value` | `string` | yes | — | The controlled value. |
| `onValueChange` | `(v: string) => void` | yes | — | Called with the new value when it changes. |
| `size` | `'sm' \| 'md' \| 'lg'` | no | `md` | Visual size of the component (e.g. 'sm', 'md', 'lg'). |
| `disabled` | `boolean` | no | `false` | When true, disables the control and removes it from the tab order. |
| `ariaLabel` | `string` | no | — | Accessible name for the group. Invisible — it names the role="group" and renders nothing. The raw DOM `aria-label` still wins over this. Not rendered — screen readers only. |
| `label` | `string` | no | — | Alias of `ariaLabel` — same invisible accessible name, the other spelling. Not rendered. Not rendered — screen readers only. |

## Examples

### Basic

```tsx
<SegmentedControl options={[{label:'Day',value:'day'},{label:'Week',value:'week'},{label:'Month',value:'month'}]} value="day" onValueChange={() => {}} />
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-bg-subtle`
- `--cascivo-color-border`
- `--cascivo-color-surface`
- `--cascivo-color-text`
- `--cascivo-radius-md`
- `--cascivo-radius-sm`
- `--cascivo-shadow-sm`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `group`
- **Keyboard:** ArrowLeft, ArrowRight

## Dependencies

- `@cascivo/core`

## Tags

form, toggle, group, segmented, input

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Select

Native select menu styled to match the design system

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add select
```

Or use it from the prebuilt package without copying:

```tsx
import { Select } from '@cascivo/react'
```

## Category

`inputs`

## Sizes

- `sm`
- `md`
- `lg`

## States

- `idle`
- `focused`
- `error`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `label` | `string` | no | — | Text label for the control. Rendered on screen. |
| `hint` | `string` | no | — | Supplementary hint text shown with the control. |
| `error` | `string` | no | — | Error message shown when the value is invalid. |
| `placeholder` | `string` | no | — | Placeholder text shown when the field is empty. |
| `options` | `{ value: string; label: string; disabled?: boolean }[]` | yes | — | The selectable options. |
| `size` | `'sm' \| 'md' \| 'lg'` | no | `md` | Visual size of the component (e.g. 'sm', 'md', 'lg'). |
| `disabled` | `boolean` | no | `false` | When true, disables the control and removes it from the tab order. |
| `ariaLabel` | `string` | no | — | Invisible accessible name, for when a visible element outside this component already labels it and `label` would render that text a second time. ⚠ `label` on this component is **visible**; `IconButton.label`/`Sparkline.label` are invisible names, which is the prior that costs adopters a duplicated label. The raw DOM `aria-label` still wins over this. Not rendered — screen readers only. |

## Examples

### Basic

```tsx
<Select label="Role" options={[{ value: "admin", label: "Admin" }]} />
```

### With placeholder

```tsx
<Select label="Country" placeholder="Choose…" options={countries} />
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-color-surface`
- `--cascivo-color-border`
- `--cascivo-color-accent`
- `--cascivo-color-text-muted`
- `--cascivo-radius-input`
- `--cascivo-focus-ring`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `listbox`
- **Keyboard:** ArrowUp, ArrowDown, Space

## Dependencies

- `@cascivo/core`

## Tags

form, dropdown, menu

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Separator

Visual or semantic divider between content

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add separator
```

Or use it from the prebuilt package without copying:

```tsx
import { Separator } from '@cascivo/react'
```

## Category

`display`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `orientation` | `'horizontal' \| 'vertical'` | no | `horizontal` | Direction the rule runs: `horizontal` draws a full-width line, `vertical` a full-height one that stretches to its flex row. |
| `decorative` | `boolean` | no | `false` | When true, the separator is purely visual and hidden from assistive tech |

## Examples

### Horizontal

```tsx
<Separator />
```

### Vertical

```tsx
<Separator orientation="vertical" />
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-color-border`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `separator`

## Dependencies

- `@cascivo/core`

## Tags

divider, rule, layout

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# ShareMenu

A Share button opening intent links for Bluesky, Mastodon, Threads, LinkedIn and X, plus copy link and the system share sheet

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add share-menu
```

Or use it from the prebuilt package without copying:

```tsx
import { ShareMenu } from '@cascivo/react'
```

## Category

`overlay`

## Sizes

- `sm`
- `md`

## States

- `closed`
- `open`
- `copied`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `url` | `string` | yes | — | The page being shared |
| `text` | `string` | no | — | Text to post alongside the link (LinkedIn takes none; it reads the page) |
| `items` | `Array<'bluesky' \| 'mastodon' \| 'threads' \| 'linkedin' \| 'x'>` | no | `['bluesky', 'mastodon', 'threads', 'linkedin', 'x']` | The networks offered, in order |
| `size` | `'sm' \| 'md'` | no | `md` | Visual size of the component (e.g. 'sm', 'md', 'lg'). |
| `labels` | `{ share?: string; copyLink?: string; copied?: string; more?: string; server?: string; shareOn?: (network: string) => string }` | no | — | Overrides the built-in i18n labels per instance |
| `className` | `string` | no | — | Class added to the root element |

## Examples

### Default

```tsx
<ShareMenu url="https://cascivo.com/blog/launch" text="cascivo 1.0 is out" />
```

### Chosen networks

Offer only the networks your readers use, in your order

```tsx
<ShareMenu url={url} items={['bluesky', 'mastodon']} size="sm" />
```

### Just the link

shareIntentUrl builds the same compose link for your own markup; it returns null for Mastodon without a server

```tsx
import { shareIntentUrl } from './share-menu'

<a href={shareIntentUrl('bluesky', { url, text }) ?? undefined}>Post to Bluesky</a>
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-color-bg-subtle`
- `--cascivo-color-border`
- `--cascivo-color-success`
- `--cascivo-color-surface`
- `--cascivo-color-surface-overlay`
- `--cascivo-color-text`
- `--cascivo-color-text-muted`
- `--cascivo-control-height-md`
- `--cascivo-control-height-sm`
- `--cascivo-focus-ring`
- `--cascivo-font-medium`
- `--cascivo-font-sans`
- `--cascivo-motion-enter`
- `--cascivo-radius-control`
- `--cascivo-radius-item`
- `--cascivo-radius-overlay`
- `--cascivo-shadow-overlay`
- `--cascivo-space-1`
- `--cascivo-space-2`
- `--cascivo-space-3`
- `--cascivo-space-4`
- `--cascivo-target-min-coarse`
- `--cascivo-text-sm`
- `--cascivo-text-xs`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `button`
- **Keyboard:** Enter, Space, Escape, Tab

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

share, social, bluesky, mastodon, threads, linkedin, popover, link

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Sheet

Slide-in panel from any edge, using popover=manual and @starting-style animations

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add sheet
```

Or use it from the prebuilt package without copying:

```tsx
import { Sheet } from '@cascivo/react'
```

## Category

`overlay`

## States

- `open`
- `closed`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `open` | `boolean` | yes | — | Whether the component is open (controlled). |
| `onClose` | `() => void` | yes | — | Called when the component is closed. |
| `title` | `React.ReactNode` | no | — | Title text for the component. |
| `side` | `'start' \| 'end' \| 'top' \| 'bottom'` | no | `end` | Edge the sheet slides in from: `end` (the inline end — right in LTR), `start`, `top` or `bottom`. |

## Examples

### Basic

```tsx
<Sheet open={isOpen} onClose={() => setIsOpen(false)} title="Filters">
  <FilterForm />
</Sheet>
```

### Bottom sheet

```tsx
<Sheet open={isOpen} onClose={close} side="bottom" title="Share">
  <ShareOptions />
</Sheet>
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-dialog-body-gap`
- `--cascivo-color-surface`
- `--cascivo-color-border`
- `--cascivo-radius-lg`
- `--cascivo-shadow-xl`
- `--cascivo-motion-enter`
- `--cascivo-motion-exit`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `dialog`
- **Keyboard:** Escape, Tab, Shift+Tab

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

overlay, drawer, panel, slide

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# ShellHeader

Console application header: brand with prefix, dropdown nav menus, global icon actions, hamburger, skip-to-content

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add shell-header
```

Or use it from the prebuilt package without copying:

```tsx
import { ShellHeader } from '@cascivo/react'
```

## Category

`navigation`

## States

- `default`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `brand` | `ShellHeaderBrand \| ReactNode` | no | — | Brand: { prefix?, name, href? } or free-form node |
| `nav` | `ShellHeaderNavItem[]` | no | — | Top nav: links ({ label, href, active?, onClick? }) or dropdown menus ({ label, items }) |
| `center` | `ReactNode` | no | — | Free-form slot between the nav and the right-hand cluster, taking the header’s spare width — where a command-palette or search trigger belongs |
| `actions` | `ShellHeaderAction[]` | no | — | Right-aligned global icon actions with aria-pressed |
| `end` | `ReactNode` | no | — | Free-form trailing slot (user menu, theme switcher) |
| `onMenuClick` | `() => void` | no | — | Renders the hamburger button; call shell.toggleSideNav |
| `menuExpanded` | `boolean` | no | — | aria-expanded for the hamburger button |
| `skipToContentHref` | `string \| false` | no | `'#cascade-main'` | Skip-link target; false disables the link |
| `labels` | `ShellHeaderLabels` | no | — | i18n overrides for built-in strings |

## Object types

### `ShellHeaderAction`

A right-aligned global icon action. `actions` is a typed array of these — pass an `icon` node per item, not free-form JSX. For non-action trailing content (user menu, theme switcher) use the `end` slot instead.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | `string` | yes | Stable key for the action. |
| `label` | `string` | yes | Accessible label (aria-label / tooltip). |
| `icon` | `ReactNode` | yes | Icon node, e.g. an @cascivo/icons glyph. |
| `active` | `boolean` | no | Renders aria-pressed for a toggle action. |
| `onClick` | `() => void` | no | Invoked when the action is activated. |

### `ShellHeaderBrand`

Structured brand for the `brand` prop (or pass any ReactNode instead).

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `prefix` | `string` | no | Muted text before the name (e.g. an org). |
| `name` | `string` | yes | Product/app name. |
| `href` | `string` | no | Link target for the brand (routed via setLinkComponent). |

### `ShellHeaderNavItem`

A top-nav entry: either a link (`{ label, href, active?, onClick? }`) or a dropdown menu (`{ label, items: { label, href, active? }[] }`).

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `label` | `string` | yes | Visible nav label. |
| `href` | `string` | no | Link target (link items). Routed via setLinkComponent. |
| `items` | `{ label: string; href: string; active?: boolean }[]` | no | Dropdown menu entries (menu items). |
| `active` | `boolean` | no | Marks the current nav entry (aria-current). |
| `onClick` | `(e: MouseEvent<HTMLAnchorElement>) => void` | no | Intercept navigation (e.g. a SPA section switch). |

## Examples

### Console header

Brand with prefix, dropdown nav, global icon action

```tsx
import { Bell } from '@cascivo/icons'

<ShellHeader
  brand={{ prefix: 'cascivo', name: 'Console', href: '/' }}
  nav={[
    { label: 'Dashboard', href: '/dash', active: true },
    { label: 'Manage', items: [{ label: 'Users', href: '/users' }] },
  ]}
  actions={[{ id: 'notifications', label: 'Notifications', icon: <Bell /> }]}
/>
```

### Command-palette trigger in the centre slot

center takes the header’s spare width, so the trigger grows and shrinks with the viewport instead of being pinned right like end

```tsx
<ShellHeader
  brand={{ name: 'Console', href: '/' }}
  center={
    <Button variant="ghost" onClick={openPalette}>
      Search incidents, alerts, services… <Kbd>⌘K</Kbd>
    </Button>
  }
  end={<UserMenu />}
/>
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-shell-header-block-size`
- `--cascivo-color-surface`
- `--cascivo-color-border`
- `--cascivo-color-text`
- `--cascivo-color-text-subtle`
- `--cascivo-color-accent`
- `--cascivo-radius-control`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `banner`
- **Keyboard:** Tab, Enter, Space, ArrowDown, ArrowUp, Escape

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

navigation, header, shell, console, menu, app-shell

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# ShimmerText

Text with a bright band sweeping through it — the "Thinking…" look for a label that marks work in progress

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add shimmer-text
```

Or use it from the prebuilt package without copying:

```tsx
import { ShimmerText } from '@cascivo/react'
```

## Category

`feedback`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `as` | `'span' \| 'p' \| 'div'` | no | `span` | `span` for inline text, `p` for a paragraph, `div` for a block that imposes no semantics of its own. |
| `children` | `ReactNode` | no | — | The label text the shimmer sweeps through. |

## Examples

### Thinking label

```tsx
<ShimmerText>Thinking…</ShimmerText>
```

### As a paragraph

```tsx
<ShimmerText as="p">Searching 12 documents…</ShimmerText>
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-shimmer-text-color`
- `--cascivo-shimmer-text-highlight`
- `--cascivo-color-text-muted`
- `--cascivo-color-ai`
- `--cascivo-duration-loop-slow`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `none`

## Dependencies

- `@cascivo/core`

## Tags

ai, loading, shimmer, thinking, text, progress

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# SideNav

Collapsible sidebar navigation with optional icons and one level of grouping

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add side-nav
```

Or use it from the prebuilt package without copying:

```tsx
import { SideNav } from '@cascivo/react'
```

## Category

`navigation`

## States

- `expanded`
- `collapsed`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `groups` | `SideNavGroup[]` | no | — | Grouped navigation items rendered under optional group labels. |
| `showCollapseToggle` | `boolean` | no | `true` | Show the collapse/expand toggle control. |
| `items` | `SideNavItem[]` | no | — | { label, href?, icon?, active?, items?, onClick?, disabled?, tone?, trailing?, render? } — an onClick-only item renders a focusable <button>; nested items render expandable menus (links, action sub-items with onSelect/selected, separators, labels); render() is an alignment-preserving escape hatch |
| `collapsed` | `boolean` | no | — | Controlled collapsed state (rail mode) |
| `defaultCollapsed` | `boolean` | no | `false` | Whether the rail is collapsed on first render (uncontrolled). |
| `onCollapsedChange` | `(collapsed: boolean) => void` | no | — | Called with the new collapsed state when it changes. |
| `label` | `string` | no | — | Alias of `ariaLabel` — the same invisible accessible name under the other spelling. Neither is deprecated. Not rendered — screen readers only. |
| `ariaLabel` | `string` | no | `Side navigation` | Accessible label for the component. Not rendered — screen readers only. |
| `collapseLabel` | `string` | no | `Collapse navigation` | Accessible label for the collapse control. |
| `expandLabel` | `string` | no | `Expand navigation` | Accessible label for the expand control. |
| `expandOnHover` | `boolean` | no | `false` | Widens the rail as an overlay on hover/focus-within; suppresses tooltips/flyouts |
| `header` | `ReactNode \| ((ctx: SideNavSlotContext) => ReactNode)` | no | — | Content rendered above the items, inside the item padding context (e.g. app-context pickers). Pass a `({ collapsed }) => …` function to shrink it to a rail icon. |
| `footer` | `ReactNode \| ((ctx: SideNavSlotContext) => ReactNode)` | no | — | Content rendered above the collapse toggle, inside the item padding context so it lines up with the nav items (e.g. version string, user info). Pass a `({ collapsed }) => …` function to shrink it to a rail icon. |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |

## Examples

### Basic

```tsx
<SideNav items={[{ label: 'Home', href: '/', active: true }, { label: 'Reports', href: '/reports' }]} />
```

### With a group

```tsx
<SideNav items={[{ label: 'Settings', items: [{ label: 'Profile', href: '/profile' }] }]} />
```

### Icon rail

Collapsed rail: icons-only with tooltips, grapheme fallback for icon-less items, flyout menus for groups

```tsx
import { Home } from '@cascivo/icons'

<SideNav collapsed items={[{ label: 'Home', href: '/', icon: <Home size={16} /> }]} />
```

### Expand on hover

Rail widens as CSS overlay on hover without reflowing adjacent content

```tsx
<SideNav collapsed expandOnHover items={items} />
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-accent-text`
- `--cascivo-sidenav-inline-size`
- `--cascivo-sidenav-rail-inline-size`
- `--cascivo-sidenav-bg`
- `--cascivo-color-surface`
- `--cascivo-color-border`
- `--cascivo-color-text`
- `--cascivo-color-text-subtle`
- `--cascivo-color-bg-subtle`
- `--cascivo-color-accent`
- `--cascivo-color-accent-subtle`
- `--cascivo-color-destructive`
- `--cascivo-color-warning`
- `--cascivo-color-success`
- `--cascivo-focus-ring`
- `--cascivo-motion-enter`
- `--cascivo-motion-exit`
- `--cascivo-motion-emphasis`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `navigation`
- **Keyboard:** Tab, Enter, Space, ArrowDown, ArrowUp, Escape

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

navigation, sidebar, app-shell, collapsible

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Skeleton

Animated loading placeholder that mirrors the shape of pending content

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add skeleton
```

Or use it from the prebuilt package without copying:

```tsx
import { Skeleton } from '@cascivo/react'
```

## Category

`display`

## Variants

- `text`
- `circle`
- `rect`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `variant` | `'text' \| 'circle' \| 'rect'` | no | `text` | Shape of the placeholder: `text` (stacked lines), `circle` (an avatar), `rect` (a block). |
| `width` | `string` | no | — | CSS length applied as an inline custom property |
| `height` | `string` | no | — | CSS length applied as an inline custom property |
| `lines` | `number` | no | `1` | Number of bars for the text variant; the last bar renders shorter |
| `ai` | `boolean` | no | `false` | Tints the placeholder and its sheen with the AI hue, marking content that an AI is generating (Carbon’s AI skeleton). |

## Examples

### Text

```tsx
<Skeleton lines={3} />
```

### Avatar

```tsx
<Skeleton variant="circle" width="3rem" height="3rem" />
```

### Image

```tsx
<Skeleton variant="rect" height="12rem" />
```

### AI-generated content

```tsx
<Skeleton ai lines={3} />
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-color-border`
- `--cascivo-color-bg-subtle`
- `--cascivo-radius-sm`
- `--cascivo-radius-full`
- `--cascivo-radius-component`
- `--cascivo-color-ai-subtle`
- `--cascivo-color-ai-sheen`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `none`

## Dependencies

- `@cascivo/core`

## Tags

loading, placeholder, shimmer, ai

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# SkipNav

Skip link that jumps keyboard users past the navigation to the main content

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add skip-nav
```

Or use it from the prebuilt package without copying:

```tsx
import { SkipNavLink, SkipNavTarget } from '@cascivo/react'
```

## Category

`navigation`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `targetId` | `string` | no | `cascade-skip-target` | SkipNavLink: id of the SkipNavTarget to jump to |
| `labels` | `{ label?: string }` | no | — | SkipNavLink: overrides the built-in i18n label per instance |
| `id` | `string` | no | `cascade-skip-target` | SkipNavTarget: anchor id — must match the link targetId |

## Examples

### Default pair

SkipNavLink must be the first focusable element on the page

```tsx
<><SkipNavLink /><nav>…</nav><SkipNavTarget /><main>…</main></>
```

### Custom target

```tsx
<><SkipNavLink targetId="main-content" /><SkipNavTarget id="main-content" /></>
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-color-surface`
- `--cascivo-color-border`
- `--cascivo-color-text`
- `--cascivo-radius-control`
- `--cascivo-focus-ring`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `link`
- **Keyboard:** Tab, Enter

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

accessibility, skip-link, keyboard, navigation

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Slider

Range input for selecting a value within bounds

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add slider
```

Or use it from the prebuilt package without copying:

```tsx
import { Slider } from '@cascivo/react'
```

## Category

`inputs`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `label` | `string` | no | — | Text label for the control. Rendered on screen. |
| `min` | `number` | no | `0` | Minimum allowed value. |
| `max` | `number` | no | `100` | Maximum allowed value. |
| `step` | `number` | no | `1` | Increment between allowed values. |
| `value` | `number` | no | — | The controlled value. |
| `defaultValue` | `number` | no | — | The initial value when uncontrolled. |
| `disabled` | `boolean` | no | `false` | When true, disables the control and removes it from the tab order. |
| `ariaLabel` | `string` | no | — | Invisible accessible name, for when a visible element outside this component already labels it and `label` would render that text a second time. ⚠ `label` on this component is **visible**; `IconButton.label`/`Sparkline.label` are invisible names, which is the prior that costs adopters a duplicated label. The raw DOM `aria-label` still wins over this. Not rendered — screen readers only. |

## Examples

### Basic

```tsx
<Slider label="Volume" defaultValue={50} />
```

### Stepped

```tsx
<Slider label="Rating" min={0} max={5} step={1} />
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-color-accent`
- `--cascivo-color-border-strong`
- `--cascivo-color-surface`
- `--cascivo-radius-full`
- `--cascivo-focus-ring`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `slider`
- **Keyboard:** ArrowLeft, ArrowRight, ArrowUp, ArrowDown, Home, End

## Dependencies

- `@cascivo/core`

## Tags

form, range, input

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Sources

Collapsible, numbered list of the sources an AI answer drew on — "Used 3 sources" — whose numbers match InlineCitation

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add sources
```

Or use it from the prebuilt package without copying:

```tsx
import { Sources } from '@cascivo/react'
```

## Category

`display`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `items` | `AiSource[]` | yes | — | The sources, in citation order. Each has `title`, `url` and an optional `description`. Only absolute http(s) URLs become links; anything else (e.g. `javascript:`) renders as text. |
| `labels` | `{ summary?: string }` | no | — | Overrides for the component’s user-visible strings (i18n). `summary` may contain `{count}`. |

## Object types

### `AiSource`

One source an answer cites.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `title` | `string` | yes | The source’s title. |
| `url` | `string` | yes | Where it lives. Treated as untrusted: only absolute http(s) URLs are linked. |
| `description` | `ReactNode` | no | An excerpt or note shown under the title. |

## Examples

### Answer sources

```tsx
<Sources
  items={[
    { title: 'Refund policy', url: 'https://example.com/refunds' },
    { title: 'Terms of service', url: 'https://example.com/terms', description: '§4 covers cancellations.' },
  ]}
/>
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-link-color`
- `--cascivo-color-accent-text`
- `--cascivo-color-text`
- `--cascivo-color-text-muted`
- `--cascivo-focus-ring`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `button`
- **Keyboard:** Enter, Space

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

ai, sources, citations, references, provenance, links

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Spinner

Indeterminate loading indicator

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add spinner
```

Or use it from the prebuilt package without copying:

```tsx
import { Spinner } from '@cascivo/react'
```

## Category

`feedback`

## Sizes

- `sm`
- `md`
- `lg`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `size` | `'sm' \| 'md' \| 'lg'` | no | `md` | Visual size of the component (e.g. 'sm', 'md', 'lg'). |
| `ariaLabel` | `string` | no | — | Alias of `label` — the same invisible accessible name under the catalog spelling. Neither is deprecated. Not rendered — screen readers only. |
| `label` | `string` | no | `Loading` | Accessible label announced by screen readers. Not rendered — screen readers only. |

## Examples

### Default

```tsx
<Spinner />
```

### Large

```tsx
<Spinner size="lg" />
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-radius-full`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `status`

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

loading, progress, feedback

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Stack

Overlaps children in a CSS grid stack with a configurable offset to create a card-pile effect

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add stack
```

Or use it from the prebuilt package without copying:

```tsx
import { Stack } from '@cascivo/react'
```

## Category

`layout`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `children` | `React.ReactNode` | yes | — | Content rendered inside the component. |
| `offset` | `number` | no | `4` | Pixel offset applied per overlapped layer in both axes. This is NOT a spacing `gap` — for gap-based vertical/horizontal layout use `Flex`/`Grid` and their `gap` prop. |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |

## Examples

### Card pile

Three cards stacked with a 6px offset to show depth

```tsx
<Stack offset={6}><Card>First</Card><Card>Second</Card><Card>Third</Card></Stack>
```

### Tight stack

Overlapping avatar group with minimal offset

```tsx
<Stack offset={2}><Avatar src="/a.jpg" /><Avatar src="/b.jpg" /><Avatar src="/c.jpg" /></Stack>
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `none`

## Tags

stack, pile, overlap, layered, z-axis, card-pile, layout

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Stat

Displays a key metric with optional delta, trend direction and help text

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add stat
```

Or use it from the prebuilt package without copying:

```tsx
import { Stat } from '@cascivo/react'
```

## Category

`display`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `card` | `boolean` | no | `false` | Wrap the tile in the same card chrome `@cascivo/charts`' `Kpi` ships (surface, border, radius, padding), so a `Stat` row and a `Kpi` row in one dashboard read as one system. Off by default: `Stat` is layout-only so it can sit inside a `Card` you control. |
| `label` | `string` | yes | — | What the metric measures — rendered visibly above the value. Rendered on screen. |
| `value` | `string \| number` | yes | — | The metric value |
| `delta` | `string` | no | — | Change indicator rendered next to the trend arrow |
| `trend` | `'up' \| 'down' \| 'flat'` | no | `flat` | Direction of the trend indicator ('up' \| 'down' \| 'flat'). |
| `goodDirection` | `'up' \| 'down' \| 'neutral'` | no | `up` | Which direction is *good* for this metric — the colour, independent of the arrow. 'up' (default) is the classic revenue tile; use 'down' for errors, latency, cost or churn, where a rise is bad news; 'neutral' keeps the arrow and drops the sentiment colour. |
| `helpText` | `string` | no | — | Fine print below the value (methodology, time range) |
| `visual` | `React.ReactNode` | no | — | Trailing decorative visual, e.g. a Sparkline from the separate @cascivo/charts package (not exported from @cascivo/react), rendered below the value/delta/helpText |

## Examples

### Default

```tsx
<Stat label="Components" value={106} />
```

### With trend

```tsx
<Stat label="Bundle size" value="12.4 kB" delta="-1.2 kB" trend="up" />
```

### With help text

```tsx
<Stat label="Axe violations" value={0} helpText="WCAG 2.1 AA, 4 app states" />
```

### With a trailing sparkline

Sparkline is from @cascivo/charts

```tsx
<Stat label="Requests / min" value="1.2k" delta="+4.3%" trend="up" visual={<Sparkline data={requestsPerMinute} label="Requests per minute trend" />} />
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-color-text`
- `--cascivo-color-text-subtle`
- `--cascivo-color-text-muted`
- `--cascivo-color-success`
- `--cascivo-color-destructive`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `none`

## Dependencies

- `@cascivo/core`

## Tags

stat, kpi, metric, number

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Status

Colored dot with a label communicating the state of a system or entity

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add status
```

Or use it from the prebuilt package without copying:

```tsx
import { Status } from '@cascivo/react'
```

## Category

`display`

## Variants

- `success`
- `warning`
- `error`
- `info`
- `neutral`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `status` | `'success' \| 'warning' \| 'error' \| 'info' \| 'neutral'` | no | `neutral` | Status state. |
| `pulse` | `boolean` | no | `false` | Pulses the dot — gated behind prefers-reduced-motion: no-preference |

## Examples

### Default

```tsx
<Status>Unknown</Status>
```

### Success

```tsx
<Status status="success">Operational</Status>
```

### Pulsing

The pulse animation respects prefers-reduced-motion

```tsx
<Status status="info" pulse>Deploying</Status>
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-color-success`
- `--cascivo-color-warning`
- `--cascivo-color-error`
- `--cascivo-color-info`
- `--cascivo-color-text-muted`
- `--cascivo-color-text`
- `--cascivo-radius-full`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `none`

## Dependencies

- `@cascivo/core`

## Tags

status, indicator, dot, badge

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Steps

Visual progress indicator for multi-step flows with horizontal and vertical orientations

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add steps
```

Or use it from the prebuilt package without copying:

```tsx
import { Steps } from '@cascivo/react'
```

## Category

`navigation`

## States

- `pending`
- `active`
- `complete`
- `error`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `label` | `string` | no | — | Alias of `ariaLabel` — the same invisible accessible name under the other spelling. Neither is deprecated. Not rendered — screen readers only. |
| `ariaLabel` | `string` | no | — | Accessible label for the steps navigation; defaults to the built-in i18n string. Not rendered — screen readers only. |
| `items` | `Step[]` | no | — | Alias of `steps` — the catalog-wide name for a config-driven collection. Exactly one of the two is required. |
| `steps` | `Step[]` | no | — | Array of step objects with label and optional explicit state |
| `activeStep` | `number` | no | `0` | Index of the currently active step (0-based) |
| `orientation` | `'horizontal' \| 'vertical'` | no | `'horizontal'` | Axis the steps flow along: `horizontal` runs them across with connectors between, `vertical` stacks them down the page. |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |

## Object types

### `Step`

Shape of an entry in `steps` / `items`.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `label` | `string` | yes | Visible step label. |
| `id` | `string` | no | Stable identity, used as the React key so reordering keeps DOM nodes. |
| `state` | `StepState \| ProgressInput` | no | Step status. `StepState` ('pending' \| 'active' \| 'complete' \| 'error') is canonical; `ProgressInput` also accepts Timeline's `current` / `upcoming` aliases. |

## Examples

### Horizontal (default)

Standard checkout or onboarding progress tracker

```tsx
<Steps
  steps={[
    { label: 'Cart' },
    { label: 'Shipping' },
    { label: 'Payment' },
    { label: 'Confirm' },
  ]}
  activeStep={1}
/>
```

### Vertical

Sidebar-style progress for tall forms

```tsx
<Steps
  orientation="vertical"
  steps={[
    { label: 'Account info' },
    { label: 'Profile details' },
    { label: 'Preferences' },
  ]}
  activeStep={0}
/>
```

### With explicit error state

Override derived state on a specific step

```tsx
<Steps
  steps={[
    { label: 'Upload' },
    { label: 'Validate', state: 'error' },
    { label: 'Process' },
  ]}
  activeStep={1}
/>
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-color-accent`
- `--cascivo-color-accent-content`
- `--cascivo-color-success`
- `--cascivo-color-success-content`
- `--cascivo-color-error`
- `--cascivo-color-error-content`
- `--cascivo-color-surface`
- `--cascivo-color-text`
- `--cascivo-color-text-subtle`
- `--cascivo-color-text-muted`
- `--cascivo-border-default`
- `--cascivo-radius-full`
- `--cascivo-ease-out`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `list`

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

steps, wizard, stepper, progress, navigation, onboarding, checkout

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# StreamingText

Reveals text character by character with a blinking cursor, catching up as a streamed reply grows

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add streaming-text
```

Or use it from the prebuilt package without copying:

```tsx
import { StreamingText } from '@cascivo/react'
```

## Category

`display`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `text` | `string` | yes | — | The target text. Pass the accumulating reply as it streams; typing catches up as it grows, and restarts if it is replaced by a shorter string. |
| `speed` | `number` | no | `2` | Characters revealed per animation frame. |
| `onComplete` | `() => void` | no | — | Called when the displayed text has caught up with `text`. |

## Examples

### Typing

```tsx
<StreamingText text="Hello, I am cascivo." speed={3} />
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-duration-loop-fast`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `none`

## Dependencies

- `@cascivo/core`

## Tags

ai, streaming, typewriter, text, chat

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# StructuredList

Tabular row list for scannable data, optionally single-selectable

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add structured-list
```

Or use it from the prebuilt package without copying:

```tsx
import { StructuredList } from '@cascivo/react'
```

## Category

`display`

## Variants

- `static`
- `selectable`

## States

- `default`
- `selected`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `label` | `string` | no | — | Alias of `ariaLabel` — the same invisible accessible name under the other spelling. Neither is deprecated. Not rendered — screen readers only. |
| `ariaLabel` | `string` | no | — | Invisible accessible name. The catalog convention; the DOM spelling `aria-label` is accepted as an alias so either guess compiles. Not rendered — screen readers only. |
| `aria-label` | `string` | no | — | Accessible label for the list table. |
| `items` | `{ id: string; cells: ReactNode[]; selected?: boolean }[]` | yes | — | The items to render. |
| `headers` | `ReactNode[]` | no | — | The column header cells. |
| `selectable` | `boolean` | no | `false` | When true, rows can be selected. |
| `value` | `string` | no | — | The controlled value. |
| `defaultValue` | `string` | no | — | The initial value when uncontrolled. |
| `onSelect` | `(id: string) => void` | no | — | Called with the selected value. |

## Examples

### Static

```tsx
<StructuredList headers={["Name", "Role"]} items={[{ id: "a", cells: ["Ada", "Engineer"] }]} />
```

### Selectable

```tsx
<StructuredList selectable defaultValue="a" items={[{ id: "a", cells: ["Ada"] }, { id: "b", cells: ["Grace"] }]} onSelect={(id) => set(id)} />
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-color-border`
- `--cascivo-color-bg-subtle`
- `--cascivo-color-text`
- `--cascivo-color-text-subtle`
- `--cascivo-color-primary`
- `--cascivo-color-surface`
- `--cascivo-focus-ring`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `table`
- **Keyboard:** ArrowDown, ArrowUp, Home, End, Enter, Space

## Dependencies

- `@cascivo/core`

## Tags

display, list, table, data

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Swap

Animated toggle between two icon/content states with rotate or flip transition

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add swap
```

Or use it from the prebuilt package without copying:

```tsx
import { Swap } from '@cascivo/react'
```

## Category

`inputs`

## Variants

- `rotate`
- `flip`

## States

- `unchecked`
- `checked`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `label` | `string` | no | — | Alias of `ariaLabel` — the same invisible accessible name under the other spelling. Neither is deprecated. Not rendered — screen readers only. |
| `ariaLabel` | `string` | no | — | Invisible accessible name. The catalog convention; `aria-label` is accepted as an alias for the DOM spelling. Not rendered — screen readers only. |
| `on` | `React.ReactNode` | yes | — | Content shown in the active (on) state. |
| `off` | `React.ReactNode` | yes | — | Content shown in the inactive (off) state. |
| `checked` | `boolean` | no | `false` | Whether the control is checked (controlled). |
| `onValueChange` | `(checked: boolean) => void` | no | — | Called with the new checked state when the swap is toggled. |
| `mode` | `'rotate' \| 'flip'` | no | `rotate` | Transition between states ('rotate' \| 'flip'). |
| `aria-label` | `string` | no | — | Accessible label used when no visible label is present. |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |

## Examples

### Theme toggle (rotate)

Sun/moon icon that rotates between two states

```tsx
<Swap on={<SunIcon />} off={<MoonIcon />} mode="rotate" aria-label="Toggle theme" />
```

### Flip mode

Heart icon that flips to filled on activation

```tsx
<Swap on={<HeartFilledIcon />} off={<HeartIcon />} mode="flip" aria-label="Favorite" />
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-ring-width`
- `--cascivo-ring-color`
- `--cascivo-radius-control`
- `--cascivo-ease-out`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `switch`
- **Keyboard:** Space, Enter

## Dependencies

- `@cascivo/core`

## Tags

toggle, icon, animate, switch, flip, rotate

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# SwipeItem

List row whose leading/trailing actions are revealed by a horizontal swipe, with keyboard parity

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add swipe-item
```

Or use it from the prebuilt package without copying:

```tsx
import { SwipeItem } from '@cascivo/react'
```

## Category

`display`

## States

- `closed`
- `leading`
- `trailing`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `children` | `React.ReactNode` | yes | — | The row content |
| `leadingActions` | `SwipeAction[]` | no | `[]` | Actions revealed by dragging toward the end edge (shown on the start edge) |
| `trailingActions` | `SwipeAction[]` | no | `[]` | Actions revealed by dragging toward the start edge (shown on the end edge) |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |

## Examples

### Trailing actions

```tsx
<SwipeItem
  trailingActions={[
    { label: 'Archive', onSelect: archive },
    { label: 'Delete', onSelect: remove, destructive: true },
  ]}
>
  <MessageRow message={message} />
</SwipeItem>
```

### Leading and trailing

```tsx
<SwipeItem
  leadingActions={[{ label: 'Pin', icon: <PinIcon />, onSelect: pin }]}
  trailingActions={[{ label: 'Delete', onSelect: remove, destructive: true }]}
>
  <TaskRow task={task} />
</SwipeItem>
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-surface`
- `--cascivo-color-accent`
- `--cascivo-color-accent-content`
- `--cascivo-color-destructive`
- `--cascivo-color-text-on-destructive`
- `--cascivo-target-min-coarse`
- `--cascivo-motion-enter`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `group`
- **Keyboard:** Tab, Enter, Space, Escape

## Dependencies

- `@cascivo/core`

## Tags

display, swipe, list, mobile, gesture, actions

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Switcher

Always-visible app/product switcher LIST — every entry is rendered at once, it does not collapse. Lives inside HeaderPanel; renders links with an active indicator and optional dividers. For a collapsed trigger with a menu, use Dropdown.

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add switcher
```

Or use it from the prebuilt package without copying:

```tsx
import { Switcher } from '@cascivo/react'
```

## Category

`navigation`

## States

- `default`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `items` | `SwitcherEntry[]` | yes | — | SwitcherLink ({ label, href, active?, icon? }) or divider ({ divider: true }) |
| `ariaLabel` | `string` | no | — | Alias of `label` — the same invisible accessible name under the catalog spelling. Neither is deprecated. Not rendered — screen readers only. |
| `label` | `string` | no | `Switch application` | Accessible name for the switcher list. Not rendered — screen readers only. |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |

## Examples

### App switcher

Place inside a HeaderPanel opened by a Grid action in ShellHeader

```tsx
<Switcher
  items={[
    { label: 'Console', href: '/console', active: true },
    { label: 'Billing', href: '/billing' },
    { divider: true },
    { label: 'Docs', href: 'https://docs.example.com' },
  ]}
/>
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-color-text`
- `--cascivo-color-bg-subtle`
- `--cascivo-color-accent`
- `--cascivo-color-accent-subtle`
- `--cascivo-color-border`
- `--cascivo-focus-ring`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `list`
- **Keyboard:** Tab, Enter

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

navigation, switcher, shell, console, app-switcher

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Tabs

Switch between related panels of content

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add tabs
```

Or use it from the prebuilt package without copying:

```tsx
import { Tabs } from '@cascivo/react'
```

## Category

`navigation`

## States

- `active`
- `inactive`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `defaultValue` | `string` | no | — | The initial value when uncontrolled. |
| `value` | `string` | no | — | The controlled value. |
| `onValueChange` | `(value: string) => void` | no | — | Called with the new value when it changes. |

## Examples

### Basic

```tsx
<Tabs defaultValue="account"><TabsList><TabsTrigger value="account">Account</TabsTrigger></TabsList><TabsContent value="account">…</TabsContent></Tabs>
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-accent`
- `--cascivo-color-text`
- `--cascivo-color-text-subtle`
- `--cascivo-color-border`
- `--cascivo-focus-ring`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `tablist`
- **Keyboard:** ArrowLeft, ArrowRight, Home, End

## Dependencies

- `@cascivo/core`

## Tags

navigation, tabs, sections

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Tag

Compact chip for labeling, categorizing, or filtering content

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add tag
```

Or use it from the prebuilt package without copying:

```tsx
import { Tag } from '@cascivo/react'
```

## Category

`display`

## Variants

- `default`
- `info`
- `success`
- `warning`
- `error`

## Sizes

- `sm`
- `md`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `variant` | `'default' \| 'info' \| 'success' \| 'warning' \| 'error'` | no | `default` | Severity tone. Accepts the catalog-wide `Tone` vocabulary (`neutral \| info \| success \| warning \| danger`) plus Tag's historical spellings (`default` → neutral, `error`/`destructive` → danger). |
| `size` | `'sm' \| 'md'` | no | `md` | Visual size of the component (e.g. 'sm', 'md', 'lg'). |
| `onDismiss` | `() => void` | no | — | When provided, renders a trailing remove button inside the chip |
| `dismissLabel` | `string` | no | `Remove` | Accessible label for the dismiss button. |

## Examples

### Default

```tsx
<Tag>Design</Tag>
```

### Success

```tsx
<Tag variant="success">Approved</Tag>
```

### Dismissible

Renders a trailing remove button labeled by dismissLabel

```tsx
<Tag onDismiss={() => removeFilter()}>Filter: Active</Tag>
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-color-bg-subtle`
- `--cascivo-color-text-subtle`
- `--cascivo-color-info`
- `--cascivo-color-info-subtle`
- `--cascivo-color-success`
- `--cascivo-color-success-subtle`
- `--cascivo-color-warning`
- `--cascivo-color-warning-subtle`
- `--cascivo-color-destructive`
- `--cascivo-color-destructive-subtle`
- `--cascivo-radius-badge`
- `--cascivo-focus-ring`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `none`
- **Keyboard:** Enter, Space

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

chip, label, filter, category

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# TagsInput

Free-form multi-value chip input

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add tags-input
```

Or use it from the prebuilt package without copying:

```tsx
import { TagsInput } from '@cascivo/react'
```

## Category

`inputs`

## States

- `idle`
- `focused`
- `disabled`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `value` | `string[]` | yes | — | The controlled value. |
| `onValueChange` | `(v: string[]) => void` | yes | — | Called with the new value when it changes. |
| `placeholder` | `string` | no | — | Placeholder text shown when the field is empty. |
| `validate` | `(tag: string) => boolean` | no | — | Returns whether a candidate tag is allowed. |
| `max` | `number` | no | — | Maximum allowed value. |
| `disabled` | `boolean` | no | `false` | When true, disables the control and removes it from the tab order. |
| `id` | `string` | no | — | Id for the **inner text input** — the focusable control, so a `<label for>` names the thing that actually takes focus. `Field` supplies this automatically. |
| `ariaLabel` | `string` | no | — | Invisible accessible name for the tag entry field. Use when no visible label names it; inside a `Field` it is not needed, as the Field label is wired through automatically. Not rendered — screen readers only. |
| `label` | `string` | no | — | Alias of `ariaLabel` — the same invisible accessible name under the other spelling. Not rendered. Not rendered — screen readers only. |

## Examples

### Basic

```tsx
<TagsInput value={['react', 'vue']} onValueChange={() => {}} placeholder="Add tag…" />
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-surface`
- `--cascivo-color-border`
- `--cascivo-color-accent`
- `--cascivo-color-destructive`
- `--cascivo-color-bg-subtle`
- `--cascivo-radius-input`
- `--cascivo-radius-full`
- `--cascivo-focus-ring`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `textbox`
- **Keyboard:** Enter, ,, Backspace

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

form, tags, chips, multi, input

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Terminal

An animated terminal that types out a script of commands and output — for demos, onboarding and agent transcripts

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add terminal
```

Or use it from the prebuilt package without copying:

```tsx
import { Terminal } from '@cascivo/react'
```

## Category

`display`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `lines` | `TerminalLine[]` | yes | — | The script. Each line has `text`, an optional `prefix` (e.g. `$`) and a `type` (`command \| output \| error \| comment`, default `output`). |
| `speed` | `number` | no | `3` | Characters typed per animation frame. |
| `loop` | `boolean` | no | `false` | Restart from the first line after the last one. |
| `onComplete` | `() => void` | no | — | Called each time the last line finishes typing. |
| `labels` | `{ label?: string }` | no | — | Overrides for the component’s user-visible strings (i18n) — `label` names the terminal for screen readers. |

## Object types

### `TerminalLine`

One line of the script.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `text` | `string` | yes | What the line says. |
| `prefix` | `string` | no | A prompt marker such as `$`, styled and not selectable. |
| `type` | `'command' \| 'output' \| 'error' \| 'comment'` | no | Colours the line. Defaults to `output`. |

## Examples

### Install transcript

```tsx
<Terminal
  lines={[
    { text: 'npx cascivo add button', prefix: '$', type: 'command' },
    { text: 'Added button to src/components.', type: 'output' },
    { text: '# done in 1.2s', type: 'comment' },
  ]}
/>
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-terminal-bg`
- `--cascivo-terminal-fg`
- `--cascivo-editor-bg`
- `--cascivo-editor-fg`
- `--cascivo-editor-border`
- `--cascivo-editor-syntax-keyword`
- `--cascivo-editor-syntax-string`
- `--cascivo-editor-syntax-comment`
- `--cascivo-color-destructive`
- `--cascivo-font-mono`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `group`

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

ai, terminal, cli, demo, typewriter, agent, transcript

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Text

Body text with size, weight, and muted variants

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add text
```

Or use it from the prebuilt package without copying:

```tsx
import { Text } from '@cascivo/react'
```

## Category

`display`

## Variants

- `normal`
- `medium`
- `semibold`

## Sizes

- `sm`
- `md`
- `lg`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `as` | `'p' \| 'span' \| 'div'` | no | `p` | `p` for a paragraph, `span` for inline text, `div` for a block that imposes no semantics of its own. |
| `size` | `'sm' \| 'md' \| 'lg'` | no | `md` | Visual size of the component (e.g. 'sm', 'md', 'lg'). |
| `weight` | `'normal' \| 'medium' \| 'semibold'` | no | `normal` | Font weight ('normal' \| 'medium' \| 'semibold'). |
| `muted` | `boolean` | no | `false` | When true, renders in a muted/subtle color. `Text` has no `tone` prop: `tone` is the severity vocabulary (Status, Badge, Timeline, SideNav); text emphasis is `muted`. |

## Examples

### Default

```tsx
<Text>Body copy reads at the base size.</Text>
```

### Muted helper

```tsx
<Text size="sm" muted>Secondary information</Text>
```

### Inline span

Use as="span" inside other flow content

```tsx
<Text as="span" weight="semibold">emphasis</Text>
```

### Icon beside text

Text renders a <p> by default, so a nested Text needs as="span" — a <p> inside a <p> is invalid HTML and the browser silently closes the outer one, breaking the layout.

```tsx
<Text>
  <CheckIcon aria-hidden />
  <Text as="span" weight="semibold">Deployed</Text>
</Text>
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-font-sans`
- `--cascivo-font-normal`
- `--cascivo-font-medium`
- `--cascivo-font-semibold`
- `--cascivo-leading-normal`
- `--cascivo-color-text`
- `--cascivo-color-text-subtle`
- `--cascivo-text-sm`
- `--cascivo-text-base`
- `--cascivo-text-lg`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `paragraph`

## Dependencies

- `@cascivo/core`

## Tags

typography, text, paragraph, body

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Textarea

Multi-line text input with optional label, hint, and error state

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add textarea
```

Or use it from the prebuilt package without copying:

```tsx
import { Textarea } from '@cascivo/react'
```

## Category

`inputs`

## States

- `idle`
- `focused`
- `error`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `label` | `string` | no | — | Text label for the control (standalone use). Omit it when wrapping the Textarea in a Field — the Field owns the label, and setting both double-labels the control. Rendered on screen. |
| `hint` | `string` | no | — | Supplementary hint text shown with the control. |
| `error` | `string` | no | — | Error message shown when the value is invalid. |
| `rows` | `number` | no | `4` | Number of visible text rows. |
| `resize` | `'none' \| 'vertical' \| 'both'` | no | `vertical` | Which directions the textarea can be resized ('none' \| 'vertical' \| 'both'). |
| `autosize` | `boolean` | no | `false` | Grow the control with its content instead of holding the fixed rows height. rows becomes the minimum and --cascivo-textarea-max-block-size (default 20lh) the ceiling. Pure CSS (field-sizing: content) — no measurement and no listener; where unsupported the fixed rows height is kept. |
| `disabled` | `boolean` | no | `false` | When true, disables the control and removes it from the tab order. |
| `ariaLabel` | `string` | no | — | Invisible accessible name, for when a visible element outside this component already labels it and `label` would render that text a second time. ⚠ `label` on this component is **visible**; `IconButton.label`/`Sparkline.label` are invisible names, which is the prior that costs adopters a duplicated label. The raw DOM `aria-label` still wins over this. Not rendered — screen readers only. |
| `ai` | `boolean` | no | `false` | AI presence: an AI-tinted border and a soft aura, marking a value AI produced or suggested. Visual only — put an AiBadge in the label so the provenance is also text, and clear `ai` once the person edits the value. |

## Examples

### With label

```tsx
<Textarea label="Message" placeholder="Type here…" />
```

### With error

```tsx
<Textarea label="Bio" error="Bio is required" />
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-color-surface`
- `--cascivo-color-border`
- `--cascivo-color-accent`
- `--cascivo-color-destructive`
- `--cascivo-radius-input`
- `--cascivo-focus-ring`
- `--cascivo-textarea-max-block-size`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `textbox`
- **Keyboard:** Tab, Shift+Tab

## Dependencies

- `@cascivo/core`

## Tags

form, text, multiline, ai

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Tile

A selectable card with radio (single) or checkbox (multi) semantics, toggled by click or keyboard

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add tile
```

Or use it from the prebuilt package without copying:

```tsx
import { Tile } from '@cascivo/react'
```

## Category

`inputs`

## Variants

- `single`
- `multi`

## States

- `default`
- `selected`
- `focus`
- `disabled`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `value` | `string` | yes | — | Identifies this tile within a group. |
| `selected` | `boolean` | no | — | Controlled selected state. |
| `defaultSelected` | `boolean` | no | — | Initial selected state for uncontrolled use. |
| `onSelect` | `(value: string) => void` | no | — | Called with this tile's value whenever it is toggled on (or off for multi). |
| `selectable` | `'single' \| 'multi'` | no | `single` | Single = radio semantics (toggle on); multi = checkbox semantics (toggle on/off). |
| `disabled` | `boolean` | no | — | When true, disables the control and removes it from the tab order. |
| `icon` | `React.ReactNode` | no | — | Optional leading icon/visual. |
| `asChild` | `boolean` | no | — | When true, renders the child element as the root via Slot, merging props (polymorphic rendering). |
| `children` | `React.ReactNode` | no | — | Content rendered inside the component. |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |

## Examples

### Single-select group

```tsx
<div role="radiogroup" aria-label="Plan">
  <Tile value="starter" selected={plan === 'starter'} onSelect={setPlan}>Starter</Tile>
  <Tile value="pro" selected={plan === 'pro'} onSelect={setPlan}>Pro</Tile>
</div>
```

### Multi-select with icon

Multi tiles toggle on and off like a checkbox.

```tsx
<Tile value="notifications" selectable="multi" icon={<BellIcon />} defaultSelected>
  Email notifications
</Tile>
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-accent-text`
- `--cascivo-color-bg`
- `--cascivo-color-border`
- `--cascivo-color-border-strong`
- `--cascivo-color-accent`
- `--cascivo-color-text`
- `--cascivo-color-text-muted`
- `--cascivo-radius-surface`
- `--cascivo-focus-ring`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `radio`
- **Keyboard:** Enter, Space

## Dependencies

- `@cascivo/core`

## Tags

inputs, tile, card, selectable, choice

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# TimePicker

Native time input wrapper with label, hint, error, and size variants

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add time-picker
```

Or use it from the prebuilt package without copying:

```tsx
import { TimePicker } from '@cascivo/react'
```

## Category

`inputs`

## Sizes

- `sm`
- `md`
- `lg`

## States

- `idle`
- `focused`
- `error`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `value` | `string` | no | — | Controlled value (HH:mm) |
| `defaultValue` | `string` | no | — | The initial value when uncontrolled. |
| `onValueChange` | `(value: string) => void` | no | — | Called with the new HH:MM time string when the value changes. |
| `min` | `string` | no | — | Minimum allowed value. |
| `max` | `string` | no | — | Maximum allowed value. |
| `step` | `number` | no | — | Increment between allowed values. |
| `label` | `string` | no | — | Text label for the control. Rendered on screen. |
| `hint` | `string` | no | — | Supplementary hint text shown with the control. |
| `error` | `string` | no | — | Error message shown when the value is invalid. |
| `size` | `'sm' \| 'md' \| 'lg'` | no | `'md'` | Visual size of the component (e.g. 'sm', 'md', 'lg'). |
| `disabled` | `boolean` | no | — | When true, disables the control and removes it from the tab order. |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |
| `ariaLabel` | `string` | no | — | Invisible accessible name, for when a visible element outside this component already labels it and `label` would render that text a second time. ⚠ `label` on this component is **visible**; `IconButton.label`/`Sparkline.label` are invisible names, which is the prior that costs adopters a duplicated label. The raw DOM `aria-label` still wins over this. Not rendered — screen readers only. |

## Examples

### Basic time picker

```tsx
<TimePicker label="Meeting time" onValueChange={(v) => console.log(v)} />
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-color-surface`
- `--cascivo-color-bg-subtle`
- `--cascivo-color-border`
- `--cascivo-color-border-strong`
- `--cascivo-color-text`
- `--cascivo-color-text-muted`
- `--cascivo-color-accent`
- `--cascivo-color-destructive`
- `--cascivo-radius-input`
- `--cascivo-radius-md`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `textbox`
- **Keyboard:** Tab

## Dependencies

- `@cascivo/core`

## Tags

time, input, form

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Timeline

Ordered sequence of events with status markers and a connector line

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add timeline
```

Or use it from the prebuilt package without copying:

```tsx
import { Timeline } from '@cascivo/react'
```

## Category

`display`

## Variants

- `vertical`
- `horizontal`

## States

- `complete`
- `current`
- `upcoming`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `items` | `{ id: string; title: ReactNode; description?: ReactNode; time?: string; icon?: ReactNode; status?: "complete" \| "current" \| "upcoming"; tone?: "neutral" \| "info" \| "success" \| "warning" \| "danger" }[]` | yes | — | The items to render. |
| `orientation` | `'vertical' \| 'horizontal'` | no | `vertical` | Axis the entries flow along: `vertical` stacks them down the page (the usual reading order), `horizontal` runs them across. |

## Examples

### Vertical timeline with statuses

```tsx
<Timeline
  items={[
    { id: '1', title: 'Order placed', time: '09:00', status: 'complete' },
    { id: '2', title: 'Shipped', time: '12:30', status: 'current' },
    { id: '3', title: 'Delivered', status: 'upcoming' },
  ]}
/>
```

### Activity feed coloured by entry type

In a feed every entry is equally done, so `tone` — not `status` — is what separates them. Keep the meaning in the text too; colour alone is not perceivable.

```tsx
<Timeline
  items={[
    { id: '1', title: 'p99 latency 4.2s', description: 'ALERT · monitor', time: '14:28', tone: 'danger' },
    { id: '2', title: 'Rolling back deploy 4821', description: 'NOTE · bo', time: '14:49', tone: 'neutral' },
    { id: '3', title: 'Status changed to monitoring', description: 'STATUS · ana', time: '15:12', tone: 'info' },
    { id: '4', title: 'Merged 2 edits from kim', description: 'MERGE · sync', time: '15:14', tone: 'success' },
  ]}
/>
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-color-border`
- `--cascivo-color-border-strong`
- `--cascivo-color-surface`
- `--cascivo-color-success`
- `--cascivo-color-primary`
- `--cascivo-color-info`
- `--cascivo-color-warning`
- `--cascivo-color-destructive`
- `--cascivo-radius-full`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `list`

## Dependencies

- `@cascivo/core`

## Tags

timeline, steps, history, progress, events

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Toast

Transient notification surfaced via the useToast hook

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add toast
```

Or use it from the prebuilt package without copying:

```tsx
import { ToastProvider, useToast } from '@cascivo/react'
```

## Category

`overlay`

## Variants

- `default`
- `success`
- `warning`
- `destructive`

## States

- `visible`
- `dismissing`
- `gone`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `title` | `string` | yes | — | Title text for the component. |
| `description` | `string` | no | — | Supporting description text. |
| `variant` | `'default' \| 'success' \| 'warning' \| 'destructive'` | no | `default` | Severity tone: `default` (neutral), `success`, `warning` or `destructive`. Sets the icon and the accent colour. Unlike Badge/Tag/Notification this is a private union, not `ToneInput` — the canonical `danger`/`neutral` spellings are not accepted here. |
| `duration` | `number` | no | `5000` | How long (ms) the toast stays visible before auto-dismiss. |

## Examples

### Trigger

```tsx
const { toast } = useToast()
toast({ title: "Saved", variant: "success" })
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-surface-overlay`
- `--cascivo-color-success`
- `--cascivo-color-warning`
- `--cascivo-color-destructive`
- `--cascivo-radius-md`
- `--cascivo-z-toast`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `status`
- **Keyboard:** Tab

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

overlay, notification, feedback

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Toc

Table of contents with scroll-spy highlighting of the active section

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add toc
```

Or use it from the prebuilt package without copying:

```tsx
import { Toc } from '@cascivo/react'
```

## Category

`navigation`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `items` | `{ id: string; label: string; level?: number }[]` | yes | — | The items to render. |
| `activeId` | `string` | no | — | Controlled active item id; disables built-in scroll-spy when set |
| `onActiveChange` | `(id: string) => void` | no | — | Called with the id of the active section when it changes. |
| `labels` | `{ nav?: string }` | no | — | Overrides for the component’s user-visible strings (i18n). |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |

## Examples

### Basic

```tsx
<Toc items={[{ id: 'intro', label: 'Introduction' }, { id: 'usage', label: 'Usage' }, { id: 'api', label: 'API', level: 3 }]} />
```

### Controlled active item

Pass activeId to drive the highlight yourself; scroll-spy is disabled.

```tsx
<Toc activeId="usage" items={[{ id: 'intro', label: 'Introduction' }, { id: 'usage', label: 'Usage' }]} />
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-color-accent-text`
- `--cascivo-font-sans`
- `--cascivo-color-text`
- `--cascivo-color-text-muted`
- `--cascivo-color-accent`
- `--cascivo-focus-ring`
- `--cascivo-target-min-coarse`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `navigation`
- **Keyboard:** Tab, Enter

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

toc, table-of-contents, navigation, scroll-spy, anchor

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Toggle

On/off switch built as an accessible button

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add toggle
```

Or use it from the prebuilt package without copying:

```tsx
import { Toggle } from '@cascivo/react'
```

## Category

`inputs`

## Sizes

- `sm`
- `md`

## States

- `off`
- `on`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `checked` | `boolean` | no | — | Whether the control is checked (controlled). |
| `defaultChecked` | `boolean` | no | `false` | Whether the control is checked on first render (uncontrolled). |
| `onValueChange` | `(checked: boolean) => void` | no | — | Called with the new checked state when the switch is toggled. |
| `label` | `string` | no | — | Visible text label beside the switch; it also becomes the accessible name. When a heading already labels the control, omit this and pass aria-label instead to avoid duplicated text. Rendered on screen. |
| `size` | `'sm' \| 'md'` | no | `md` | Visual size of the component (e.g. 'sm', 'md', 'lg'). |
| `disabled` | `boolean` | no | `false` | When true, disables the control and removes it from the tab order. |
| `ariaLabel` | `string` | no | — | Invisible accessible name, for when a visible element outside this component already labels it and `label` would render that text a second time. ⚠ `label` on this component is **visible**; `IconButton.label`/`Sparkline.label` are invisible names, which is the prior that costs adopters a duplicated label. The raw DOM `aria-label` still wins over this. Not rendered — screen readers only. |

## Examples

### Uncontrolled

```tsx
<Toggle label="Notifications" defaultChecked />
```

### Controlled

```tsx
<Toggle checked={enabled} onValueChange={setEnabled} label="Dark mode" />
```

## Client JavaScript

Enhancement only. The component still does its job with JavaScript disabled — the server-rendered HTML is correct and nothing is unreachable; client JS adds polish on top.

## Design tokens

- `--cascivo-color-accent`
- `--cascivo-color-border-strong`
- `--cascivo-color-surface`
- `--cascivo-radius-full`
- `--cascivo-focus-ring`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `switch`
- **Keyboard:** Space, Enter

## Dependencies

- `@cascivo/core`

## Tags

switch, form, boolean

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# ToggleGroup

A set of toggle buttons for single or multiple selection

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add toggle-group
```

Or use it from the prebuilt package without copying:

```tsx
import { ToggleGroup } from '@cascivo/react'
```

## Category

`inputs`

## Variants

- `single`
- `multiple`

## Sizes

- `sm`
- `md`
- `lg`

## States

- `on`
- `off`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `type` | `'single' \| 'multiple'` | yes | — | Whether one or multiple items can be pressed at once ('single' \| 'multiple'). |
| `value` | `string \| string[]` | no | — | The controlled value. |
| `defaultValue` | `string \| string[]` | no | — | The initial value when uncontrolled. |
| `onValueChange` | `(value: string \| string[]) => void` | no | — | Called with the new value when it changes. |
| `items` | `{ value: string; label?: string; icon?: React.ReactNode; disabled?: boolean }[]` | yes | — | The items to render. |
| `orientation` | `'horizontal' \| 'vertical'` | no | `horizontal` | Axis the options flow along: `horizontal` for a segmented row, `vertical` for a stacked column. |
| `size` | `'sm' \| 'md' \| 'lg'` | no | `md` | Visual size of the component (e.g. 'sm', 'md', 'lg'). |
| `disabled` | `boolean` | no | `false` | When true, disables the control and removes it from the tab order. |

## Examples

### Single selection

```tsx
<ToggleGroup type="single" defaultValue="left" items={[{ value: "left", label: "Left" }, { value: "center", label: "Center" }, { value: "right", label: "Right" }]} />
```

### Multiple selection

```tsx
<ToggleGroup type="multiple" defaultValue={["bold"]} items={[{ value: "bold", label: "Bold" }, { value: "italic", label: "Italic" }]} />
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-control-height-sm`
- `--cascivo-control-height-md`
- `--cascivo-control-height-lg`
- `--cascivo-radius-control`
- `--cascivo-radius-item`
- `--cascivo-color-bg-subtle`
- `--cascivo-color-surface`
- `--cascivo-color-text`
- `--cascivo-shadow-sm`
- `--cascivo-focus-ring`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `radiogroup`
- **Keyboard:** ArrowRight, ArrowLeft, ArrowUp, ArrowDown, Home, End, Enter, Space

## Dependencies

- `@cascivo/core`

## Tags

selection, segmented, toolbar, choice

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Toggletip

A click-triggered info popover for supplementary, selectable content

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add toggletip
```

Or use it from the prebuilt package without copying:

```tsx
import { Toggletip } from '@cascivo/react'
```

## Category

`overlay`

## States

- `open`
- `closed`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `trigger` | `ReactNode` | yes | — | Trigger content, rendered inside a button (e.g. an info icon) |
| `children` | `ReactNode` | yes | — | The popover content — interactive and selectable |
| `placement` | `'top' \| 'bottom' \| 'left' \| 'right' \| 'top-start' \| 'top-end' \| 'bottom-start' \| 'bottom-end'` | no | `'top'` | Side and alignment of the bubble relative to the trigger |
| `defaultOpen` | `boolean` | no | `false` | Initial open state when uncontrolled |
| `open` | `boolean` | no | — | Controlled open state |
| `onOpenChange` | `(open: boolean) => void` | no | — | Called whenever the open state should change |
| `labels` | `{ label?: string }` | no | — | Override the trigger accessible name |

## Examples

### Info toggletip

An info button that reveals supplementary text on click

```tsx
<Toggletip trigger={<InfoIcon />}>
  Your password must contain at least 12 characters.
</Toggletip>
```

### Controlled

Drive the open state from the parent

```tsx
<Toggletip
  trigger={<InfoIcon />}
  open={open}
  onOpenChange={setOpen}
  placement="bottom-start"
>
  <a href="/docs">Learn more</a>
</Toggletip>
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-surface`
- `--cascivo-color-border`
- `--cascivo-color-text`
- `--cascivo-color-bg-subtle`
- `--cascivo-radius-control`
- `--cascivo-radius-overlay`
- `--cascivo-shadow-md`
- `--cascivo-focus-ring`
- `--cascivo-motion-enter`
- `--cascivo-z-tooltip`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `status`
- **Keyboard:** Enter, Space, Escape

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

overlay, toggletip, info, popover, floating

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# ToolCall

Card for one AI tool invocation — the tool name, its lifecycle status, collapsible input/output, and approval actions

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add tool-call
```

Or use it from the prebuilt package without copying:

```tsx
import { ToolCall } from '@cascivo/react'
```

## Category

`display`

## States

- `pending`
- `running`
- `awaiting-approval`
- `complete`
- `error`
- `denied`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `name` | `string` | yes | — | The tool’s name, shown in monospace (e.g. `search_web`). |
| `status` | `'pending' \| 'running' \| 'awaiting-approval' \| 'complete' \| 'error' \| 'denied'` | yes | — | Lifecycle, matching the AI SDK tool-part states: `pending` (input streaming), `running`, `awaiting-approval`, `complete`, `error`, `denied`. |
| `input` | `ReactNode` | no | — | The call’s arguments. A string (e.g. `JSON.stringify(args, null, 2)`) renders preformatted; any other node renders as given. |
| `output` | `ReactNode` | no | — | The tool’s result — a string renders preformatted, a node as given. |
| `error` | `ReactNode` | no | — | Why the call failed. The panel opens itself when status is `error`. |
| `actions` | `ReactNode` | no | — | Rich slot below the card — typically Approve / Deny buttons while `awaiting-approval`. Always visible, never inside the collapsible panel. |
| `labels` | `{ pending?: string; running?: string; awaitingApproval?: string; complete?: string; error?: string; denied?: string; input?: string; output?: string; errorHeading?: string }` | no | — | Overrides for the component’s user-visible strings (i18n). |

## Examples

### Running

```tsx
<ToolCall name="search_web" status="running" input={'{ "query": "cascivo pricing" }'} />
```

### Complete

```tsx
<ToolCall
  name="get_weather"
  status="complete"
  input={'{ "city": "Berlin" }'}
  output={'{ "tempC": 18, "sky": "clear" }'}
/>
```

### Awaiting approval

```tsx
<ToolCall
  name="send_email"
  status="awaiting-approval"
  input={'{ "to": "team@example.com", "subject": "Weekly report" }'}
  actions={
    <>
      <Button variant="ghost" size="sm">Deny</Button>
      <Button size="sm">Approve</Button>
    </>
  }
/>
```

### Error

```tsx
<ToolCall name="fetch_page" status="error" error="The page returned 404." />
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-color-ai`
- `--cascivo-color-surface`
- `--cascivo-color-border`
- `--cascivo-color-bg-subtle`
- `--cascivo-color-text-muted`
- `--cascivo-color-warning`
- `--cascivo-color-destructive`
- `--cascivo-radius-surface`
- `--cascivo-font-mono`
- `--cascivo-focus-ring`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `group`
- **Keyboard:** Tab, Enter, Space

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

ai, agent, tool, function-call, approval, mcp, status

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# Tooltip

Contextual label shown on hover or focus

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add tooltip
```

Or use it from the prebuilt package without copying:

```tsx
import { Tooltip } from '@cascivo/react'
```

## Category

`overlay`

## States

- `hidden`
- `visible`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `content` | `ReactNode` | yes | — | The tooltip content shown on hover/focus. |
| `placement` | `'top' \| 'right' \| 'bottom' \| 'left'` | no | `top` | Side of the trigger the tip opens on: `top`, `right`, `bottom` or `left`. |
| `children` | `ReactElement` | yes | — | Content rendered inside the component. |
| `delay` | `number` | no | `200` | Milliseconds to wait before showing |

## Examples

### Basic

```tsx
<Tooltip content="Copy to clipboard"><Button>Copy</Button></Tooltip>
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-text`
- `--cascivo-color-text-on-accent`
- `--cascivo-radius-sm`
- `--cascivo-z-tooltip`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `tooltip`
- **Keyboard:** Tab, Escape

## Dependencies

- `@cascivo/core`

## Tags

overlay, hint, popover

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# TreeView

Hierarchical, expandable tree of nodes with keyboard navigation and selection

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add tree-view
```

Or use it from the prebuilt package without copying:

```tsx
import { TreeView } from '@cascivo/react'
```

## Category

`display`

## Variants

- `single`
- `multi`

## States

- `default`
- `expanded`
- `collapsed`
- `selected`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `label` | `string` | no | — | Alias of `ariaLabel` — the same invisible accessible name under the other spelling. Neither is deprecated. Not rendered — screen readers only. |
| `ariaLabel` | `string` | no | — | Invisible accessible name. The catalog convention; `aria-label` is accepted as an alias for the DOM spelling. Not rendered — screen readers only. |
| `aria-label` | `string` | no | — | Accessible label for the tree. |
| `items` | `{ id: string; label: ReactNode; icon?: ReactNode; children?: TreeNode[] }[]` | yes | — | The items to render. |
| `selectionMode` | `'single' \| 'multi'` | no | `single` | Whether one or multiple nodes can be selected ('single' \| 'multi'). |
| `selected` | `string \| string[]` | no | — | The controlled selected node id(s). |
| `defaultSelected` | `string \| string[]` | no | — | The initially selected node id(s) when uncontrolled. |
| `onSelectChange` | `(selected: string \| string[]) => void` | no | — | Called with the new selection when it changes. |
| `onValueChange` | `(selected: string \| string[]) => void` | no | — | Called with the new selection. Preferred over `onSelectChange`, which is the catalog’s only value-carrying handler not named onValueChange and is deprecated. |
| `expanded` | `string[]` | no | — | The controlled set of expanded node ids. |
| `defaultExpanded` | `string[]` | no | — | The initially expanded node ids when uncontrolled. |
| `onExpandedChange` | `(expanded: string[]) => void` | no | — | Called with the new expanded set when it changes. |

## Examples

### Single select

```tsx
<TreeView defaultExpanded={["src"]} items={[{ id: "src", label: "src", children: [{ id: "index", label: "index.ts" }] }]} />
```

### Multi select

```tsx
<TreeView selectionMode="multi" items={nodes} onSelectChange={(ids) => set(ids)} />
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-tree-indent`
- `--cascivo-color-border`
- `--cascivo-color-bg-subtle`
- `--cascivo-color-text`
- `--cascivo-color-text-subtle`
- `--cascivo-radius-control`
- `--cascivo-focus-ring`
- `--cascivo-duration-200`
- `--cascivo-ease-out`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `tree`
- **Keyboard:** *, ArrowDown, ArrowUp, ArrowRight, ArrowLeft, Home, End, Enter, Space, Typeahead

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

display, tree, hierarchy, navigation, files

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# TypingIndicator

Three bouncing dots that hold a chat message slot while an assistant (or a person) is composing a reply

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add typing-indicator
```

Or use it from the prebuilt package without copying:

```tsx
import { TypingIndicator } from '@cascivo/react'
```

## Category

`feedback`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `ariaLabel` | `string` | no | `Assistant is typing` | Accessible name announced by the status region. Not rendered — screen readers only. |
| `label` | `string` | no | — | Alias of `ariaLabel` — the same invisible accessible name. Neither is deprecated. Not rendered — screen readers only. |

## Examples

### Default

```tsx
<TypingIndicator />
```

### In a chat bubble

```tsx
<ChatBubble name="Assistant"><TypingIndicator /></ChatBubble>
```

### A person typing

```tsx
<TypingIndicator ariaLabel="Ada is typing" />
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-typing-indicator-color`
- `--cascivo-color-text-muted`
- `--cascivo-radius-full`
- `--cascivo-space-1`
- `--cascivo-space-2`
- `--cascivo-duration-loop-fast`
- `--cascivo-ease-in-out`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `status`

## Dependencies

- `@cascivo/core`
- `@cascivo/i18n`

## Tags

ai, chat, typing, loading, dots, thinking

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# User

Identity composite: an avatar with a name, description, and optional action slot

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add user
```

Or use it from the prebuilt package without copying:

```tsx
import { User } from '@cascivo/react'
```

## Category

`display`

## States

- `default`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `name` | `ReactNode` | yes | — | The user’s display name. |
| `description` | `ReactNode` | no | — | Supporting description text. |
| `avatarProps` | `AvatarProps` | no | — | Forwarded to the composed <Avatar> |

## Examples

### Basic

```tsx
<User name="Jane Doe" description="jane@acme.com" avatarProps={{ src: "/jane.jpg", alt: "Jane Doe" }} />
```

### With action

```tsx
<User name="Jane Doe" description="Admin"><IconButton aria-label="More" /></User>
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Design tokens

- `--cascivo-color-text`
- `--cascivo-color-text-muted`
- `--cascivo-space-3`
- `--cascivo-text-sm`
- `--cascivo-text-xs`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `group`

## Dependencies

- `@cascivo/core`

## Tags

user, avatar, identity, display

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# VirtualList

Renders only the rows inside the viewport, so list length costs no extra DOM

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add virtual-list
```

Or use it from the prebuilt package without copying:

```tsx
import { VirtualList } from '@cascivo/react'
```

## Category

`display`

## States

- `default`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `items` | `Item[]` | yes | — | The full collection; only the visible window is rendered |
| `itemHeight` | `number` | yes | — | Fixed row height in px — every row must be this tall |
| `height` | `number` | yes | — | Height of the scrolling viewport, in px — not a CSS length, because the visible row count is computed from it |
| `renderItem` | `(item: Item, index: number) => React.ReactNode` | yes | — | Renders one row |
| `overscan` | `number` | no | `3` | Extra rows rendered above and below the visible window, to cover fast scrolling. |
| `label` | `string` | no | — | Alias of `ariaLabel` — the same invisible accessible name under the other spelling. Neither is deprecated. Not rendered — screen readers only. |
| `ariaLabel` | `string` | no | — | Accessible label for the list; label it when the list stands alone. Not rendered — screen readers only. |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |

## Examples

### Basic

Ten thousand rows cost the same DOM as ten.

```tsx
<VirtualList
  items={Array.from({ length: 10000 }, (_, i) => i)}
  itemHeight={40}
  height={320}
  ariaLabel="Results"
  renderItem={(n) => <span>Row {n + 1}</span>}
/>
```

### Smoother fast scrolling

A larger overscan trades DOM nodes for fewer blank frames when flinging.

```tsx
<VirtualList items={rows} itemHeight={40} height={320} overscan={10} renderItem={renderRow} />
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-accent`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `list`
- **Keyboard:** Tab, ArrowUp, ArrowDown, PageUp, PageDown, Home, End

## Dependencies

- `@cascivo/core`

## Tags

display, virtual, virtualization, list, performance, scroll

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# VisuallyHidden

Hides content visually while keeping it available to screen readers

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add visually-hidden
```

Or use it from the prebuilt package without copying:

```tsx
import { VisuallyHidden } from '@cascivo/react'
```

## Category

`display`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `children` | `ReactNode` | yes | — | Content announced by assistive technology but not painted |

## Examples

### Icon button label

Gives an icon-only control an accessible name

```tsx
<button type="button"><CloseIcon /><VisuallyHidden>Close dialog</VisuallyHidden></button>
```

### Table context

```tsx
<th>Price <VisuallyHidden>(in euros)</VisuallyHidden></th>
```

## Client JavaScript

None. Renders complete and correct with JavaScript disabled, and can be rendered directly from a React Server Component without hydrating.

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `none`

## Dependencies

- `@cascivo/core`

## Tags

accessibility, screen-reader, sr-only, hidden

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

---

# WheelPicker

iOS-style drum picker — a column of options that scrolls and snaps to a selection

## Install

Copy-paste the source (you own and can edit it):

```bash
npx cascivo add wheel-picker
```

Or use it from the prebuilt package without copying:

```tsx
import { WheelPicker } from '@cascivo/react'
```

## Category

`inputs`

## States

- `idle`
- `focused`
- `scrolling`

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `options` | `WheelPickerOption[]` | yes | — | The rows of the wheel, in order |
| `value` | `string` | yes | — | The selected option value; the component is controlled |
| `onValueChange` | `(value: string) => void` | yes | — | Called with the new value when the wheel settles or a key moves the selection |
| `visibleCount` | `number` | no | `5` | How many rows are visible. Odd numbers keep the selection centred. |
| `itemHeight` | `number` | no | `36` | Row height in px. |
| `label` | `string` | no | — | Alias of `ariaLabel` — the same invisible accessible name under the other spelling. Neither is deprecated. Not rendered — screen readers only. |
| `ariaLabel` | `string` | no | — | Accessible label for the wheel — required when it has no visible label. Not rendered — screen readers only. |
| `className` | `string` | no | — | Additional CSS class names merged onto the root element. |

## Object types

### `WheelPickerOption`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `value` | `string` | yes | Value reported on change |
| `label` | `string` | yes | Visible row text |

## Examples

### Basic

Controlled — the caller owns the value.

```tsx
<WheelPicker
  ariaLabel="Hour"
  value={hour}
  onValueChange={setHour}
  options={[
    { value: '09', label: '09' },
    { value: '10', label: '10' },
    { value: '11', label: '11' },
  ]}
/>
```

### Taller wheel

Shows more rows around the selection.

```tsx
<WheelPicker ariaLabel="Minute" value={minute} onValueChange={setMinute} options={minutes} visibleCount={7} />
```

### Several columns

Compose one wheel per field; each column is independently operable.

```tsx
<Flex gap="0">
  <WheelPicker ariaLabel="Hour" value={hour} onValueChange={setHour} options={hours} />
  <WheelPicker ariaLabel="Minute" value={minute} onValueChange={setMinute} options={minutes} />
</Flex>
```

## Client JavaScript

Required. The component's primary job needs client JavaScript, so do not render it from a Server Component without hydrating — even if some or all of its markup appears in the server HTML.

## Design tokens

- `--cascivo-color-foreground`
- `--cascivo-color-text-muted`
- `--cascivo-border-subtle`
- `--cascivo-text-ui`
- `--cascivo-font-semibold`
- `--cascivo-radius-md`
- `--cascivo-ring-width`
- `--cascivo-ring-color`

## Accessibility

- **WCAG level:** 2.2-AA
- **ARIA role:** `listbox`
- **Keyboard:** ArrowUp, ArrowDown, Home, End, PageUp, PageDown, Tab

## Dependencies

- `@cascivo/core`

## Tags

inputs, picker, wheel, drum, scroll-snap, mobile, ios

---

_Generated from registry v1.9.0 on 2026-10-09. Docs track `main`; compare with https://cascivo.com/registry.json `.version`._

_Generated: 2026-10-09 from registry v1.9.0_