# Zen

> React components in dark glass: translucent surfaces, hairline borders that catch a pointer light, one accent colour. Tailwind v4, no runtime dependencies.

## Installation

```sh
pnpm add @rinzai/zen
```

React 19 is the only peer dependency.

**Using Tailwind CSS v4?** Add Zen's theme after Tailwind in your stylesheet. Your one Tailwind build then generates everything Zen's components use:

```css
@import 'tailwindcss';
@import '@rinzai/zen/tailwind.css';
```

**Not using Tailwind?** Import the complete stylesheet once, near the root of your app. It includes the default theme:

```js
import '@rinzai/zen/css';
```

Zen never styles your own elements. For its page setup (the background showing through), heading scale, inline code and quiet scrollbars, also add the optional base:

```css
@import '@rinzai/zen/base.css';
```

The look is set in [Geist](https://vercel.com/font); load it however you like.

## Usage

```tsx
import { Backdrop, Button, Card, CardHeader, CardTitle } from '@rinzai/zen';

export default function App() {
    return (
        <>
            <Backdrop />
            <Card>
                <CardHeader>
                    <CardTitle>Budget</CardTitle>
                </CardHeader>
                <Button>Save changes</Button>
            </Card>
        </>
    );
}
```

## Props

Every component takes `className`, and a class you pass always overrides the component's default. Other props (`id`, `aria-*`, `data-*`, handlers) and `ref` reach its element, and parts that render a link or button take `asChild` to use your own (a router's Link, say).

Zen exports no icons. Use any icon set (the examples use [Heroicons](https://heroicons.com)) and pass icons in as elements, such as `icon={<HomeIcon />}`.

## Values and forms

Controls report changes with `onValueChange` (`onCheckedChange` for Checkbox and Toggle). Pass `value` to control one, or `defaultValue` to let it keep its own. Give a control a `name` and it's submitted with its form, the custom ones (Combobox, the date pickers, MoneyInput, ColorPicker, TagInput…) included, and goes back to its first value when the form is reset.

## Languages and right to left

```tsx
import { LocaleProvider } from '@rinzai/zen';

<LocaleProvider locale="fr-FR" messages={{ clear: 'Effacer', noResults: 'Aucun résultat' }}>
    <App />
</LocaleProvider>;
```

The locale formats dates, numbers and money, and sets the week's first day. `messages` replaces any of the words Zen shows or announces (`ENGLISH` lists them all); the rest stay English. With `dir="rtl"` on the page or any element above, layout, arrow keys and chevrons mirror.

## Theming

Dark is the default. Add the `light` class (or `data-theme="light"`) for the light palette. Colours are OKLCH `L C H` triplets; override any token in your own CSS:

```css
:root {
    --primary: 0.72 0.13 200; /* teal instead of violet */
    --glow: 0.7 0.13 200;
}
```

Or generate a whole theme at runtime:

```ts
import { applyPreset, applyTheme, DEFAULT_THEME } from '@rinzai/zen';

applyTheme(applyPreset(DEFAULT_THEME, 'ocean'));
```

## Overlays

For a page composited over something else, such as an OBS browser source, which never gets a pointer:

```html
<html data-zen-glow="ambient" data-zen-page="transparent"></html>
```

`data-zen-glow="ambient"` sends the edge light round each glowing border by itself (on any element, it does so for what's inside). `data-zen-page="transparent"` paints nothing behind the content; it needs the base stylesheet.

## Browser support

Chrome and Edge 114+, Safari 17+ and Firefox 128+: the versions with the native Popover API that popups, menus and toasts are built on, and with what Tailwind v4 needs.

- **Popups** are placed with CSS anchor positioning where the browser has it (Chrome 129+, Safari 26+, recent Firefox). Elsewhere Zen places them itself, the same way.
- **Glass** is blurred live where there's a GPU and a mouse. On touch screens, without hardware acceleration, and with the OS's "reduce transparency", surfaces are solid instead.
- **Motion** such as entry animations is left out where a browser lacks it, and for anyone who prefers reduced motion.

In a project with Zen installed, the same pages are in node_modules/@rinzai/zen/dist/docs, for the installed version. All of them in one file: https://zen.rinzai.dev/llms-full.txt. Showcase apps: a budget app at https://zen.rinzai.dev/showcase/ and a music player at https://zen.rinzai.dev/showcase/music/.

## Components

- [Accordion](https://zen.rinzai.dev/docs/accordion.md): Sections under headings that open one at a time, or several: questions and answers, or groups of settings.
- [Alert](https://zen.rinzai.dev/docs/alert.md): A notice, warning or failure beside what it is about: a tinted box, or a plain line in a form or card.
- [Animated Number](https://zen.rinzai.dev/docs/animated-number.md): Numbers and amounts that count smoothly to each new value.
- [Avatar](https://zen.rinzai.dev/docs/avatar.md): A round picture, or the name's initial on the glowing accent. With an in-browser crop for uploads.
- [Backdrop](https://zen.rinzai.dev/docs/backdrop.md): The page background: aurora glows over contours or dots, and a light that follows the pointer and catches card edges, or drifts round them by itself on pages with no pointer.
- [Badge](https://zen.rinzai.dev/docs/badge.md): A small label for status, counts and tags.
- [Breadcrumbs](https://zen.rinzai.dev/docs/breadcrumbs.md): Where a page sits: its parents as links, then the page itself. Works with any router.
- [Button](https://zen.rinzai.dev/docs/button.md): Actions, from the one glowing primary action to quiet ghost buttons.
- [Button Group](https://zen.rinzai.dev/docs/button-group.md): Buttons joined into one, rounded only at the ends: a split button, or Previous, Today and Next.
- [Calendar](https://zen.rinzai.dev/docs/calendar.md): A month grid to pick a date or a range, fully keyboard-driven, with limits, blocked days and a year view to jump far.
- [Calendar Heatmap](https://zen.rinzai.dev/docs/calendar-heatmap.md): A month of days shaded by their value, like spending per day.
- [Canvas](https://zen.rinzai.dev/docs/canvas.md): A fixed-size surface where items sit anywhere, like the cards of a stream overlay: drag, resize and select several, by pointer, touch or keyboard, with snapping, a grid, undo and a fit-to-width scale.
- [Card](https://zen.rinzai.dev/docs/card.md): Glass panels for grouping content, and stats for single figures.
- [Carousel](https://zen.rinzai.dev/docs/carousel.md): Slides in a row that snap as you swipe or scroll, with glass buttons and dots that light the current one beneath, and the arrow keys. Native scrolling, so it follows the finger exactly.
- [Chart](https://zen.rinzai.dev/docs/chart.md): Areas, lines and bars on one axis, a donut and an allocation bar: plain SVG that draws itself in, with a crosshair tooltip, keyboard reading, a legend and a table for screen readers.
- [Checkbox](https://zen.rinzai.dev/docs/checkbox.md): A native checkbox whose tick draws itself in, with a label, a description and a mixed state.
- [Chip](https://zen.rinzai.dev/docs/chip.md): Small pressable buttons for quick picks beside a field, like common tenures.
- [Code Block](https://zen.rinzai.dev/docs/code-block.md): Code with a copy button; bring your own highlighter for colours. The copy button runs on useCopyToClipboard, which you can use for copy buttons anywhere.
- [Code Input](https://zen.rinzai.dev/docs/code-input.md): A one-time code, a box per character, that types, pastes and autofills from a text message like any field.
- [Collapse](https://zen.rinzai.dev/docs/collapse.md): Shows as many items as fit on one line, and the rest behind "+N".
- [Color Picker](https://zen.rinzai.dev/docs/color-picker.md): Pick a colour by eye or by hex: a saturation and brightness area, hue and opacity, and your own swatches. With hexToOklch to give a colour to the theme engine.
- [Combobox](https://zen.rinzai.dev/docs/combobox.md): Search and pick one or several items of any shape, composed from parts: field, panel, search, a virtualized list, empty and create rows.
- [Command Palette](https://zen.rinzai.dev/docs/command-palette.md): Search everything and act on it from the keyboard: a field over a list that narrows as you type, opened with ⌘K.
- [Date Picker](https://zen.rinzai.dev/docs/date-picker.md): A field that opens a calendar: one date, or a range previewed as you point. Dates are "YYYY-MM-DD" strings, so they never shift with time zones.
- [Dialog](https://zen.rinzai.dev/docs/dialog.md): Modal dialogs on the native <dialog> element, sheets that slide in from an edge, and a confirmation for destructive actions.
- [Disclosure](https://zen.rinzai.dev/docs/disclosure.md): A button that shows and hides a section, like finished goals under a list.
- [Editable Cell](https://zen.rinzai.dev/docs/editable-cell.md): A value edited in place: shows the value, swaps in any editor on click or Enter.
- [Empty State](https://zen.rinzai.dev/docs/empty-state.md): What a list or page shows when there's nothing in it yet, and the action that fills it.
- [Field](https://zen.rinzai.dev/docs/field.md): A label, hint and error wired to their control for screen readers, and messages for a whole form.
- [File Drop](https://zen.rinzai.dev/docs/file-drop.md): Somewhere to drop files, or click to choose them, that lights up as files are dragged over it.
- [Filter Bar](https://zen.rinzai.dev/docs/filter-bar.md): The filters in effect, each removed with its ×, and Clear all.
- [Header](https://zen.rinzai.dev/docs/header.md): A sticky glass bar across the top of the page.
- [Hover Card](https://zen.rinzai.dev/docs/hover-card.md): A preview of what a link points to, like a person or an account: a glass card once the pointer rests on the link, or while it has keyboard focus.
- [Icon Picker](https://zen.rinzai.dev/docs/icon-picker.md): An icon and a colour for something, like a spending category, from a grid in a popover.
- [Input](https://zen.rinzai.dev/docs/input.md): Text fields in faint glass that glow on focus.
- [Input Group](https://zen.rinzai.dev/docs/input-group.md): A field with slots: put symbols, icons, units, buttons or menus before and after the input.
- [Inset](https://zen.rinzai.dev/docs/inset.md): A faint box set into a card: a tile for one figure, or a bordered panel for a result, tinted for good or bad news.
- [Kbd](https://zen.rinzai.dev/docs/kbd.md): Keys on the keyboard, for shortcuts in hints and tooltips.
- [Keypad](https://zen.rinzai.dev/docs/keypad.md): A number pad for typing an amount on a phone.
- [Load More](https://zen.rinzai.dev/docs/load-more.md): The end of a long list that has more: loads the next page when it scrolls into view, or on a press.
- [Locale Provider](https://zen.rinzai.dev/docs/locale-provider.md): The language for everything inside: how dates, numbers and money read, and every word components show or announce. Without it, "en-US" and English.
- [Marquee](https://zen.rinzai.dev/docs/marquee.md): One line of text cut off with an ellipsis, that scrolls to show the rest on hover or focus (of itself or of its row), or all the time. Only text that doesn't fit moves.
- [Menu](https://zen.rinzai.dev/docs/menu.md): A button that opens a menu, or a context menu from a right-click or long press, with your own trigger, a header, icons, groups, destructive items, checkbox and radio items, submenus, a bottom sheet on phones, and a menubar of menus.
- [Meter](https://zen.rinzai.dev/docs/meter.md): A measure against a limit, like spend against a budget: warm near it, red past it.
- [Money Input](https://zen.rinzai.dev/docs/money-input.md): Amounts in any currency and locale, with shorthand like 1.5L or 10k and sums like 120+45.50, exact to the paisa, and typed in other currencies, converted at your rates. Built on Input Group.
- [Month Picker](https://zen.rinzai.dev/docs/month-picker.md): A field showing a month that opens a year and a 12-month grid, with optional limits and clearing.
- [Navigation Menu](https://zen.rinzai.dev/docs/navigation-menu.md): A site’s navigation: links, and labels that open glass panels of links on hover or click, switching at once between them; works with any router.
- [Number Field](https://zen.rinzai.dev/docs/number-field.md): A number to type or step with − and +, the arrow keys and Page Up and Down: shown the locale’s way, as a percentage or a unit, and kept within bounds. Each change says whether it was a step (and by how much) or typed, and onValueCommit fires once it’s finished.
- [Page Header](https://zen.rinzai.dev/docs/page-header.md): Eyebrow, aurora title and lead paragraph for the top of a page.
- [Page Transition](https://zen.rinzai.dev/docs/page-transition.md): The old page fades out as the new one rises in, when your router changes page in a view transition.
- [Pagination](https://zen.rinzai.dev/docs/pagination.md): The pages a long list is split into, as buttons or links for your router.
- [Pills](https://zen.rinzai.dev/docs/pills.md): A glass track with a glowing pill that slides to the current page. In a nav, it is site navigation; works with any router.
- [Player Bar](https://zen.rinzai.dev/docs/player-bar.md): What's playing, along the bottom of the screen, sitting on a TabBar on phones. useMediaPlayer drives your own <audio> or <video>; useMediaSession puts it on the lock screen and the media keys.
- [Popover](https://zen.rinzai.dev/docs/popover.md): A glass panel that opens from a button, on the native Popover API: small forms, cards and settings. For hints use Tooltip; for actions, Menu.
- [Progress Ring](https://zen.rinzai.dev/docs/progress-ring.md): Circular progress with room for a label in the middle.
- [Radio Cards](https://zen.rinzai.dev/docs/radio-cards.md): Choose one of a few cards that each show their option, like a colour palette.
- [Radio Group](https://zen.rinzai.dev/docs/radio-group.md): Choose one of a list, each option with a label and a description; native radios, so arrow keys work.
- [Range Slider](https://zen.rinzai.dev/docs/range-slider.md): Two thumbs on one track, for a span like an amount from $50 to $500.
- [Repeat Picker](https://zen.rinzai.dev/docs/repeat-picker.md): How often something recurs, like a bill, said in words, with the next dates it falls on.
- [Resizable](https://zen.rinzai.dev/docs/resizable.md): Panels with handles between them to drag, or to move with the arrow keys, within limits you set; groups nest, and the layout is reported to keep.
- [Seek Bar](https://zen.rinzai.dev/docs/seek-bar.md): Where playback is in a track, and the way to move it: played and loaded on one track, the time played and the length beside it or under its ends.
- [Segmented](https://zen.rinzai.dev/docs/segmented.md): A pill row for a few mutually exclusive options.
- [Select](https://zen.rinzai.dev/docs/select.md): Pick one value from a short list, fully keyboard-driven. For long or searchable lists, use Combobox.
- [Separator](https://zen.rinzai.dev/docs/separator.md): A hairline between groups of content, across or upright.
- [Side Nav](https://zen.rinzai.dev/docs/side-nav.md): Vertical navigation in titled groups, for docs and settings sidebars. Works with any router.
- [Skeleton & Spinner](https://zen.rinzai.dev/docs/skeleton.md): Placeholders for content on its way.
- [Slider](https://zen.rinzai.dev/docs/slider.md): A native range input with a glowing thumb and any track you like, at full size or small.
- [Sortable List](https://zen.rinzai.dev/docs/sortable.md): Put a list in order, or a tree of groups (a table’s rows, say), by dragging items by a grip or with the keyboard, each step announced: into other groups, open sub-items, or under another item. Also a virtualized list of hundreds.
- [Sparkline](https://zen.rinzai.dev/docs/sparkline.md): A small line of how a number has moved, with no axes, for beside a figure. It draws itself in.
- [Spinner](https://zen.rinzai.dev/docs/spinner.md): A small loading spinner in the current text colour, announced to screen readers when labelled.
- [Status Pill](https://zen.rinzai.dev/docs/status-pill.md): A small status that changes in place, such as Saving…, Saved or Not saved with a Retry, and fades back once the news is old.
- [Stepper](https://zen.rinzai.dev/docs/stepper.md): The steps of a flow and where you are in it; the line between them fills in as you go.
- [Tab Bar](https://zen.rinzai.dev/docs/tab-bar.md): Phone navigation fixed to the bottom of the screen. Works with any router.
- [Table](https://zen.rinzai.dev/docs/table.md): Composable tables: a glass panel that scrolls, sticky headers, first column and totals, sortable columns, rows reordered by drag and drop (into groups and under other rows), and virtual rows for long lists.
- [Table of Contents](https://zen.rinzai.dev/docs/table-of-contents.md): An "On this page" list that highlights the section being read.
- [Tabs](https://zen.rinzai.dev/docs/tabs.md): Switch between panels in place, with an underline or a glowing pill that slides to the active tab. To go to another page, use Pills.
- [Tag Input](https://zen.rinzai.dev/docs/tag-input.md): A field of short values (tags, emails): Enter or a comma adds one, Backspace takes the last back.
- [Textarea](https://zen.rinzai.dev/docs/textarea.md): Multi-line text, styled like Input.
- [Theme Toggle](https://zen.rinzai.dev/docs/theme-toggle.md): Switches between the dark and light themes, remembering the choice itself or leaving it to your app.
- [Theming & styling](https://zen.rinzai.dev/docs/theming.md): Your own colours from a few settings, readable in dark and light for any hue; and className overrides that always win.
- [Time Field](https://zen.rinzai.dev/docs/time-field.md): A time of day, typed or stepped a part at a time, in the locale’s order, digits and 12- or 24-hour clock.
- [Timeline](https://zen.rinzai.dev/docs/timeline.md): Events in order, each on a dot joined by a line: an activity feed or a history.
- [Toast](https://zen.rinzai.dev/docs/toast.md): Short messages that confirm an action or report a problem, with an optional action like Undo. They stack into a deck that fans out when pointed at, and swipe away.
- [Toggle](https://zen.rinzai.dev/docs/toggle.md): An on/off switch.
- [Toggle Group](https://zen.rinzai.dev/docs/toggle-group.md): Buttons that stay pressed, in a row: any number of them, like filters, or at most one. One stop in the tab order; the arrow keys go through them.
- [Toolbar](https://zen.rinzai.dev/docs/toolbar.md): A row of controls for one thing, like a table’s: one stop for Tab, and the arrow keys through its buttons, toggles and fields.
- [Tooltip](https://zen.rinzai.dev/docs/tooltip.md): A short glass hint on hover or keyboard focus, describing its trigger to screen readers; below its trigger or beside it.
- [Tree Table](https://zen.rinzai.dev/docs/tree.md): Rows that open into child rows, animated, built from useTree and the Table parts. With virtual rows and editable cells, enough for a budget planner.
- [Trend](https://zen.rinzai.dev/docs/trend.md): A change, like +12% with an arrow, coloured by whether it is good news.

---

# Accordion

Sections under headings that open one at a time, or several: questions and answers, or groups of settings.

```tsx
import { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { Accordion, AccordionContent, AccordionItem, AccordionTrigger, Card, CardHeader, CardTitle } from '@rinzai/zen';

const QUESTIONS = [
    {
        q: 'How are other currencies converted?',
        a: 'At the day’s rate when you save the entry. The original amount and rate are kept with it, so the conversion never changes later.',
    },
    {
        q: 'Can I split one payment across categories?',
        a: 'Yes: add it once, then split it. Each part counts towards its own category’s budget.',
    },
    {
        q: 'What happens to a budget I go over?',
        a: 'Nothing is blocked. The bar turns red, and the overspend is shown in the month’s summary.',
    },
];

/** Questions and answers: opening one closes the last. */
export default function Default() {
    return (
        <Card className="w-full max-w-md gap-2">
            <CardHeader>
                <CardTitle>Questions</CardTitle>
            </CardHeader>
            <Accordion defaultValue="0">
                {QUESTIONS.map(({ q, a }, i) => (
                    <AccordionItem key={q} value={String(i)}>
                        <AccordionTrigger>{q}</AccordionTrigger>
                        <AccordionContent>{a}</AccordionContent>
                    </AccordionItem>
                ))}
            </Accordion>
        </Card>
    );
}
```

### Multiple

```tsx
import { Accordion, AccordionContent, AccordionItem, AccordionTrigger, Toggle } from '@rinzai/zen';

/** `multiple`: each section opens and closes on its own. */
export default function Multiple() {
    return (
        <Accordion multiple defaultValue={['alerts']} className="w-full max-w-sm">
            <AccordionItem value="alerts">
                <AccordionTrigger>Alerts</AccordionTrigger>
                <AccordionContent className="flex flex-col gap-3">
                    <label className="flex items-center justify-between font-normal">
                        Over budget
                        <Toggle defaultChecked />
                    </label>
                    <label className="flex items-center justify-between font-normal">
                        Large payments
                        <Toggle />
                    </label>
                </AccordionContent>
            </AccordionItem>
            <AccordionItem value="export">
                <AccordionTrigger>Export</AccordionTrigger>
                <AccordionContent>Download every entry as a CSV file, one row each.</AccordionContent>
            </AccordionItem>
            <AccordionItem value="danger">
                <AccordionTrigger>Delete data</AccordionTrigger>
                <AccordionContent>Removes every entry and budget. This can’t be undone.</AccordionContent>
            </AccordionItem>
        </Accordion>
    );
}
```

## API reference

### Accordion

Sections under headings that open one at a time (or several, with
`multiple`), e.g. questions and answers. Each AccordionItem is a Disclosure:
an AccordionTrigger and an AccordionContent that grows open and folds shut.
↑↓ move between the headings, Home and End jump to the first and last.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultValue` | `string \| readonly string[] \| null` |  |  |
| `multiple` | `boolean` |  | One section open at a time (the default); opening one closes the other. Any number open at once. |
| `onValueChange` | `((value: string \| null) => void) \| ((value: readonly string[]) => void)` |  |  |
| `value` | `string \| readonly string[] \| null` |  | The open section's value, or null for none, when you keep it. |

### AccordionItem

One section: an AccordionTrigger and its AccordionContent.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `string` |  | Names the section in the Accordion's value. |

### AccordionTrigger

The heading and its button: your label, and a chevron that turns over while open.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `level` | `2 \| 3 \| 4 \| 5 \| 6` | `3` | The heading level it sits in, to fit the page's outline. Default 3. |

### AccordionContent

What the trigger shows and hides; only in the page while open (or folding shut).

No props of its own; it accepts the props of the element it renders.

---

# Alert

A notice, warning or failure beside what it is about: a tinted box, or a plain line in a form or card.

```tsx
import { Alert } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { Alert } from '@rinzai/zen';

/** A tinted box per tone; a `title` leads, and the text under it is quieter. */
export default function Default() {
    return (
        <div className="flex w-full max-w-md flex-col gap-3">
            <Alert>Changes to this item apply from next month.</Alert>
            <Alert tone="positive">Your data is up to date on every device.</Alert>
            <Alert tone="negative" title="Your data will be deleted for good.">
                Without your password or recovery key, nobody can open it. Starting over gives you a new, empty vault.
            </Alert>
        </div>
    );
}
```

### Plain

```tsx
import { Alert, Card, CardHeader, CardTitle, Spinner } from '@rinzai/zen';

/** `plain`: just the icon and text, for a line inside a card or a form. Any icon, or none. */
export default function Plain() {
    return (
        <Card className="flex w-full max-w-sm flex-col gap-3">
            <CardHeader className="mb-0">
                <CardTitle>Currency</CardTitle>
            </CardHeader>
            <Alert plain icon={<Spinner className="text-primary" />}>
                Getting today’s rate…
            </Alert>
            <Alert plain tone="negative">
                Couldn’t get today’s rate, so converting isn’t possible right now.
            </Alert>
        </Card>
    );
}
```

## API reference

### Alert

A message beside the content it's about: a notice, a warning, a failure.
A tinted box by default, or with `plain`, just the icon and text in the
tone's colour. With a `title`, the title takes the tone and the text under
it is quieter. Bad news is announced at once (role="alert"), anything else
politely (role="status"); pass `role` to change that, e.g. "note" for a
message that doesn't change.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `ReactNode` |  | Replaces the tone's icon (info, check, warning); `null` for none. |
| `plain` | `boolean` | `false` | Just the icon and text, no box: for a line inside a form or a card. |
| `title` | `ReactNode` |  | A first line in the tone's colour; the text under it is quieter. |
| `tone` | `"default" \| "negative" \| "positive"` | `default` | `positive` in the accent colour, `negative` in red for bad news. |

---

# Animated Number

Numbers and amounts that count smoothly to each new value.

```tsx
import { AnimatedNumber, AnimatedMoney } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { AnimatedMoney, AnimatedNumber, Button, Stat, StatRow } from '@rinzai/zen';
import { useState } from 'react';

/** Numbers count to each new value (and up from zero when first shown). */
export default function Default() {
    const [net, setNet] = useState(625400);
    const [entries, setEntries] = useState(42);
    return (
        <div className="flex w-full max-w-lg flex-col gap-4">
            <StatRow className="sm:grid-cols-2!">
                <Stat
                    label="Net this month"
                    tone="positive"
                    value={<AnimatedMoney value={net} currency="USD" locale="en-US" />}
                />
                <Stat label="Entries" value={<AnimatedNumber value={entries} />} />
            </StatRow>
            <Button
                variant="outline"
                className="self-start"
                onClick={() => {
                    setNet((n) => n + Math.round((Math.random() - 0.4) * 300000));
                    setEntries((e) => e + 1);
                }}
            >
                Add an entry
            </Button>
        </div>
    );
}
```

### Roll

```tsx
import { AnimatedMoney, Button, Stat } from '@rinzai/zen';
import { useState } from 'react';

/** With `roll`, each digit rolls to its new one, like an odometer. */
export default function Roll() {
    const [total, setTotal] = useState(184250);
    return (
        <div className="flex w-full max-w-xs flex-col gap-4">
            <Stat
                label="Spent this month"
                value={<AnimatedMoney roll value={total} currency="USD" locale="en-US" showDecimals />}
            />
            <Button
                variant="outline"
                className="self-start"
                onClick={() => setTotal((t) => t + Math.round(Math.random() * 40000))}
            >
                Add a purchase
            </Button>
        </div>
    );
}
```

## API reference

### AnimatedNumber

A number that counts smoothly to each new value (and up from zero when it
first appears). Rounds to whole numbers while moving, so money in minor
units never shows fractions. With `roll`, each digit rolls to its new one
instead, like an odometer: easier to read when a total changes. Instant
with reduced motion.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `number` |  |  |
| `className` | `string` |  |  |
| `duration` | `number` | `650` | Milliseconds per change. |
| `format` | `((value: number) => string)` |  | Turns the (whole) number into text, e.g. with Intl.NumberFormat. |
| `fromZero` | `boolean` | `true` | Count up from zero when first shown (default), or start at the value. |
| `roll` | `boolean` | `false` | Roll each digit to its new one, like an odometer, instead of counting. |

### AnimatedMoney

An amount of money (minor units) that counts to each new value.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `currency` (required) | `string` |  |  |
| `value` (required) | `number` |  |  |
| `className` | `string` |  |  |
| `duration` | `number` |  | Milliseconds per change. |
| `fromZero` | `boolean` |  | Count up from zero when first shown (default), or start at the value. |
| `locale` | `string` |  | Defaults to the LocaleProvider's. |
| `roll` | `boolean` |  | Roll each digit to its new one, like an odometer, instead of counting. |
| `showDecimals` | `boolean` | `false` |  |

---

# Avatar

A round picture, or the name's initial on the glowing accent. With an in-browser crop for uploads.

```tsx
import { Avatar } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { Avatar } from '@rinzai/zen';

const PHOTO =
    'data:image/svg+xml;utf8,' +
    encodeURIComponent(
        '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64"><rect width="64" height="64" fill="#2f2943"/><circle cx="32" cy="26" r="12" fill="#ab93ed"/><rect x="12" y="42" width="40" height="30" rx="15" fill="#ab93ed"/></svg>',
    );

/** An image, or the name's initial on the accent. Size it with className. */
export default function Default() {
    return (
        <div className="flex items-center gap-4">
            <Avatar name="rin@example.com" />
            <Avatar name="Sam" className="size-12 text-lg" />
            <Avatar name="Alex" src={PHOTO} alt="Alex" className="size-12" />
            <div className="flex items-center gap-2 text-sm">
                <Avatar name="Priya" className="size-7 text-xs" />
                Priya
            </div>
        </div>
    );
}
```

### Upload

```tsx
import { Avatar, Button, cropImageToSquare, ImageCropError } from '@rinzai/zen';
import { useRef, useState } from 'react';

/** cropImageToSquare centres, crops and shrinks a chosen image in the browser to a small data URL. */
export default function Upload() {
    const [src, setSrc] = useState<string | null>(null);
    const [error, setError] = useState<string | null>(null);
    const input = useRef<HTMLInputElement>(null);
    return (
        <div className="flex items-center gap-4">
            <Avatar name="You" src={src} className="size-16 text-xl" />
            <div className="flex flex-col gap-1">
                <Button variant="outline" size="sm" onClick={() => input.current?.click()}>
                    Choose a picture
                </Button>
                {error && <span className="text-destructive text-xs">{error}</span>}
            </div>
            <input
                ref={input}
                type="file"
                accept="image/*"
                hidden
                onChange={async (e) => {
                    const file = e.target.files?.[0];
                    if (!file) return;
                    try {
                        setSrc(await cropImageToSquare(file, 160));
                        setError(null);
                    } catch (err) {
                        setError(err instanceof ImageCropError ? err.message : 'Something went wrong.');
                    }
                }}
            />
        </div>
    );
}
```

## API reference

### Avatar

Round profile picture; without an image, the name's initial on the glowing
accent. Decorative (hidden from screen readers) unless you give it `alt`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` (required) | `string` |  | Name or email, for the initial. |
| `alt` | `string` |  | Accessible name; leave out when the name is shown next to the avatar. |
| `className` | `string` |  | Size and more, e.g. "size-12 text-lg" (default size-9). |
| `src` | `string \| null` |  | Image URL (or data URL); without it, or if it fails to load, the initial is shown. |

---

# Backdrop

The page background: aurora glows over contours or dots, and a light that follows the pointer and catches card edges, or drifts round them by itself on pages with no pointer.

```tsx
import { Backdrop } from '@rinzai/zen';
```

## Examples

### Contours

```tsx
import { Backdrop, Button, Card, CardHeader, CardTitle } from '@rinzai/zen';

import topo from './topo.svg';

export default function Contours() {
    return (
        // Backdrop is fixed to the viewport; the transform keeps it inside this frame for the demo.
        <div className="relative h-96 w-full [transform:translateZ(0)] overflow-hidden rounded-xl">
            <Backdrop topoSrc={topo} />
            <div className="flex h-full items-center justify-center p-8">
                <Card className="w-72">
                    <CardHeader>
                        <CardTitle>Move the pointer</CardTitle>
                    </CardHeader>
                    <p className="text-muted-foreground mt-0! mb-4 text-sm">
                        Card edges and the contour lines light up near it.
                    </p>
                    <Button variant="outline">Outline buttons too</Button>
                </Card>
            </div>
        </div>
    );
}
```

### Dots

```tsx
import { Backdrop, Stat } from '@rinzai/zen';

export default function Dots() {
    return (
        // Backdrop is fixed to the viewport; the transform keeps it inside this frame for the demo.
        <div className="relative h-96 w-full [transform:translateZ(0)] overflow-hidden rounded-xl">
            <Backdrop pattern="dots" />
            <div className="flex h-full items-center justify-center p-8">
                <Stat label="Net this month" value="$3,330" tone="positive" className="w-60" />
            </div>
        </div>
    );
}
```

### Ambient

```tsx
import { Card, CardTitle, Input, Stat } from '@rinzai/zen';

/**
 * For a page that never gets a pointer, such as an OBS browser source: `data-zen-glow="ambient"`
 * sends the edge light slowly round each border by itself. Put it on `<html>` for the whole page, or
 * on any element for what's inside it. `data-zen-page="transparent"` on `<html>` (with the base
 * stylesheet) paints nothing behind the content, so the stream shows through.
 */
export default function Ambient() {
    return (
        <div data-zen-glow="ambient" className="flex flex-wrap items-start gap-4 p-4">
            <Stat label="Now playing" value="Lo-fi beats" className="w-56" />
            <Card className="w-64">
                <CardTitle className="mb-3">Chat</CardTitle>
                <Input placeholder="Say something" aria-label="Message" />
            </Card>
        </div>
    );
}
```

## API reference

### Backdrop

Fixed page background: slow aurora glows over a faint pattern (topographic
contours or a dot grid), with a light that follows the pointer. It also
lights `.glow-edge` and `.glow-border` borders (cards, outline buttons,
dialogs, fields) near the pointer. Render once, behind everything.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` |  | Classes for the backdrop layer (e.g. a view-transition-name). |
| `pattern` | `"contours" \| "dots"` |  | Background pattern. Defaults to contours when `topoSrc` is given, dots otherwise. |
| `topoSrc` | `string` |  | URL of a contour-line image (strokes on transparent), used as a mask. |

---

# Badge

A small label for status, counts and tags.

```tsx
import { Badge } from '@rinzai/zen';
```

## Examples

### Variants

```tsx
import { Badge } from '@rinzai/zen';

export default function Variants() {
    return (
        <div className="flex flex-wrap items-center gap-3">
            <Badge>New</Badge>
            <Badge variant="secondary">Draft</Badge>
            <Badge tone="negative">Overdue</Badge>
            <Badge variant="outline">Archived</Badge>
        </div>
    );
}
```

## API reference

### Badge

A small label for status, counts and tags; `tone="negative"` for bad news.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tone` | `"default" \| "negative" \| null` |  |  |
| `variant` | `"default" \| "outline" \| "secondary" \| null` |  |  |

---

# Breadcrumbs

Where a page sits: its parents as links, then the page itself. Works with any router.

```tsx
import { Breadcrumbs, Breadcrumb } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { Breadcrumb, Breadcrumbs } from '@rinzai/zen';

/** Parents as links (with a router, Breadcrumb asChild around its Link), then the current page. */
export default function Default() {
    return (
        <Breadcrumbs>
            <Breadcrumb href="#">Budgets</Breadcrumb>
            <Breadcrumb href="#">2026</Breadcrumb>
            <Breadcrumb current>September</Breadcrumb>
        </Breadcrumbs>
    );
}
```

## API reference

### Breadcrumbs

Where a page sits: its parents as links, then the page itself. Give the last crumb `current`.

No props of its own; it accepts the props of the element it renders.

### Breadcrumb

One crumb: a link, or with `current`, the page you're on (not a link). With
`asChild`, the styles go onto your own link element (a router's Link).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `asChild` | `boolean` |  | Style the single child element (e.g. a router link) instead of rendering an <a>. |
| `current` | `boolean` |  | The page you're on: the last crumb. |

---

# Button

Actions, from the one glowing primary action to quiet ghost buttons.

```tsx
import { Button } from '@rinzai/zen';
```

## Examples

### Variants

```tsx
import { Button } from '@rinzai/zen';

export default function Variants() {
    return (
        <div className="flex flex-wrap items-center gap-3">
            <Button>Save changes</Button>
            <Button variant="secondary">Export</Button>
            <Button variant="outline">Cancel</Button>
            <Button variant="ghost">Skip</Button>
            <Button tone="negative">Delete</Button>
            <Button variant="link">Learn more</Button>
        </div>
    );
}
```

### Sizes

```tsx
import { Button } from '@rinzai/zen';

export default function Sizes() {
    return (
        <div className="flex flex-wrap items-center gap-3">
            <Button size="sm">Small</Button>
            <Button>Default</Button>
            <Button size="lg">Large</Button>
        </div>
    );
}
```

### Tones

```tsx
import { Button } from '@rinzai/zen';
// Icons from Heroicons (https://heroicons.com): XMark (x-mark).

/** A link sits in the text and truncates; `tone` quiets it or makes it red. An icon button with a destructive tone turns red only when pointed at. */
export default function Tones() {
    return (
        <div className="flex flex-col gap-3 text-sm">
            <p>
                Saved. <Button variant="link">Undo</Button> or{' '}
                <Button variant="link" tone="muted">
                    see history
                </Button>
            </p>
            <div className="flex items-center gap-3">
                <Button variant="link" tone="negative">
                    Delete account
                </Button>
                <Button variant="ghost" size="icon" tone="negative" aria-label="Remove">
                    <XMark className="size-4" />
                </Button>
            </div>
        </div>
    );
}
```

### Loading

```tsx
import { Button } from '@rinzai/zen';
import { useState } from 'react';

export default function Loading() {
    const [saving, setSaving] = useState(false);
    return (
        <Button
            loading={saving}
            onClick={() => {
                setSaving(true);
                setTimeout(() => setSaving(false), 1500);
            }}
        >
            {saving ? 'Saving…' : 'Save'}
        </Button>
    );
}
```

### As link

```tsx
import { Button } from '@rinzai/zen';

/** asChild puts the button's styles on your own element, here a link (a router's Link works the same way). */
export default function AsLink() {
    return (
        <div className="flex gap-3">
            <Button asChild>
                <a href="#get-started">Get started</a>
            </Button>
            <Button asChild variant="outline">
                <a href="#docs">Read the docs</a>
            </Button>
        </div>
    );
}
```

## API reference

### Button

A button in one of Zen's styles. With `asChild`, the styles go onto your own
single child element instead, such as a router's Link (`loading` and `type`
then don't apply).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `asChild` | `boolean` | `false` | Put the button's styles on the single child element (e.g. a link) instead of a <button>. |
| `loading` | `boolean` | `false` | Shows a spinner and disables the button while an action runs. |
| `size` | `"default" \| "icon-lg" \| "icon-sm" \| "icon-xs" \| "icon" \| "lg" \| "sm" \| null` |  |  |
| `tone` | `"default" \| "inherit" \| "muted" \| "negative" \| null` |  |  |
| `variant` | `"default" \| "ghost" \| "link" \| "outline" \| "secondary" \| null` |  |  |

---

# Button Group

Buttons joined into one, rounded only at the ends: a split button, or Previous, Today and Next.

```tsx
import { ButtonGroup } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { Button, ButtonGroup } from '@rinzai/zen';
// Icons from Heroicons (https://heroicons.com): ChevronLeft (chevron-left), ChevronRight (chevron-right).

/** Previous, today and next, joined: one control for moving through months. */
export default function Default() {
    return (
        <ButtonGroup aria-label="Month">
            <Button variant="outline" size="icon" aria-label="Previous month">
                <ChevronLeft className="size-4 rtl:-scale-x-100" />
            </Button>
            <Button variant="outline">This month</Button>
            <Button variant="outline" size="icon" aria-label="Next month">
                <ChevronRight className="size-4 rtl:-scale-x-100" />
            </Button>
        </ButtonGroup>
    );
}
```

### Split

```tsx
import { Button, ButtonGroup, buttonVariants, Menu, MenuContent, MenuItem, MenuTrigger, useToast } from '@rinzai/zen';
// Icons from Heroicons (https://heroicons.com): ChevronDown (chevron-down).

/** A split button: the usual action, and a menu of the others. */
export default function Split() {
    const toast = useToast();
    return (
        <ButtonGroup>
            <Button variant="outline" onClick={() => toast('Exported as CSV', { tone: 'positive' })}>
                Export CSV
            </Button>
            <Menu>
                <MenuTrigger
                    aria-label="More export formats"
                    className={buttonVariants({ variant: 'outline', size: 'icon' })}
                >
                    <ChevronDown className="size-4" />
                </MenuTrigger>
                <MenuContent align="end">
                    <MenuItem onSelect={() => toast('Exported as Excel', { tone: 'positive' })}>Excel</MenuItem>
                    <MenuItem onSelect={() => toast('Exported as PDF', { tone: 'positive' })}>PDF</MenuItem>
                </MenuContent>
            </Menu>
        </ButtonGroup>
    );
}
```

## API reference

### ButtonGroup

Buttons joined into one: shared edges, rounded only at the ends, e.g. a
split button (an action and a menu of others) or Previous / Today / Next.
Best with `outline` buttons, whose hairlines meet. Upright with
`orientation="vertical"`. Give it an aria-label when the buttons' names
don't say what they're for together.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"horizontal" \| "vertical"` | `horizontal` |  |

---

# Calendar

A month grid to pick a date or a range, fully keyboard-driven, with limits, blocked days and a year view to jump far.

```tsx
import { Calendar } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { Calendar, formatDate } from '@rinzai/zen';
import { useState } from 'react';

/** Click a day, or use the keyboard: arrows, Home/End, Page Up/Down (Shift for years). The title jumps to any month and year. */
export default function Default() {
    const [date, setDate] = useState<string | null>('2026-09-30');
    return (
        <div className="flex flex-col items-center gap-3">
            <Calendar value={date} onValueChange={setDate} locale="en-US" />
            <p className="text-muted-foreground mt-0! text-xs">
                {date ? formatDate(date, 'en-US', 'full') : 'No date'}
            </p>
        </div>
    );
}
```

### Range

```tsx
import { Calendar, type DateRange, daysBetween, formatDateRange } from '@rinzai/zen';
import { useState } from 'react';

/** Two months side by side: pick a start, then an end. The days between are previewed as you point. */
export default function Range() {
    const [range, setRange] = useState<DateRange | null>({ start: '2026-10-05', end: '2026-10-12' });
    return (
        <div className="flex flex-col items-center gap-3">
            <Calendar mode="range" months={2} value={range} onValueChange={setRange} locale="en-GB" />
            <p className="text-muted-foreground mt-0! text-xs">
                {range?.end
                    ? `${formatDateRange(range.start, range.end, 'en-GB')} · ${daysBetween(range.start, range.end) + 1} days`
                    : 'Pick the last day'}
            </p>
        </div>
    );
}
```

### Limits

```tsx
import { addDays, Calendar, dayOfWeek, today } from '@rinzai/zen';
import { useState } from 'react';

/** Only the next 60 days, and no weekends: min, max and isDisabled. Weeks start on Monday here, whatever the locale. */
export default function Limits() {
    const start = today();
    const [date, setDate] = useState<string | null>(null);
    return (
        <Calendar
            value={date}
            onValueChange={setDate}
            locale="en-US"
            weekStartsOn={1}
            min={start}
            max={addDays(start, 60)}
            isDisabled={(d) => dayOfWeek(d) === 0 || dayOfWeek(d) === 6}
        />
    );
}
```

## API reference

### Calendar

A month grid to pick a date, or a range of dates, fully keyboard-driven:
arrows move by day and week, Home and End to the week's ends, Page Up and
Down by month (with Shift, by year). The title opens a year and month grid
to jump far. Dates are "YYYY-MM-DD" strings, so they never shift a day with
time zones. Inline on a page, or in a popup with DatePicker.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `autoFocus` | `boolean` |  | Focus the chosen date (or today) when shown, e.g. in a popup. |
| `className` | `string` |  |  |
| `defaultMonth` | `string` |  | Month shown first ("YYYY-MM"). Defaults to the chosen date's, or this month. |
| `defaultValue` | `DateRange \| string \| null` |  | The first date, when the calendar keeps its own. The first range, when the calendar keeps its own. |
| `isDisabled` | `((date: string) => boolean)` |  | Dates that can't be picked, e.g. weekends or booked days. |
| `locale` | `string` |  | Decides month and weekday names, and the first day of the week, e.g. "en-IN". Defaults to the LocaleProvider's. |
| `max` | `string` |  | Latest date that can be picked. |
| `min` | `string` |  | Earliest date that can be picked ("YYYY-MM-DD"). |
| `mode` | `"range" \| "single"` |  | Pick a start and then an end; the days between are highlighted, previewed while pointing. |
| `months` | `number` |  | Months shown side by side (e.g. 2 for ranges). |
| `onValueChange` | `((date: string) => void) \| ((range: DateRange) => void)` |  |  |
| `value` | `DateRange \| string \| null` |  | "YYYY-MM-DD", or null for none, when you keep it. The range when you keep it; `end` is null while only the start is picked. |
| `weekStartsOn` | `number` |  | 0 for Sunday … 6 for Saturday. Defaults to the locale's. |

---

# Calendar Heatmap

A month of days shaded by their value, like spending per day.

```tsx
import { CalendarHeatmap } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { CalendarHeatmap, type DateString, formatDate, formatMoney } from '@rinzai/zen';
import { useState } from 'react';

const SPENT: Partial<Record<DateString, number>> = {
    '2026-09-01': 185000,
    '2026-09-03': 3840,
    '2026-09-05': 2500,
    '2026-09-06': 7800,
    '2026-09-08': 1460,
    '2026-09-12': 16450,
    '2026-09-13': 9150,
    '2026-09-15': 4200,
    '2026-09-19': 3180,
    '2026-09-20': 41200,
    '2026-09-22': 1199,
    '2026-09-26': 6420,
    '2026-09-27': 2210,
};
const money = (cents: number) => formatMoney(cents, 'USD', 'en-US', { showDecimals: false });

/** What was spent each day of a month: pick a day to see it. */
export default function Default() {
    const [day, setDay] = useState<DateString | null>('2026-09-12');
    return (
        <div className="flex w-full max-w-xs flex-col gap-3">
            <CalendarHeatmap
                month="2026-09"
                values={SPENT}
                locale="en-US"
                format={money}
                onSelectedChange={setDay}
                selected={day}
            />
            <p className="text-muted-foreground mt-0! text-sm">
                {day ? `${formatDate(day, 'en-US', 'long')}: ${money(SPENT[day] ?? 0)} spent` : 'Pick a day'}
            </p>
        </div>
    );
}
```

## API reference

### CalendarHeatmap

A month as a grid of days, each shaded by its value (e.g. what was spent
that day): busy days stand out at a glance. Hover a day for its figure;
with `onSelectedChange`, days are buttons.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `month` (required) | `string` |  |  |
| `values` (required) | `Partial<Record<string, number>>` |  | Each day's value, by date ("2026-09-03"); days missing have none. |
| `className` | `string` |  |  |
| `format` | `((value: number) => string)` |  | Turns a value into text for its label, e.g. as money. |
| `label` | `string` |  | Accessible name (default: the month, e.g. "September 2026"). |
| `locale` | `string` |  |  |
| `onSelectedChange` | `((day: string) => void)` |  | Makes the days buttons. |
| `selected` | `string \| null` |  |  |
| `weekStartsOn` | `number` |  | 0 for Sunday … 6 for Saturday (default: the locale's). |

---

# Canvas

A fixed-size surface where items sit anywhere, like the cards of a stream overlay: drag, resize and select several, by pointer, touch or keyboard, with snapping, a grid, undo and a fit-to-width scale.

```tsx
import { Canvas, CanvasItem } from '@rinzai/zen';
```

## Examples

### Designer

```tsx
import {
    Button,
    Canvas,
    CanvasItem,
    type CanvasItemRect,
    ColorPicker,
    InputGroup,
    InputGroupAddon,
    InputGroupInput,
    Kbd,
    SortableHandle,
    SortableItem,
    SortableList,
    cx,
} from '@rinzai/zen';
import { KeyboardEvent, useRef, useState } from 'react';

interface Layer extends CanvasItemRect {
    kind: 'text' | 'bar' | 'image';
    name: string;
    color: string;
}

const W = 640;
const H = 360;

const START: Layer[] = [
    { id: 'scene', kind: 'image', name: 'Backdrop', color: '#1b1630', x: 0, y: 0, w: W, h: H, locked: true },
    { id: 'cam', kind: 'image', name: 'Camera', color: '#7c5cff', x: 404, y: 20, w: 216, h: 122 },
    { id: 'title', kind: 'text', name: 'Title', color: '#ffffff', x: 24, y: 252, w: 300, h: 40 },
    { id: 'goal', kind: 'bar', name: 'Sub goal', color: '#2bb3a3', x: 24, y: 304, w: 300, h: 16 },
];

const NEW: Record<Layer['kind'], Omit<Layer, 'id' | 'x' | 'y'>> = {
    text: { kind: 'text', name: 'Text', color: '#ffffff', w: 200, h: 32 },
    bar: { kind: 'bar', name: 'Bar', color: '#f0a83a', w: 220, h: 14 },
    image: { kind: 'image', name: 'Image', color: '#ef5a7a', w: 120, h: 120 },
};

/**
 * A small overlay designer: a 640×360 scene that fits its width, a layers list whose order is the
 * stacking (drag to reorder), and an inspector for the selected card. `onItemsChangeEnd` gives each change
 * with the items before it, which is all Undo needs. Try `⌘Z`, `⇧⌘Z` and `Delete`.
 */
export default function Designer() {
    const [items, setItems] = useState(START);
    const [selected, setSelected] = useState<string[]>(['title']);
    const [past, setPast] = useState<Layer[][]>([]);
    const [future, setFuture] = useState<Layer[][]>([]);
    const editing = useRef<Layer[] | null>(null);
    const count = useRef(0);

    const remember = (before: Layer[]) => {
        setPast((p) => [...p, before]);
        setFuture([]);
    };
    const commit = (next: Layer[]) => {
        remember(items);
        setItems(next);
    };
    // Live edits (a colour being dragged) become one step of history when they end.
    const live = (next: Layer[]) => {
        editing.current ??= items;
        setItems(next);
    };
    const settle = () => {
        if (editing.current) remember(editing.current);
        editing.current = null;
    };
    const undo = () => {
        if (!past.length) return;
        setFuture((f) => [items, ...f]);
        setItems(past[past.length - 1]);
        setPast((p) => p.slice(0, -1));
    };
    const redo = () => {
        if (!future.length) return;
        setPast((p) => [...p, items]);
        setItems(future[0]);
        setFuture((f) => f.slice(1));
    };
    const add = (kind: Layer['kind']) => {
        const id = `${kind}-${++count.current}`;
        const base = NEW[kind];
        commit([
            ...items,
            { ...base, id, name: `${base.name} ${count.current}`, x: (W - base.w) / 2, y: (H - base.h) / 2 },
        ]);
        setSelected([id]);
    };
    const remove = () => {
        const gone = new Set(selected.filter((id) => !items.find((i) => i.id === id)?.locked));
        if (!gone.size) return;
        commit(items.filter((i) => !gone.has(i.id)));
        setSelected([]);
    };
    const onKeyDown = (e: KeyboardEvent) => {
        const mod = e.metaKey || e.ctrlKey;
        if (mod && e.key.toLowerCase() === 'z') {
            e.preventDefault();
            if (e.shiftKey) redo();
            else undo();
        } else if ((e.key === 'Delete' || e.key === 'Backspace') && (e.target as Element).closest('[data-canvas-id]')) {
            e.preventDefault();
            remove();
        }
    };

    // Top of the stack first; the locked backdrop stays at the bottom.
    const layers = items.filter((i) => !i.locked).reverse();
    const one = selected.length === 1 ? items.find((i) => i.id === selected[0]) : undefined;
    const update = (patch: Partial<Layer>) =>
        one && commit(items.map((i) => (i.id === one.id ? { ...i, ...patch } : i)));
    const field = (key: 'x' | 'y' | 'w' | 'h', max: number) => (
        <InputGroup className="h-9">
            <InputGroupAddon className="w-3 uppercase">{key}</InputGroupAddon>
            <InputGroupInput
                type="number"
                aria-label={{ x: 'X', y: 'Y', w: 'Width', h: 'Height' }[key]}
                value={one?.[key] ?? ''}
                disabled={!one || one.locked}
                min={0}
                max={max}
                onChange={(e) => {
                    const v = Math.round(Number(e.target.value));
                    if (one && Number.isFinite(v))
                        update({ [key]: Math.min(max, Math.max(key === 'w' || key === 'h' ? 8 : 0, v)) });
                }}
                className="tabular-nums"
            />
        </InputGroup>
    );

    return (
        <div className="flex w-full max-w-3xl flex-col gap-4" onKeyDown={onKeyDown}>
            <div className="flex flex-wrap items-center gap-2">
                <Button size="sm" variant="secondary" onClick={() => add('text')}>
                    Text
                </Button>
                <Button size="sm" variant="secondary" onClick={() => add('bar')}>
                    Bar
                </Button>
                <Button size="sm" variant="secondary" onClick={() => add('image')}>
                    Image
                </Button>
                <span className="flex-1" />
                <Button size="sm" variant="ghost" onClick={undo} disabled={!past.length}>
                    Undo
                </Button>
                <Button size="sm" variant="ghost" onClick={redo} disabled={!future.length}>
                    Redo
                </Button>
                <Button size="sm" variant="ghost" tone="negative" onClick={remove} disabled={!selected.length}>
                    Delete
                </Button>
            </div>

            <Canvas
                aria-label="Scene"
                width={W}
                height={H}
                scale="fit"
                snap
                items={items}
                onItemsChange={setItems}
                onItemsChangeEnd={(_, before) => remember([...before])}
                selected={selected}
                onSelectedChange={setSelected}
            >
                {items.map((layer) => (
                    <CanvasItem key={layer.id} id={layer.id} label={layer.name} className="flex items-center">
                        {layer.kind === 'text' && (
                            <span
                                className="truncate font-semibold tracking-tight"
                                style={{ color: layer.color, fontSize: layer.h * 0.72, lineHeight: 1 }}
                            >
                                Live in 5 minutes
                            </span>
                        )}
                        {layer.kind === 'bar' && (
                            <div className="size-full overflow-hidden rounded-full bg-white/10">
                                <div className="h-full w-3/5 rounded-full" style={{ background: layer.color }} />
                            </div>
                        )}
                        {layer.kind === 'image' && (
                            <div
                                className={cx('size-full', !layer.locked && 'rounded-xl')}
                                style={{
                                    background: layer.locked
                                        ? `radial-gradient(ellipse at 20% 0%, ${layer.color}, #0b0a12 70%)`
                                        : `radial-gradient(circle at 30% 25%, color-mix(in oklch, ${layer.color} 70%, white), ${layer.color})`,
                                }}
                            />
                        )}
                    </CanvasItem>
                ))}
            </Canvas>

            <div className="grid gap-4 sm:grid-cols-2">
                <section className="flex flex-col gap-2">
                    <h4 className="text-muted-foreground m-0! text-xs font-medium tracking-widest uppercase">Layers</h4>
                    <SortableList
                        aria-label="Layers"
                        value={layers.map((i) => i.id)}
                        onValueChange={(order) =>
                            commit([
                                ...items.filter((i) => i.locked),
                                ...[...order].reverse().map((id) => items.find((i) => i.id === id)!),
                            ])
                        }
                    >
                        {layers.map((layer) => (
                            <SortableItem
                                key={layer.id}
                                id={layer.id}
                                className={cx(
                                    'flex items-center gap-1 rounded-lg pr-2',
                                    selected.includes(layer.id) && 'bg-primary/10',
                                )}
                            >
                                <SortableHandle id={layer.id} label={layer.name} />
                                <button
                                    type="button"
                                    onClick={() => setSelected([layer.id])}
                                    className="flex min-w-0 flex-1 cursor-pointer items-center gap-2 py-1.5 text-left text-sm outline-hidden"
                                >
                                    <span
                                        aria-hidden
                                        className="size-3 shrink-0 rounded-sm"
                                        style={{ background: layer.color }}
                                    />
                                    <span className="truncate">{layer.name}</span>
                                </button>
                            </SortableItem>
                        ))}
                    </SortableList>
                    {items
                        .filter((i) => i.locked)
                        .map((layer) => (
                            <p
                                key={layer.id}
                                className="text-muted-foreground mt-0! flex items-center gap-2 py-1.5 pl-9 text-sm"
                            >
                                <span
                                    aria-hidden
                                    className="size-3 shrink-0 rounded-sm"
                                    style={{ background: layer.color }}
                                />
                                {layer.name}
                                <span className="ml-auto pr-2 text-xs">Locked</span>
                            </p>
                        ))}
                </section>
                <section className="flex flex-col gap-2">
                    <h4 className="text-muted-foreground m-0! text-xs font-medium tracking-widest uppercase">
                        {one ? one.name : selected.length ? `${selected.length} selected` : 'Nothing selected'}
                    </h4>
                    <div className="grid grid-cols-2 gap-2">
                        {field('x', W)}
                        {field('y', H)}
                        {field('w', W)}
                        {field('h', H)}
                    </div>
                    <ColorPicker
                        aria-label="Colour"
                        value={one?.color ?? '#000000'}
                        disabled={!one}
                        onValueChange={(color) =>
                            one && live(items.map((i) => (i.id === one.id ? { ...i, color } : i)))
                        }
                        onValueCommit={settle}
                    />
                    <p className="text-muted-foreground mt-0! text-xs">
                        <Kbd>Shift</Kbd> keeps a card's shape as you resize; draw a box to select several.
                    </p>
                </section>
            </div>
        </div>
    );
}
```

### Dashboard

```tsx
import { Canvas, CanvasItem, type CanvasItemRect, Meter, Sparkline, Stat, StatusPill } from '@rinzai/zen';
import { ReactNode, useState } from 'react';

const WIDGETS: Record<string, { label: string; render: () => ReactNode }> = {
    spent: {
        label: 'Spent',
        render: () => (
            <Stat label="Spent" value="$2,742" tone="negative" className="size-full">
                <Sparkline
                    values={[40, 52, 48, 61, 58, 66, 72, 69, 80]}
                    tone="negative"
                    area
                    className="mt-2 h-auto min-h-0 w-full flex-1"
                />
            </Stat>
        ),
    },
    left: {
        label: 'Left to spend',
        render: () => <Stat label="Left to spend" value="$1,258" tone="positive" className="size-full" />,
    },
    budgets: {
        label: 'Budgets',
        render: () => (
            <div className="glass glow-edge flex size-full flex-col gap-4 rounded-xl p-3.5 md:p-4">
                <span className="text-muted-foreground text-2xs tracking-widest uppercase sm:text-xs">Budgets</span>
                <Meter label="Groceries" value={207} max={600} detail="$207 / $600" />
                <Meter label="Dining out" value={170} max={150} detail="$170 / $150" />
                <Meter label="Transport" value={64} max={120} detail="$64 / $120" />
                <Meter label="Bills" value={310} max={340} detail="$310 / $340" />
            </div>
        ),
    },
    balance: {
        label: 'Balance',
        render: () => (
            <Stat label="Balance" value="$18,400" className="size-full">
                <Sparkline
                    values={[12, 13, 13.5, 14, 15.2, 15, 16.4, 17.1, 18.4]}
                    area
                    className="mt-2 h-auto min-h-0 w-full flex-1"
                />
            </Stat>
        ),
    },
};

/**
 * A dashboard you lay out yourself: widgets on a 20-unit `grid`, lining up with each other as you drag
 * (`snap`), with `minSize` so none gets too small. Widgets are any content; here Stat, Meter and
 * Sparkline. `onItemsChangeEnd` is the moment to save the layout.
 */
export default function Dashboard() {
    const [items, setItems] = useState<CanvasItemRect[]>([
        { id: 'spent', x: 0, y: 0, w: 220, h: 140 },
        { id: 'left', x: 240, y: 0, w: 220, h: 140 },
        { id: 'budgets', x: 480, y: 0, w: 240, h: 300 },
        { id: 'balance', x: 0, y: 160, w: 460, h: 140 },
    ]);
    const [selected, setSelected] = useState<string[]>([]);
    const [saves, setSaves] = useState(0);
    return (
        <div className="flex w-full max-w-3xl flex-col gap-3">
            <Canvas
                aria-label="Dashboard"
                width={720}
                height={300}
                scale="fit"
                snap
                grid={20}
                minSize={100}
                items={items}
                onItemsChange={setItems}
                onItemsChangeEnd={() => setSaves((n) => n + 1)}
                selected={selected}
                onSelectedChange={setSelected}
                className="bg-transparent shadow-none"
            >
                {items.map((item) => (
                    <CanvasItem key={item.id} id={item.id} label={WIDGETS[item.id].label} className="rounded-xl">
                        {WIDGETS[item.id].render()}
                    </CanvasItem>
                ))}
            </Canvas>
            <div className="flex justify-end">
                <StatusPill tone={saves ? 'positive' : 'default'} quiet={!saves}>
                    {saves ? `Layout saved (${saves})` : 'Drag a widget, or a handle to resize it'}
                </StatusPill>
            </div>
        </div>
    );
}
```

### Notes

```tsx
import { Button, Canvas, CanvasItem, type CanvasItemRect, Textarea } from '@rinzai/zen';
import { useRef, useState } from 'react';

interface Note extends CanvasItemRect {
    text: string;
    color: string;
}

const COLORS = ['var(--chart-4)', 'var(--chart-3)', 'var(--chart-5)', 'var(--chart-1)'];

/**
 * Sticky notes with a field in each: typing, selecting text and the × button work as usual, because
 * presses on fields and buttons inside an item go to them. Drag a note by its edge or top strip.
 */
export default function Notes() {
    const [notes, setNotes] = useState<Note[]>([
        { id: 'n1', x: 24, y: 24, w: 170, h: 150, color: COLORS[0], text: 'Rent goes out on the 1st' },
        { id: 'n2', x: 220, y: 60, w: 170, h: 150, color: COLORS[1], text: 'Move $400 to the holiday fund' },
        { id: 'n3', x: 420, y: 30, w: 170, h: 150, color: COLORS[2], text: 'Cancel the old phone plan' },
    ]);
    const [selected, setSelected] = useState<string[]>([]);
    const count = useRef(notes.length);
    const edit = (id: string, patch: Partial<Note>) =>
        setNotes((all) => all.map((n) => (n.id === id ? { ...n, ...patch } : n)));

    return (
        <div className="flex w-full max-w-3xl flex-col gap-3">
            <Canvas
                aria-label="Notes"
                width={620}
                height={260}
                scale="fit"
                minSize={120}
                items={notes}
                onItemsChange={setNotes}
                selected={selected}
                onSelectedChange={setSelected}
            >
                {notes.map((note, i) => (
                    <CanvasItem
                        key={note.id}
                        id={note.id}
                        label={`Note ${i + 1}`}
                        style={{ background: `color-mix(in oklch, ${note.color} 22%, oklch(var(--card)))` }}
                        className="flex flex-col overflow-hidden rounded-xl shadow-[0_10px_30px_-12px_oklch(0_0_0/0.6)]"
                    >
                        <div className="flex h-7 shrink-0 items-center justify-between pr-1 pl-3">
                            <span aria-hidden className="h-1 w-8 rounded-full" style={{ background: note.color }} />
                            <button
                                type="button"
                                aria-label={`Remove note ${i + 1}`}
                                onClick={() => setNotes((all) => all.filter((n) => n.id !== note.id))}
                                className="text-muted-foreground hover:text-foreground grid size-6 cursor-pointer place-items-center rounded-md"
                            >
                                ×
                            </button>
                        </div>
                        <Textarea
                            aria-label={`Note ${i + 1}`}
                            value={note.text}
                            onChange={(e) => edit(note.id, { text: e.target.value })}
                            className="min-h-0 flex-1 resize-none rounded-none border-0 bg-transparent px-3 pt-0 shadow-none"
                        />
                    </CanvasItem>
                ))}
            </Canvas>
            <div>
                <Button
                    size="sm"
                    variant="secondary"
                    onClick={() => {
                        const id = `n${++count.current}`;
                        setNotes((all) => [
                            ...all,
                            {
                                id,
                                x: 225,
                                y: 55,
                                w: 170,
                                h: 150,
                                color: COLORS[count.current % COLORS.length],
                                text: '',
                            },
                        ]);
                        setSelected([id]);
                    }}
                >
                    Add a note
                </Button>
            </div>
        </div>
    );
}
```

### Snapping

```tsx
import { Canvas, CanvasItem, type CanvasItemRect, Segmented, SegmentedItem } from '@rinzai/zen';
import { useState } from 'react';

type Mode = 'off' | 'guides' | 'grid';

/** Off: items go where you drop them. Guides (`snap`): edges and centres line up with the surface and each other. Grid (`grid`, here with `snap`): they keep to a 20-unit grid, its dots showing while you drag. */
export default function Snapping() {
    const [mode, setMode] = useState<Mode>('guides');
    const [items, setItems] = useState<CanvasItemRect[]>([
        { id: 'a', x: 20, y: 20, w: 120, h: 70 },
        { id: 'b', x: 210, y: 70, w: 100, h: 100 },
        { id: 'c', x: 330, y: 30, w: 100, h: 40 },
    ]);
    const [selected, setSelected] = useState<string[]>([]);
    return (
        <div className="flex flex-col items-start gap-3">
            <Segmented label="Snapping" value={mode} onValueChange={setMode}>
                <SegmentedItem value="off">Off</SegmentedItem>
                <SegmentedItem value="guides">Guides</SegmentedItem>
                <SegmentedItem value="grid">Grid</SegmentedItem>
            </Segmented>
            <Canvas
                aria-label="Layout"
                width={460}
                height={220}
                snap={mode !== 'off'}
                grid={mode === 'grid' ? 20 : undefined}
                items={items}
                onItemsChange={setItems}
                selected={selected}
                onSelectedChange={setSelected}
            >
                {items.map((item, n) => (
                    <CanvasItem
                        key={item.id}
                        id={item.id}
                        label={`Card ${n + 1}`}
                        className="glass text-muted-foreground grid place-items-center rounded-lg text-sm tabular-nums"
                    >
                        {item.x}, {item.y}
                    </CanvasItem>
                ))}
            </Canvas>
        </div>
    );
}
```

## API reference

### Canvas

A fixed-size surface where items sit anywhere, such as the cards of a
stream overlay or a slide. Drag an item to move it, and the handles of the
selected one to resize it (Shift keeps its shape); Escape mid-drag puts it
back. Shift- or Cmd-click, or drag a box on empty space, to select several
and move them together. From the keyboard, Tab reaches each item, the arrow
keys move the selection (Shift by 10), Alt and the arrow keys resize, Cmd or
Ctrl+A selects all, and Escape deselects; each change is announced.

Items stay on the surface; with `snap` they line up with its edges and
centre and with each other, and with `grid` they keep to a grid. `scale`
shows the design larger or smaller, or `"fit"` fills the width it's given.
`onItemsChange` gets the items with every step of a change; `onItemsChangeEnd`, once
it's made, with the items before it, for undo or saving.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `height` (required) | `number` |  |  |
| `items` (required) | `readonly T[]` |  | Where each item is (other fields are kept); render a CanvasItem for each. |
| `onItemsChange` (required) | `(items: T[]) => void` |  | The items, with every step of a move or resize. |
| `width` (required) | `number` |  | The surface's size, in your design's units (px at scale 1). |
| `grid` | `number` |  | Keep positions and sizes to multiples of this (design units) when no line is in reach. |
| `minSize` | `number` | `8` | Smallest width and height an item can be resized to. |
| `onItemsChangeEnd` | `((items: T[], before: readonly T[]) => void)` |  | The items once a change is made (a drag let go, a key pressed), and as they were before: for undo or saving. |
| `onSelectedChange` | `((ids: string[]) => void)` |  |  |
| `scale` | `"fit" \| number` | `1` | How large to show it: 2 shows a 400×120 design 800×240; "fit" fills the width it's given. Positions stay in design units. |
| `selected` | `readonly string[]` | `[]` | The selected items' ids. |
| `snap` | `boolean \| number` | `false` | Line items up with the surface and each other: true, or how close counts, in screen px (true is 6). |

### CanvasItem

One item on a Canvas, placed where the canvas's `items` say for its `id`;
later items sit on top of earlier ones. `label` names it ("Title") in what's
announced. Its content is yours: fields and buttons in it work as usual,
and pressing them doesn't drag it (nor anything with data-canvas-no-drag).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` (required) | `string` |  |  |
| `label` (required) | `string` |  | The item's name, e.g. "Title", for what's announced. |

---

# Card

Glass panels for grouping content, and stats for single figures.

```tsx
import { Card, CardHeader, CardTitle, CardDescription, Stat, StatRow } from '@rinzai/zen';
```

## Examples

### Goal

```tsx
import {
    Button,
    buttonVariants,
    Card,
    CardHeader,
    CardTitle,
    Menu,
    MenuContent,
    MenuItem,
    MenuTrigger,
    ProgressRing,
} from '@rinzai/zen';
// Icons from Heroicons (https://heroicons.com): Ellipsis (ellipsis-horizontal).

export default function Goal() {
    return (
        <Card className="w-full max-w-sm">
            <CardHeader>
                <CardTitle>Emergency fund</CardTitle>
                <Menu>
                    <MenuTrigger
                        aria-label="Goal actions"
                        className={buttonVariants({ variant: 'ghost', size: 'icon' })}
                    >
                        <Ellipsis />
                    </MenuTrigger>
                    <MenuContent>
                        <MenuItem>Edit</MenuItem>
                    </MenuContent>
                </Menu>
            </CardHeader>
            <div className="flex items-center gap-4">
                <ProgressRing value={0.64} label="Emergency fund">
                    <span className="text-sm font-semibold tabular-nums">64%</span>
                </ProgressRing>
                <div className="flex flex-col gap-1">
                    <span className="text-muted-foreground text-sm">$6,400 of $10,000</span>
                    <Button size="sm" variant="secondary" className="self-start">
                        Add money
                    </Button>
                </div>
            </div>
        </Card>
    );
}
```

### Stats

```tsx
import { Stat, StatRow } from '@rinzai/zen';

export default function Stats() {
    return (
        <StatRow className="w-full max-w-3xl">
            <Stat label="Income" value="$8,450" hint="+4% on last month" />
            <Stat label="Spent" value="$5,120" tone="negative" />
            <Stat label="Net this month" value="$3,330" tone="positive" />
        </StatRow>
    );
}
```

### Morph

```tsx
import { Button, Card, CardDescription, CardHeader, CardTitle, Sparkline } from '@rinzai/zen';
import { startTransition, useState, ViewTransition } from 'react';

const accounts = [
    { id: 'checking', name: 'Checking', balance: '$4,280.15', trend: [31, 34, 30, 38, 36, 42, 40, 45] },
    { id: 'savings', name: 'Savings', balance: '$12,940.00', trend: [80, 82, 83, 85, 86, 88, 91, 94] },
    { id: 'card', name: 'Credit card', balance: '−$612.40', trend: [12, 18, 15, 22, 27, 21, 30, 26] },
];

export default function Morph() {
    const [open, setOpen] = useState<string | null>(null);
    const go = (id: string | null) => startTransition(() => setOpen(id));
    const account = accounts.find((a) => a.id === open);

    if (account)
        return (
            <ViewTransition name={`account-${account.id}`} share="zen-morph">
                <Card className="w-full max-w-md">
                    <CardHeader>
                        <CardTitle>{account.name}</CardTitle>
                        <Button size="sm" variant="ghost" onClick={() => go(null)}>
                            Back
                        </Button>
                    </CardHeader>
                    <p className="text-3xl font-semibold tabular-nums">{account.balance}</p>
                    <CardDescription className="mt-1">Last 8 weeks</CardDescription>
                    <Sparkline values={account.trend} className="mt-4 h-24 w-full" />
                </Card>
            </ViewTransition>
        );

    return (
        <div className="grid w-full max-w-md gap-3">
            {accounts.map((a) => (
                <ViewTransition key={a.id} name={`account-${a.id}`} share="zen-morph">
                    <Card className="p-0 md:p-0">
                        <button
                            type="button"
                            onClick={() => go(a.id)}
                            className="flex w-full items-center justify-between rounded-xl p-4 text-left"
                        >
                            <span className="font-medium">{a.name}</span>
                            <span className="tabular-nums">{a.balance}</span>
                        </button>
                    </Card>
                </ViewTransition>
            ))}
        </div>
    );
}
```

## API reference

### Card

Glass panel whose border catches the pointer light. For a title with an
action beside it, start it with a CardHeader holding a CardTitle and the action.

No props of its own; it accepts the props of the element it renders.

### CardHeader

The top row of a Card: its title, and an action (a button, a menu) at the end.

No props of its own; it accepts the props of the element it renders.

### CardTitle

The card's title: an h4 by default; with `asChild`, your own heading (an h2, say) gets its look.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `asChild` | `boolean` |  | Put the title's look on your own heading element instead of an h4. |

### CardDescription

A line under the CardTitle: what the card is about, or a figure's context ("₹12L at 8.5% · 20 years").

No props of its own; it accepts the props of the element it renders.

### Stat

A single figure with a label, e.g. "Revenue  $12,400".

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` |  |  |
| `value` (required) | `ReactNode` |  |  |
| `children` | `ReactNode` |  | Under the figure: how it got there, like a Sparkline. |
| `className` | `string` |  |  |
| `hint` | `ReactNode` |  |  |
| `tone` | `"default" \| "negative" \| "positive"` | `default` |  |

### StatRow

Row of stats: two columns on phones (an odd last one spans both), three from `sm` up.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` |  |  |

---

# Carousel

Slides in a row that snap as you swipe or scroll, with glass buttons and dots that light the current one beneath, and the arrow keys. Native scrolling, so it follows the finger exactly.

```tsx
import { Carousel, CarouselContent, CarouselItem, CarouselControls, CarouselPrevious, CarouselNext, CarouselDots } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import {
    Card,
    Carousel,
    CarouselContent,
    CarouselControls,
    CarouselDots,
    CarouselItem,
    CarouselNext,
    CarouselPrevious,
    ProgressRing,
} from '@rinzai/zen';

const GOALS = [
    { name: 'Emergency fund', saved: 6400, target: 10000 },
    { name: 'New laptop', saved: 1150, target: 1800 },
    { name: 'Trip to Kyoto', saved: 2100, target: 4500 },
    { name: 'Wedding gift', saved: 300, target: 300 },
];

const usd = new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD', maximumFractionDigits: 0 });

/** One slide at a time, with buttons and dots below. Swipe or scroll it too, or focus it and use the arrow keys. */
export default function Default() {
    return (
        <Carousel aria-label="Savings goals" className="w-full max-w-sm">
            <CarouselContent>
                {GOALS.map((goal) => (
                    <CarouselItem key={goal.name}>
                        <Card className="flex items-center gap-5">
                            <ProgressRing value={goal.saved / goal.target} label={goal.name}>
                                <span className="text-sm font-semibold tabular-nums">
                                    {Math.round((goal.saved / goal.target) * 100)}%
                                </span>
                            </ProgressRing>
                            <div className="flex min-w-0 flex-col gap-1">
                                <span className="truncate font-medium">{goal.name}</span>
                                <span className="text-muted-foreground text-sm tabular-nums">
                                    {usd.format(goal.saved)} of {usd.format(goal.target)}
                                </span>
                            </div>
                        </Card>
                    </CarouselItem>
                ))}
            </CarouselContent>
            <CarouselControls>
                <CarouselPrevious />
                <CarouselDots />
                <CarouselNext />
            </CarouselControls>
        </Carousel>
    );
}
```

### Several

```tsx
import { Carousel, CarouselContent, CarouselControls, CarouselItem, CarouselNext, CarouselPrevious } from '@rinzai/zen';

const CATEGORIES = [
    { name: 'Groceries', spent: '$412', chart: 6 },
    { name: 'Rent', spent: '$1,600', chart: 7 },
    { name: 'Transport', spent: '$96', chart: 1 },
    { name: 'Eating out', spent: '$238', chart: 2 },
    { name: 'Subscriptions', spent: '$54', chart: 5 },
    { name: 'Health', spent: '$120', chart: 3 },
];

/**
 * Several slides in view: size the items (here a half, then a third on wider
 * screens). It snaps to each; the buttons sit together at the end, each gone when there's no further to go.
 */
export default function Several() {
    return (
        <Carousel aria-label="Spending by category" className="w-full max-w-xl">
            <CarouselContent className="gap-3">
                {CATEGORIES.map((c) => (
                    <CarouselItem key={c.name} className="basis-[calc(50%-0.375rem)] sm:basis-[calc(33.333%-0.5rem)]">
                        <div
                            className="border-tint/10 flex h-28 flex-col justify-end gap-0.5 rounded-xl border p-4"
                            style={{
                                // The chart palette, so each category looks as it does in charts.
                                background: `linear-gradient(160deg, color-mix(in oklch, var(--chart-${c.chart}) 35%, transparent), color-mix(in oklch, var(--chart-${c.chart}) 6%, transparent))`,
                            }}
                        >
                            <span className="text-muted-foreground text-xs">{c.name}</span>
                            <span className="text-lg font-semibold tabular-nums">{c.spent}</span>
                        </div>
                    </CarouselItem>
                ))}
            </CarouselContent>
            <CarouselControls className="justify-end">
                <CarouselPrevious />
                <CarouselNext />
            </CarouselControls>
        </Carousel>
    );
}
```

## API reference

### Carousel

Slides in a row that scrolls sideways and snaps to each one: swipe, scroll,
use the arrow keys once it has focus, or the CarouselPrevious and
CarouselNext buttons. Put a CarouselContent of CarouselItems inside, then a
CarouselControls of the buttons and CarouselDots if you want them. A slide is as wide as the
carousel unless you size it (e.g. `basis-1/3` for three in view).

No props of its own; it accepts the props of the element it renders.

### CarouselContent

The scrolling row of slides.

No props of its own; it accepts the props of the element it renders.

### CarouselItem

One slide: it's announced as which of how many.

No props of its own; it accepts the props of the element it renders.

### CarouselControls

The row under the slides: CarouselPrevious at the start, CarouselNext at the end, CarouselDots between.

No props of its own; it accepts the props of the element it renders.

### CarouselPrevious

Scroll back one slide: a round glass button, gone at the first (keeping its
place, so the controls don't shift). Put it in CarouselControls, under the
slides, where it never covers them.

No props of its own; it accepts the props of the element it renders.

### CarouselNext

Scroll on one slide: a round glass button, gone at the last.

No props of its own; it accepts the props of the element it renders.

### CarouselDots

A dot for each place it can scroll to, the current one drawn out long and lit; each goes there.

No props of its own; it accepts the props of the element it renders.

---

# Chart

Areas, lines and bars on one axis, a donut and an allocation bar: plain SVG that draws itself in, with a crosshair tooltip, keyboard reading, a legend and a table for screen readers.

```tsx
import { Chart, ChartArea, ChartLine, ChartBar, ChartReference, ChartTooltipCard, DonutChart, AllocationBar } from '@rinzai/zen';
```

## Examples

### Balance

```tsx
import { Chart, ChartArea, ChartReference } from '@rinzai/zen';

const MONTHS = [
    '2026-04',
    '2026-05',
    '2026-06',
    '2026-07',
    '2026-08',
    '2026-09',
    '2026-10',
    '2026-11',
    '2026-12',
    '2027-01',
    '2027-02',
    '2027-03',
];
const BALANCE = [4.2, 5.1, 3.8, 4.6, 6.2, 7.1, 6.4, 7.9, 8.8, 7.6, 9.4, 10.2].map((l) => l * 100000);
const TODAY = '2026-09';
// One series split in two at today: solid where it happened, dashed where it's projected.
const DATA = MONTHS.map((month, i) => ({
    month,
    balance: month <= TODAY ? BALANCE[i] : null,
    projected: month >= TODAY ? BALANCE[i] : null,
}));
const label = (m: string) => new Date(`${m}-01T00:00Z`).toLocaleString('en-IN', { month: 'short', timeZone: 'UTC' });
const money = new Intl.NumberFormat('en-IN', {
    style: 'currency',
    currency: 'INR',
    notation: 'compact',
    maximumFractionDigits: 1,
});

/** An area in the theme's glow: solid up to today, dashed ahead, with a "Today" marker. Point at it, or focus it and use the arrow keys. */
export default function Balance() {
    return (
        <Chart
            data={DATA}
            x="month"
            label="Balance over time"
            summary="Balance grows from ₹4.2L in April to a projected ₹10.2L next March."
            formatX={label}
            formatY={(v) => money.format(v)}
            className="w-full max-w-2xl"
        >
            <ChartArea dataKey="balance" label="Balance" color="oklch(var(--glow))" />
            <ChartArea dataKey="projected" label="Projected" color="oklch(var(--glow-2))" dashed />
            <ChartReference x={TODAY} label="Today" />
        </Chart>
    );
}
```

### Cashflow

```tsx
import { Chart, ChartBar, ChartLine, ChartReference } from '@rinzai/zen';

const DATA = [
    { month: 'Apr', income: 92000, spending: 61000 },
    { month: 'May', income: 92000, spending: 74000 },
    { month: 'Jun', income: 98000, spending: 58000 },
    { month: 'Jul', income: 98000, spending: 103000 },
    { month: 'Aug', income: 98000, spending: 66000 },
    { month: 'Sep', income: 112000, spending: 71000 },
    { month: 'Oct', income: 112000, spending: 69000 },
    { month: 'Nov', income: 112000, spending: 80000 },
].map((r) => ({ ...r, net: r.income - r.spending }));
const inr = new Intl.NumberFormat('en-IN', {
    style: 'currency',
    currency: 'INR',
    notation: 'compact',
    maximumFractionDigits: 1,
});

/** Bars grouped by month with a line on the same axis; months still to come are faded. */
export default function Cashflow() {
    return (
        <Chart
            data={DATA}
            x="month"
            label="Income and spending by month"
            formatY={(v) => inr.format(v)}
            className="w-full max-w-2xl"
        >
            <ChartBar dataKey="income" label="Income" dim={(_, i) => i > 5} />
            <ChartBar dataKey="spending" label="Spending" dim={(_, i) => i > 5} />
            <ChartLine dataKey="net" label="Net" color="var(--chart-3)" />
            <ChartReference y={0} tone="negative" />
        </Chart>
    );
}
```

### Lines

```tsx
import { Chart, ChartLine } from '@rinzai/zen';

const DATA = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'].map((day, i) => ({
    day,
    web: [420, 480, 510, 470, 560, 690, 640][i],
    ios: [310, 330, 360, 390, 380, 450, 470][i],
    android: [220, 260, 250, 300, 330, 310, 360][i],
}));

/** Several series in the chart palette, in the order they're written; the legend appears for two or more. */
export default function Lines() {
    return (
        <Chart data={DATA} x="day" label="Sessions by platform" height={220} className="w-full max-w-2xl">
            <ChartLine dataKey="web" label="Web" />
            <ChartLine dataKey="ios" label="iOS" />
            <ChartLine dataKey="android" label="Android" />
        </Chart>
    );
}
```

### Donut

```tsx
import { DonutChart, paletteColor } from '@rinzai/zen';

const SPENDING = [
    { key: 'home', label: 'Home', value: 28000 },
    { key: 'food', label: 'Food', value: 14500 },
    { key: 'travel', label: 'Travel', value: 9200 },
    { key: 'fun', label: 'Fun', value: 6100 },
    { key: 'other', label: 'Other', value: 3400 },
];
const total = SPENDING.reduce((s, x) => s + x.value, 0);
const inr = (v: number) =>
    new Intl.NumberFormat('en-IN', { style: 'currency', currency: 'INR', maximumFractionDigits: 0 }).format(v);

/** Parts of a whole with the total in the middle, and a legend of your own beside it, in the chart's colours (paletteColor). */
export default function Donut() {
    return (
        <div className="flex flex-wrap items-center gap-8">
            <DonutChart items={SPENDING} label="Spending by category" formatValue={inr}>
                <div>
                    <div className="text-muted-foreground text-[0.68rem] tracking-[0.1em] uppercase">Spent</div>
                    <div className="text-lg font-semibold tracking-tight">{inr(total)}</div>
                </div>
            </DonutChart>
            <ul className="flex min-w-48 flex-col gap-2 text-sm">
                {SPENDING.map((s, i) => (
                    <li key={s.key} className="flex items-center gap-2.5">
                        <span
                            className="size-2.5 rounded-[3px]"
                            style={{ background: paletteColor('chart', i, SPENDING.length) }}
                        />
                        <span className="flex-1">{s.label}</span>
                        <span className="font-medium tabular-nums">{inr(s.value)}</span>
                    </li>
                ))}
            </ul>
        </div>
    );
}
```

### Allocation

```tsx
import { AllocationBar, formatMoney } from '@rinzai/zen';

/** Where September's income went. */
export default function Allocation() {
    return (
        <AllocationBar
            label="Income in September"
            className="w-full max-w-md"
            locale="en-US"
            formatValue={(v) => formatMoney(v, 'USD', 'en-US', { showDecimals: false })}
            items={[
                { key: 'bills', label: 'Bills', value: 182000 },
                { key: 'spending', label: 'Spending', value: 145600 },
                { key: 'savings', label: 'Savings', value: 96000 },
                { key: 'investing', label: 'Investing', value: 50000 },
                { key: 'left', label: 'Left over', value: 26400 },
            ]}
        />
    );
}
```

## API reference

### Chart

A chart on one axis: areas, lines and bars over rows of data (e.g. months),
with a recessive grid, a crosshair and a tooltip listing every series at the
pointer (or keyboard: focus it and use the arrow keys), a legend for two or
more series, and a table of the values for screen readers. Series draw in
as they appear. Colours default to the chart palette (--chart-1…8) in the
order the series are written; give each its own `color` for meaning (e.g.
the theme's glow).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` |  | ChartArea, ChartLine, ChartBar and ChartReference parts. |
| `data` (required) | `readonly T[]` |  | One row per point on the x axis (e.g. a month). |
| `label` (required) | `string` |  | Names the chart for screen readers. |
| `x` (required) | `string` |  | The row field placed along the x axis. |
| `className` | `string` |  |  |
| `formatTooltipX` | `((value: T[X]) => string)` |  | The tooltip's title for an x value (defaults to formatX). |
| `formatX` | `((value: T[X]) => string)` |  | Axis labels for x values. |
| `formatY` | `((value: number) => string)` | `(n: number) => compactFormat.format(n)` | Axis ticks and tooltip values (defaults to compact numbers: 1.2K). |
| `height` | `number` | `240` | Height in px, including the axis labels. |
| `legend` | `boolean` |  | Show the legend. Defaults to on for two or more series, or a bar's `dimLabel`. |
| `palette` | `ChartPalette` | `chart` | Colours for series that don't give their own: the categorical palette (default), or shades of the theme's glow. |
| `renderTooltip` | `((row: T, index: number) => ReactNode)` |  | Your own tooltip for a row (build it from ChartTooltipCard). |
| `summary` | `string` |  | A sentence on what the chart shows, for screen readers (e.g. its highest and lowest points). |

### ChartArea

A line with a soft fill down to the baseline.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `dataKey` (required) | `string` |  | The row field holding this series' values (numbers; null for none). |
| `label` (required) | `string` |  | Its name in the legend, the tooltip and the table. |
| `color` | `string` |  | Any CSS colour. Defaults to the next of --chart-1…8. |
| `curve` | `"linear" \| "monotone"` |  | Smooth (default) or straight between points. |
| `dashed` | `boolean` |  | Dashed (e.g. a projection). |

### ChartLine

A 2px line. Gaps (null values) break it, so one series can be split into solid and dashed parts.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `dataKey` (required) | `string` |  | The row field holding this series' values (numbers; null for none). |
| `label` (required) | `string` |  | Its name in the legend, the tooltip and the table. |
| `color` | `string` |  | Any CSS colour. Defaults to the next of --chart-1…8. |
| `curve` | `"linear" \| "monotone"` |  | Smooth (default) or straight between points. |
| `dashed` | `boolean` |  | Dashed (e.g. a projection). |

### ChartBar

Bars, grouped with the other bar series, growing from the baseline.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `dataKey` (required) | `string` |  | The row field holding this series' values (numbers; null for none). |
| `label` (required) | `string` |  | Its name in the legend, the tooltip and the table. |
| `color` | `string` |  | Any CSS colour. Defaults to the next of --chart-1…8. |
| `dim` | `((row: Row, index: number) => boolean)` |  | Rows whose bar is faded, e.g. months still to come. |
| `dimLabel` | `string` |  | What the faded bars mean, e.g. "Planned": the legend gets a faded key for it (and shows, even for one series). |

### ChartReference

A marker across the plot: a horizontal line at `y` (e.g. zero), or a vertical one at the row whose x is `x` (e.g. today).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `dashed` | `boolean` |  | Vertical lines are dashed unless `dashed={false}`; horizontal ones solid unless `dashed`. |
| `label` | `string` |  | Text beside a vertical line, e.g. "Today". |
| `tone` | `"muted" \| "negative"` |  | Destructive for a line that warns (e.g. below zero). |
| `x` | `unknown` |  | A vertical line at the row whose x field equals this. |
| `y` | `number` |  | A horizontal line at this value. |

### ChartTooltipCard

The tooltip's card: a title and one row per series, the value first and the
series keyed by a short stroke of its colour. Use it in `renderTooltip` to
show your own rows.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `rows` (required) | `{ label: string; value: string; color?: string \| undefined; dashed?: boolean \| undefined; }[]` |  |  |
| `title` (required) | `ReactNode` |  |  |
| `className` | `string` |  |  |

### DonutChart

A ring of parts of a whole (e.g. spending by category), with your content in
the middle (e.g. the total). Segments are parted by a small gap, with
rounded corners; pointing at one (or focusing it) lifts it and shows its
value. A part too small to show at its share is drawn as a pill, the
narrowest segment, taking the room from the larger parts in proportion. Best
for a handful of parts: past about six, use bars. Colours default to the
chart palette in order.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `{ key: string; label: string; value: number; color?: string \| undefined; }[]` |  | The parts, in order round the ring from 12 o'clock. |
| `label` (required) | `string` |  | Names the chart for screen readers. |
| `children` | `ReactNode` |  | Content in the middle, e.g. the total. |
| `className` | `string` |  |  |
| `formatValue` | `((value: number) => string)` |  | Values in the tooltip and for screen readers. |
| `palette` | `ChartPalette` | `chart` | Colours for items that don't give their own: the categorical palette (default), or shades of the theme's glow. |
| `size` | `number` | `200` | Diameter in px. |
| `thickness` | `number` | `0.32` | Ring thickness as a share of the radius. |

### AllocationBar

Where a whole went, as one bar split into its parts (e.g. income across
spending, savings and bills), with a legend of each part's value and share.
Pointing at a part, in the bar or the legend, picks it out; screen readers
hear every part's value and share from the bar's label. Sweeps in from
the start the first time it's seen. Colours default to the chart palette in
order, like DonutChart's.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `AllocationItem[]` |  |  |
| `label` (required) | `string` |  | What the whole is, e.g. "Income in September", for screen readers. |
| `className` | `string` |  |  |
| `formatValue` | `((value: number) => string)` |  |  |
| `legend` | `boolean` | `true` | The list of parts under the bar (default on). |
| `locale` | `string` |  | For the shares' percent format. |
| `palette` | `ChartPalette` | `chart` | Colours for items that don't give their own: the categorical palette (default), or shades of the theme's glow. |

---

# Checkbox

A native checkbox whose tick draws itself in, with a label, a description and a mixed state.

```tsx
import { Checkbox } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { Checkbox } from '@rinzai/zen';
import { useState } from 'react';

/** With a label and a description; the tick draws itself in. */
export default function Default() {
    const [remind, setRemind] = useState(true);
    const [share, setShare] = useState(false);
    return (
        <div className="flex flex-col gap-4">
            <Checkbox checked={remind} onCheckedChange={setRemind} description="A nudge on the 1st of each month.">
                Remind me to log spending
            </Checkbox>
            <Checkbox checked={share} onCheckedChange={setShare}>
                Share anonymous usage data
            </Checkbox>
            <Checkbox disabled>Sync to the cloud (coming soon)</Checkbox>
        </div>
    );
}
```

### Select all

```tsx
import { Checkbox } from '@rinzai/zen';
import { useState } from 'react';

const ACCOUNTS = ['Salary account', 'Credit card', 'Savings'];

/** A "select all" that shows a dash while only some are checked. */
export default function SelectAll() {
    const [picked, setPicked] = useState<string[]>(['Credit card']);
    const all = picked.length === ACCOUNTS.length;
    return (
        <div className="flex flex-col gap-3">
            <Checkbox
                checked={all}
                indeterminate={picked.length > 0 && !all}
                onCheckedChange={() => setPicked(all ? [] : ACCOUNTS)}
                className="font-medium"
            >
                All accounts
            </Checkbox>
            <div className="flex flex-col gap-3 pl-7">
                {ACCOUNTS.map((a) => (
                    <Checkbox
                        key={a}
                        checked={picked.includes(a)}
                        onCheckedChange={(on) => setPicked((p) => (on ? [...p, a] : p.filter((x) => x !== a)))}
                    >
                        {a}
                    </Checkbox>
                ))}
            </div>
        </div>
    );
}
```

## API reference

### Checkbox

A checkbox: a native one, styled, so forms, the keyboard and screen readers
work as usual. The tick draws itself in when checked; `indeterminate` shows a
dash (e.g. "some selected"). With children, they're its label (and
`description` a line under it); without, label it yourself or put it in a Field.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` |  | The label. |
| `className` | `string` |  | Classes for the label (or, without one, the box). |
| `description` | `ReactNode` |  | A muted line under the label. |
| `indeterminate` | `boolean` | `false` | Shows a dash instead of the tick, e.g. when some of a group are checked. |
| `onCheckedChange` | `((checked: boolean) => void)` |  |  |

---

# Chip

Small pressable buttons for quick picks beside a field, like common tenures.

```tsx
import { Chip } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { Chip, Input } from '@rinzai/zen';
import { useState } from 'react';

const YEARS = [5, 10, 15, 20, 30];

/** Quick picks beside a field: the chip matching the field's value shows pressed. */
export default function Default() {
    const [years, setYears] = useState('20');
    return (
        <div className="flex flex-col gap-3">
            <Input
                aria-label="Tenure in years"
                value={years}
                onChange={(e) => setYears(e.target.value)}
                className="w-24"
            />
            <div role="group" aria-label="Common tenures" className="flex flex-wrap gap-1.5">
                {YEARS.map((y) => (
                    <Chip key={y} pressed={years === String(y)} onClick={() => setYears(String(y))}>
                        {y} yrs
                    </Chip>
                ))}
            </div>
        </div>
    );
}
```

## API reference

### Chip

A small rounded button that can be pressed in, for quick picks beside a
field (e.g. common tenures): `pressed` marks the one matching the field.
For choosing exactly one of a few options, use Segmented.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `pressed` | `boolean` |  | Shown pressed in (aria-pressed). |

---

# Code Block

Code with a copy button; bring your own highlighter for colours. The copy button runs on useCopyToClipboard, which you can use for copy buttons anywhere.

```tsx
import { CodeBlock, useCopyToClipboard } from '@rinzai/zen';
```

## Examples

### Highlighted

```tsx
import { CodeBlock } from '@rinzai/zen';
import { highlight } from 'sugar-high';

const CODE = `import { Button } from '@rinzai/zen';

export default function Save() {
    return <Button loading>Saving…</Button>;
}`;

/** Colours come from any highlighter that turns code into HTML; here sugar-high. Hover to copy. */
export default function Highlighted() {
    return (
        <CodeBlock
            code={CODE}
            language="typescript"
            highlight={(code) => highlight(code)}
            className="w-full max-w-xl"
        />
    );
}
```

### Plain

```tsx
import { CodeBlock } from '@rinzai/zen';

/** Without a highlighter, the code shows as plain text. */
export default function Plain() {
    return <CodeBlock code="pnpm add @rinzai/zen" language="shell" className="w-full max-w-xl" />;
}
```

### In card

```tsx
import { Card, CardHeader, CardTitle, CodeBlock } from '@rinzai/zen';

/** Inside a card or panel that already has a surface, `variant="plain"` drops the block's own. */
export default function InCard() {
    return (
        <Card className="w-full max-w-xl overflow-hidden p-0!">
            <CardHeader className="mb-0 px-5 pt-5">
                <CardTitle>Install</CardTitle>
            </CardHeader>
            <CodeBlock variant="plain" code="pnpm add @rinzai/zen" language="shell" />
        </Card>
    );
}
```

### Copy button

```tsx
import { Button, InputGroup, InputGroupAddon, InputGroupInput, useCopyToClipboard } from '@rinzai/zen';
import { useRef } from 'react';

const LINK = 'https://zen.rinzai.dev/components/code-block/';

/**
 * A copy button of your own, with the hook CodeBlock copies with: `copy` resolves false when the
 * browser won't copy, and here the link is then selected to copy by hand.
 */
export default function CopyButton() {
    const { copy, copied } = useCopyToClipboard();
    const input = useRef<HTMLInputElement>(null);
    return (
        <InputGroup className="w-full max-w-sm pr-1">
            <InputGroupInput ref={input} value={LINK} readOnly aria-label="Link" />
            <InputGroupAddon>
                <Button
                    variant="ghost"
                    size="sm"
                    className="h-7"
                    onClick={async () => {
                        if (await copy(LINK)) return;
                        input.current?.focus();
                        input.current?.select();
                    }}
                >
                    {copied ? 'Copied' : 'Copy'}
                </Button>
            </InputGroupAddon>
        </InputGroup>
    );
}
```

## API reference

### CodeBlock

Code on a glass panel whose edge catches the pointer light, with a copy
button. Give it a max height (className) and the code scrolls inside. Zen ships no highlighter: pass `highlight` (code → HTML string, e.g.
sugar-high's `highlight`) for colours.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `code` (required) | `string` |  |  |
| `copyable` | `boolean` | `true` | Show the copy button (on hover and focus). |
| `highlight` | `((code: string, language?: string) => string)` |  | Turns the code into HTML with coloured tokens. Without it, plain text. |
| `language` | `string` |  | Passed to `highlight`, and set as data-language. |
| `variant` | `"glass" \| "plain"` | `glass` | `glass` (default): its own lit glass panel. `plain`: no surface, for code inside a card or panel. |

---

# Code Input

A one-time code, a box per character, that types, pastes and autofills from a text message like any field.

```tsx
import { CodeInput } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { CodeInput, Field } from '@rinzai/zen';
import { useState } from 'react';

/** A six-digit sign-in code, checked as soon as it's complete. */
export default function Default() {
    const [code, setCode] = useState('');
    const [checked, setChecked] = useState<string>();
    return (
        <Field label="Sign-in code" hint={checked ? `Checking ${checked}…` : 'We sent it to your phone.'}>
            <CodeInput
                value={code}
                onValueChange={(next) => {
                    setCode(next);
                    setChecked(undefined);
                }}
                onComplete={setChecked}
            />
        </Field>
    );
}
```

## API reference

### CodeInput

A one-time code (sign-in, verification): a box per character. It's one real
field under the boxes, so typing, pasting, deleting and the phone's
autofill from a text message all work as in any field. `onComplete` gets the
code once every box is filled.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `allowed` | `RegExp` | `/\d/` | Which characters count (one at a time); digits by default. Others typed or pasted are dropped. |
| `defaultValue` | `string` |  |  |
| `length` | `number` | `6` | How many characters (boxes). |
| `onComplete` | `((code: string) => void)` |  | Called with the code when the last box is filled. |
| `onValueChange` | `((value: string) => void)` |  |  |
| `value` | `string` |  |  |

---

# Collapse

Shows as many items as fit on one line, and the rest behind "+N".

```tsx
import { Collapse } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { Badge, Collapse } from '@rinzai/zen';

const TAGS = ['Groceries', 'Rent', 'Transport', 'Dining out', 'Subscriptions', 'Travel', 'Gifts', 'Health', 'Books'];

/** Shows as many tags as fit on one line, and the rest behind "+N". Resize the window to see it adapt. */
export default function Default() {
    return (
        <Collapse items={TAGS} className="w-full max-w-md gap-1">
            {(tag) => <Badge variant="secondary">{tag}</Badge>}
        </Collapse>
    );
}
```

## API reference

### Collapse

A row showing as many items as fit on one line, and the rest behind a "+N"
button that opens them in a popover. It measures the items as rendered (any
content, font or style), and fits again whenever the row resizes. Its width
is the room it's given, not its items': size the row with className (e.g.
w-full, max-w-md, gap-1).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `(item: string, index: number, itemData?: TData \| undefined) => ReactNode` |  | Renders one item (in the row, or in the popover when it doesn't fit). |
| `items` (required) | `string[]` |  |  |
| `badgeClassName` | `string` |  | Classes for the "+N" badge. |
| `badgeVariant` | `"default" \| "outline" \| "secondary" \| null` | `secondary` |  |
| `className` | `string` |  | Classes for the row: its width, and the gap between items. |
| `data` | `TData[]` |  | Extra data per item, passed to `children` with it. |
| `moreLabel` | `string` |  | Text after the count on the "+N" button, e.g. "tags". |

---

# Color Picker

Pick a colour by eye or by hex: a saturation and brightness area, hue and opacity, and your own swatches. With hexToOklch to give a colour to the theme engine.

```tsx
import { ColorPicker, ColorPanel, hexToOklch, oklchToHex } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { ColorPicker, Field } from '@rinzai/zen';
import { useState } from 'react';

export default function Default() {
    const [color, setColor] = useState('#7c5cff');
    return (
        <Field label="Title colour" className="w-64">
            <ColorPicker value={color} onValueChange={setColor} />
        </Field>
    );
}
```

### Swatches

```tsx
import { ColorPicker, Field } from '@rinzai/zen';
import { useState } from 'react';

const SWATCHES = [
    { label: 'Violet', value: '#7c5cff' },
    { label: 'Teal', value: '#2bb3a3' },
    { label: 'Amber', value: '#f0a83a' },
    { label: 'Rose', value: '#ef5a7a' },
    { label: 'White', value: '#ffffff' },
    { label: 'Black', value: '#000000' },
];

/** With `alpha`, an opacity slider, and values like "#7c5cff99". Swatches are yours, such as your brand's colours. */
export default function Swatches() {
    const [color, setColor] = useState('#2bb3a3cc');
    return (
        <Field label="Card background" className="w-64">
            <ColorPicker value={color} onValueChange={setColor} alpha swatches={SWATCHES} />
        </Field>
    );
}
```

### Inline

```tsx
import { Card, ColorPanel } from '@rinzai/zen';
import { useState } from 'react';

/** ColorPanel is the picker's panel on its own, for a sidebar or an inspector. `onValueCommit` fires once a change is made, the moment to save. */
export default function Inline() {
    const [color, setColor] = useState('#ef5a7a');
    const [saved, setSaved] = useState(color);
    return (
        <Card className="flex flex-col gap-3 p-4!">
            <ColorPanel value={color} onValueChange={setColor} onValueCommit={setSaved} />
            <p className="text-muted-foreground mt-0! text-xs">
                Saved: <span className="text-foreground font-mono">{saved}</span>
            </p>
        </Card>
    );
}
```

### Accent

```tsx
import { applyTheme, Badge, Button, ColorPicker, customize, DEFAULT_THEME, Field, hexToOklch } from '@rinzai/zen';
import { useEffect, useRef, useState } from 'react';

/** `hexToOklch` gives a picked colour's hue to the theme engine, which keeps it readable in dark and light. */
export default function Accent() {
    const [color, setColor] = useState('#2bb3a3');
    const preview = useRef<HTMLDivElement>(null);
    useEffect(() => {
        const oklch = hexToOklch(color);
        const root = document.documentElement;
        const apply = () =>
            oklch &&
            preview.current &&
            applyTheme(customize(DEFAULT_THEME, { hue: Math.round(oklch.h) }), {
                appearance: root.classList.contains('light') ? 'light' : 'dark',
                target: preview.current,
            });
        apply();
        const watch = new MutationObserver(apply);
        watch.observe(root, { attributes: true, attributeFilter: ['class'] });
        return () => watch.disconnect();
    }, [color]);
    return (
        <div className="flex flex-wrap items-end gap-6">
            <Field label="Accent" className="w-56">
                <ColorPicker value={color} onValueChange={setColor} />
            </Field>
            <div ref={preview} className="flex items-center gap-3">
                <Button>Save</Button>
                <Badge>New</Badge>
            </div>
        </div>
    );
}
```

## API reference

### ColorPicker

A field showing a colour and its hex that opens a ColorPanel: drag or use
the arrow keys in the area, slide the hue (and opacity, with `alpha`), type
a hex or pick a swatch. Works in a Field like any input.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `alpha` | `boolean` |  | Offer opacity; values may then be "#rrggbbaa". |
| `defaultValue` | `string` | `#000000` | The first colour, when the picker keeps its own. Black by default. |
| `name` | `string` |  | Form field name: the hex is submitted with the form. |
| `onValueChange` | `((value: string) => void)` |  | Every change, while dragging too. |
| `onValueCommit` | `((value: string) => void)` |  | Once a change is made: let go of the area or a slider, a key, a hex entered, a swatch picked. |
| `size` | `"default" \| "lg" \| "sm"` | `default` | Height, matching Button's: sm (32px), default (40px) or lg (44px). |
| `swatches` | `ColorSwatch[]` |  | Colours to pick in one press, such as your theme's. |
| `value` | `string` |  | "#rrggbb", or "#rrggbbaa" with `alpha`, when you keep it. |

### ColorPanel

Everything ColorPicker opens: a saturation and brightness area, hue and
alpha sliders, the hex, and your swatches. Use it inline, or in a popup of
your own. Values are hex: "#rrggbb", or "#rrggbbaa" with `alpha`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `alpha` | `boolean` | `false` | Offer opacity; values may then be "#rrggbbaa". |
| `defaultValue` | `string` | `#000000` | The first colour, when the picker keeps its own. Black by default. |
| `onValueChange` | `((value: string) => void)` |  | Every change, while dragging too. |
| `onValueCommit` | `((value: string) => void)` |  | Once a change is made: let go of the area or a slider, a key, a hex entered, a swatch picked. |
| `swatches` | `ColorSwatch[]` |  | Colours to pick in one press, such as your theme's. |
| `value` | `string` |  | "#rrggbb", or "#rrggbbaa" with `alpha`, when you keep it. |

---

# Combobox

Search and pick one or several items of any shape, composed from parts: field, panel, search, a virtualized list, empty and create rows.

```tsx
import { Combobox, ComboboxTrigger, ComboboxSearch, ComboboxList, ComboboxItem, ComboboxEmpty, ComboboxCreate } from '@rinzai/zen';
```

## Examples

### Accounts

```tsx
import {
    Combobox,
    ComboboxEmpty,
    ComboboxItem,
    ComboboxList,
    ComboboxPopup,
    ComboboxSearch,
    ComboboxTrigger,
} from '@rinzai/zen';
import { useState } from 'react';

interface Account {
    id: string;
    name: string;
    number: string;
}

const ACCOUNTS: Account[] = [
    { id: 'chk', name: 'Everyday checking', number: '•• 4821' },
    { id: 'sav', name: 'Rainy-day savings', number: '•• 0937' },
    { id: 'crd', name: 'Travel credit card', number: '•• 1150' },
    { id: 'brk', name: 'Brokerage', number: '•• 7302' },
];

/** Any shape of item (itemKey, itemText), your own rows, your own empty message. ↑↓ and Enter work in the search. */
export default function Accounts() {
    const [account, setAccount] = useState<string | null>('chk');
    return (
        <Combobox
            items={ACCOUNTS}
            itemKey={(a) => a.id}
            itemText={(a) => a.name}
            value={account}
            onValueChange={setAccount}
        >
            <ComboboxTrigger aria-label="Account" placeholder="Pick an account" className="w-72" />
            <ComboboxPopup>
                <ComboboxSearch placeholder="Search accounts" />
                <ComboboxList<Account>
                    renderItem={(a) => (
                        <ComboboxItem item={a}>
                            <span className="flex justify-between gap-3">
                                {a.name}
                                <span className="text-muted-foreground tabular-nums">{a.number}</span>
                            </span>
                        </ComboboxItem>
                    )}
                >
                    <ComboboxEmpty>No account by that name</ComboboxEmpty>
                </ComboboxList>
            </ComboboxPopup>
        </Combobox>
    );
}
```

### Tags

```tsx
import { Combobox, ComboboxCreate, ComboboxList, ComboboxPopup, ComboboxSearch, ComboboxTrigger } from '@rinzai/zen';
import { useState } from 'react';

const asText = (tag: string) => tag;

/** Several at once (chips, removable), and typing a new name offers to add it: ComboboxCreate (Enter works too). */
export default function Tags() {
    const [tags, setTags] = useState(['Essential', 'Shared', 'Work', 'Treat', 'Annual']);
    const [chosen, setChosen] = useState(['Essential', 'Shared']);
    return (
        <Combobox multiple items={tags} itemKey={asText} itemText={asText} value={chosen} onValueChange={setChosen}>
            <ComboboxTrigger aria-label="Tags" placeholder="No tags" className="w-80" />
            <ComboboxPopup>
                <ComboboxSearch />
                <ComboboxList>
                    <ComboboxCreate
                        onCreate={(tag) => {
                            setTags((all) => [...all, tag]);
                            setChosen((c) => [...c, tag]);
                        }}
                    />
                </ComboboxList>
            </ComboboxPopup>
        </Combobox>
    );
}
```

### Many items

```tsx
import { Combobox, ComboboxEmpty, ComboboxList, ComboboxPopup, ComboboxSearch, ComboboxTrigger } from '@rinzai/zen';
import { useState } from 'react';

const ACCOUNTS = Array.from({ length: 2000 }, (_, i) => ({
    key: String(i + 1),
    text: `Account ${String(i + 1).padStart(4, '0')}`,
}));

/** 2,000 items: the list renders only the rows in view, so it opens and scrolls instantly. Type to filter. */
export default function ManyItems() {
    const [account, setAccount] = useState<string | null>('1');
    return (
        <Combobox items={ACCOUNTS} value={account} onValueChange={setAccount}>
            <ComboboxTrigger aria-label="Account" className="w-64" />
            <ComboboxPopup>
                <ComboboxSearch />
                <ComboboxList>
                    <ComboboxEmpty />
                </ComboboxList>
            </ComboboxPopup>
        </Combobox>
    );
}
```

## API reference

### Combobox

Pick one or several items from a list you can search: a field that opens a
panel with a search box and the matching items. Compose it from
ComboboxTrigger, ComboboxPopup, ComboboxSearch, ComboboxList (virtualized,
for long lists), ComboboxItem, ComboboxEmpty and ComboboxCreate. Keyboard:
Enter, Space or ↓ on the field opens it, typing searches, ↑↓ move, Enter
chooses, Escape closes. Items can be any shape: say how to read a key and
text from one with `itemKey` and `itemText`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `readonly T[]` |  |  |
| `defaultValue` | `string \| readonly string[] \| null` |  |  |
| `filter` | `((item: T, query: string) => boolean)` |  | Whether an item matches the search (default: its text contains it, any case). |
| `itemKey` | `((item: T) => string)` |  | How to read an item's unique key (default: its `key`). |
| `itemText` | `((item: T) => string)` |  | How to read an item's text, shown and searched (default: its `text`). |
| `multiple` | `boolean` |  |  |
| `name` | `string` |  | Form field name: the chosen key is submitted with the form (with `multiple`, each key). |
| `onValueChange` | `((key: string) => void) \| ((keys: string[]) => void)` |  |  |
| `selectedItems` | `readonly T[]` |  | Chosen items that aren't in `items` (e.g. just created), so the field can still show them. |
| `value` | `string \| readonly string[] \| null` |  |  |

### ComboboxTrigger

The field: shows the choice (text, or chips when `multiple`) or the
placeholder, and opens the panel. Pass children to show the value your own way.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` |  | Your own display of the value (default: its text, or chips). |
| `disabled` | `boolean` |  |  |
| `placeholder` | `string` |  | Shown while nothing is chosen. |
| `size` | `"default" \| "lg" \| "sm"` | `default` | Height, matching Button's: sm (32px), default (40px) or lg (44px). |

### ComboboxSearch

The search box: focused when the panel opens; ↑↓ move through the matches and Enter chooses.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-label` | `string` |  |  |
| `placeholder` | `string` |  |  |

### ComboboxList

The matching items, rendered only while in view (so thousands stay fast).
Rows are `itemHeight` px tall; `renderItem` draws each (default: a
ComboboxItem). Put ComboboxEmpty or ComboboxCreate inside for no matches.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `itemHeight` | `number` | `35` | Height of every row, in px (default 35). |
| `renderItem` | `((item: T) => ReactNode)` |  |  |

### ComboboxItem

One item in a ComboboxList: a check when chosen, then its text (or your own content).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `item` (required) | `T` |  |  |
| `className` | `string` |  |  |

### ComboboxEmpty

Shown when the search matches nothing.

No props of its own; it accepts the props of the element it renders.

### ComboboxCreate

Offered when the search matches nothing: adds what was typed (Enter works
too). `children` renders the row from the text (default "Add …").

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onCreate` (required) | `(text: string) => void` |  |  |

---

# Command Palette

Search everything and act on it from the keyboard: a field over a list that narrows as you type, opened with ⌘K.

```tsx
import { CommandPalette, useCommandPaletteShortcut } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { Button, CommandPalette, Kbd, useCommandPaletteShortcut, type CommandItem } from '@rinzai/zen';
import { useState } from 'react';
// Icons from Heroicons (https://heroicons.com): ChartBar (chart-bar), ListBullet (list-bullet), Settings (cog-6-tooth).

/** Pages and actions in one search. Open it with the button, or ⌘K / Ctrl+K. */
export default function Default() {
    const [open, setOpen] = useState(false);
    const [last, setLast] = useState<string>();
    useCommandPaletteShortcut(() => setOpen(true));
    const go = (label: string) => () => setLast(label);
    const items: CommandItem[] = [
        { label: 'Overview', group: 'Pages', icon: <ChartBar />, onSelect: go('Overview') },
        { label: 'Entries', group: 'Pages', icon: <ListBullet />, keywords: ['transactions'], onSelect: go('Entries') },
        { label: 'Settings', group: 'Pages', icon: <Settings />, keywords: ['preferences'], onSelect: go('Settings') },
        { label: 'Add entry', group: 'Actions', hint: 'N', onSelect: go('Add entry') },
        { label: 'Import a statement', group: 'Actions', keywords: ['csv', 'bank'], onSelect: go('Import') },
        { label: 'Export to CSV', group: 'Actions', onSelect: go('Export') },
    ];
    return (
        <div className="flex flex-col items-center gap-3">
            <Button variant="outline" onClick={() => setOpen(true)}>
                Search…
                <span className="ml-2 flex gap-0.5">
                    <Kbd>⌘</Kbd>
                    <Kbd>K</Kbd>
                </span>
            </Button>
            {last && <p className="text-muted-foreground mt-0! text-sm">Ran: {last}</p>}
            <CommandPalette open={open} onOpenChange={setOpen} items={items} placeholder="Search pages and actions…" />
        </div>
    );
}
```

## API reference

### CommandPalette

Search everything and act on it (pages, commands, records): a field over a
list that narrows as you type. Arrow keys move, Enter runs the item and
closes. Open it from a button, or anywhere with ⌘K / Ctrl+K
(useCommandPaletteShortcut).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `CommandItem[]` |  |  |
| `onOpenChange` (required) | `(open: boolean) => void` |  |  |
| `open` (required) | `boolean` |  |  |
| `className` | `string` |  |  |
| `empty` | `ReactNode` |  | Shown when nothing matches. |
| `label` | `string` |  | Names the palette and its list, for screen readers. |
| `placeholder` | `string` |  |  |

---

# Date Picker

A field that opens a calendar: one date, or a range previewed as you point. Dates are "YYYY-MM-DD" strings, so they never shift with time zones.

```tsx
import { DatePicker, DateRangePicker } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { DatePicker } from '@rinzai/zen';
import { useState } from 'react';

/** Opens on the chosen date, ready for the keyboard; picking a day closes it. With onClear, it can be emptied. */
export default function Default() {
    const [date, setDate] = useState<string | null>('2026-09-30');
    return (
        <DatePicker
            aria-label="Due date"
            value={date}
            onValueChange={setDate}
            clearable
            locale="en-IN"
            className="w-56"
        />
    );
}
```

### Range

```tsx
import { type DateRange, DateRangePicker } from '@rinzai/zen';
import { useState } from 'react';

/** A trip: the start, then the end, across two months. Closes once both are picked. */
export default function Range() {
    const [trip, setTrip] = useState<DateRange | null>(null);
    return (
        <DateRangePicker
            aria-label="Trip dates"
            value={trip}
            onValueChange={setTrip}
            clearable
            months={2}
            locale="en-US"
            className="w-64"
        />
    );
}
```

### Presets

```tsx
import { commonRanges, type DateRange, DateRangePicker, today } from '@rinzai/zen';
import { useState } from 'react';

/** The ranges people pick most, one tap each, beside the calendar. */
export default function Presets() {
    const r = commonRanges(today());
    const [range, setRange] = useState<DateRange | null>(r.thisMonth);
    return (
        <DateRangePicker
            aria-label="Entries between"
            value={range}
            onValueChange={setRange}
            locale="en-US"
            className="w-64"
            presets={[
                { label: 'This week', range: r.thisWeek },
                { label: 'Last 7 days', range: r.last7Days },
                { label: 'Last 30 days', range: r.last30Days },
                { label: 'This month', range: r.thisMonth },
                { label: 'Last month', range: r.lastMonth },
                { label: 'This year', range: r.thisYear },
            ]}
        />
    );
}
```

### In field

```tsx
import { addDays, DatePicker, Field, today } from '@rinzai/zen';
import { useState } from 'react';

/** In a Field: the label, hint and error are wired to the picker. Only dates from today on. */
export default function InField() {
    const [date, setDate] = useState<string | null>(null);
    const [touched, setTouched] = useState(false);
    return (
        <Field
            label="Start date"
            hint="When the plan begins."
            error={touched && !date ? 'Pick a start date.' : undefined}
            className="w-64"
        >
            <DatePicker
                value={date}
                onValueChange={setDate}
                onBlur={() => setTouched(true)}
                locale="en-US"
                min={today()}
                max={addDays(today(), 365)}
            />
        </Field>
    );
}
```

## API reference

### DatePicker

Date field: shows the date ("Sep 30, 2026" for the locale) and opens a
Calendar to pick one, focused on the chosen date so the keyboard works at
once. Dates are "YYYY-MM-DD" strings. When `clearable`, the popup also offers
`clearLabel` to empty it. With `name`, it's submitted with a form.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` |  | Classes for the trigger (e.g. a width, instead of the default full width). |
| `clearable` | `boolean` | `false` | Offers a clear option in the popup (shown when a value is set); clearing reports null. |
| `clearLabel` | `string` |  |  |
| `defaultValue` | `string \| null` | `null` | The first date, when the picker keeps its own. |
| `isDisabled` | `((date: string) => boolean)` |  | Dates that can't be picked, e.g. weekends or booked days. |
| `locale` | `string` |  | Decides the date format, month and weekday names, and the first day of the week, e.g. "en-IN". Defaults to the LocaleProvider's. |
| `max` | `string` |  | Latest date that can be picked. |
| `min` | `string` |  | Earliest date that can be picked ("YYYY-MM-DD"). |
| `name` | `string` |  | Form field name: the value is submitted with the form ("YYYY-MM-DD", a range as "start/end"). |
| `onValueChange` | `((date: string \| null) => void)` |  |  |
| `placeholder` | `string` |  |  |
| `size` | `"default" \| "lg" \| "sm"` |  | Height, matching Button's: sm (32px), default (40px) or lg (44px). |
| `value` | `string \| null` |  | "YYYY-MM-DD", or null for none, when you keep it. |
| `weekStartsOn` | `number` |  | 0 for Sunday … 6 for Saturday. Defaults to the locale's. |

### DateRangePicker

Date range field: pick a start and then an end in a Calendar (the days
between are previewed while pointing); it closes once the range is complete.
Shows the range the locale's way, e.g. "Sep 3 – 10, 2026". With `presets`,
common ranges ("Last 30 days") sit beside the calendar, one tap each (see
commonRanges).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` |  | Classes for the trigger (e.g. a width, instead of the default full width). |
| `clearable` | `boolean` | `false` | Offers a clear option in the popup (shown when a value is set); clearing reports null. |
| `clearLabel` | `string` |  |  |
| `defaultValue` | `DateRange \| null` | `null` | The first range, when the picker keeps its own. |
| `isDisabled` | `((date: string) => boolean)` |  | Dates that can't be picked, e.g. weekends or booked days. |
| `locale` | `string` |  | Decides the date format, month and weekday names, and the first day of the week, e.g. "en-IN". Defaults to the LocaleProvider's. |
| `max` | `string` |  | Latest date that can be picked. |
| `min` | `string` |  | Earliest date that can be picked ("YYYY-MM-DD"). |
| `months` | `number` | `1` | Months shown side by side (2 suits wide screens). |
| `name` | `string` |  | Form field name: the value is submitted with the form ("YYYY-MM-DD", a range as "start/end"). |
| `onValueChange` | `((range: DateRange \| null) => void)` |  |  |
| `placeholder` | `string` |  |  |
| `presets` | `DateRangePreset[]` |  | Ranges picked in one tap, beside the calendar. |
| `size` | `"default" \| "lg" \| "sm"` |  | Height, matching Button's: sm (32px), default (40px) or lg (44px). |
| `value` | `DateRange \| null` |  | The range when you keep it; `end` is null while only the start is picked. |
| `weekStartsOn` | `number` |  | 0 for Sunday … 6 for Saturday. Defaults to the locale's. |

---

# Dialog

Modal dialogs on the native <dialog> element, sheets that slide in from an edge, and a confirmation for destructive actions.

```tsx
import { Dialog, DialogFooter, DialogClose, ConfirmDialog } from '@rinzai/zen';
```

## Examples

### Form

```tsx
import { Button, Dialog, DialogClose, DialogFooter, Input } from '@rinzai/zen';
import { useState } from 'react';

export default function Form() {
    const [open, setOpen] = useState(false);
    return (
        <>
            <Button onClick={() => setOpen(true)}>Rename</Button>
            <Dialog
                open={open}
                onOpenChange={setOpen}
                title="Rename category"
                description="Entries in this category keep their history."
            >
                <label className="flex flex-col gap-2">
                    Name
                    <Input defaultValue="Groceries" />
                </label>
                <DialogFooter>
                    <DialogClose variant="outline">Cancel</DialogClose>
                    <DialogClose>Save</DialogClose>
                </DialogFooter>
            </Dialog>
        </>
    );
}
```

### Sheets

```tsx
import { Button, Checkbox, Dialog, DialogClose, DialogFooter } from '@rinzai/zen';
import { useState } from 'react';

/** With side, a dialog slides in from an edge: a bottom sheet (phones) or a side panel (filters, details). */
export default function Sheets() {
    const [open, setOpen] = useState(false);
    const [side, setSide] = useState<'bottom' | 'right'>('bottom');
    const show = (from: 'bottom' | 'right') => {
        setSide(from);
        setOpen(true);
    };
    return (
        <div className="flex flex-wrap gap-2">
            <Button variant="outline" onClick={() => show('bottom')}>
                Bottom sheet
            </Button>
            <Button variant="outline" onClick={() => show('right')}>
                Side panel
            </Button>
            <Dialog
                open={open}
                onOpenChange={setOpen}
                side={side}
                title="Filters"
                description="Show only what you need."
            >
                <div className="flex flex-col gap-3">
                    <Checkbox defaultChecked>Income</Checkbox>
                    <Checkbox defaultChecked>Spending</Checkbox>
                    <Checkbox>Transfers</Checkbox>
                </div>
                <DialogFooter className="mt-auto">
                    <DialogClose variant="ghost">Cancel</DialogClose>
                    <DialogClose>Apply</DialogClose>
                </DialogFooter>
            </Dialog>
        </div>
    );
}
```

### Pickers

```tsx
import {
    Button,
    Dialog,
    DialogClose,
    DialogFooter,
    Combobox,
    DatePicker,
    ComboboxEmpty,
    ComboboxList,
    ComboboxPopup,
    ComboboxSearch,
    ComboboxTrigger,
    MonthPicker,
    Select,
    SelectItem,
    useToast,
} from '@rinzai/zen';
import { useState } from 'react';

const CATEGORIES = [
    { value: 'groceries', label: 'Groceries' },
    { value: 'rent', label: 'Rent' },
    { value: 'transport', label: 'Transport' },
    { value: 'dining', label: 'Dining out' },
] as const;
const TAGS = ['Essential', 'Shared', 'Work', 'Treat'];
const asText = (tag: string) => tag;

/** Selects, pickers and menus open above the dialog, and toasts show over it (try Save draft). */
export default function Pickers() {
    const toast = useToast();
    const [open, setOpen] = useState(false);
    const [category, setCategory] = useState<(typeof CATEGORIES)[number]['value'] | null>('groceries');
    const [month, setMonth] = useState<string | null>('2026-09');
    const [start, setStart] = useState<string | null>('2026-09-30');
    const [tags, setTags] = useState<string[]>([TAGS[0]]);
    return (
        <>
            <Button onClick={() => setOpen(true)}>Add budget</Button>
            <Dialog open={open} onOpenChange={setOpen} title="Add budget">
                <div className="grid gap-3 sm:grid-cols-2">
                    <label className="flex flex-col gap-2 text-sm">
                        Category
                        <Select aria-label="Category" value={category} onValueChange={setCategory}>
                            {CATEGORIES.map((c) => (
                                <SelectItem key={c.value} value={c.value}>
                                    {c.label}
                                </SelectItem>
                            ))}
                        </Select>
                    </label>
                    <label className="flex flex-col gap-2 text-sm">
                        From
                        <MonthPicker aria-label="From" value={month} onValueChange={setMonth} locale="en-IN" />
                    </label>
                </div>
                <label className="flex flex-col gap-2 text-sm">
                    Starts on
                    <DatePicker aria-label="Starts on" value={start} onValueChange={setStart} locale="en-IN" />
                </label>
                <div className="flex flex-col gap-2 text-sm">
                    <span>Tags</span>
                    <Combobox
                        multiple
                        items={TAGS}
                        itemKey={asText}
                        itemText={asText}
                        value={tags}
                        onValueChange={setTags}
                    >
                        <ComboboxTrigger className="w-full" />
                        <ComboboxPopup>
                            <ComboboxSearch />
                            <ComboboxList>
                                <ComboboxEmpty />
                            </ComboboxList>
                        </ComboboxPopup>
                    </Combobox>
                </div>
                <DialogFooter>
                    <Button
                        variant="ghost"
                        className="mr-auto"
                        onClick={() => toast('Draft saved', { tone: 'default' })}
                    >
                        Save draft
                    </Button>
                    <DialogClose variant="outline">Cancel</DialogClose>
                    <DialogClose onClick={() => toast('Budget added', { tone: 'positive' })}>Add</DialogClose>
                </DialogFooter>
            </Dialog>
        </>
    );
}
```

### Confirm

```tsx
import { Button, ConfirmDialog } from '@rinzai/zen';
import { useState } from 'react';

export default function Confirm() {
    const [open, setOpen] = useState(false);
    return (
        <>
            <Button tone="negative" onClick={() => setOpen(true)}>
                Delete goal
            </Button>
            <ConfirmDialog
                open={open}
                onOpenChange={setOpen}
                title="Delete this goal?"
                description="Its progress history is removed too. This can't be undone."
                confirmLabel="Delete"
                tone="negative"
                onConfirm={() => {}}
            />
        </>
    );
}
```

## API reference

### Dialog

Modal dialog on the native <dialog> element: focus is trapped and restored,
the page behind is inert, and Escape closes it. `dismissible={false}` is for
flows the user must finish (no Escape, outside-click or close button). With `side`,
it's a sheet that slides in from that edge: a bottom sheet on phones, a side
panel for filters or details. On touch, a sheet swipes back to its edge to close.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` (required) | `boolean` |  |  |
| `title` (required) | `ReactNode` |  |  |
| `closeLabel` | `string` |  | The close button's accessible name. |
| `description` | `ReactNode` |  |  |
| `dismissible` | `boolean` | `true` |  |
| `initialFocus` | `RefObject<HTMLElement \| null>` |  | Element to focus when the dialog opens (default: the first focusable one). |
| `onOpenChange` | `((open: boolean) => void)` |  |  |
| `side` | `"bottom" \| "left" \| "right"` |  | Slide in from this edge as a sheet, instead of appearing in the middle. |
| `size` | `"lg" \| "md"` | `md` | "lg" for dialogs holding a whole tool rather than a short form. |

### DialogFooter

The row of actions at the end of a dialog, right-aligned.

No props of its own; it accepts the props of the element it renders.

### DialogClose

A button that closes its dialog (after its own onClick, unless that calls
preventDefault). Takes every Button prop: variant, size, asChild…

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `asChild` | `boolean` |  | Put the button's styles on the single child element (e.g. a link) instead of a <button>. |
| `loading` | `boolean` |  | Shows a spinner and disables the button while an action runs. |
| `size` | `"default" \| "icon-lg" \| "icon-sm" \| "icon-xs" \| "icon" \| "lg" \| "sm" \| null` |  |  |
| `tone` | `"default" \| "inherit" \| "muted" \| "negative" \| null` |  |  |
| `variant` | `"default" \| "ghost" \| "link" \| "outline" \| "secondary" \| null` |  |  |

### ConfirmDialog

Confirmation for destructive or irreversible actions. Cancel has focus, so Enter is the safe choice.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `confirmLabel` (required) | `string` |  |  |
| `onConfirm` (required) | `() => void` |  |  |
| `onOpenChange` (required) | `(open: boolean) => void` |  |  |
| `open` (required) | `boolean` |  |  |
| `title` (required) | `ReactNode` |  |  |
| `cancelLabel` | `string` |  |  |
| `closeLabel` | `string` |  | The close button's accessible name. |
| `description` | `ReactNode` |  |  |
| `dismissible` | `boolean` |  |  |
| `initialFocus` | `RefObject<HTMLElement \| null>` |  | Element to focus when the dialog opens (default: the first focusable one). |
| `side` | `"bottom" \| "left" \| "right"` |  | Slide in from this edge as a sheet, instead of appearing in the middle. |
| `size` | `"lg" \| "md"` |  | "lg" for dialogs holding a whole tool rather than a short form. |
| `tone` | `"default" \| "negative"` | `default` | `negative` for a destructive action: the confirm button is red. |

---

# Disclosure

A button that shows and hides a section, like finished goals under a list.

```tsx
import { Disclosure, DisclosureTrigger, DisclosureContent } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { Card, CardHeader, CardTitle, Disclosure, DisclosureContent, DisclosureTrigger, Meter } from '@rinzai/zen';

const ACTIVE = [
    { name: 'New phone', saved: 42000, target: 60000 },
    { name: 'Emergency fund', saved: 180000, target: 300000 },
];
const PAST = ['Laptop', 'Trip to Goa', 'Wedding gift'];

/** Finished goals folded away under the active ones; the section grows open and folds shut. */
export default function Default() {
    return (
        <Card className="w-full max-w-sm gap-4">
            <CardHeader>
                <CardTitle>Goals</CardTitle>
            </CardHeader>
            <ul className="flex flex-col gap-3 text-sm">
                {ACTIVE.map((g) => (
                    <li key={g.name} className="flex flex-col gap-1.5">
                        <div className="flex justify-between">
                            <span>{g.name}</span>
                            <span className="text-muted-foreground tabular-nums">
                                {Math.round((g.saved / g.target) * 100)}%
                            </span>
                        </div>
                        <Meter value={g.saved} max={g.target} aria-label={g.name} />
                    </li>
                ))}
            </ul>
            <Disclosure>
                <DisclosureTrigger className="mt-2">Past ({PAST.length})</DisclosureTrigger>
                <DisclosureContent>
                    <ul className="border-tint/[0.07] flex flex-col gap-2 border-l pl-4 text-sm">
                        {PAST.map((g) => (
                            <li key={g} className="text-muted-foreground flex items-center justify-between">
                                {g}
                                <span className="text-xs">Done</span>
                            </li>
                        ))}
                    </ul>
                </DisclosureContent>
            </Disclosure>
        </Card>
    );
}
```

## API reference

### Disclosure

A section that a button shows and hides, e.g. "Past (3)" under a list. Put
a DisclosureTrigger and a DisclosureContent inside (it adds no element of its
own). Opens and closes on its own, or follows `open`/`onOpenChange`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultOpen` | `boolean` | `false` |  |
| `onOpenChange` | `((open: boolean) => void)` |  |  |
| `open` | `boolean` |  | Show or hide it from your state; leave it out to let the trigger do it. |

### DisclosureTrigger

The button: your label after a chevron that turns down as the section opens. Brightens on hover and while open.

No props of its own; it accepts the props of the element it renders.

### DisclosureContent

What the trigger shows and hides. It grows open and folds shut (the height
animates, the content fades and settles). While closed it isn't rendered at
all, so what's inside costs nothing and can't be found, focused or read; it
mounts as it opens and unmounts once it has folded shut. className goes on
the content itself.

No props of its own; it accepts the props of the element it renders.

---

# Editable Cell

A value edited in place: shows the value, swaps in any editor on click or Enter.

```tsx
import { EditableCell } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { EditableCell, formatMoney, Input, MoneyInput } from '@rinzai/zen';
import { useState } from 'react';

/** Click a value (or Tab to it and press Enter) to edit; Enter or blur saves, Escape cancels. */
export default function Default() {
    const [amount, setAmount] = useState<number | null>(1850000);
    const [note, setNote] = useState('Due on the 5th');
    return (
        <div className="grid w-80 grid-cols-[auto_1fr] items-center gap-x-4 gap-y-2 text-sm">
            <span className="text-muted-foreground">Rent</span>
            <EditableCell
                label={`Rent: ${amount === null ? 'none' : formatMoney(amount, 'INR', 'en-IN')}`}
                editor={(close) => (
                    <MoneyInput
                        compact
                        autoFocus
                        allowEmpty
                        aria-label="Rent"
                        value={amount}
                        currency="INR"
                        locale="en-IN"
                        onValueChange={(v) => {
                            setAmount(v);
                            close();
                        }}
                        onCancel={close}
                    />
                )}
            >
                {amount === null ? '–' : formatMoney(amount, 'INR', 'en-IN', { showDecimals: false })}
            </EditableCell>
            <span className="text-muted-foreground">Note</span>
            <EditableCell
                label={`Note: ${note}`}
                className="text-left"
                editor={(close) => (
                    <Input
                        autoFocus
                        aria-label="Note"
                        defaultValue={note}
                        className="h-7"
                        onBlur={(e) => {
                            setNote(e.target.value);
                            close();
                        }}
                        onKeyDown={(e) => {
                            if (e.key === 'Enter') e.currentTarget.blur();
                            if (e.key === 'Escape') close();
                        }}
                    />
                )}
            >
                {note}
            </EditableCell>
        </div>
    );
}
```

## API reference

### EditableCell

A value edited in place, e.g. in a table cell: shows `children` as a button,
and on click (or Enter) swaps in your editor. Call `close()` from the editor
when it's done (committed or cancelled). Works with any editor: a compact
MoneyInput, an Input, a Select. A value changed by an edit glows briefly
when the editor closes.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` |  | What the cell shows when not editing. |
| `editor` (required) | `(close: () => void) => ReactNode` |  | The editor to show while editing; call `close` when it's done. |
| `editing` | `boolean` |  | Control the editing state yourself (with onEditingChange). |
| `label` | `string` |  | Accessible name of the value, e.g. "Rent, Oct 2026: ₹18,500"; " Edit" is added for the button. |
| `onEditingChange` | `((editing: boolean) => void)` |  |  |
| `readOnly` | `boolean` | `false` | Show the value without making it editable. |

---

# Empty State

What a list or page shows when there's nothing in it yet, and the action that fills it.

```tsx
import { EmptyState } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { Button, Card, EmptyState } from '@rinzai/zen';
// Icons from Heroicons (https://heroicons.com): ListBullet (list-bullet).

/** A month with no entries yet: what's missing, and the action that adds the first one. */
export default function Default() {
    return (
        <Card className="w-full max-w-md">
            <EmptyState
                icon={<ListBullet />}
                title="No entries this month"
                description="Add your income and spending, or bring them in from a bank statement."
            >
                <Button>Add entry</Button>
                <Button variant="outline">Import</Button>
            </EmptyState>
        </Card>
    );
}
```

## API reference

### EmptyState

What a list, table or page shows when there's nothing in it yet: an icon on
a soft glow, a title, a line on what to do, and the action that does it
(children, e.g. a Button).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` (required) | `ReactNode` |  |  |
| `description` | `ReactNode` |  |  |
| `icon` | `ReactNode` |  | An icon, shown on the accent's glow. |

---

# Field

A label, hint and error wired to their control for screen readers, and messages for a whole form.

```tsx
import { Field, FormMessage } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { Button, Field, FormMessage, Input } from '@rinzai/zen';
import { FormEvent, useState } from 'react';

/** Field links the label, hint and error to its control; FormMessage speaks for the whole form. */
export default function Default() {
    const [email, setEmail] = useState('');
    const [submitted, setSubmitted] = useState(false);
    const invalid = submitted && !email.includes('@');
    return (
        <form
            className="flex w-80 flex-col gap-4"
            noValidate
            onSubmit={(e: FormEvent) => {
                e.preventDefault();
                setSubmitted(true);
            }}
        >
            <Field
                label="Email"
                hint="We'll send a sign-in link."
                error={invalid ? 'Enter an email address.' : undefined}
            >
                <Input
                    type="email"
                    value={email}
                    onChange={(e) => setEmail(e.target.value)}
                    placeholder="you@example.com"
                />
            </Field>
            {submitted && !invalid && <FormMessage tone="positive">Check your inbox for the link.</FormMessage>}
            <Button type="submit" className="self-start">
                Send link
            </Button>
        </form>
    );
}
```

## API reference

### Field

A labelled form control with an optional hint and error. Links them for
screen readers: the control gets an id (if it has none), aria-describedby
for the hint or error, and aria-invalid while there's an error. The error
shows in place of the hint until it's fixed.

The direct child gets these as props. When the control sits inside other
markup (e.g. an amount beside a unit select), give it an id and pass the
same id as `htmlFor`: Zen's controls with that id pick them up themselves.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` |  | One control (Input, Select, MoneyInput…), or anything else (then link it yourself). |
| `label` (required) | `ReactNode` |  |  |
| `className` | `string` |  |  |
| `error` | `ReactNode` |  | Error under the control, in place of the hint; marks it invalid. |
| `hint` | `ReactNode` |  | Help text under the control. |
| `htmlFor` | `string` |  | The control's id, when it isn't the direct child (it's inside other markup). |

### FormMessage

A message for a form as a whole: an error or success in a tinted box, or a quiet note. An Alert, set for forms.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `ReactNode` |  | Replaces the tone's icon (info, check, warning); `null` for none. |
| `title` | `ReactNode` |  | A first line in the tone's colour; the text under it is quieter. |
| `tone` | `"default" \| "negative" \| "positive"` | `default` |  |

---

# File Drop

Somewhere to drop files, or click to choose them, that lights up as files are dragged over it.

```tsx
import { FileDrop } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { FileDrop } from '@rinzai/zen';
import { useState } from 'react';

/** A bank statement to import: CSV or Excel, one at a time. */
export default function Default() {
    const [file, setFile] = useState<File>();
    return (
        <FileDrop accept=".csv,.xlsx" onFiles={([f]) => setFile(f)} className="w-full max-w-md">
            <span className="text-foreground font-medium">{file ? file.name : 'Drop a statement here'}</span>
            <span className="text-xs">
                {file ? `${Math.ceil(file.size / 1024)} KB · choose another` : 'CSV or Excel, or click to choose'}
            </span>
        </FileDrop>
    );
}
```

## API reference

### FileDrop

Somewhere to drop files, or click (or press Enter) to choose them: it lights
up while files are dragged over it. `onFiles` gets those that `accept` allows
(one, unless `multiple`). Children are what it says, e.g. "Drop a CSV here".

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onFiles` (required) | `(files: File[]) => void` |  |  |
| `accept` | `string` |  | As an <input type="file">'s accept: ".csv,.xlsx", "image/*". Dropped files are held to it too. |
| `disabled` | `boolean` | `false` |  |
| `multiple` | `boolean` | `false` |  |

---

# Filter Bar

The filters in effect, each removed with its ×, and Clear all.

```tsx
import { FilterBar, FilterChip } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { Button, FilterBar, FilterChip } from '@rinzai/zen';
import { useState } from 'react';

const ALL = { amount: 'Amount: $50–$500', category: 'Category: Dining out', tag: 'Tag: Shared' };
type Key = keyof typeof ALL;

/** The filters on a list of entries; remove one, or all at once. */
export default function Default() {
    const [on, setOn] = useState<Key[]>(['amount', 'category', 'tag']);
    return (
        <div className="flex min-h-16 w-full max-w-md flex-col items-start gap-3">
            <FilterBar onClear={() => setOn([])}>
                {on.map((key) => (
                    <FilterChip
                        key={key}
                        onRemove={() => setOn((keys) => keys.filter((k) => k !== key))}
                        removeLabel={`Remove ${key} filter`}
                    >
                        {ALL[key]}
                    </FilterChip>
                ))}
            </FilterBar>
            {on.length === 0 && (
                <Button variant="outline" size="sm" onClick={() => setOn(['amount', 'category', 'tag'])}>
                    Filter again
                </Button>
            )}
        </div>
    );
}
```

## API reference

### FilterBar

The filters in effect, as chips each removed with its ×, and "Clear all"
once there are two or more. Renders nothing when no filter is set.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `clearLabel` | `ReactNode` |  |  |
| `onClear` | `(() => void)` |  | Removes every filter; shown as "Clear all" once there are two or more. |

### FilterChip

One filter in a FilterBar: what it is (e.g. "Amount: $50–$500"), and its × to remove it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onRemove` (required) | `() => void` |  |  |
| `className` | `string` |  |  |
| `removeLabel` | `string` |  | The × button's name for screen readers, e.g. "Remove amount filter". |

---

# Header

A sticky glass bar across the top of the page.

```tsx
import { Header } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { Header, Pill, PillIndicator, Pills, ThemeToggle } from '@rinzai/zen';

export default function Default() {
    return (
        <div className="w-full overflow-hidden rounded-xl">
            <Header className="static">
                <span className="text-lg font-semibold tracking-tight">Zen</span>
                <nav aria-label="Main">
                    <Pills>
                        <PillIndicator />
                        <Pill href="#docs" active>
                            Docs
                        </Pill>
                        <Pill href="#components">Components</Pill>
                    </Pills>
                </nav>
                <ThemeToggle />
            </Header>
        </div>
    );
}
```

## API reference

### Header

A sticky bar across the top of the page: the page colour, translucent and
heavily blurred, over a hairline. Clears the notch on phones, where it's
solid instead (a live blur over scrolling content stutters there).

Its first stop for the keyboard is a "Skip to content" link, hidden until
focused, that moves focus to the page's <main> past the bar's links (WCAG
2.4.1). Change its text with `skipLabel`, or pass null to leave it out.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `skipLabel` | `string \| null` |  | The skip link's text; null for no skip link (e.g. when the page has its own). |

---

# Hover Card

A preview of what a link points to, like a person or an account: a glass card once the pointer rests on the link, or while it has keyboard focus.

```tsx
import { HoverCard, HoverCardTrigger, HoverCardContent } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { Avatar, HoverCard, HoverCardContent, HoverCardTrigger } from '@rinzai/zen';

/** Rest the pointer on the name, or tab to it: a preview of who it is. */
export default function Default() {
    return (
        <p className="mt-0! text-sm">
            Paid to{' '}
            <HoverCard>
                <HoverCardTrigger href="#priya">Priya Sharma</HoverCardTrigger>
                <HoverCardContent className="flex gap-3">
                    <Avatar name="Priya Sharma" />
                    <div className="flex flex-col gap-1">
                        <span className="font-medium">Priya Sharma</span>
                        <span className="text-muted-foreground text-xs">Flatmate · shares rent and bills</span>
                        <span className="text-muted-foreground mt-1 text-xs tabular-nums">
                            12 payments this year, $4,210 in all
                        </span>
                    </div>
                </HoverCardContent>
            </HoverCard>{' '}
            on 3 October.
        </p>
    );
}
```

### Trend

```tsx
import { HoverCard, HoverCardContent, HoverCardTrigger, Sparkline } from '@rinzai/zen';

const MERCHANTS = [
    { name: 'Corner Market', spent: [120, 96, 140, 118, 152, 131], total: '$757' },
    { name: 'City Transit', spent: [64, 70, 58, 66, 61, 72], total: '$391' },
];

/** More than a name: each merchant's spending over six months, a glance away. */
export default function Trend() {
    return (
        <ul className="flex flex-col gap-2 text-sm">
            {MERCHANTS.map((m) => (
                <li key={m.name}>
                    <HoverCard>
                        <HoverCardTrigger href={`#${m.name}`}>{m.name}</HoverCardTrigger>
                        <HoverCardContent className="flex w-56 flex-col gap-2">
                            <div className="flex items-baseline justify-between">
                                <span className="font-medium">{m.name}</span>
                                <span className="text-muted-foreground text-xs tabular-nums">{m.total}</span>
                            </div>
                            <Sparkline
                                values={m.spent}
                                area
                                className="h-10 w-full"
                                aria-label={`${m.name}, last six months`}
                            />
                            <span className="text-muted-foreground text-xs">Last six months</span>
                        </HoverCardContent>
                    </HoverCard>
                </li>
            ))}
        </ul>
    );
}
```

## API reference

### HoverCard

A preview of what a link points to, e.g. a person or an account: a glass
card shown after the pointer rests on the link (`openDelay`), or while it
has keyboard focus, and kept while the pointer or focus is on the card.
Escape hides it. What it shows is extra, out of the tab order: everything in
it should be reachable by following the link too. Put a HoverCardTrigger and
a HoverCardContent inside (it can go in a paragraph).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `closeDelay` | `number` | `200` | How long it stays after the pointer leaves, in ms, so the pointer can reach it. Default 200. |
| `openDelay` | `number` | `500` | How long the pointer rests on the trigger before the card shows, in ms. Default 500. |

### HoverCardTrigger

What the card previews: a link by default (give it `href`). With `asChild`, your own element (e.g. your router's link).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `asChild` | `boolean` |  | Put the trigger's props on your own element instead of rendering a link. |

### HoverCardContent

The card: glass, below the trigger (above it if there's no room), lined up with its start by default.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `"center" \| "end" \| "start"` |  | Lined up with the trigger's start (default) or end edge, or centred on it. |
| `offset` | `number` |  | Gap from the trigger, in px. |

---

# Icon Picker

An icon and a colour for something, like a spending category, from a grid in a popover.

```tsx
import { IconPicker } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { Field, IconPicker, Input } from '@rinzai/zen';
import { useState } from 'react';

const ICONS = [
    { value: 'groceries', label: 'Groceries', icon: '🛒' },
    { value: 'dining', label: 'Dining', icon: '🍽️' },
    { value: 'transport', label: 'Transport', icon: '🚆' },
    { value: 'home', label: 'Home', icon: '🏠' },
    { value: 'bills', label: 'Bills', icon: '💡' },
    { value: 'gifts', label: 'Gifts', icon: '🎁' },
    { value: 'health', label: 'Health', icon: '💊' },
    { value: 'fun', label: 'Fun', icon: '🎬' },
    { value: 'travel', label: 'Travel', icon: '✈️' },
    { value: 'books', label: 'Books', icon: '📚' },
    { value: 'pets', label: 'Pets', icon: '🐾' },
    { value: 'work', label: 'Work', icon: '💼' },
];

/** A new category: its icon and colour beside its name. */
export default function Default() {
    const [look, setLook] = useState<{ icon: string; color?: string }>({ icon: 'groceries', color: 'teal' });
    return (
        <div className="flex w-full max-w-sm items-end gap-3">
            <IconPicker label="Category icon" icons={ICONS} value={look} onValueChange={setLook} />
            <Field label="Name" className="flex-1">
                <Input defaultValue="Groceries" />
            </Field>
        </div>
    );
}
```

## API reference

### IconPicker

Pick an icon and a colour for something, e.g. a spending category: a button
showing the choice opens a grid of icons and a row of colours. Icons are
yours (emoji work); colours default to the chart palette. Both are radio
groups, so arrow keys move through them.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icons` (required) | `{ value: string; label: string; icon: ReactNode; }[]` |  |  |
| `label` (required) | `string` |  | What it's the icon of, e.g. "Category icon"; the button also says the current choice. |
| `asChild` | `boolean` |  | Put the trigger's props on your own button element instead of rendering one. |
| `className` | `string` |  |  |
| `colors` | `IconColor[]` | `[ { value: 'blue', color: 'var(--chart-1)' }, { value: 'orange', color: 'var(--chart-2)' }, { value: 'teal', color: 'var(--chart-3)' }, { value: 'amber', color: 'var(--chart-4)' }, { value: 'pink', color: 'var(--chart-5)' }, { value: 'green', color: 'var(--chart-6)' }, { value: 'violet', color: 'var(--chart-7)' }, { value: 'red', color: 'var(--chart-8)' }, ]` | Default: ICON_COLORS, the chart palette. |
| `defaultValue` | `{ icon: string; color?: string; }` | `{ icon: '' }` | The first choice, when the picker keeps its own. |
| `name` | `string` |  | Form field name: the icon is submitted under it, the colour under `${name}-color`. |
| `onValueChange` | `((value: { icon: string; color?: string; }) => void)` |  |  |
| `value` | `{ icon: string; color?: string; }` |  | The choice, when you keep it. |

---

# Input

Text fields in faint glass that glow on focus.

```tsx
import { Input } from '@rinzai/zen';
```

## Examples

### States

```tsx
import { Input } from '@rinzai/zen';

export default function States() {
    return (
        <div className="flex w-72 flex-col gap-3">
            <Input aria-label="Empty" placeholder="Placeholder" />
            <Input aria-label="Filled" defaultValue="With a value" />
            <Input aria-label="Disabled" defaultValue="Disabled" disabled />
        </div>
    );
}
```

## API reference

### Input

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"default" \| "lg" \| "sm"` |  | Height, matching Button's: sm (32px), default (40px) or lg (44px). |

---

# Input Group

A field with slots: put symbols, icons, units, buttons or menus before and after the input.

```tsx
import { InputGroup, InputGroupInput, InputGroupAddon } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { InputGroup, InputGroupAddon, InputGroupInput } from '@rinzai/zen';
// Icons from Heroicons (https://heroicons.com): Search (magnifying-glass).

export default function Default() {
    return (
        <div className="flex w-80 flex-col gap-3">
            <InputGroup>
                <InputGroupAddon>
                    <Search />
                </InputGroupAddon>
                <InputGroupInput placeholder="Search entries" />
            </InputGroup>
            <InputGroup>
                <InputGroupAddon>https://</InputGroupAddon>
                <InputGroupInput placeholder="zen.rinzai" />
                <InputGroupAddon>.dev</InputGroupAddon>
            </InputGroup>
            <InputGroup>
                <InputGroupInput placeholder="72" inputMode="numeric" className="tabular-nums" />
                <InputGroupAddon>kg</InputGroupAddon>
            </InputGroup>
        </div>
    );
}
```

### With button

```tsx
import { Button, InputGroup, InputGroupAddon, InputGroupInput } from '@rinzai/zen';
import { useState } from 'react';

/** Controls in addons keep their own clicks; the text around them focuses the input. */
export default function WithButton() {
    const [query, setQuery] = useState('rent');
    return (
        <InputGroup className="w-80 pr-1">
            <InputGroupAddon>Filter</InputGroupAddon>
            <InputGroupInput value={query} onChange={(e) => setQuery(e.target.value)} aria-label="Filter" />
            {query && (
                <InputGroupAddon>
                    <Button variant="ghost" size="sm" className="h-7" onClick={() => setQuery('')}>
                        Clear
                    </Button>
                </InputGroupAddon>
            )}
        </InputGroup>
    );
}
```

## API reference

### InputGroup

A field with slots: compose an InputGroupInput with InputGroupAddons before
or after it (a currency symbol, an icon, a unit, a button, a menu trigger).
The whole group looks like one field and glows while anything in it has
focus; clicking an addon's text focuses the input.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `invalid` | `boolean` |  | Show the field in its error state (e.g. alongside aria-invalid on the input). |
| `size` | `"default" \| "lg" \| "sm"` | `default` | Height, matching Button's: sm (32px), default (40px) or lg (44px). |

### InputGroupInput

The input inside an InputGroup: borderless, filling the space between the addons.

No props of its own; it accepts the props of the element it renders.

### InputGroupAddon

Content before or after the input: text, an icon, a button or a menu trigger.

No props of its own; it accepts the props of the element it renders.

---

# Inset

A faint box set into a card: a tile for one figure, or a bordered panel for a result, tinted for good or bad news.

```tsx
import { Inset } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { Card, CardDescription, CardHeader, CardTitle, Inset } from '@rinzai/zen';

/** Tiles for single figures inside a card, and a tinted panel for a result. */
export default function Default() {
    return (
        <Card className="flex w-full max-w-sm flex-col gap-4">
            <CardHeader className="mb-0">
                <div className="min-w-0">
                    <CardTitle>Car loan</CardTitle>
                    <CardDescription>$32,000 at 8.5% · 5 years</CardDescription>
                </div>
            </CardHeader>
            <dl className="grid grid-cols-2 gap-3 text-sm">
                <Inset className="flex flex-col gap-0.5">
                    <dt className="text-muted-foreground text-xs">Next payment</dt>
                    <dd className="font-medium tabular-nums">$656</dd>
                </Inset>
                <Inset tone="positive" className="flex flex-col gap-0.5">
                    <dt className="text-muted-foreground text-xs">Debt-free</dt>
                    <dd className="font-medium">Mar 2031</dd>
                </Inset>
            </dl>
            <Inset bordered tone="positive" className="text-sm" role="status">
                Paying $200 more a month saves <strong>$2,140</strong> in interest.
            </Inset>
        </Card>
    );
}
```

## API reference

### Inset

A faint box set into a card or dialog: a small tile for one figure (e.g.
"Next EMI"), or with `bordered`, a panel for a result or a note. `tone`
tints it for good or bad news. With `asChild`, your own element (a <p>, a
status region) gets its look.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `asChild` | `boolean` |  | Put the look on your single child element instead of a <div>. |
| `bordered` | `boolean` | `false` | A bordered panel instead of a small tile. |
| `tone` | `"default" \| "negative" \| "positive"` | `default` |  |

---

# Kbd

Keys on the keyboard, for shortcuts in hints and tooltips.

```tsx
import { Kbd } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { Kbd } from '@rinzai/zen';

/** Shortcuts in a sentence: each key its own Kbd. */
export default function Default() {
    return (
        <p className="text-muted-foreground mt-0! flex flex-wrap items-center gap-1 text-sm">
            Search with <Kbd>⌘</Kbd>
            <Kbd>K</Kbd> on a Mac, <Kbd>Ctrl</Kbd>
            <Kbd>K</Kbd> elsewhere; close with <Kbd>Esc</Kbd>.
        </p>
    );
}
```

## API reference

### Kbd

A key on the keyboard, for shortcuts in hints and tooltips: <Kbd>⌘</Kbd><Kbd>K</Kbd>. Sized from the text around it.

No props of its own; it accepts the props of the element it renders.

---

# Keypad

A number pad for typing an amount on a phone.

```tsx
import { Keypad } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { Button, Keypad } from '@rinzai/zen';
import { useState } from 'react';

/** Entering an amount on a phone: the figure above, the pad below. */
export default function Default() {
    const [typed, setTyped] = useState('');
    const amount = Number(typed || 0);
    return (
        <div className="flex w-full max-w-72 flex-col gap-4">
            <p className="mt-0! text-center text-4xl font-semibold tracking-tight tabular-nums" aria-live="polite">
                ${typed || '0'}
            </p>
            <Keypad value={typed} onValueChange={setTyped} />
            <Button disabled={amount <= 0} onClick={() => setTyped('')}>
                Add ${amount.toFixed(2)}
            </Button>
        </div>
    );
}
```

## API reference

### Keypad

A number pad for typing an amount on a phone, where the system keyboard
covers half the screen. The value is the text typed ("12.5"), so a
trailing point or zero stays until you convert it: no leading zeros, one
point, at most `decimals` digits after it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `decimals` | `number` | `2` | Digits allowed after the point (default 2; 0 hides the point). |
| `defaultValue` | `string` |  | What's typed at first, when the keypad keeps its own. |
| `deleteLabel` | `string` |  | The delete key's name for screen readers. |
| `maxLength` | `number` | `12` |  |
| `onValueChange` | `((value: string) => void)` |  |  |
| `value` | `string` |  | What's been typed, e.g. "12.5", when you keep it. |

---

# Load More

The end of a long list that has more: loads the next page when it scrolls into view, or on a press.

```tsx
import { LoadMore } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { LoadMore } from '@rinzai/zen';
import { useState } from 'react';

const PAGE = 12;
const TOTAL = 60;
const entry = (i: number) => ({ id: i, label: `Entry ${i + 1}`, amount: `−$${((i * 37) % 180) + 6}` });

/** Scroll to the end and the next page loads; there's a button for it too. */
export default function Default() {
    const [entries, setEntries] = useState(() => Array.from({ length: PAGE }, (_, i) => entry(i)));
    const [loading, setLoading] = useState(false);
    const more = () => {
        setLoading(true);
        // Stands in for a request.
        setTimeout(() => {
            setEntries((es) => [...es, ...Array.from({ length: PAGE }, (_, i) => entry(es.length + i))]);
            setLoading(false);
        }, 700);
    };
    return (
        <div className="glass glow-edge h-80 w-full max-w-sm overflow-y-auto rounded-xl">
            <ul className="rise-list divide-tint/[0.06] divide-y">
                {entries.map((e) => (
                    <li key={e.id} className="flex justify-between px-4 py-2.5 text-sm">
                        <span>{e.label}</span>
                        <span className="tabular-nums">{e.amount}</span>
                    </li>
                ))}
            </ul>
            <LoadMore onLoadMore={more} loading={loading} hasMore={entries.length < TOTAL} />
        </div>
    );
}
```

## API reference

### LoadMore

The end of a long list that has more: a "Load more" button, which also
presses itself when it scrolls into view (`auto`, default). While `loading`
it shows a spinner and won't ask again; once there's nothing left
(`hasMore` false) it's gone. Put it after the list, or in a table's last row.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `hasMore` (required) | `boolean` |  |  |
| `onLoadMore` (required) | `() => void` |  |  |
| `auto` | `boolean` | `true` | Load when it scrolls into view, not only on press (default true). |
| `className` | `string` |  |  |
| `label` | `string` |  |  |
| `loading` | `boolean` | `false` | While true, it shows a spinner and won't ask for more. |
| `loadingLabel` | `string` |  |  |

---

# Locale Provider

The language for everything inside: how dates, numbers and money read, and every word components show or announce. Without it, "en-US" and English.

```tsx
import { LocaleProvider, useLocale, useMessages, ENGLISH } from '@rinzai/zen';
```

## Examples

### French

```tsx
import { DatePicker, Field, LocaleProvider, MoneyInput, RepeatPicker } from '@rinzai/zen';

const FRENCH = {
    pickDate: 'Choisir une date',
    chooseDate: 'Choisir la date',
    clear: 'Effacer',
    previousMonth: 'Mois précédent',
    nextMonth: 'Mois suivant',
    chooseMonthAndYear: (month: string) => `${month}, choisir le mois et l’année`,
    enterAmount: 'Saisissez un montant.',
    repeats: 'Répétition',
    every: 'Tous les',
    next: 'Prochaines :',
    repeatUnit: (unit: 'day' | 'week' | 'month' | 'year', count: number) =>
        ({ day: 'jour', week: 'semaine', month: 'mois', year: 'an' })[unit] +
        (count > 1 && unit !== 'month' ? 's' : ''),
    repeatEvery: (every: number, unit: string) => (every === 1 ? `Chaque ${unit}` : `Tous les ${every} ${unit}`),
    repeatOn: (rule: string, when: string) => `${rule} le ${when}`,
};

/**
 * `locale` sets how dates, numbers and money read, and the week's first day;
 * `messages` gives the words. Anything you leave out stays English.
 */
export default function French() {
    return (
        <LocaleProvider locale="fr-FR" messages={FRENCH}>
            <div className="flex w-80 flex-col gap-4">
                <Field label="Date">
                    <DatePicker />
                </Field>
                <Field label="Montant">
                    <MoneyInput currency="EUR" defaultValue={128050} />
                </Field>
                <RepeatPicker defaultValue={{ every: 2, unit: 'week' }} start="2026-10-12" />
            </div>
        </LocaleProvider>
    );
}
```

### Right to left

```tsx
import { Calendar, LocaleProvider, Pagination, Slider, Tab, TabList, Tabs } from '@rinzai/zen';
import { useState } from 'react';

/**
 * Right to left: set `dir="rtl"` on the page (or any part of it). Layout,
 * arrow keys and arrows follow; LocaleProvider gives the locale and words.
 */
export default function RightToLeft() {
    const [page, setPage] = useState(2);
    return (
        <div dir="rtl" className="flex w-80 flex-col gap-5">
            <LocaleProvider locale="ar-EG" messages={{ previousPage: 'الصفحة السابقة', nextPage: 'الصفحة التالية' }}>
                <Tabs defaultValue="month">
                    <TabList>
                        <Tab value="month">الشهر</Tab>
                        <Tab value="year">السنة</Tab>
                    </TabList>
                </Tabs>
                <Calendar defaultValue="2026-10-12" />
                <Slider aria-label="الميزانية" defaultValue={30} />
                <Pagination page={page} count={5} onPageChange={setPage} />
            </LocaleProvider>
        </div>
    );
}
```

## API reference

### LocaleProvider

The language for everything inside: `locale` formats dates, numbers and
money and picks month and weekday names and the week's first day (a
component's own `locale` prop still wins), and `messages` replaces any of the
words components show or announce (see ENGLISH for them all; the rest stay
English). Without it, components use "en-US" and English. Nest one to change
part of the page.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `locale` | `string` |  | e.g. "en-IN", "fr-FR". Defaults to the enclosing provider's, or "en-US". |
| `messages` | `Partial<{ clear: string; cancel: string; close: string; back: string; dismiss: string; delete: string; remove: (item: string) => string; noResults: string; search: string; expand: string; collapse: string; minimum: string; ... 109 more ...; timeOf: (time: string, total: string) => string; }>` |  | Any of the words to replace; the others are kept. |

---

# Marquee

One line of text cut off with an ellipsis, that scrolls to show the rest on hover or focus (of itself or of its row), or all the time. Only text that doesn't fit moves.

```tsx
import { Marquee } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { Marquee } from '@rinzai/zen';

const TRACKS = [
    { title: 'Glass Aurora', artist: 'Halcyon Drift' },
    {
        title: 'The Long Way Home Through the Harbour Lights (Extended Night Mix)',
        artist: 'Mira Vale and the Quiet Hours Orchestra',
    },
    { title: 'Paper Moons', artist: 'Mira Vale' },
];

/**
 * Hover a row, or Tab to it: names too long for it scroll, the rest stay put.
 * `data-zen-marquee-host` makes the whole row the trigger.
 */
export default function Default() {
    return (
        <ul className="flex w-72 flex-col gap-1">
            {TRACKS.map((t) => (
                <li key={t.title}>
                    <a
                        href="#play"
                        data-zen-marquee-host
                        onClick={(e) => e.preventDefault()}
                        className="focus-ring hover:bg-tint/[0.06] flex flex-col rounded-lg px-3 py-2"
                    >
                        <Marquee className="text-sm font-medium">{t.title}</Marquee>
                        <Marquee className="text-muted-foreground text-xs">{t.artist}</Marquee>
                    </a>
                </li>
            ))}
        </ul>
    );
}
```

### Always

```tsx
import { Marquee } from '@rinzai/zen';

/** `trigger="always"` keeps it moving, for what's playing: to the end, a pause, and back. */
export default function Always() {
    return (
        <div className="border-tint/10 flex w-56 items-center gap-3 rounded-xl border p-3">
            <div className="from-primary size-10 shrink-0 rounded-md bg-linear-135 to-fuchsia-400" />
            <div className="min-w-0">
                <Marquee trigger="always" className="text-sm font-medium">
                    The Long Way Home Through the Harbour Lights
                </Marquee>
                <Marquee trigger="always" className="text-muted-foreground text-xs">
                    Mira Vale
                </Marquee>
            </div>
        </div>
    );
}
```

## API reference

### Marquee

One line of text that's cut off with an ellipsis, and scrolls to show the
rest: to the end, a pause, and back. Only text that doesn't fit moves.
With `trigger="hover"` (the default) it moves while it, or the closest
element marked `data-zen-marquee-host` (a row, a tile, a link), is hovered
or holds focus; `"always"` keeps it moving, e.g. for what's playing. Stays
an ellipsis for reduced motion. Set the type and colour with className.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `trigger` | `"always" \| "hover"` | `hover` | `'hover'` (default): moves while it or its `data-zen-marquee-host` is hovered or focused. `'always'`: keeps moving. |

---

# Menu

A button that opens a menu, or a context menu from a right-click or long press, with your own trigger, a header, icons, groups, destructive items, checkbox and radio items, submenus, a bottom sheet on phones, and a menubar of menus.

```tsx
import { Menu, MenuTrigger, MenuContextTrigger, MenuContent, MenuItem, MenuCheckboxItem, MenuRadioGroup, MenuRadioItem, MenuSub, MenuSubTrigger, MenuSubContent, MenuSeparator, MenuHeader, Menubar } from '@rinzai/zen';
```

## Examples

### Account

```tsx
import { Avatar, Menu, MenuContent, MenuHeader, MenuItem, MenuSeparator, MenuTrigger, useToast } from '@rinzai/zen';
// Icons from Heroicons (https://heroicons.com): Lock (lock-closed), Logout (arrow-right-start-on-rectangle), Settings (cog-6-tooth).

/** Your own trigger (an avatar), a header that isn't a choice, icons, groups, and a destructive item. */
export default function Account() {
    const toast = useToast();
    const email = 'rin@example.com';
    return (
        <Menu>
            <MenuTrigger
                aria-label="Account menu"
                className="focus-visible:ring-ring/50 data-popup-open:ring-ring/40 rounded-full outline-hidden transition-transform duration-200 hover:scale-105 focus-visible:ring-2 data-popup-open:ring-2"
            >
                <Avatar name={email} />
            </MenuTrigger>
            <MenuContent offset={10} className="w-64 shadow-[0_20px_60px_-20px_oklch(0_0_0/0.8)]">
                <MenuHeader>
                    <Avatar name={email} className="size-10" />
                    <div className="min-w-0">
                        <div className="text-muted-foreground text-xs">Signed in as</div>
                        <div className="truncate text-sm font-medium" title={email}>
                            {email}
                        </div>
                    </div>
                </MenuHeader>
                <MenuSeparator />
                <MenuItem icon={<Settings className="size-4" />} onSelect={() => toast('Settings')}>
                    Settings
                </MenuItem>
                <MenuItem icon={<Lock className="size-4" />} onSelect={() => toast('Locked', { tone: 'positive' })}>
                    Lock now
                </MenuItem>
                <MenuSeparator />
                <MenuItem tone="negative" icon={<Logout className="size-4" />} onSelect={() => toast('Logged out')}>
                    Log out
                </MenuItem>
            </MenuContent>
        </Menu>
    );
}
```

### Actions

```tsx
import { buttonVariants, Menu, MenuContent, MenuItem, MenuTrigger, useToast } from '@rinzai/zen';
// Icons from Heroicons (https://heroicons.com): Ellipsis (ellipsis-horizontal).

/** The usual "⋯" menu of actions for one thing: an icon button as the trigger, and a destructive item last. */
export default function Actions() {
    const toast = useToast();
    return (
        <Menu>
            <MenuTrigger aria-label="Goal actions" className={buttonVariants({ variant: 'ghost', size: 'icon' })}>
                <Ellipsis />
            </MenuTrigger>
            <MenuContent>
                <MenuItem onSelect={() => toast('Edit')}>Edit</MenuItem>
                <MenuItem onSelect={() => toast('Duplicated', { tone: 'positive' })}>Duplicate</MenuItem>
                <MenuItem tone="negative" onSelect={() => toast('Deleted', { tone: 'negative' })}>
                    Delete
                </MenuItem>
            </MenuContent>
        </Menu>
    );
}
```

### Context

```tsx
import { Menu, MenuContent, MenuContextTrigger, MenuItem, MenuSeparator, useToast } from '@rinzai/zen';
import { useState } from 'react';

const ENTRIES = [
    { id: 1, label: 'Weekly shop', amount: '−$165' },
    { id: 2, label: 'Train pass', amount: '−$92' },
    { id: 3, label: 'Salary', amount: '+$4,200' },
];

/** Right-click an entry (or press and hold on a phone) for its actions. One menu serves the whole list. */
export default function Context() {
    const toast = useToast();
    const [entry, setEntry] = useState(ENTRIES[0]);
    return (
        <Menu>
            <ul className="glass glow-edge divide-tint/[0.06] w-full max-w-sm divide-y rounded-xl">
                {ENTRIES.map((e) => (
                    <MenuContextTrigger
                        key={e.id}
                        asChild
                        onContextMenu={() => setEntry(e)}
                        onPointerDown={() => setEntry(e)}
                    >
                        <li
                            tabIndex={0}
                            className="focus-visible:ring-ring/40 data-popup-open:bg-primary/12 flex justify-between px-4 py-3 text-sm outline-hidden transition-colors select-none first:rounded-t-xl last:rounded-b-xl focus-visible:ring-2"
                        >
                            <span>{e.label}</span>
                            <span className="tabular-nums">{e.amount}</span>
                        </li>
                    </MenuContextTrigger>
                ))}
            </ul>
            <MenuContent aria-label={`${entry.label} actions`}>
                <MenuItem onSelect={() => toast(`Editing ${entry.label}`)}>Edit</MenuItem>
                <MenuItem onSelect={() => toast(`Duplicated ${entry.label}`, { tone: 'positive' })}>Duplicate</MenuItem>
                <MenuSeparator />
                <MenuItem tone="negative" onSelect={() => toast(`Deleted ${entry.label}`, { tone: 'negative' })}>
                    Delete
                </MenuItem>
            </MenuContent>
        </Menu>
    );
}
```

### Options

```tsx
import {
    buttonVariants,
    Menu,
    MenuCheckboxItem,
    MenuContent,
    MenuItem,
    MenuRadioGroup,
    MenuRadioItem,
    MenuSeparator,
    MenuSub,
    MenuSubContent,
    MenuSubTrigger,
    MenuTrigger,
    useToast,
} from '@rinzai/zen';
import { useState } from 'react';
// Icons from Heroicons (https://heroicons.com): Settings (cog-6-tooth).

/**
 * Settings that stay put while you change them: checkbox items turn columns on
 * and off, radio items pick the order, and a submenu holds the less used
 * exports. Hover, or use the arrow keys, to open it.
 */
export default function Options() {
    const toast = useToast();
    const [sort, setSort] = useState('date');
    return (
        <Menu>
            <MenuTrigger className={buttonVariants({ variant: 'outline' })}>
                <Settings className="size-4" />
                View
            </MenuTrigger>
            <MenuContent className="w-56">
                <MenuCheckboxItem defaultChecked>Category</MenuCheckboxItem>
                <MenuCheckboxItem defaultChecked>Account</MenuCheckboxItem>
                <MenuCheckboxItem>Notes</MenuCheckboxItem>
                <MenuSeparator />
                <MenuRadioGroup aria-label="Sort by" value={sort} onValueChange={setSort}>
                    <MenuRadioItem value="date">Newest first</MenuRadioItem>
                    <MenuRadioItem value="amount">Largest first</MenuRadioItem>
                </MenuRadioGroup>
                <MenuSeparator />
                <MenuSub>
                    <MenuSubTrigger>Export</MenuSubTrigger>
                    <MenuSubContent>
                        <MenuItem onSelect={() => toast('Exported as CSV')}>CSV</MenuItem>
                        <MenuItem onSelect={() => toast('Exported as PDF')}>PDF</MenuItem>
                        <MenuItem onSelect={() => toast('Exported as JSON')}>JSON</MenuItem>
                    </MenuSubContent>
                </MenuSub>
            </MenuContent>
        </Menu>
    );
}
```

### Sheet

```tsx
import {
    buttonVariants,
    Menu,
    MenuContent,
    MenuItem,
    MenuSeparator,
    MenuSub,
    MenuSubContent,
    MenuSubTrigger,
    MenuTrigger,
    useToast,
} from '@rinzai/zen';
// Icons from Heroicons (https://heroicons.com): Ellipsis (ellipsis-horizontal), Heart (heart), MusicalNote (musical-note), QueueList (queue-list).

/** A song's menu: on a phone (narrow the window), a bottom sheet, its playlists sliding in over it. */
export default function Sheet() {
    const toast = useToast();
    return (
        <Menu>
            <MenuTrigger aria-label="Song actions" className={buttonVariants({ variant: 'ghost', size: 'icon' })}>
                <Ellipsis />
            </MenuTrigger>
            <MenuContent sheet>
                <MenuItem icon={<QueueList className="size-4" />} onSelect={() => toast('Playing next')}>
                    Play next
                </MenuItem>
                <MenuItem icon={<Heart className="size-4" />} onSelect={() => toast('Liked', { tone: 'positive' })}>
                    Like
                </MenuItem>
                <MenuSub>
                    <MenuSubTrigger icon={<MusicalNote className="size-4" />}>Add to playlist</MenuSubTrigger>
                    <MenuSubContent>
                        {['Late night', 'Focus', 'Running', 'Sunday morning'].map((name) => (
                            <MenuItem key={name} onSelect={() => toast(`Added to ${name}`, { tone: 'positive' })}>
                                {name}
                            </MenuItem>
                        ))}
                    </MenuSubContent>
                </MenuSub>
                <MenuSeparator />
                <MenuItem tone="negative" onSelect={() => toast('Removed from queue', { tone: 'negative' })}>
                    Remove from queue
                </MenuItem>
            </MenuContent>
        </Menu>
    );
}
```

### Bar

```tsx
import {
    Menu,
    Menubar,
    MenuCheckboxItem,
    MenuContent,
    MenuItem,
    MenuRadioGroup,
    MenuRadioItem,
    MenuSeparator,
    MenuSub,
    MenuSubContent,
    MenuSubTrigger,
    MenuTrigger,
    useToast,
} from '@rinzai/zen';
import { useState } from 'react';

/**
 * A row of menus, as at the top of an app. Tab to it once: ←→ move between
 * the menus and ↓ opens one; with one open, ←→ go to the next and pointing at
 * another label switches to it.
 */
export default function Bar() {
    const toast = useToast();
    const [period, setPeriod] = useState('month');
    return (
        <Menubar aria-label="Ledger">
            <Menu>
                <MenuTrigger>File</MenuTrigger>
                <MenuContent>
                    <MenuItem onSelect={() => toast('New entry')}>New entry</MenuItem>
                    <MenuItem onSelect={() => toast('Imported')}>Import…</MenuItem>
                    <MenuSub>
                        <MenuSubTrigger>Export</MenuSubTrigger>
                        <MenuSubContent>
                            <MenuItem onSelect={() => toast('Exported as CSV')}>CSV</MenuItem>
                            <MenuItem onSelect={() => toast('Exported as PDF')}>PDF</MenuItem>
                        </MenuSubContent>
                    </MenuSub>
                </MenuContent>
            </Menu>
            <Menu>
                <MenuTrigger>Edit</MenuTrigger>
                <MenuContent>
                    <MenuItem onSelect={() => toast('Undone')}>Undo</MenuItem>
                    <MenuItem onSelect={() => toast('Redone')}>Redo</MenuItem>
                    <MenuSeparator />
                    <MenuItem tone="negative" onSelect={() => toast('Deleted', { tone: 'negative' })}>
                        Delete entry
                    </MenuItem>
                </MenuContent>
            </Menu>
            <Menu>
                <MenuTrigger>View</MenuTrigger>
                <MenuContent className="w-52">
                    <MenuRadioGroup aria-label="Period" value={period} onValueChange={setPeriod}>
                        <MenuRadioItem value="week">Week</MenuRadioItem>
                        <MenuRadioItem value="month">Month</MenuRadioItem>
                        <MenuRadioItem value="year">Year</MenuRadioItem>
                    </MenuRadioGroup>
                    <MenuSeparator />
                    <MenuCheckboxItem defaultChecked>Show categories</MenuCheckboxItem>
                </MenuContent>
            </Menu>
        </Menubar>
    );
}
```

## API reference

### Menu

A list of actions that opens from a button: a native popover, so outside
clicks and Escape close it and focus returns to the button. Arrow keys, Home
and End move between items. Put a MenuTrigger (its content is yours: an icon,
an avatar, a label) and a MenuContent inside; fill the content with MenuItem,
MenuSeparator and MenuHeader. For a context menu, put a MenuContextTrigger
around what it's for instead of a MenuTrigger.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onOpenChange` | `((open: boolean) => void)` |  | Every open and close: the trigger, choosing an item, outside clicks, Escape. |

### MenuTrigger

The button that opens the menu (↓ or ↑ opens it at its first or last item).
Give it an `aria-label` when it shows only an icon or avatar; the menu is
named after it. In a Menubar it's one of the bar's items, and looks it. With
`asChild`, your own button instead.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `asChild` | `boolean` |  | Put the trigger's props on your own button element instead of rendering one. |

### MenuContextTrigger

What a context menu is for, e.g. a row or a card: right-click (or the
keyboard's menu key, or Shift+F10) opens the Menu where the pointer is, and
so does a long press on a phone. While its menu is open it has
`data-popup-open`, to show what the menu is for. With `asChild`, your own
element instead of a div.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `asChild` | `boolean` |  | Put its props on your own element (the single child) instead of a div. |
| `disabled` | `boolean` |  | Leave the browser's own context menu. |

### MenuContent

The menu panel: glass, below the button (above it if there's no room), lined
up with its end edge by default (its start edge in a Menubar). A context menu opens from the pointer
instead; name it with `aria-label`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `"center" \| "end" \| "start"` |  | Which edge of the button the menu lines up with (default end; a context menu starts at the pointer), or centred on it. |
| `offset` | `number` |  | Gap between the button and the menu, in px. |
| `sheet` | `boolean` |  | On phones (below `md`), a bottom sheet instead, as music apps show a song's menu: across the bottom of the screen over a scrim, swiped down to close; its submenus slide in over it, with a way back at the top. |

### MenuItem

One choice in a Menu: closes the menu, then runs `onSelect`. An `icon` sits
before the label (muted, or red with the label when `tone` is negative). With
`asChild`, the item's role and styles go onto your own element instead, such
as a router's Link.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `asChild` | `boolean` |  | Put the item's role and styles on the single child element (a link) instead of a button. |
| `icon` | `ReactNode` |  | Shown before the label; size it yourself (e.g. size-4). |
| `onSelect` | `(() => void)` |  | Runs after the menu closes. |
| `tone` | `"default" \| "negative"` | `default` | `negative` for a destructive choice: red. |

### MenuCheckboxItem

A choice that's on or off, e.g. a column to show: choosing it flips
`checked` and leaves the menu open, so several can be set at once. A tick
shows while it's on.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `checked` | `boolean` |  | On (ticked); give it to control the item, or `defaultChecked` to start it. |
| `defaultChecked` | `boolean` | `false` |  |
| `onCheckedChange` | `((checked: boolean) => void)` |  |  |

### MenuRadioGroup

One choice out of several, e.g. how to sort: put MenuRadioItems inside. Choosing one leaves the menu open.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultValue` | `string \| null` | `null` |  |
| `onValueChange` | `((value: string) => void)` |  |  |
| `value` | `string \| null` |  | The chosen item's `value`; give it to control the group, or `defaultValue` to start it. |

### MenuRadioItem

One of a MenuRadioGroup's choices; a dot marks the chosen one.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `string` |  |  |

### MenuSub

A menu inside a menu, opening beside its item: on hover, or with Enter,
Space or the arrow towards it; the arrow back (or Escape) closes it. Put a
MenuSubTrigger and a MenuSubContent inside, in a MenuContent.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onOpenChange` | `((open: boolean) => void)` |  | Every open and close: the trigger, choosing an item, outside clicks, Escape. |

### MenuSubTrigger

The item a submenu opens from; a chevron after its label points the way.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `ReactNode` |  | Shown before the label; size it yourself (e.g. size-4). |

### MenuSubContent

The submenu's panel, beside its item (on the other side if there's no room), its first item level with it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `offset` | `number` | `8` | Gap between the item and the submenu, in px (counting the menu's own padding). |

### MenuSeparator

A hairline between groups of items.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` |  |  |

### MenuHeader

Content at the top of a menu that isn't a choice, e.g. who is signed in.

No props of its own; it accepts the props of the element it renders.

### Menubar

A row of menus, as at the top of an app (File, Edit, View): put a Menu for
each inside, its MenuTrigger a label. One Tab stop: ←→ move between the
menus, ↓ or Enter opens one; while one is open, ←→ open the one beside it
and pointing at another switches to it. Name it with `aria-label`.

No props of its own; it accepts the props of the element it renders.

---

# Meter

A measure against a limit, like spend against a budget: warm near it, red past it.

```tsx
import { Meter } from '@rinzai/zen';
```

## Examples

### Budget

```tsx
import { formatMoney, Meter } from '@rinzai/zen';

const inr = (paise: number) => formatMoney(paise, 'INR', 'en-IN', { showDecimals: false });

/** Spend against a budget: the bar warms near the limit and turns red past it. */
export default function Budget() {
    const budgets = [
        { label: 'Groceries', spent: 620000, budget: 1000000 },
        { label: 'Dining out', spent: 270000, budget: 300000 },
        { label: 'Transport', spent: 410000, budget: 350000 },
    ];
    return (
        <div className="flex w-80 flex-col gap-5">
            {budgets.map(({ label, spent, budget }) => {
                const over = spent > budget;
                const status = over ? `${inr(spent - budget)} over` : `${inr(budget - spent)} left`;
                return (
                    <Meter
                        key={label}
                        label={label}
                        value={spent}
                        max={budget}
                        detail={`${inr(spent)} / ${inr(budget)}`}
                        hint={status}
                        valueText={`${inr(spent)} of ${inr(budget)}, ${status}`}
                    />
                );
            })}
        </div>
    );
}
```

### Milestones

```tsx
import { Button, formatMoney, Meter } from '@rinzai/zen';
import { useState } from 'react';

const money = (cents: number) => formatMoney(cents, 'USD', 'en-US', { showDecimals: false });

/** A savings goal with milestones at each quarter: the ones passed are notched into the fill. */
export default function Milestones() {
    const [saved, setSaved] = useState(420000);
    const goal = 1000000;
    return (
        <div className="flex w-full max-w-sm flex-col gap-4">
            <Meter
                label="Emergency fund"
                value={saved}
                max={goal}
                marks={[goal / 4, goal / 2, (goal * 3) / 4]}
                tone="default"
                detail={`${money(saved)} / ${money(goal)}`}
                hint={`${Math.floor((saved / goal) * 4)} of 4 milestones`}
                valueText={`${money(saved)} of ${money(goal)}`}
            />
            <Button
                variant="outline"
                className="self-start"
                onClick={() => setSaved((s) => Math.min(goal, s + 100000))}
            >
                Add $1,000
            </Button>
        </div>
    );
}
```

## API reference

### Meter

A measure against a limit, e.g. spend against a budget: a bar with a label,
a figure and a note. Over the limit it turns red; near it, warm. Announced
as a meter, with `valueText` read out instead of the bare number.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `number` |  |  |
| `className` | `string` |  |  |
| `detail` | `ReactNode` |  | Top right, e.g. "₹8,200 / ₹10,000". |
| `hint` | `ReactNode` |  | Below the bar, e.g. "₹1,800 left". |
| `label` | `ReactNode` |  |  |
| `marks` | `number[]` |  | Milestones along the bar, in the same units as value: e.g. [2500, 5000, 7500] of 10000. |
| `max` | `number` | `100` | The limit (default 100). Values past it fill the bar and turn it red. |
| `tone` | `"auto" \| "default" \| "negative" \| "warning"` | `auto` | `auto` picks warning past `warnAt` of max and negative past max. |
| `valueText` | `string` |  | What screen readers say for the value, e.g. "₹8,200 of ₹10,000, ₹1,800 left". |
| `warnAt` | `number` | `0.85` | Fraction of max where `auto` turns to warning (default 0.85). |

---

# Money Input

Amounts in any currency and locale, with shorthand like 1.5L or 10k and sums like 120+45.50, exact to the paisa, and typed in other currencies, converted at your rates. Built on Input Group.

```tsx
import { MoneyInput, MoneyCurrencyMenu, MoneyConversionHint } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { formatMoney, MoneyInput } from '@rinzai/zen';
import { useState } from 'react';

/** Try 1.5L, 2cr, 10k or 1,52,000. Commits on blur or Enter; Escape reverts. */
export default function Default() {
    const [amount, setAmount] = useState<number | null>(15200000);
    return (
        <div className="flex w-64 flex-col gap-2">
            <MoneyInput aria-label="Amount" value={amount} onValueChange={setAmount} currency="INR" locale="en-IN" />
            <p className="text-muted-foreground mt-0! text-xs">
                Value: {amount === null ? 'empty' : `${amount} paise (${formatMoney(amount, 'INR', 'en-IN')})`}
            </p>
        </div>
    );
}
```

### Dollars

```tsx
import { MoneyInput } from '@rinzai/zen';
import { useState } from 'react';

/** Any currency and locale; `allowEmpty` makes an empty field mean null. */
export default function Dollars() {
    const [amount, setAmount] = useState<number | null>(null);
    return (
        <MoneyInput
            aria-label="Budget"
            value={amount}
            onValueChange={setAmount}
            currency="USD"
            locale="en-US"
            allowEmpty
            className="w-64"
        />
    );
}
```

### Convert

```tsx
import { type ForeignAmount, formatMoney, MoneyInput, type RateTable } from '@rinzai/zen';
import { useState } from 'react';

// Your app fetches these (e.g. the ECB's daily rates, from your server); here, a fixed sample.
const SAMPLE: RateTable = {
    base: 'EUR',
    date: '2026-09-29',
    rates: { INR: 98.4, USD: 1.17, GBP: 0.87, AED: 4.3, SGD: 1.5, JPY: 172.6 },
};
const loadRates = () => new Promise<RateTable>((done) => setTimeout(() => done(SAMPLE), 600));

/** Pick another currency from the symbol and type in it: it's converted into rupees at the loaded rate, and the original is kept. */
export default function Convert() {
    const [amount, setAmount] = useState<number | null>(3274000);
    const [original, setOriginal] = useState<ForeignAmount | null>(null);
    return (
        <div className="flex w-72 flex-col gap-2">
            <MoneyInput
                aria-label="Amount"
                value={amount}
                onValueChange={setAmount}
                currency="INR"
                locale="en-IN"
                convert={{
                    currencies: ['USD', 'EUR', 'GBP', 'AED', 'SGD', 'JPY'],
                    loadRates,
                    source: 'ECB',
                    onForeign: setOriginal,
                }}
            />
            <p className="text-muted-foreground mt-0! text-xs">
                Saved: {amount === null ? 'empty' : formatMoney(amount, 'INR', 'en-IN')}
                {original && `, typed as ${formatMoney(original.amount, original.currency, 'en-IN')}`}
            </p>
        </div>
    );
}
```

### Compact

```tsx
import { MoneyInput } from '@rinzai/zen';
import { useState } from 'react';

/** `compact`: shorter and right-aligned, for editing inside table rows. */
export default function Compact() {
    const [amount, setAmount] = useState<number | null>(1640000);
    return (
        <MoneyInput
            compact
            aria-label="Groceries"
            value={amount}
            onValueChange={setAmount}
            currency="INR"
            locale="en-IN"
            className="w-36"
        />
    );
}
```

## API reference

### MoneyInput

Amount input in one currency. Shows grouped digits for the locale (1,52,000
for en-IN) and accepts shorthand: 1.5L, 2cr, 10k, 1.2m, and sums: 120+45.50,
3*12.99. Commits on blur or Enter; Escape reverts. Values are integer minor
units (paise, cents), or null when empty.

With `convert`, the symbol becomes a currency switch: type an amount in e.g.
USD and it's converted at the rates you load (in the browser; the amount is
never sent anywhere). Replace the symbol with `start`, or build your own field
from useMoneyInput, MoneyCurrencyMenu and MoneyConversionHint.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `currency` (required) | `string` |  | ISO 4217 code, e.g. "INR", "USD". |
| `allowEmpty` | `boolean` |  |  |
| `allowNegative` | `boolean` |  |  |
| `compact` | `boolean` | `false` | Smaller still and right-aligned, for editing inside table rows. |
| `convert` | `CurrencyConversion` |  | Let people type in another currency, converted at the rates you load. |
| `defaultValue` | `number \| null` |  | The first amount, when the field keeps its own. |
| `end` | `ReactNode` |  | Content after the input, e.g. a unit or a clear button. |
| `live` | `boolean` |  | For forms: report the amount (converted, when typed in another currency) on every keystroke instead of on blur, so a Save button can never miss it. Invalid text reports null. |
| `locale` | `string` |  | Decides digit grouping and the symbol, e.g. "en-IN" (1,52,000) or "en-US" (152,000). Defaults to the LocaleProvider's. |
| `onCancel` | `(() => void)` |  | Called on Escape, after reverting. |
| `onValueChange` | `((value: number \| null) => void)` |  |  |
| `size` | `"default" \| "lg" \| "sm"` |  | Height, matching Button's: sm (32px), default (40px) or lg (44px). |
| `start` | `ReactNode` |  | Replaces the currency symbol (or the currency switch), e.g. with your own. |
| `value` | `number \| null` |  | Amount in minor units (paise, cents), or null when empty, when you keep it. |

### MoneyCurrencyMenu

The currency switch for a converting field (`convert`): shows the symbol, or
the code of the foreign currency being typed in, and opens a menu of your
currency and the ones with a rate. Put it in an InputGroup's start slot.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `money` (required) | `{ inputProps: { readonly type: "text"; readonly inputMode: "decimal"; readonly autoComplete: "off"; readonly spellCheck: false; readonly value: string; readonly 'aria-invalid': true \| undefined; ... 4 more ...; readonly onKeyDown: (e: KeyboardEvent<...>) => void; }; ... 10 more ...; conversion: { ...; } \| null; }` |  |  |
| `className` | `string` |  |  |

### MoneyConversionHint

The line under a converting field: getting the rate, the rate and what the
typed amount comes to, or what the last amount was converted from.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `money` (required) | `{ inputProps: { readonly type: "text"; readonly inputMode: "decimal"; readonly autoComplete: "off"; readonly spellCheck: false; readonly value: string; readonly 'aria-invalid': true \| undefined; ... 4 more ...; readonly onKeyDown: (e: KeyboardEvent<...>) => void; }; ... 10 more ...; conversion: { ...; } \| null; }` |  |  |
| `className` | `string` |  |  |

---

# Month Picker

A field showing a month that opens a year and a 12-month grid, with optional limits and clearing.

```tsx
import { MonthPicker } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { MonthPicker } from '@rinzai/zen';
import { useState } from 'react';

export default function Default() {
    const [month, setMonth] = useState<string | null>('2026-09');
    return <MonthPicker aria-label="Month" value={month} onValueChange={setMonth} locale="en-IN" className="w-48" />;
}
```

### Range

```tsx
import { addMonths, MonthPicker } from '@rinzai/zen';
import { useState } from 'react';

/** A start and an optional end: the end can't come before the start, and can be cleared. */
export default function Range() {
    const [start, setStart] = useState<string | null>('2026-10');
    const [end, setEnd] = useState<string | null>('2027-09');
    return (
        <div className="flex items-end gap-3">
            <label className="flex flex-col gap-2 text-sm font-medium">
                Starts
                <MonthPicker value={start} onValueChange={setStart} locale="en-US" className="w-40" />
            </label>
            <label className="flex flex-col gap-2 text-sm font-medium">
                Ends
                <MonthPicker
                    value={end}
                    onValueChange={setEnd}
                    locale="en-US"
                    min={start ? addMonths(start, 1) : undefined}
                    placeholder="No end"
                    clearable
                    clearLabel="No end"
                    className="w-40"
                />
            </label>
        </div>
    );
}
```

## API reference

### MonthPicker

Month selector: a field showing "Sep 2026" that opens a year and a 12-month
grid. Months are "YYYY-MM" strings. When `clearable`, the popup also offers
`clearLabel` (e.g. "No end") to empty it. With `name`, it's submitted with a form.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` |  | Classes for the trigger (e.g. a width, instead of the default full width). |
| `clearable` | `boolean` | `false` | Offers a clear option in the popup (shown when a month is set); clearing reports null. |
| `clearLabel` | `string` |  |  |
| `defaultValue` | `string \| null` | `null` | The first month, when the picker keeps its own. |
| `disabled` | `boolean` | `false` |  |
| `id` | `string` |  |  |
| `locale` | `string` |  | Decides month names and format, e.g. "en-IN". Defaults to the LocaleProvider's. |
| `max` | `string` |  | Latest month that can be picked. |
| `min` | `string` |  | Earliest month that can be picked ("YYYY-MM"). |
| `name` | `string` |  | Form field name: the month ("YYYY-MM") is submitted with the form. |
| `onValueChange` | `((month: string \| null) => void)` |  |  |
| `placeholder` | `string` |  |  |
| `size` | `"default" \| "lg" \| "sm"` | `default` | Height, matching Button's: sm (32px), default (40px) or lg (44px). |
| `value` | `string \| null` |  | "YYYY-MM", or null for none, when you keep it. |

---

# Navigation Menu

A site’s navigation: links, and labels that open glass panels of links on hover or click, switching at once between them; works with any router.

```tsx
import { NavigationMenu, NavigationMenuItem, NavigationMenuTrigger, NavigationMenuContent, NavigationMenuLink } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import {
    NavigationMenu,
    NavigationMenuContent,
    NavigationMenuItem,
    NavigationMenuLink,
    NavigationMenuTrigger,
} from '@rinzai/zen';

/**
 * A site's top navigation: rest the pointer on Plan or Reports (or click, or
 * Tab to one and press Enter) for its panel; once one is open, moving to the
 * other switches at once.
 */
export default function Default() {
    return (
        <NavigationMenu aria-label="Site">
            <NavigationMenuItem>
                <NavigationMenuLink href="#overview" active>
                    Overview
                </NavigationMenuLink>
            </NavigationMenuItem>
            <NavigationMenuItem>
                <NavigationMenuTrigger>Plan</NavigationMenuTrigger>
                <NavigationMenuContent className="grid w-[26rem] grid-cols-2 gap-1">
                    <NavigationMenuLink href="#budgets" description="Limits for each category, month by month.">
                        Budgets
                    </NavigationMenuLink>
                    <NavigationMenuLink href="#goals" description="Savings with a target and a date.">
                        Goals
                    </NavigationMenuLink>
                    <NavigationMenuLink href="#bills" description="What's due, and when it repeats.">
                        Bills
                    </NavigationMenuLink>
                    <NavigationMenuLink href="#planner" description="The year ahead, item by item.">
                        Planner
                    </NavigationMenuLink>
                </NavigationMenuContent>
            </NavigationMenuItem>
            <NavigationMenuItem>
                <NavigationMenuTrigger>Reports</NavigationMenuTrigger>
                <NavigationMenuContent className="flex w-60 flex-col">
                    <NavigationMenuLink href="#spending">Spending</NavigationMenuLink>
                    <NavigationMenuLink href="#income">Income</NavigationMenuLink>
                    <NavigationMenuLink href="#net-worth">Net worth</NavigationMenuLink>
                </NavigationMenuContent>
            </NavigationMenuItem>
            <NavigationMenuItem>
                <NavigationMenuLink href="#help">Help</NavigationMenuLink>
            </NavigationMenuItem>
        </NavigationMenu>
    );
}
```

### Router

```tsx
import {
    NavigationMenu,
    NavigationMenuContent,
    NavigationMenuItem,
    NavigationMenuLink,
    NavigationMenuTrigger,
} from '@rinzai/zen';
import { useState } from 'react';

const ACCOUNTS = ['Everyday', 'Savings', 'Credit card'];

/**
 * With your router: `asChild` puts each link's look and wiring on your own
 * Link (a button stands in for one here), and `active` follows the page.
 */
export default function Router() {
    const [page, setPage] = useState('Everyday');
    return (
        <div className="flex flex-col items-center gap-4">
            <NavigationMenu aria-label="Accounts">
                <NavigationMenuItem>
                    <NavigationMenuTrigger>Accounts</NavigationMenuTrigger>
                    <NavigationMenuContent className="flex w-48 flex-col">
                        {ACCOUNTS.map((name) => (
                            <NavigationMenuLink key={name} asChild active={page === name}>
                                <button type="button" className="text-start" onClick={() => setPage(name)}>
                                    {name}
                                </button>
                            </NavigationMenuLink>
                        ))}
                    </NavigationMenuContent>
                </NavigationMenuItem>
            </NavigationMenu>
            <p className="text-muted-foreground mt-0! text-sm">Showing {page}</p>
        </div>
    );
}
```

## API reference

### NavigationMenu

A site's navigation: links, and labels that open panels of links below
them, on hover (after `openDelay`; at once while another is open) or with a
click or Enter. Escape, a click outside or Tab moving on closes it. Fill it
with NavigationMenuItems, each a NavigationMenuLink, or a
NavigationMenuTrigger and a NavigationMenuContent. Name it with
`aria-label` when there's more than one nav on the page.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `closeDelay` | `number` | `200` | How long a panel opened by the pointer stays after it leaves, in ms (time to reach the panel). |
| `openDelay` | `number` | `150` | How long the pointer rests on a label before its panel opens, in ms. |

### NavigationMenuItem

One place in the menu: a link, or a label with its panel.

No props of its own; it accepts the props of the element it renders.

### NavigationMenuTrigger

The label that opens its item's panel; a chevron after it turns over while it's open.

No props of its own; it accepts the props of the element it renders.

### NavigationMenuContent

The panel: glass, below its label (above it if there's no room), lined up with its start. Lay out its links as you like.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `"center" \| "end" \| "start"` | `start` |  |
| `offset` | `number` | `8` | Gap below the label, in px. |

### NavigationMenuLink

A link: one of the bar's labels at the top, or a row in a panel (with an
optional `description` under its text). `active` marks the page you're on.
With `asChild`, your router's link instead of an `<a>`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `active` | `boolean` |  | The page it leads to is the one you're on. |
| `asChild` | `boolean` |  | Put its props on your own link (the single child), e.g. a router's Link. |
| `description` | `string` |  | In a panel, a line under the link's text. |

---

# Number Field

A number to type or step with − and +, the arrow keys and Page Up and Down: shown the locale’s way, as a percentage or a unit, and kept within bounds. Each change says whether it was a step (and by how much) or typed, and onValueCommit fires once it’s finished.

```tsx
import { NumberField } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { Field, NumberField } from '@rinzai/zen';

/** Type, use − and +, or ↑↓: kept between 1 and 12. */
export default function Default() {
    return (
        <Field label="Split between" hint="People sharing the bill" className="w-56">
            <NumberField defaultValue={2} min={1} max={12} />
        </Field>
    );
}
```

### Formats

```tsx
import { Field, NumberField } from '@rinzai/zen';
import { useState } from 'react';

/** `formatOptions` shows it as a percentage, a unit or with set decimals, and reads it back typed that way. */
export default function Formats() {
    const [rate, setRate] = useState<number | null>(0.065);
    return (
        <div className="flex w-56 flex-col gap-4">
            <Field label="Interest rate">
                <NumberField
                    value={rate}
                    onValueChange={setRate}
                    step={0.0025}
                    min={0}
                    max={0.3}
                    formatOptions={{ style: 'percent', minimumFractionDigits: 2 }}
                />
            </Field>
            <Field label="Distance">
                <NumberField
                    defaultValue={12.5}
                    step={0.5}
                    min={0}
                    formatOptions={{ style: 'unit', unit: 'kilometer' }}
                />
            </Field>
        </div>
    );
}
```

### Steps

```tsx
import { Field, NumberField } from '@rinzai/zen';
import { useState } from 'react';

const clamp = (n: number) => Math.min(10, Math.max(0, n));

/**
 * A count kept somewhere else, such as a server another device also changes.
 * `onValueCommit` says how each change came about: − + and ↑↓ send their step
 * (`delta`), added to whatever the count is by then; a typed number is sent
 * once, on Enter or on leaving the field.
 */
export default function Steps() {
    const [count, setCount] = useState(3);
    const [sent, setSent] = useState<string | null>(null);
    return (
        <Field label="Episodes watched" hint={sent ? `Sent ${sent}` : 'Out of 10'} className="w-56">
            <NumberField
                value={count}
                min={0}
                max={10}
                size="sm"
                onValueCommit={(n, change) => {
                    if (change.reason === 'step') {
                        setCount((now) => clamp(now + change.delta));
                        setSent(change.delta > 0 ? `+${change.delta}` : `−${-change.delta}`);
                    } else {
                        setCount(n ?? 0);
                        setSent(String(n ?? 0));
                    }
                }}
            />
        </Field>
    );
}
```

## API reference

### NumberField

A number to type or step: − and + on either side, ↑↓ by `step`, Page Up and
Page Down by `largeStep`, Home and End to `min` and `max`. Shown in the
locale's way (`formatOptions`: a percentage, a unit, decimals) and read back
from what's typed in it, digits, separators and all. Kept within `min` and
`max` once you leave the field; empty is null.

Each change says how it came about: `{ reason: 'step', delta }` for − +,
↑↓ and Page Up/Down, `'input'` for typing, `'limit'` for Home and End. So a
step can be sent on as a step, and the number kept by whoever owns it.
`onValueCommit` fires once per finished change: each step, and what's typed
on Enter or on leaving the field.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultValue` | `number \| null` | `null` | The first number, when the field keeps its own. |
| `formatOptions` | `NumberFormatOptions` |  | How it's shown, as for Intl.NumberFormat: { style: 'percent' }, { maximumFractionDigits: 2 }, a unit. |
| `invalid` | `boolean` |  | Show the field in its error state. |
| `largeStep` | `number` | `step * 10` | What Page Up and Page Down do. Default ten steps. |
| `locale` | `string` |  | Defaults to the LocaleProvider's. |
| `max` | `number` |  |  |
| `min` | `number` |  |  |
| `name` | `string` |  | Form field name: the number is submitted under it. |
| `onValueChange` | `((value: number \| null, details: NumberFieldChange) => void)` |  | Every change, typing included; `details` says how it came about. |
| `onValueCommit` | `((value: number \| null, details: NumberFieldChange) => void)` |  | Each finished change: a step, Home or End, or what's typed, on Enter or on leaving the field. |
| `size` | `"default" \| "lg" \| "sm"` | `default` | Height, matching Button's. |
| `step` | `number` | `1` | What ↑↓ and − + add or take away. Default 1. |
| `value` | `number \| null` |  | The number, or null for empty, when you keep it. |

---

# Page Header

Eyebrow, aurora title and lead paragraph for the top of a page.

```tsx
import { PageHeader } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { buttonVariants, PageHeader } from '@rinzai/zen';

export default function Default() {
    return (
        <PageHeader eyebrow="Budget" title="Month overview" lead="Where your money went in September, and what's left.">
            <div className="flex gap-3">
                <a href="#add" className={buttonVariants()}>
                    Add entry
                </a>
                <a href="#export" className={buttonVariants({ variant: 'outline' })}>
                    Export
                </a>
            </div>
        </PageHeader>
    );
}
```

## API reference

### PageHeader

Top of a page: a small eyebrow label, the title in the aurora gradient, and a lead paragraph.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` (required) | `ReactNode` |  |  |
| `children` | `ReactNode` |  | Anything after the lead, e.g. a row of buttons. |
| `className` | `string` |  |  |
| `eyebrow` | `ReactNode` |  |  |
| `lead` | `ReactNode` |  |  |

---

# Page Transition

The old page fades out as the new one rises in, when your router changes page in a view transition.

```tsx
import { PageTransition } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { PageTransition, Pill, PillIndicator, Pills, Stat, StatRow } from '@rinzai/zen';
import { useState } from 'react';
import { flushSync } from 'react-dom';

const PAGES = {
    overview: {
        title: 'Overview',
        stats: [
            ['Net', '$2,410'],
            ['Spent', '$1,845'],
        ],
    },
    budgets: {
        title: 'Budgets',
        stats: [
            ['On track', '4 of 5'],
            ['Left', '$655'],
        ],
    },
    goals: {
        title: 'Goals',
        stats: [
            ['Saved', '$12,940'],
            ['Next', 'Holiday'],
        ],
    },
} as const;
type Page = keyof typeof PAGES;

/** A router does this for you (React Router: `viewTransition` on a Link); here, by hand. */
export default function Default() {
    const [page, setPage] = useState<Page>('overview');
    const go = (next: Page) => {
        if (!document.startViewTransition) return setPage(next);
        document.startViewTransition(() => flushSync(() => setPage(next)));
    };
    return (
        <div className="flex w-full max-w-md flex-col gap-4">
            <nav aria-label="Pages">
                <Pills>
                    <PillIndicator />
                    {(Object.keys(PAGES) as Page[]).map((p) => (
                        <Pill
                            key={p}
                            href={`#${p}`}
                            active={p === page}
                            onClick={(e) => {
                                e.preventDefault();
                                go(p);
                            }}
                        >
                            {PAGES[p].title}
                        </Pill>
                    ))}
                </Pills>
            </nav>
            <PageTransition>
                <h3 className="mb-3 text-lg font-semibold">{PAGES[page].title}</h3>
                <StatRow className="sm:grid-cols-2!">
                    {PAGES[page].stats.map(([label, value]) => (
                        <Stat key={label} label={label} value={value} />
                    ))}
                </StatRow>
            </PageTransition>
        </div>
    );
}
```

## API reference

### PageTransition

The page's content, which changes between pages: wrap your route's outlet in
it, and when the router changes page in a view transition (React Router's
`viewTransition`, or document.startViewTransition yourself) the old page
fades out as the new one rises in, while everything outside (header, nav)
stays still. One per page.

No props of its own; it accepts the props of the element it renders.

---

# Pagination

The pages a long list is split into, as buttons or links for your router.

```tsx
import { Pagination } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { Pagination } from '@rinzai/zen';
import { useState } from 'react';

/** Pages as buttons. With a router, give `href` and render each with its Link through `renderLink`. */
export default function Default() {
    const [page, setPage] = useState(6);
    return <Pagination page={page} count={12} onPageChange={setPage} />;
}
```

## API reference

### Pagination

The pages a long list is split into: previous and next, the first and last
pages, and those around the current one (`page`, from 1). Pages are buttons
calling `onPageChange`, or with `href`, links (render them with your router's
Link through `renderLink`).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `count` (required) | `number` |  | How many pages there are. With fewer than 2, nothing is shown. |
| `page` (required) | `number` |  | The current page, from 1. |
| `aria-label` | `string` |  |  |
| `className` | `string` |  |  |
| `href` | `((page: number) => string)` |  | Pages as links: the URL of each. |
| `onPageChange` | `((page: number) => void)` |  |  |
| `renderLink` | `((props: DetailedHTMLProps<AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>, page: number) => ReactNode)` | `(props) => <a {...props} />` | Renders a page link, e.g. with your router's Link. |
| `siblings` | `number` | `1` | Pages shown either side of the current one. |

---

# Pills

A glass track with a glowing pill that slides to the current page. In a nav, it is site navigation; works with any router.

```tsx
import { Pills, Pill, PillIndicator } from '@rinzai/zen';
```

## Examples

### Navigation

```tsx
import { Pill, PillIndicator, Pills } from '@rinzai/zen';
import { useState } from 'react';

const PAGES = ['Month', 'Planner', 'Loans', 'Goals', 'Trends'];

/**
 * Site navigation: Pills in a <nav>. With a router, pass its link as the child:
 * <Pill asChild><NavLink to="/goals">Goals</NavLink></Pill>.
 */
export default function Navigation() {
    const [current, setCurrent] = useState('Month');
    return (
        <nav aria-label="Main">
            <Pills>
                <PillIndicator />
                {PAGES.map((page) => (
                    <Pill
                        key={page}
                        href={`#${page.toLowerCase()}`}
                        active={page === current}
                        onClick={(e) => {
                            e.preventDefault();
                            setCurrent(page);
                        }}
                    >
                        {page}
                    </Pill>
                ))}
            </Pills>
        </nav>
    );
}
```

## API reference

### Pills

A glass track of pills, with an optional glowing pill that slides to the
active one: whichever has aria-current="page" (router links such as React
Router's NavLink set it themselves) or aria-selected="true". It adds no role
of its own; what you wrap it in says what it is. Site navigation:

  <nav aria-label="Main">
      <Pills>
          <PillIndicator />
          <Pill href="/month" active>Month</Pill>
          <Pill asChild><NavLink to="/goals">Goals</NavLink></Pill>
      </Pills>
  </nav>

For tabs that switch panels in place, use Tabs with `<TabList variant="pills">`.

No props of its own; it accepts the props of the element it renders.

### Pill

One pill: a link. `active` marks the current page. With `asChild`, the
styles go onto your own element instead (a router's Link or NavLink).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `active` | `boolean` |  | This pill is the current page (aria-current="page"). |
| `asChild` | `boolean` |  | Style the single child element (e.g. a router link) instead of rendering an <a>. |

### PillIndicator

The glowing pill under the active item. Place it inside Pills; hidden while none is active.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` |  |  |

---

# Player Bar

What's playing, along the bottom of the screen, sitting on a TabBar on phones. useMediaPlayer drives your own <audio> or <video>; useMediaSession puts it on the lock screen and the media keys.

```tsx
import { PlayerBar, useMediaPlayer, useMediaSession } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { Button, PlayerBar, SeekBar, Slider, useMediaPlayer, useMediaSession } from '@rinzai/zen';

import { useDemoTrack } from './demo-track';
// Icons from Heroicons (https://heroicons.com): Backward (backward), Pause (pause), Play (play), SpeakerWave (speaker-wave), SpeakerXMark (speaker-x-mark).

/**
 * Your own <audio>, driven by useMediaPlayer: the cover and title, the controls
 * over a SeekBar, and the volume. useMediaSession puts it on the lock screen
 * and the media keys. Fixed to the bottom of the screen; here it sits in a frame.
 */
export default function Default() {
    const src = useDemoTrack();
    const [audioRef, player] = useMediaPlayer();
    useMediaSession(player, { title: 'Glass Aurora', artist: 'Zen' });
    return (
        <div className="border-tint/10 relative h-48 w-full [transform:translateZ(0)] overflow-hidden rounded-2xl border">
            <audio ref={audioRef} src={src} preload="metadata" />
            <PlayerBar aria-label="Now playing" className="absolute! justify-between rounded-b-[15px]">
                <div className="flex min-w-0 flex-1 items-center gap-3">
                    <div className="from-primary size-11 shrink-0 rounded-lg bg-linear-135 to-fuchsia-400" />
                    <div className="min-w-0">
                        <p className="truncate text-sm font-medium">Glass Aurora</p>
                        <p className="text-muted-foreground truncate text-xs">Zen</p>
                    </div>
                </div>
                <div className="flex flex-[2] flex-col items-center gap-1">
                    <div className="flex items-center gap-2">
                        <Button variant="ghost" size="icon-sm" aria-label="Restart" onClick={() => player.seek(0)}>
                            <Backward className="size-4" />
                        </Button>
                        <Button
                            size="icon"
                            className="rounded-full"
                            aria-label={player.playing ? 'Pause' : 'Play'}
                            disabled={!src}
                            onClick={() => player.toggle()}
                        >
                            {player.playing ? <Pause className="size-5" /> : <Play className="size-5" />}
                        </Button>
                    </div>
                    <SeekBar
                        className="w-full"
                        currentTime={player.currentTime}
                        playing={player.playing && !player.waiting}
                        playbackRate={player.playbackRate}
                        duration={player.duration}
                        buffered={player.buffered}
                        onSeek={player.seek}
                    />
                </div>
                <div className="hidden flex-1 items-center justify-end gap-2 sm:flex">
                    <Button
                        variant="ghost"
                        size="icon-sm"
                        aria-label={player.muted ? 'Unmute' : 'Mute'}
                        onClick={() => player.setMuted(!player.muted)}
                    >
                        {player.muted ? <SpeakerXMark className="size-4" /> : <SpeakerWave className="size-4" />}
                    </Button>
                    <Slider
                        aria-label="Volume"
                        className="w-24"
                        value={player.muted ? 0 : Math.round(player.volume * 100)}
                        onValueChange={(v) => {
                            player.setVolume(v / 100);
                            if (v > 0 && player.muted) player.setMuted(false);
                        }}
                    />
                </div>
            </PlayerBar>
        </div>
    );
}
```

### On tab bar

```tsx
import { Button, PlayerBar, TabBar, TabBarItem, useMediaPlayer } from '@rinzai/zen';

import { useDemoTrack } from './demo-track';
// Icons from Heroicons (https://heroicons.com): Pause (pause), Play (play), Search (magnifying-glass), Squares (squares-2x2), ListBullet (list-bullet).

/**
 * On a phone, it sits on the TabBar beside it, and the page pads its end by
 * both bars' heights (--zen-tab-bar-height and --zen-player-bar-height).
 */
export default function OnTabBar() {
    const src = useDemoTrack();
    const [audioRef, player] = useMediaPlayer();
    const progress = player.duration ? (player.currentTime / player.duration) * 100 : 0;
    return (
        <div className="border-tint/10 relative h-96 w-80 [transform:translateZ(0)] overflow-hidden rounded-2xl border">
            <audio ref={audioRef} src={src} preload="metadata" />
            <div className="h-full overflow-y-auto p-4 pb-[calc(var(--zen-tab-bar-height,0px)+var(--zen-player-bar-height,0px))]">
                <p className="text-muted-foreground text-sm">Home</p>
            </div>
            <PlayerBar aria-label="Now playing" className="absolute! gap-3 px-3 pt-2 pb-2">
                <div className="from-primary size-9 shrink-0 rounded-md bg-linear-135 to-fuchsia-400" />
                <div className="min-w-0 flex-1">
                    <p className="truncate text-sm font-medium">Glass Aurora</p>
                    <p className="text-muted-foreground truncate text-xs">Zen</p>
                </div>
                <Button
                    variant="ghost"
                    size="icon-sm"
                    aria-label={player.playing ? 'Pause' : 'Play'}
                    disabled={!src}
                    onClick={() => player.toggle()}
                >
                    {player.playing ? <Pause className="size-5" /> : <Play className="size-5" />}
                </Button>
                <span
                    aria-hidden
                    className="bg-primary absolute start-0 bottom-0 h-0.5 shadow-[0_0_8px_oklch(var(--glow)/calc(0.8*var(--glow-k)))]"
                    style={{ width: `${progress}%` }}
                />
            </PlayerBar>
            <TabBar aria-label="Main" hideFrom={false} className="absolute! rounded-b-[15px]">
                <TabBarItem href="#home" icon={<Squares />} active onClick={(e) => e.preventDefault()}>
                    Home
                </TabBarItem>
                <TabBarItem href="#search" icon={<Search />} onClick={(e) => e.preventDefault()}>
                    Search
                </TabBarItem>
                <TabBarItem href="#library" icon={<ListBullet />} onClick={(e) => e.preventDefault()}>
                    Library
                </TabBarItem>
            </TabBar>
        </div>
    );
}
```

## API reference

### PlayerBar

What's playing, along the bottom of the screen: a glass bar for the cover,
the title, the controls and a SeekBar, laid out as you like. It sits on a
TabBar beside it (in the same parent), and clears the home indicator where
there's none. Its height is kept in `--zen-player-bar-height` on that
parent, for the page to pad its end by. Name it with an aria-label ("Now playing"). Drive it with useMediaPlayer.

No props of its own; it accepts the props of the element it renders.

---

# Popover

A glass panel that opens from a button, on the native Popover API: small forms, cards and settings. For hints use Tooltip; for actions, Menu.

```tsx
import { Popover, PopoverTrigger, PopoverContent, PopoverClose } from '@rinzai/zen';
```

## Examples

### Profile card

```tsx
import { Badge, Button, Popover, PopoverContent, PopoverTrigger } from '@rinzai/zen';

/** Your own trigger: here an avatar button. */
export default function ProfileCard() {
    return (
        <Popover>
            <PopoverTrigger
                aria-label="Alex Johnson"
                className="bg-primary text-primary-foreground flex size-9 items-center justify-center rounded-full text-sm font-bold"
            >
                AJ
            </PopoverTrigger>
            <PopoverContent aria-label="Alex Johnson">
                <div className="flex w-64 flex-col gap-3 p-4">
                    <div className="flex items-center gap-3">
                        <div className="bg-primary text-primary-foreground flex size-10 items-center justify-center rounded-full text-sm font-bold">
                            AJ
                        </div>
                        <div className="flex flex-col">
                            <span className="text-sm font-semibold">Alex Johnson</span>
                            <span className="text-muted-foreground text-xs">alex@example.com</span>
                        </div>
                    </div>
                    <div className="flex gap-2">
                        <Badge>Admin</Badge>
                        <Badge variant="outline">Pro</Badge>
                    </div>
                    <div className="border-tint/10 flex flex-col gap-1 border-t pt-3">
                        <Button variant="ghost" size="sm" className="justify-start">
                            View profile
                        </Button>
                        <Button variant="ghost" size="sm" className="justify-start">
                            Settings
                        </Button>
                        <Button variant="ghost" size="sm" className="text-destructive justify-start">
                            Sign out
                        </Button>
                    </div>
                </div>
            </PopoverContent>
        </Popover>
    );
}
```

### Feedback form

```tsx
import { Button, Input, Popover, PopoverClose, PopoverContent, PopoverTrigger, Textarea } from '@rinzai/zen';

export default function FeedbackForm() {
    return (
        <Popover>
            <PopoverTrigger asChild>
                <Button variant="outline">Give feedback</Button>
            </PopoverTrigger>
            <PopoverContent aria-labelledby="feedback-title">
                <div className="flex w-72 flex-col gap-3 p-4">
                    <p id="feedback-title" className="text-sm font-semibold">
                        Send feedback
                    </p>
                    <Input placeholder="Subject" />
                    <Textarea placeholder="Describe your feedback…" className="resize-none" />
                    <div className="flex justify-end gap-2">
                        <PopoverClose variant="outline" size="sm">
                            Cancel
                        </PopoverClose>
                        <Button size="sm">Submit</Button>
                    </div>
                </div>
            </PopoverContent>
        </Popover>
    );
}
```

### Settings

```tsx
import { Button, Popover, PopoverContent, PopoverTrigger, Toggle } from '@rinzai/zen';
import { useState } from 'react';

export default function Settings() {
    const [settings, setSettings] = useState({ notifications: true, sounds: false, autoSave: true });
    const rows = [
        { key: 'notifications', label: 'Notifications' },
        { key: 'sounds', label: 'Sounds' },
        { key: 'autoSave', label: 'Auto-save' },
    ] as const;
    return (
        <Popover>
            <PopoverTrigger asChild>
                <Button variant="outline">Preferences</Button>
            </PopoverTrigger>
            <PopoverContent aria-label="Preferences">
                <div className="flex w-60 flex-col gap-3 p-4">
                    <p className="text-sm font-semibold">Preferences</p>
                    {rows.map(({ key, label }) => (
                        <label key={key} className="flex items-center justify-between font-normal">
                            {label}
                            <Toggle
                                checked={settings[key]}
                                onCheckedChange={(on) => setSettings((s) => ({ ...s, [key]: on }))}
                            />
                        </label>
                    ))}
                </div>
            </PopoverContent>
        </Popover>
    );
}
```

### Controlled

```tsx
import { Button, Popover, PopoverClose, PopoverContent, PopoverTrigger } from '@rinzai/zen';
import { useState } from 'react';

/** Follow your own state with `open`; `onOpenChange` hears every open and close (outside clicks, Escape…). */
export default function Controlled() {
    const [open, setOpen] = useState(false);
    return (
        <Popover open={open} onOpenChange={setOpen}>
            <PopoverTrigger asChild>
                <Button>{open ? 'Hide' : 'Show'} popover</Button>
            </PopoverTrigger>
            <PopoverContent aria-label="Controlled">
                <div className="flex flex-col gap-2 p-3 text-sm">
                    <p className="font-medium">Manually controlled</p>
                    <PopoverClose size="sm" variant="secondary">
                        Close
                    </PopoverClose>
                </div>
            </PopoverContent>
        </Popover>
    );
}
```

## API reference

### Popover

A panel that opens from a button: a small form, a profile card, settings. A
native popover, so outside clicks and Escape close it and focus returns to
the button. Put a PopoverTrigger and a PopoverContent inside. Opens and closes
on its own, or follows `open` (with `onOpenChange` to hear the user close it).
For a hint on hover or focus, use Tooltip; for a list of actions, Menu.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultOpen` | `boolean` | `false` | Open when it first appears. |
| `onOpenChange` | `((open: boolean) => void)` |  | Every open and close: the trigger, outside clicks, Escape, PopoverClose. |
| `open` | `boolean` |  | Open or close it from your state; leave it out to let the trigger do it. |

### PopoverTrigger

The button that opens and closes the popover. With `asChild`, your own button (e.g. a Button) instead.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `asChild` | `boolean` |  | Put the trigger's props on your own button element instead of rendering one. |

### PopoverContent

The panel: glass, below the trigger (above it if there's no room), centred on
it by default. A dialog to assistive tech; give it `aria-label` or a heading
it's labelled by when it holds a form.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `"center" \| "end" \| "start"` | `center` | Centred on the trigger (default), or lined up with its start or end edge. |
| `offset` | `number` | `5` | Gap from the trigger, in px. |

### PopoverClose

A button that closes its popover (after its own onClick, unless that calls
preventDefault). Takes every Button prop: variant, size, asChild…

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `asChild` | `boolean` |  | Put the button's styles on the single child element (e.g. a link) instead of a <button>. |
| `loading` | `boolean` |  | Shows a spinner and disables the button while an action runs. |
| `size` | `"default" \| "icon-lg" \| "icon-sm" \| "icon-xs" \| "icon" \| "lg" \| "sm" \| null` |  |  |
| `tone` | `"default" \| "inherit" \| "muted" \| "negative" \| null` |  |  |
| `variant` | `"default" \| "ghost" \| "link" \| "outline" \| "secondary" \| null` |  |  |

---

# Progress Ring

Circular progress with room for a label in the middle.

```tsx
import { ProgressRing } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { ProgressRing } from '@rinzai/zen';

export default function Default() {
    return (
        <div className="flex items-center gap-6">
            {[0.28, 0.64, 1].map((value) => (
                <ProgressRing key={value} value={value} label={`${Math.round(value * 100)}% saved`}>
                    <span className="text-sm font-semibold tabular-nums">{Math.round(value * 100)}%</span>
                </ProgressRing>
            ))}
        </div>
    );
}
```

### Goal

```tsx
import { Button, ProgressRing } from '@rinzai/zen';
import { useState } from 'react';

/** Reaching the goal sends out a ring of glow. */
export default function Goal() {
    const [saved, setSaved] = useState(120);
    const goal = 200;
    return (
        <div className="flex items-center gap-6">
            <ProgressRing value={saved / goal} label="Holiday fund">
                <span className="text-sm font-semibold tabular-nums">${saved}</span>
            </ProgressRing>
            <div className="flex flex-col gap-2">
                <Button variant="outline" onClick={() => setSaved((s) => Math.min(s + 40, goal))}>
                    Save $40
                </Button>
                <Button variant="ghost" onClick={() => setSaved(120)}>
                    Reset
                </Button>
            </div>
        </div>
    );
}
```

## API reference

### ProgressRing

Circular progress, 0–1, with optional content in the middle. Reaching 1
while shown sends out a ring of glow, once.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` |  | Accessible name, e.g. "Savings goal". |
| `value` (required) | `number` |  | Progress from 0 to 1; values outside are clamped. |
| `className` | `string` |  |  |
| `size` | `number` | `84` |  |
| `stroke` | `number` | `7` |  |

---

# Radio Cards

Choose one of a few cards that each show their option, like a colour palette.

```tsx
import { RadioCards, RadioCard } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { RadioCard, RadioCards } from '@rinzai/zen';
import { useState } from 'react';

const PALETTES = [
    { id: 'violet', label: 'Violet', hue: 295 },
    { id: 'ocean', label: 'Ocean', hue: 250 },
    { id: 'teal', label: 'Teal', hue: 195 },
    { id: 'amber', label: 'Amber', hue: 75 },
];

/** Each card shows what it picks; the whole card is the click target, and arrow keys move the choice. */
export default function Default() {
    const [palette, setPalette] = useState('violet');
    return (
        <RadioCards
            label="Palette"
            value={palette}
            onValueChange={setPalette}
            className="grid grid-cols-2 gap-2 sm:grid-cols-4"
        >
            {PALETTES.map((p) => (
                <RadioCard key={p.id} value={p.id}>
                    <span
                        aria-hidden
                        className="size-7 shrink-0 rounded-full"
                        style={{
                            background: `oklch(0.72 0.13 ${p.hue})`,
                            boxShadow: `0 0 14px -2px oklch(0.7 0.13 ${p.hue})`,
                        }}
                    />
                    <span className="font-medium">{p.label}</span>
                </RadioCard>
            ))}
        </RadioCards>
    );
}
```

## API reference

### RadioCards

A choice of one among a few cards, each showing what it picks (a palette, a
plan). Native radio inputs underneath, so arrow keys and forms work as for any
radio group. Lay the cards out with className (e.g. a grid); fill it with
RadioCard. For short text options, use Segmented.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` |  | The RadioCards. |
| `className` | `string` |  | Classes for the cards' container: its layout (e.g. a grid). |
| `defaultValue` | `string` |  | The first chosen card, when the group keeps its own. |
| `label` | `string` |  | Shown above the cards, naming the group. Without it, give the group an aria-label or aria-labelledby. |
| `name` | `string` |  | Form field name; defaults to a generated one. |
| `onValueChange` | `((value: V) => void)` |  |  |
| `value` | `string` |  | The chosen card, when you keep it. |

### RadioCard

One card: a native radio covering whatever you put inside, so the whole card
is the click target. Outlined, lit when chosen; style it further with
className and style (e.g. a background showing the choice).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `string` |  |  |
| `className` | `string` |  |  |
| `disabled` | `boolean` |  | Can't be chosen (and the arrow keys skip it). |
| `style` | `CSSProperties` |  |  |

---

# Radio Group

Choose one of a list, each option with a label and a description; native radios, so arrow keys work.

```tsx
import { RadioGroup, Radio } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { Radio, RadioGroup } from '@rinzai/zen';
import { useState } from 'react';

/** Arrow keys move between options and pick them, as for any radio group. */
export default function Default() {
    const [repay, setRepay] = useState<'emi' | 'tenure'>('emi');
    return (
        <RadioGroup label="After a prepayment" value={repay} onValueChange={setRepay}>
            <Radio value="emi" description="Keep the end date; pay less each month.">
                Lower the EMI
            </Radio>
            <Radio value="tenure" description="Keep the EMI; finish sooner and save more interest.">
                Shorten the tenure
            </Radio>
        </RadioGroup>
    );
}
```

### Horizontal

```tsx
import { Radio, RadioGroup } from '@rinzai/zen';
import { useState } from 'react';

/** In a row, with one option disabled. */
export default function Horizontal() {
    const [every, setEvery] = useState<string | null>(null);
    return (
        <RadioGroup label="Repeat" value={every} onValueChange={setEvery} orientation="horizontal">
            <Radio value="week">Weekly</Radio>
            <Radio value="month">Monthly</Radio>
            <Radio value="year">Yearly</Radio>
            <Radio value="custom" disabled>
                Custom
            </Radio>
        </RadioGroup>
    );
}
```

## API reference

### RadioGroup

Choose one of a list: native radios underneath, so arrow keys move and pick
within the group, and forms work as usual. Fill it with Radio. For a few
short options side by side use Segmented; for options that show themselves,
RadioCards.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` |  | The Radios. |
| `className` | `string` |  | Classes for the options' container. |
| `defaultValue` | `string \| null` | `null` | The first chosen option, when the group keeps its own. |
| `disabled` | `boolean` | `false` |  |
| `label` | `ReactNode` |  | Shown above the options, naming the group. Without it, give the group an aria-label. |
| `name` | `string` |  | Form field name; defaults to a generated one. |
| `onValueChange` | `((value: V) => void)` |  |  |
| `orientation` | `"horizontal" \| "vertical"` | `vertical` | Options in a column (default) or wrapping in a row. |
| `value` | `string \| null` |  | The chosen option when you keep it, or null for none yet. |

### Radio

One option: a round radio that fills with a glowing dot when chosen, its label, and an optional description.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` |  | The label. |
| `value` (required) | `string` |  |  |
| `className` | `string` |  |  |
| `description` | `ReactNode` |  | A muted line under the label. |
| `disabled` | `boolean` |  | Can't be chosen (and the arrow keys skip it). |

---

# Range Slider

Two thumbs on one track, for a span like an amount from $50 to $500.

```tsx
import { RangeSlider } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { RangeSlider } from '@rinzai/zen';
import { useState } from 'react';

/** Entries between two amounts. */
export default function Default() {
    const [span, setSpan] = useState<[number, number]>([50, 500]);
    return (
        <div className="flex w-full max-w-sm flex-col gap-3">
            <div className="flex justify-between text-sm">
                <span className="font-medium">Amount</span>
                <span className="text-muted-foreground tabular-nums">
                    ${span[0]} – ${span[1]}
                </span>
            </div>
            <RangeSlider
                label="Amount"
                min={0}
                max={1000}
                step={10}
                value={span}
                onValueChange={setSpan}
                valueText={(v) => `$${v}`}
            />
        </div>
    );
}
```

## API reference

### RangeSlider

Two thumbs on one track, for a span such as an amount from $50 to $500:
two native range inputs (keyboard, forms and screen readers work as on
Slider), the span between them filled. The thumbs can meet but not cross.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` |  | Accessible name of the pair, e.g. "Amount". |
| `className` | `string` |  |  |
| `defaultValue` | `readonly [number, number]` |  | The first span, when the slider keeps its own (default the whole range). |
| `disabled` | `boolean` |  |  |
| `max` | `number` | `100` |  |
| `min` | `number` | `0` |  |
| `name` | `string` |  | Form field name: low and high are submitted under it, in that order. |
| `onValueChange` | `((value: [number, number]) => void)` |  | While dragging (every step). |
| `onValueCommit` | `((value: [number, number]) => void)` |  | Once the user lets go: the moment to save or filter. |
| `size` | `"md" \| "sm"` | `md` | `'sm'`: a thin track and small thumbs, as on Slider. |
| `step` | `number` | `1` |  |
| `thumbLabels` | `readonly [string, string]` |  | Each thumb's name (default "Minimum", "Maximum"). |
| `value` | `readonly [number, number]` |  | The span, low then high, when you keep it. |
| `valueText` | `((value: number) => string)` |  | Spoken value of a thumb, e.g. (v) => `$${v}`. |

---

# Repeat Picker

How often something recurs, like a bill, said in words, with the next dates it falls on.

```tsx
import { RepeatPicker } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { type Repeat, RepeatPicker } from '@rinzai/zen';
import { useState } from 'react';

/** Rent: monthly on the 1st, from November. */
export default function Default() {
    const [repeat, setRepeat] = useState<Repeat>({ every: 1, unit: 'month', day: 1 });
    return (
        <RepeatPicker value={repeat} onValueChange={setRepeat} locale="en-US" start="2026-11-01" className="max-w-sm" />
    );
}
```

## API reference

### RepeatPicker

How often something recurs, e.g. a bill: every n days, weeks, months or
years, on chosen weekdays or a day of the month. Says what it means in
words, and with a `start` date, the next few dates it falls on.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` |  |  |
| `defaultValue` | `Repeat` | `{ every: 1, unit: 'month' }` | The first rule, when the picker keeps its own. Every month by default. |
| `label` | `string` |  | The group's name for screen readers (default "Repeats"). |
| `locale` | `string` |  | For weekday and date names, and the week's first day. Defaults to the LocaleProvider's. |
| `name` | `string` |  | Form field name: the rule is submitted as JSON. |
| `onValueChange` | `((value: Repeat) => void)` |  |  |
| `start` | `string` |  | When it starts: its weekday and day of the month are the defaults, and the next dates are shown. |
| `value` | `Repeat` |  | The rule, when you keep it. |
| `weekStartsOn` | `number` |  | 0 for Sunday … 6. Defaults to the locale's. |

---

# Resizable

Panels with handles between them to drag, or to move with the arrow keys, within limits you set; groups nest, and the layout is reported to keep.

```tsx
import { ResizablePanelGroup, ResizablePanel, ResizableHandle } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { ResizableHandle, ResizablePanel, ResizablePanelGroup } from '@rinzai/zen';

/** A sidebar beside the main view, and a detail pane under it: drag a line, or focus it and use the arrow keys. */
export default function Default() {
    return (
        <ResizablePanelGroup className="border-tint/10 h-72 w-full max-w-2xl rounded-xl border">
            <ResizablePanel defaultSize={30} minSize={20} maxSize={50}>
                <div className="flex h-full flex-col gap-1 p-4">
                    <span className="text-muted-foreground mb-2 text-xs font-medium tracking-wide uppercase">
                        Accounts
                    </span>
                    <span className="text-sm">Everyday</span>
                    <span className="text-sm">Savings</span>
                    <span className="text-sm">Credit card</span>
                </div>
            </ResizablePanel>
            <ResizableHandle aria-label="Resize accounts" />
            <ResizablePanel>
                <ResizablePanelGroup orientation="vertical">
                    <ResizablePanel defaultSize={65} minSize={30}>
                        <div className="flex h-full items-center justify-center text-sm">Transactions</div>
                    </ResizablePanel>
                    <ResizableHandle aria-label="Resize details" />
                    <ResizablePanel minSize={20}>
                        <div className="text-muted-foreground flex h-full items-center justify-center text-sm">
                            Details
                        </div>
                    </ResizablePanel>
                </ResizablePanelGroup>
            </ResizablePanel>
        </ResizablePanelGroup>
    );
}
```

### Stacked

```tsx
import { ResizableHandle, ResizablePanel, ResizablePanelGroup } from '@rinzai/zen';

/** Three panels stacked, each with a smallest size: drag either line, or focus one and use ↑↓. */
export default function Stacked() {
    return (
        <ResizablePanelGroup orientation="vertical" className="border-tint/10 h-80 w-full max-w-md rounded-xl border">
            <ResizablePanel defaultSize={25} minSize={15}>
                <div className="flex h-full flex-col justify-center gap-0.5 px-4">
                    <span className="text-muted-foreground text-xs">Balance</span>
                    <span className="text-lg font-semibold tabular-nums">$12,480</span>
                </div>
            </ResizablePanel>
            <ResizableHandle aria-label="Resize balance" />
            <ResizablePanel defaultSize={45} minSize={20}>
                <div className="text-muted-foreground flex h-full items-center justify-center text-sm">This month</div>
            </ResizablePanel>
            <ResizableHandle aria-label="Resize this month" />
            <ResizablePanel minSize={15}>
                <div className="text-muted-foreground flex h-full items-center justify-center text-sm">Upcoming</div>
            </ResizablePanel>
        </ResizablePanelGroup>
    );
}
```

## API reference

### ResizablePanelGroup

Panels side by side (or stacked, `orientation="vertical"`) with handles
between them to drag, or to focus and move with the arrow keys. Sizes are
percentages of the group; `onLayout` reports them all after each change,
e.g. to keep for next time as the panels' `defaultSize`. Groups nest.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onLayout` | `((sizes: number[]) => void)` |  | Every panel's size, in percent and in order, after each change. |
| `orientation` | `"horizontal" \| "vertical"` | `horizontal` | Side by side (default), or stacked. |

### ResizablePanel

One panel: `defaultSize` is a percentage of the group (those without one share what's left); `minSize` and `maxSize` bound it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultSize` | `number` |  | Its share of the group, in percent. |
| `maxSize` | `number` | `100` |  |
| `minSize` | `number` | `0` |  |

### ResizableHandle

The boundary between two panels: a hairline that lights up while it's
dragged, hovered or focused, with a wider grip than it looks. Arrow keys move
it, Home and End take the panel before it to its smallest and largest.

No props of its own; it accepts the props of the element it renders.

---

# Seek Bar

Where playback is in a track, and the way to move it: played and loaded on one track, the time played and the length beside it or under its ends.

```tsx
import { SeekBar, formatDuration } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { Button, SeekBar, useMediaPlayer } from '@rinzai/zen';

import { useDemoTrack } from '../../player-bar/examples/demo-track';
// Icons from Heroicons (https://heroicons.com): Pause (pause), Play (play).

/** Filled to the time played, shaded on to what's loaded. Drag it: the track plays on, and seeks when you let go. */
export default function Default() {
    const src = useDemoTrack();
    const [audioRef, player] = useMediaPlayer();
    return (
        <div className="flex w-96 items-center gap-3">
            <audio ref={audioRef} src={src} preload="metadata" />
            <Button
                size="icon-sm"
                className="rounded-full"
                aria-label={player.playing ? 'Pause' : 'Play'}
                disabled={!src}
                onClick={() => player.toggle()}
            >
                {player.playing ? <Pause className="size-4" /> : <Play className="size-4" />}
            </Button>
            <SeekBar
                className="flex-1"
                currentTime={player.currentTime}
                playing={player.playing && !player.waiting}
                playbackRate={player.playbackRate}
                duration={player.duration}
                buffered={player.buffered}
                onSeek={player.seek}
            />
        </div>
    );
}
```

### Times below

```tsx
import { SeekBar, useMediaPlayer } from '@rinzai/zen';

import { useDemoTrack } from '../../player-bar/examples/demo-track';

/** The times under the bar's ends, as on a phone's Now Playing screen. */
export default function TimesBelow() {
    const src = useDemoTrack();
    const [audioRef, player] = useMediaPlayer();
    return (
        <div className="w-80">
            <audio ref={audioRef} src={src} preload="metadata" />
            <SeekBar
                times="below"
                currentTime={player.currentTime}
                playing={player.playing && !player.waiting}
                playbackRate={player.playbackRate}
                duration={player.duration}
                buffered={player.buffered}
                onSeek={player.seek}
            />
        </div>
    );
}
```

## API reference

### SeekBar

Where playback is in a track, and the way to move it: filled up to the
current time, shaded on to what's loaded, between the time played and the
length. While playing it glides, run by the browser's compositor between
the player's time updates. While dragging, the time follows the thumb and
the track keeps playing; letting go seeks. The arrow keys seek 5 seconds.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `currentTime` (required) | `number` |  | Seconds played. |
| `duration` (required) | `number` |  | Seconds long; 0 while unknown (the bar is disabled). |
| `onSeek` (required) | `(time: number) => void` |  | When the user lets go, or steps with the keys: the time to play from. |
| `buffered` | `number` | `0` | Seconds loaded, shaded on the track past the time played. |
| `playbackRate` | `number` | `1` | How fast it moves on while playing (default 1). |
| `playing` | `boolean` | `false` | While the time is running (playing, not waiting for data): the bar glides on between time updates. |
| `thumbColor` | `string` |  | CSS colour for the thumb (default: the accent). |
| `times` | `"below" \| "beside"` | `beside` | Where the time played and the length go: either side of the bar (default), or under its ends, as on a phone's Now Playing screen. |
| `valueText` | `((value: number) => string)` |  | Spoken value, e.g. (v) => `Hue ${v} degrees`. |

---

# Segmented

A pill row for a few mutually exclusive options.

```tsx
import { Segmented, SegmentedItem } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { Segmented, SegmentedItem } from '@rinzai/zen';
import { useState } from 'react';

export default function Default() {
    const [glow, setGlow] = useState<'off' | 'soft' | 'bright'>('soft');
    return (
        <Segmented label="Glow" value={glow} onValueChange={setGlow}>
            <SegmentedItem value="off">Off</SegmentedItem>
            <SegmentedItem value="soft">Soft</SegmentedItem>
            <SegmentedItem value="bright">Bright</SegmentedItem>
        </Segmented>
    );
}
```

### With icons

```tsx
import { Segmented, SegmentedItem } from '@rinzai/zen';
import { useState } from 'react';
// Icons from Heroicons (https://heroicons.com): ChartBarIcon (chart-bar), ListBullet (list-bullet), Squares (squares-2x2).

/** SegmentedItem holds anything (here an icon and text), and an option can be disabled. */
export default function WithIcons() {
    const [view, setView] = useState('list');
    return (
        <Segmented label="View" value={view} onValueChange={setView}>
            <SegmentedItem value="list">
                <span className="flex items-center gap-1.5">
                    <ListBullet className="size-4" /> List
                </span>
            </SegmentedItem>
            <SegmentedItem value="grid">
                <span className="flex items-center gap-1.5">
                    <Squares className="size-4" /> Grid
                </span>
            </SegmentedItem>
            <SegmentedItem value="chart" disabled>
                <span className="flex items-center gap-1.5">
                    <ChartBarIcon className="size-4" /> Chart
                </span>
            </SegmentedItem>
        </Segmented>
    );
}
```

## API reference

### Segmented

A small set of mutually exclusive options, shown as a pill row. Native radio
inputs underneath, so arrow keys and forms work as for any radio group. The
selection slides between options, like Pills. Fill it with
SegmentedItem (any content: text, icons, a disabled option).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` |  | The SegmentedItems. |
| `className` | `string` |  |  |
| `defaultValue` | `string` |  | The first chosen option, when the control keeps its own. |
| `label` | `ReactNode` |  | Shown above the options, naming the group. Without it, give the group an aria-label or aria-labelledby. |
| `name` | `string` |  | Form field name; defaults to a generated one. |
| `onValueChange` | `((value: V) => void)` |  |  |
| `value` | `string` |  | The chosen option, when you keep it. |

### SegmentedItem

One option of a Segmented: a native radio covering whatever you put inside.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` |  | What the option shows: text, an icon, both. |
| `value` (required) | `string` |  |  |
| `className` | `string` |  |  |
| `disabled` | `boolean` |  | Skipped by the arrow keys and can't be chosen. |

---

# Select

Pick one value from a short list, fully keyboard-driven. For long or searchable lists, use Combobox.

```tsx
import { Select, SelectItem, SelectGroup, SelectSeparator } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { Select, SelectItem } from '@rinzai/zen';
import { useState } from 'react';

const CATEGORIES = ['Groceries', 'Rent', 'Transport', 'Dining out', 'Subscriptions', 'Health', 'Travel'];

/** Keyboard: arrows, Home/End, type a letter to jump, Enter to choose, Escape to close. */
export default function Default() {
    const [category, setCategory] = useState<string | null>('rent');
    return (
        <Select aria-label="Category" value={category} onValueChange={setCategory} className="w-56">
            {CATEGORIES.map((label) => (
                <SelectItem key={label} value={label.toLowerCase().replace(/\s+/g, '-')}>
                    {label}
                </SelectItem>
            ))}
        </Select>
    );
}
```

### Custom options

```tsx
import { currencySymbol, Select, SelectItem } from '@rinzai/zen';
import { useState } from 'react';

const CURRENCIES = [
    { value: 'INR', label: 'Indian rupee' },
    { value: 'USD', label: 'US dollar' },
    { value: 'EUR', label: 'Euro' },
    { value: 'JPY', label: 'Japanese yen', disabled: true },
];

/** An item can show anything; its `label` is what the field shows and typing matches. Disabled items are skipped by the keyboard. */
export default function CustomOptions() {
    const [currency, setCurrency] = useState<string | null>(null);
    return (
        <Select
            aria-label="Currency"
            placeholder="Choose a currency"
            value={currency}
            onValueChange={setCurrency}
            className="w-64"
        >
            {CURRENCIES.map((c) => (
                <SelectItem key={c.value} value={c.value} label={c.label} disabled={c.disabled}>
                    <span className="flex items-center justify-between gap-3">
                        {c.label}
                        <span className="text-muted-foreground tabular-nums">
                            {c.value} {currencySymbol(c.value, 'en')}
                        </span>
                    </span>
                </SelectItem>
            ))}
        </Select>
    );
}
```

### Groups

```tsx
import { Select, SelectGroup, SelectItem, SelectSeparator } from '@rinzai/zen';
import { useState } from 'react';

/** SelectItem children, organised with SelectGroup and SelectSeparator; the keyboard skips the disabled one. */
export default function Groups() {
    const [category, setCategory] = useState<string | null>('groceries');
    return (
        <Select aria-label="Category" value={category} onValueChange={setCategory} className="w-64">
            <SelectGroup label="Essentials">
                <SelectItem value="rent">Rent</SelectItem>
                <SelectItem value="groceries">Groceries</SelectItem>
                <SelectItem value="transport">Transport</SelectItem>
            </SelectGroup>
            <SelectSeparator />
            <SelectGroup label="Lifestyle">
                <SelectItem value="dining">Dining out</SelectItem>
                <SelectItem value="travel" disabled>
                    Travel (over budget)
                </SelectItem>
            </SelectGroup>
        </Select>
    );
}
```

## API reference

### Select

Pick one value from a short list: a field-styled button that opens a list
below it. Keyboard: arrows, Home/End, type to jump, Enter to choose, Escape
to close. Fill it with SelectItem, organised with SelectGroup and
SelectSeparator. For long or searchable lists, use Combobox.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` |  | SelectItem, SelectGroup and SelectSeparator. |
| `className` | `string` |  | Classes for the trigger (e.g. a width, instead of the default full width). |
| `defaultValue` | `string \| null` | `null` | The first value, when the select keeps its own. |
| `disabled` | `boolean` | `false` |  |
| `id` | `string` |  |  |
| `listClassName` | `string` |  | Classes for the popup list. |
| `name` | `string` |  | Form field name: adds a hidden input with the value. |
| `onValueChange` | `((value: V) => void)` |  |  |
| `placeholder` | `string` |  | Shown while nothing is chosen. |
| `size` | `"default" \| "lg" \| "sm"` | `default` | Height, matching Button's: sm (32px), default (40px) or lg (44px). |
| `value` | `string \| null` |  | The chosen value, when you keep it; null for none. |

### SelectItem

One choice in a Select. Its `label` (or its text, when that's all it holds)
shows in the field once chosen and is matched when typing to jump.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `string` |  |  |
| `className` | `string` |  |  |
| `disabled` | `boolean` |  |  |
| `label` | `string` |  | Text for the field and for typing to jump (defaults to the item's text). |

### SelectGroup

A labelled group of SelectItems.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `ReactNode` |  |  |

### SelectSeparator

A hairline between items or groups.

No props of its own; it accepts the props of the element it renders.

---

# Separator

A hairline between groups of content, across or upright.

```tsx
import { Separator } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { Separator } from '@rinzai/zen';

/** Across between sections, and upright between items in a row. */
export default function Default() {
    return (
        <div className="flex w-full max-w-xs flex-col gap-3 text-sm">
            <div>
                <p className="mt-0! font-medium">September 2026</p>
                <p className="text-muted-foreground mt-0!">Budgets, entries and goals</p>
            </div>
            <Separator />
            <div className="text-muted-foreground flex h-5 items-center gap-3">
                <span>Spent $2,742</span>
                <Separator orientation="vertical" />
                <span>Left $1,258</span>
                <Separator orientation="vertical" />
                <span>12 entries</span>
            </div>
        </div>
    );
}
```

### Stats

```tsx
import { Card, Separator } from '@rinzai/zen';

/** Upright between figures in a card: it takes the row's height, so it spans each label and value. */
export default function Stats() {
    return (
        <Card className="flex w-full max-w-md items-stretch justify-between gap-4 py-4">
            {[
                ['Income', '$6,200'],
                ['Spent', '$4,180'],
                ['Saved', '$2,020'],
            ].map(([label, value], i) => (
                <div key={label} className="contents">
                    {i > 0 && <Separator orientation="vertical" decorative />}
                    <div className="flex flex-1 flex-col gap-1">
                        <span className="text-muted-foreground text-xs">{label}</span>
                        <span className="text-lg font-semibold tabular-nums">{value}</span>
                    </div>
                </div>
            ))}
        </Card>
    );
}
```

## API reference

### Separator

A hairline between groups of content, across (the default) or upright
(`orientation="vertical"`, e.g. between toolbar buttons; it takes its
container's height). Screen readers hear it only when it divides something
meaningful: pass `decorative` for one that's just visual.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `decorative` | `boolean` |  | Only visual: hidden from screen readers. |
| `orientation` | `"horizontal" \| "vertical"` | `horizontal` |  |

---

# Side Nav

Vertical navigation in titled groups, for docs and settings sidebars. Works with any router.

```tsx
import { SideNav, SideNavGroup, SideNavLink } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { SideNav, SideNavGroup, SideNavLink } from '@rinzai/zen';
import { useState } from 'react';

const GROUPS = [
    { title: 'Account', links: ['Profile', 'Security', 'Passkeys'] },
    { title: 'Workspace', links: ['Members', 'Billing', 'Integrations'] },
];

/** With a router, pass its link as the child: <SideNavLink asChild><NavLink to="/billing">Billing</NavLink></SideNavLink>. */
export default function Default() {
    const [current, setCurrent] = useState('Security');
    return (
        <SideNav aria-label="Settings" className="w-56">
            {GROUPS.map((group) => (
                <SideNavGroup key={group.title} title={group.title}>
                    {group.links.map((link) => (
                        <SideNavLink
                            key={link}
                            href={`#${link.toLowerCase()}`}
                            active={link === current}
                            onClick={(e) => {
                                e.preventDefault();
                                setCurrent(link);
                            }}
                        >
                            {link}
                        </SideNavLink>
                    ))}
                </SideNavGroup>
            ))}
        </SideNav>
    );
}
```

## API reference

### SideNav

Vertical navigation, e.g. a docs or settings sidebar. Give it an aria-label.

No props of its own; it accepts the props of the element it renders.

### SideNavGroup

A titled group of links.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` |  |  |
| `title` | `ReactNode` |  |  |

### SideNavLink

One link. `active` marks the current page. With `asChild`, the styles go onto
your own link element instead (a router's Link or NavLink, which may set
aria-current itself).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `active` | `boolean` |  | This link is the current page. |
| `asChild` | `boolean` |  | Style the single child element (e.g. a router link) instead of rendering an <a>. |

---

# Skeleton & Spinner

Placeholders for content on its way.

```tsx
import { Skeleton, Spinner } from '@rinzai/zen';
```

## Examples

### Loading card

```tsx
import { Skeleton } from '@rinzai/zen';

export default function LoadingCard() {
    return (
        <div className="glass glow-edge flex w-80 flex-col gap-3 rounded-xl p-4">
            <Skeleton className="h-3 w-24" />
            <Skeleton className="h-7 w-40" />
            <Skeleton className="h-3 w-full" />
        </div>
    );
}
```

### Reveal

```tsx
import { Button, Skeleton } from '@rinzai/zen';
import { useState } from 'react';

export default function Reveal() {
    const [loading, setLoading] = useState(true);
    return (
        <div className="flex flex-col items-start gap-4">
            <div className="glass glow-edge flex w-80 flex-col gap-3 rounded-xl p-4">
                <Skeleton loading={loading} className="h-3 w-24">
                    <p className="text-muted-foreground text-xs">Balance</p>
                </Skeleton>
                <Skeleton loading={loading} className="h-7 w-40">
                    <p className="text-2xl font-semibold tabular-nums">$4,280.15</p>
                </Skeleton>
            </div>
            <Button variant="outline" onClick={() => setLoading((l) => !l)}>
                {loading ? 'Load' : 'Reload'}
            </Button>
        </div>
    );
}
```

### With spinner

```tsx
import { Spinner } from '@rinzai/zen';

export default function WithSpinner() {
    return (
        <div className="text-muted-foreground flex items-center gap-2 text-sm">
            <Spinner /> Loading…
        </div>
    );
}
```

## API reference

### Skeleton

Shimmering placeholder in the shape of content that's on its way. Size it with className.

Give it the content as its child and `loading`: the placeholder shows while
loading, then the content fades in where it was.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` |  | The content this stands in for, a single element. |
| `loading` | `boolean` |  | With children: show the placeholder instead of them while true. |

### Spinner

Small circular spinner in the current text colour; size it with className
(default size-4). Decorative by default (e.g. inside a loading Button). Give
it a `label` when it stands on its own, and screen readers announce it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` |  | What is loading, e.g. "Loading entries". Makes the spinner announce itself. |

---

# Slider

A native range input with a glowing thumb and any track you like, at full size or small.

```tsx
import { Slider } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { Slider } from '@rinzai/zen';
import { useState } from 'react';

/** Filled up to the value; arrow keys and Home/End work as on any range input. */
export default function Default() {
    const [savings, setSavings] = useState(30);
    return (
        <div className="flex w-72 flex-col gap-2">
            <div className="flex justify-between text-sm">
                <span className="font-medium">Save each month</span>
                <span className="text-muted-foreground tabular-nums">{savings}%</span>
            </div>
            <Slider
                aria-label="Save each month"
                value={savings}
                onValueChange={setSavings}
                valueText={(v) => `${v} percent`}
            />
        </div>
    );
}
```

### Small

```tsx
import { Button, Slider } from '@rinzai/zen';
import { useState } from 'react';
// Icons from Heroicons (https://heroicons.com): SpeakerWave (speaker-wave), SpeakerXMark (speaker-x-mark).

/** size="sm": a thin track and a small thumb, for a compact control like a player's volume. Still 20px tall to grab. */
export default function Small() {
    const [volume, setVolume] = useState(70);
    const [muted, setMuted] = useState(false);
    return (
        <div className="flex items-center gap-1">
            <Button
                variant="ghost"
                size="icon-sm"
                aria-label={muted ? 'Unmute' : 'Mute'}
                onClick={() => setMuted(!muted)}
            >
                {muted ? <SpeakerXMark className="size-4" /> : <SpeakerWave className="size-4" />}
            </Button>
            <Slider
                size="sm"
                aria-label="Volume"
                className="w-28"
                value={muted ? 0 : volume}
                onValueChange={(v) => {
                    setVolume(v);
                    setMuted(v === 0);
                }}
                valueText={(v) => `${v} percent`}
            />
        </div>
    );
}
```

### Hue

```tsx
import { Slider } from '@rinzai/zen';
import { useState } from 'react';

/** A custom track (every hue) and thumb (the chosen colour); onValueCommit fires once, when you let go. */
export default function Hue() {
    const [hue, setHue] = useState(295);
    const [saved, setSaved] = useState(295);
    const gradient = `linear-gradient(to right, ${Array.from({ length: 13 }, (_, i) => `oklch(0.72 0.13 ${i * 30})`).join(', ')})`;
    return (
        <div className="flex w-72 flex-col gap-2">
            <Slider
                aria-label="Accent hue"
                min={0}
                max={359}
                value={hue}
                onValueChange={setHue}
                onValueCommit={setSaved}
                trackBackground={gradient}
                thumbColor={`oklch(0.72 0.13 ${hue})`}
                valueText={(v) => `Hue ${v} degrees`}
            />
            <p className="text-muted-foreground mt-0! text-xs">Saved: {saved}°</p>
        </div>
    );
}
```

## API reference

### Slider

A range slider on the native <input type="range"> (keyboard, forms and
screen readers work as usual): a rounded track, filled up to the value in
the accent unless you give it your own `trackBackground` (e.g. a hue
gradient), and a glowing thumb.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultValue` | `number` |  | The first value, when the slider keeps its own (default `min`). |
| `max` | `number` | `100` |  |
| `min` | `number` | `0` |  |
| `onValueChange` | `((value: number) => void)` |  | While dragging (every step). |
| `onValueCommit` | `((value: number) => void)` |  | Once the user lets go: the moment to save. |
| `size` | `"md" \| "sm"` | `md` | `'sm'`: a thin track and a small thumb, for a compact control such as a volume slider. |
| `step` | `"any" \| number` | `1` | `'any'` for no snapping; the arrow keys then move by the browser's own amount. |
| `thumbColor` | `string` |  | CSS colour for the thumb (default: the accent). |
| `trackBackground` | `string` |  | CSS background for the track, e.g. a gradient of hues. |
| `value` | `number` |  | The value, when you keep it. |
| `valueText` | `((value: number) => string)` |  | Spoken value, e.g. (v) => `Hue ${v} degrees`. |

---

# Sortable List

Put a list in order, or a tree of groups (a table’s rows, say), by dragging items by a grip or with the keyboard, each step announced: into other groups, open sub-items, or under another item. Also a virtualized list of hundreds.

```tsx
import { SortableList, SortableTree, SortableItem, SortableHandle, flattenTree } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { Meter, SortableHandle, SortableItem, SortableList } from '@rinzai/zen';
import { useState } from 'react';

const BUDGETS: Record<string, { name: string; spent: number; limit: number }> = {
    rent: { name: 'Rent', spent: 1800, limit: 1800 },
    groceries: { name: 'Groceries', spent: 412, limit: 500 },
    transport: { name: 'Transport', spent: 64, limit: 120 },
    dining: { name: 'Eating out', spent: 188, limit: 150 },
    fun: { name: 'Fun', spent: 40, limit: 100 },
};

/** Drag a budget by its grip to put them in your order (or Tab to a grip, Space, arrows, Space). */
export default function Default() {
    const [order, setOrder] = useState(Object.keys(BUDGETS));
    return (
        <SortableList value={order} onValueChange={setOrder} aria-label="Budgets" className="w-full max-w-md gap-2">
            {order.map((id) => {
                const b = BUDGETS[id];
                return (
                    <SortableItem
                        key={id}
                        id={id}
                        className="glass glow-edge flex items-center gap-2 rounded-xl py-2 pr-4 pl-1.5"
                    >
                        <SortableHandle id={id} label={b.name} />
                        <Meter
                            label={b.name}
                            value={b.spent}
                            max={b.limit}
                            detail={`$${b.spent} / $${b.limit}`}
                            className="flex-1"
                        />
                    </SortableItem>
                );
            })}
        </SortableList>
    );
}
```

### Groups

```tsx
import { flattenTree, SortableHandle, SortableItem, type SortableNode, SortableTree } from '@rinzai/zen';
import { useState } from 'react';

const NAMES: Record<string, string> = {
    bills: 'Bills',
    rent: 'Rent',
    phone: 'Phone',
    streaming: 'Streaming',
    life: 'Lifestyle',
    gym: 'Gym',
    books: 'Books',
};
const GROUPS = new Set(['bills', 'life']);
const AMOUNTS: Record<string, string> = {
    rent: '$1,800',
    phone: '$45',
    streaming: '$32',
    gym: '$60',
    books: '$25',
};

/**
 * Budgets in groups, with SortableTree: drag one within its group, into the
 * other, or sideways to tuck it under another budget. Groups stay at the top
 * and take budgets; budgets never sit at the top on their own.
 */
export default function Groups() {
    const [tree, setTree] = useState<SortableNode[]>([
        { id: 'bills', children: [{ id: 'rent' }, { id: 'phone' }, { id: 'streaming' }] },
        { id: 'life', children: [{ id: 'gym' }, { id: 'books' }] },
    ]);
    return (
        <SortableTree
            aria-label="Budgets"
            value={tree}
            onValueChange={setTree}
            accepts={(id, parent) => (GROUPS.has(id) ? parent === null : parent !== null)}
            className="w-full max-w-sm gap-1.5"
        >
            {flattenTree(tree).map(({ id, depth }) => (
                <SortableItem key={id} id={id} style={{ marginInlineStart: Math.max(0, depth - 1) * 24 }}>
                    {GROUPS.has(id) ? (
                        <div className="flex items-center gap-1 pt-2">
                            <SortableHandle id={id} label={NAMES[id]} />
                            <span className="text-muted-foreground text-xs font-medium tracking-wide uppercase">
                                {NAMES[id]}
                            </span>
                        </div>
                    ) : (
                        <div className="glass glow-edge flex items-center gap-1 rounded-xl py-1.5 ps-1.5 pe-4">
                            <SortableHandle id={id} label={NAMES[id]} />
                            <span className="flex-1 text-sm">{NAMES[id]}</span>
                            <span className="text-muted-foreground text-sm tabular-nums">{AMOUNTS[id]}</span>
                        </div>
                    )}
                </SortableItem>
            ))}
        </SortableTree>
    );
}
```

### Virtual

```tsx
import { SortableHandle, SortableItem, SortableList, useVirtualList } from '@rinzai/zen';
import { useRef, useState } from 'react';

const ROW = 48;
const ARTISTS = ['Nils Frahm', 'Ólafur Arnalds', 'Hania Rani', 'Max Richter', 'Bonobo', 'Tycho', 'Jon Hopkins'];
const SONGS = Object.fromEntries(
    Array.from({ length: 500 }, (_, i) => [`s${i}`, { title: `Track ${i + 1}`, artist: ARTISTS[(i * 3) % 7] }]),
);

/**
 * A queue of 500, rendering only the rows in view: `itemHeight` on the list,
 * and the dragged row kept rendered (`keep`) as it scrolls the list along.
 */
export default function Virtual() {
    const [order, setOrder] = useState(Object.keys(SONGS));
    const [lifted, setLifted] = useState<string | null>(null);
    const scrollRef = useRef<HTMLDivElement>(null);
    const rows = useVirtualList({
        count: order.length,
        itemHeight: ROW,
        scrollRef,
        keep: lifted ? order.indexOf(lifted) : undefined,
    });
    return (
        <div ref={scrollRef} className="glass h-96 w-full max-w-md overflow-y-auto rounded-xl">
            <SortableList
                value={order}
                onValueChange={setOrder}
                itemHeight={ROW}
                onLiftedChange={setLifted}
                aria-label="Up next"
                style={{ height: rows.totalSize }}
            >
                {rows.items.map(({ index, start }) => {
                    const id = order[index];
                    const song = SONGS[id];
                    return (
                        <SortableItem
                            key={id}
                            id={id}
                            className="absolute! inset-x-0 flex items-center gap-2 px-1.5"
                            style={{ top: start, height: ROW }}
                        >
                            <SortableHandle id={id} label={song.title} />
                            <div className="min-w-0">
                                <div className="truncate text-sm font-medium">{song.title}</div>
                                <div className="text-muted-foreground truncate text-xs">{song.artist}</div>
                            </div>
                        </SortableItem>
                    );
                })}
            </SortableList>
        </div>
    );
}
```

## API reference

### SortableList

A list put in order by dragging, e.g. budget categories: drag an item by its
SortableHandle and the others make way (a phone taps lightly at each new
place); it settles into place when let go.
From the keyboard, Space or Enter on a handle picks the item up, the arrow
keys move it, Space or Enter drops it and Escape puts it back; each step is
announced. `value` is the ids in order; render a SortableItem for each.
With `asChild` (and `asChild` on the items), your own elements instead: a
TableBody of TableRows, say, one per group, each sorted on its own.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onValueChange` (required) | `(value: string[]) => void` |  |  |
| `value` (required) | `readonly string[]` |  | The items' ids, in order. |
| `asChild` | `boolean` |  | Put the list's props on your own element (the single child, e.g. a TableBody) instead of a ul. |
| `itemHeight` | `number` |  | For a virtualized list (useVirtualList), its rows' height, gap included: render just the items in view, each placed at its place in `value` times this, and the drag works from `value` instead of the rows on screen. |
| `onLiftedChange` | `((id: string \| null) => void)` |  | When an item is picked up (by its handle, or from the keyboard), and when it's put down (null). A virtualized list keeps that row rendered meanwhile (useVirtualList's `keep`), so it stays under the pointer as the list scrolls. |

### SortableTree

Items in groups, and groups in groups, put in order by dragging: an item
can go anywhere in its group, into another group (or one open inside it),
or under another item. While dragging, a glowing line shows where it will
land, set in as deep as it'll go, and the group it would join is lit; drag
sideways to go a level in or out. From the keyboard, Space or Enter on a
handle picks it up, the up and down arrows move it through every place it
can go, left and right a level out or in, Space or Enter drops it and
Escape puts it back; each step is announced.

`value` is the tree of ids. Render a SortableItem for each row shown, in
order (flattenTree lists them, with their depths): what's under a closed
one isn't shown, and moves with it. `accepts` says which group takes which
item. With `asChild`, your own element (a Table, its rows SortableItems with
asChild on TableRows) instead of a ul.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onValueChange` (required) | `(value: SortableNode[]) => void` |  |  |
| `value` (required) | `readonly SortableNode[]` |  | The tree of ids, in order. |
| `accepts` | `((id: string, parentId: string \| null) => boolean)` |  | Whether `parentId` (null: the top level) takes item `id`; by default, everything goes anywhere. |
| `asChild` | `boolean` |  | Put its props on your own element (the single child, e.g. a Table) instead of a ul. |
| `indent` | `number` | `24` | How far in a level is set, in px: the drop line is set in this far, and dragging this far sideways goes a level in or out. |

### SortableItem

One item in a SortableList or SortableTree; give it the `id` it has in the list's value. With `asChild`, your own element (a TableRow).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` (required) | `string` |  |  |
| `asChild` | `boolean` |  | Put the item's props on your own element (the single child, e.g. a TableRow) instead of an li. |
| `label` | `string` |  | Its name, for one without a SortableHandle (a group others go into), to say "2 of 3 in Food". |

### SortableHandle

What an item is dragged by: a grip button. `label` names the item ("Rent");
the button reads "Reorder Rent". It takes no scroll gestures, so dragging it
never scrolls the page.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` (required) | `string` |  | The item's id, as in the list's value. |
| `label` (required) | `string` |  | The item's name, e.g. "Rent". |

---

# Sparkline

A small line of how a number has moved, with no axes, for beside a figure. It draws itself in.

```tsx
import { Sparkline } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { Sparkline, Stat, StatRow } from '@rinzai/zen';

/** Beside the figures they explain: a balance over the month, and spending by week. */
export default function Default() {
    return (
        <StatRow className="w-full max-w-lg">
            <Stat
                label="Balance"
                value={
                    <span className="flex items-center justify-between gap-3">
                        $6,908
                        <Sparkline values={[4100, 4300, 3900, 5200, 5600, 5400, 6100, 6908]} />
                    </span>
                }
            />
            <Stat
                label="Spent"
                tone="negative"
                value={
                    <span className="flex items-center justify-between gap-3">
                        $2,742
                        <Sparkline tone="negative" values={[620, 540, 810, 772]} />
                    </span>
                }
            />
        </StatRow>
    );
}
```

## API reference

### Sparkline

A small line of how a number has moved (a balance over a month, spending by
week), with no axes: for beside a figure in a Stat or a table row. It takes
its size from className (e.g. h-8 w-24) and draws itself in.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `values` (required) | `number[]` |  |  |
| `area` | `boolean` | `true` | A soft fill under the line. |
| `tone` | `"default" \| "muted" \| "negative"` | `default` | The accent (`primary`), red (`negative`), or grey (`muted`). |

---

# Spinner

A small loading spinner in the current text colour, announced to screen readers when labelled.

```tsx
import { Spinner } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { Spinner } from '@rinzai/zen';

/** Sized and coloured with className; it follows the text colour. */
export default function Default() {
    return (
        <div className="flex items-center gap-6">
            <Spinner />
            <Spinner className="size-6" />
            <Spinner className="text-primary size-8 border-[3px]" />
            <Spinner className="text-muted-foreground size-5" />
        </div>
    );
}
```

### Loading

```tsx
import { Button, Card, CardHeader, CardTitle, Spinner } from '@rinzai/zen';
import { useState } from 'react';

/** Standing on its own, a spinner needs a label so screen readers announce what is loading. */
export default function Loading() {
    const [loading, setLoading] = useState(true);
    return (
        <Card className="w-80">
            <CardHeader>
                <CardTitle>Entries</CardTitle>
            </CardHeader>
            {loading ? (
                <div className="text-muted-foreground flex items-center gap-3 py-6 text-sm">
                    <Spinner label="Loading entries" />
                    Loading entries…
                </div>
            ) : (
                <p className="py-6 text-sm">12 entries this month.</p>
            )}
            <Button variant="outline" size="sm" onClick={() => setLoading((l) => !l)}>
                {loading ? 'Finish loading' : 'Load again'}
            </Button>
        </Card>
    );
}
```

## API reference

### Spinner

Small circular spinner in the current text colour; size it with className
(default size-4). Decorative by default (e.g. inside a loading Button). Give
it a `label` when it stands on its own, and screen readers announce it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` |  | What is loading, e.g. "Loading entries". Makes the spinner announce itself. |

---

# Status Pill

A small status that changes in place, such as Saving…, Saved or Not saved with a Retry, and fades back once the news is old.

```tsx
import { StatusPill, StatusPillAction } from '@rinzai/zen';
```

## Examples

### Save

```tsx
import { Button, Spinner, StatusPill, StatusPillAction } from '@rinzai/zen';
import { useEffect, useState } from 'react';
// Icons from Heroicons (https://heroicons.com): AlertTriangle (exclamation-triangle), Check (check).

type Save = 'saving' | 'saved' | 'error';

/** A save indicator: saving spins, saved checks and then quietens, a failure is red and offers a retry. */
export default function Save() {
    const [state, setState] = useState<Save>('saved');
    const [quiet, setQuiet] = useState(false);
    useEffect(() => {
        setQuiet(false);
        if (state !== 'saved') return;
        const t = window.setTimeout(() => setQuiet(true), 2500);
        return () => window.clearTimeout(t);
    }, [state]);
    const save = (ok: boolean) => {
        setState('saving');
        window.setTimeout(() => setState(ok ? 'saved' : 'error'), 1200);
    };

    return (
        <div className="flex flex-col items-center gap-4">
            {state === 'error' ? (
                <StatusPill tone="negative">
                    <AlertTriangle />
                    Not saved
                    <StatusPillAction onClick={() => save(true)}>Retry</StatusPillAction>
                </StatusPill>
            ) : (
                <StatusPill tone={state === 'saved' ? 'positive' : 'default'} quiet={state === 'saved' && quiet}>
                    {state === 'saving' ? <Spinner /> : <Check />}
                    {state === 'saving' ? 'Saving…' : 'Saved'}
                </StatusPill>
            )}
            <div className="flex gap-2">
                <Button variant="outline" size="sm" onClick={() => save(true)}>
                    Save
                </Button>
                <Button variant="outline" size="sm" onClick={() => save(false)}>
                    Save and fail
                </Button>
            </div>
        </div>
    );
}
```

## API reference

### StatusPill

A small rounded status that changes in place, e.g. an app's "Saving…",
"Saved", "Not saved · Retry": an icon (a Spinner, a Check) and a few words.
`quiet` fades it back once the news is old (a save a few seconds ago).
Changes are read out politely (role="status"). For an action inside it,
such as Retry, use StatusPillAction. For a fixed label or count, use Badge.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `quiet` | `boolean` | `false` | Faded back into the page: the news is old. |
| `tone` | `"default" \| "negative" \| "positive"` | `default` | `positive` in the accent colour (done), `negative` in red (failed); `default` is muted (in progress). |

### StatusPillAction

A text button inside a StatusPill, e.g. Retry, in the pill's colour.

No props of its own; it accepts the props of the element it renders.

---

# Stepper

The steps of a flow and where you are in it; the line between them fills in as you go.

```tsx
import { Stepper, Step } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { Button, Step, Stepper } from '@rinzai/zen';
import { useState } from 'react';

/** Importing a statement in three steps. */
export default function Default() {
    const [step, setStep] = useState(1);
    return (
        <div className="flex w-full max-w-lg flex-col items-center gap-8">
            <Stepper value={step}>
                <Step description="CSV or Excel">Upload</Step>
                <Step description="Match the columns">Map</Step>
                <Step description="Check and import">Review</Step>
            </Stepper>
            <div className="flex gap-2">
                <Button variant="outline" disabled={step === 0} onClick={() => setStep(step - 1)}>
                    Back
                </Button>
                <Button disabled={step === 3} onClick={() => setStep(step + 1)}>
                    {step >= 2 ? 'Import' : 'Next'}
                </Button>
            </div>
        </div>
    );
}
```

## API reference

### Stepper

The steps of a flow (sign-up, checkout, import), with where you are: steps
before `value` (from 0) are done, the one at it is current. The line between
them fills in as you go.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `number` |  | The current step, from 0. Steps before it are done; past the last, all are. |

### Step

One step's label, and optionally a line under it (`description`).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` |  |  |
| `description` | `ReactNode` |  |  |

---

# Tab Bar

Phone navigation fixed to the bottom of the screen. Works with any router.

```tsx
import { TabBar, TabBarItem } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { TabBar, TabBarItem } from '@rinzai/zen';
import { useState } from 'react';
// Icons from Heroicons (https://heroicons.com): CalendarIcon (calendar), Flag (flag), Settings (cog-6-tooth), TableIcon (table-cells).

const TABS = [
    { label: 'Month', icon: <CalendarIcon /> },
    { label: 'Planner', icon: <TableIcon /> },
    { label: 'Goals', icon: <Flag /> },
    { label: 'Settings', icon: <Settings /> },
];

/** Phone navigation. Fixed to the bottom of the screen; here it sits in a phone-sized frame. */
export default function Default() {
    const [current, setCurrent] = useState('Month');
    return (
        <div className="border-tint/10 relative h-72 w-80 [transform:translateZ(0)] overflow-hidden rounded-2xl border">
            <p className="text-muted-foreground p-4 text-sm">{current}</p>
            <TabBar aria-label="Main" hideFrom={false} className="absolute! rounded-b-[15px]">
                {TABS.map((t) => (
                    <TabBarItem
                        key={t.label}
                        href={`#${t.label.toLowerCase()}`}
                        icon={t.icon}
                        active={t.label === current}
                        onClick={(e) => {
                            e.preventDefault();
                            setCurrent(t.label);
                        }}
                    >
                        {t.label}
                    </TabBarItem>
                ))}
            </TabBar>
        </div>
    );
}
```

## API reference

### TabBar

Phone navigation: a glass bar fixed to the bottom, clear of the home
indicator, hidden from `hideFrom` up (default md). Fill it with TabBarItems.
Its height is kept in `--zen-tab-bar-height` on its parent (0px while
hidden): a PlayerBar beside it sits on it, and the page can pad its end by it.
Inside a rounded frame, round the bar to match (className, e.g.
rounded-b-[15px]): with GPU compositing, Chrome doesn't clip a blurred
backdrop to an ancestor's rounded corners, only to the element's own.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `hideFrom` | `"lg" \| "md" \| "sm" \| false` | `md` | Hide the bar from this breakpoint up (false: always show). |

### TabBarItem

One destination: an icon over a label. `active` marks the current page; with
`asChild`, the styles go onto your own link (e.g. a router's NavLink, which
sets aria-current itself).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `active` | `boolean` |  |  |
| `asChild` | `boolean` |  | Style the single child element (a router link holding the label) instead of rendering an <a>; `icon` goes inside it. |
| `icon` | `ReactNode` |  |  |

---

# Table

Composable tables: a glass panel that scrolls, sticky headers, first column and totals, sortable columns, rows reordered by drag and drop (into groups and under other rows), and virtual rows for long lists.

```tsx
import { TableContainer, Table, TableHead, TableCell, TableFooter, TableFooterCell, TableSpacerRow, TableSelectCell, TableSelectHead, SelectionBar, TableSwipeRow, TableSwipeAction } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { Badge, Table, TableBody, TableCell, TableContainer, TableHead, TableHeader, TableRow } from '@rinzai/zen';

const ENTRIES = [
    { label: 'Rent', category: 'Housing', amount: -1850, recurring: true },
    { label: 'Paycheck', category: 'Salary', amount: 8450, recurring: true },
    { label: 'Weekly shop', category: 'Groceries', amount: -164, recurring: false },
];

export default function Default() {
    return (
        <TableContainer className="w-full max-w-xl">
            <Table>
                <TableHeader>
                    <TableRow>
                        <TableHead>Entry</TableHead>
                        <TableHead>Category</TableHead>
                        <TableHead numeric>Amount</TableHead>
                    </TableRow>
                </TableHeader>
                <TableBody className="rise-list">
                    {ENTRIES.map((e) => (
                        <TableRow key={e.label}>
                            <TableCell className="font-medium">
                                {e.label} {e.recurring && <Badge variant="outline">Monthly</Badge>}
                            </TableCell>
                            <TableCell className="text-muted-foreground">{e.category}</TableCell>
                            <TableCell numeric className={e.amount > 0 ? 'text-primary' : undefined}>
                                {e.amount > 0 ? '+' : '−'}${Math.abs(e.amount).toLocaleString('en-US')}
                            </TableCell>
                        </TableRow>
                    ))}
                </TableBody>
            </Table>
        </TableContainer>
    );
}
```

### Sortable

```tsx
import {
    Table,
    TableBody,
    TableCell,
    TableContainer,
    TableEmpty,
    TableHead,
    TableHeader,
    TableRow,
    useSort,
} from '@rinzai/zen';

interface Payment {
    month: string;
    principal: number;
    interest: number;
    balance: number;
}

// An amortization schedule: 240 000 over 12 months at 9%.
const SCHEDULE: Payment[] = (() => {
    let balance = 240000;
    const rate = 0.09 / 12;
    const emi = (balance * rate) / (1 - (1 + rate) ** -12);
    return Array.from({ length: 12 }, (_, i) => {
        const interest = balance * rate;
        const principal = emi - interest;
        balance -= principal;
        return {
            month: new Date(2026, 9 + i).toLocaleString('en-US', { month: 'short', year: 'numeric' }),
            principal,
            interest,
            balance: Math.max(0, balance),
        };
    });
})();

const COMPARE = {
    principal: (a: Payment, b: Payment) => a.principal - b.principal,
    interest: (a: Payment, b: Payment) => a.interest - b.interest,
    balance: (a: Payment, b: Payment) => a.balance - b.balance,
};

const money = (n: number) => n.toLocaleString('en-US', { maximumFractionDigits: 0 });

/** Click a heading to sort by it, again to reverse, a third time to clear. The header stays put as the rows scroll. */
export default function Sortable() {
    const { rows, headProps } = useSort(SCHEDULE, COMPARE);
    return (
        <TableContainer label="Repayment schedule" className="max-h-80 w-full max-w-xl">
            <Table>
                <TableHeader>
                    <TableRow>
                        <TableHead>Month</TableHead>
                        <TableHead numeric {...headProps('principal')}>
                            Principal
                        </TableHead>
                        <TableHead numeric {...headProps('interest')}>
                            Interest
                        </TableHead>
                        <TableHead numeric {...headProps('balance')}>
                            Balance
                        </TableHead>
                    </TableRow>
                </TableHeader>
                <TableBody>
                    {rows.length === 0 && <TableEmpty colSpan={4} />}
                    {rows.map((p) => (
                        <TableRow key={p.month}>
                            <TableCell>{p.month}</TableCell>
                            <TableCell numeric>{money(p.principal)}</TableCell>
                            <TableCell numeric className="text-muted-foreground">
                                {money(p.interest)}
                            </TableCell>
                            <TableCell numeric>{money(p.balance)}</TableCell>
                        </TableRow>
                    ))}
                </TableBody>
            </Table>
        </TableContainer>
    );
}
```

### Reorder

```tsx
import {
    flattenTree,
    SortableHandle,
    SortableItem,
    type SortableNode,
    SortableTree,
    Table,
    TableBody,
    TableCell,
    TableContainer,
    TableHead,
    TableHeader,
    TableRow,
} from '@rinzai/zen';
import { useState } from 'react';
// Icons from Heroicons (https://heroicons.com): ChevronRightMicro (chevron-right).

const NAMES: Record<string, string> = {
    home: 'Home',
    rent: 'Rent',
    power: 'Electricity',
    internet: 'Internet',
    food: 'Food',
    groceries: 'Groceries',
    dining: 'Eating out',
    coffee: 'Coffee',
    takeaway: 'Takeaway',
};

const AMOUNTS: Record<string, number[]> = {
    rent: [1800, 1800, 1800, 1800],
    power: [92, 88, 75, 70],
    internet: [60, 60, 60, 60],
    groceries: [420, 395, 410, 430],
    dining: [180, 150, 210, 160],
    coffee: [42, 38, 45, 40],
    takeaway: [64, 50, 80, 55],
};

const MONTHS = ['Jul', 'Aug', 'Sep', 'Oct'];
const CATEGORIES = new Set(['home', 'food']);

/**
 * Rows reordered by drag and drop (SortableTree, with asChild on the table and
 * its rows). Drag a row by its grip within its category, into the other one,
 * into an open sub-item (Eating out), or under another row (drag sideways a
 * level in or out); or Tab to a grip and use Space and the arrow keys.
 * Categories stay at the top level and can be reordered too. The first column
 * stays in view as it scrolls sideways.
 */
export default function Reorder() {
    const [tree, setTree] = useState<SortableNode[]>([
        { id: 'home', children: [{ id: 'rent' }, { id: 'power' }, { id: 'internet' }] },
        {
            id: 'food',
            children: [{ id: 'groceries' }, { id: 'dining', children: [{ id: 'coffee' }, { id: 'takeaway' }] }],
        },
    ]);
    const [closed, setClosed] = useState(new Set<string>());
    const toggle = (id: string) =>
        setClosed((now) => {
            const next = new Set(now);
            if (!next.delete(id)) next.add(id);
            return next;
        });
    const childrenOf = (id: string, nodes = tree): SortableNode[] | undefined => {
        for (const node of nodes) {
            if (node.id === id) return node.children;
            const found = node.children && childrenOf(id, node.children);
            if (found) return found;
        }
    };
    return (
        <TableContainer label="Planner" className="w-full max-w-xl">
            <SortableTree
                asChild
                value={tree}
                onValueChange={setTree}
                accepts={(id, parent) => (CATEGORIES.has(id) ? parent === null : parent !== null)}
            >
                <Table className="min-w-[36rem]">
                    <TableHeader>
                        <TableRow>
                            <TableHead sticky="start">Item</TableHead>
                            {MONTHS.map((m) => (
                                <TableHead key={m} numeric>
                                    {m}
                                </TableHead>
                            ))}
                        </TableRow>
                    </TableHeader>
                    <TableBody>
                        {flattenTree(tree, (id) => !closed.has(id)).map(({ id, depth }) => {
                            const category = CATEGORIES.has(id);
                            const kids = childrenOf(id);
                            return (
                                <SortableItem key={id} id={id} label={NAMES[id]} asChild>
                                    <TableRow>
                                        <TableCell sticky="start" className="py-1.5">
                                            <span
                                                className="flex items-center gap-1"
                                                style={{ paddingInlineStart: Math.max(0, depth - 1) * 24 }}
                                            >
                                                <SortableHandle id={id} label={NAMES[id]} />
                                                {!category && kids?.length ? (
                                                    <button
                                                        type="button"
                                                        aria-expanded={!closed.has(id)}
                                                        aria-label={NAMES[id]}
                                                        onClick={() => toggle(id)}
                                                        className="text-muted-foreground hover:text-foreground -ms-1 grid size-6 cursor-pointer place-items-center rounded-md"
                                                    >
                                                        <ChevronRightMicro
                                                            className={`size-4 transition-transform rtl:-scale-x-100 ${closed.has(id) ? '' : 'rotate-90'}`}
                                                        />
                                                    </button>
                                                ) : null}
                                                <span
                                                    className={
                                                        category
                                                            ? 'text-muted-foreground text-xs font-medium tracking-wide uppercase'
                                                            : ''
                                                    }
                                                >
                                                    {NAMES[id]}
                                                </span>
                                            </span>
                                        </TableCell>
                                        {MONTHS.map((m, i) => (
                                            <TableCell key={m} numeric className="py-1.5">
                                                {AMOUNTS[id] ? `$${AMOUNTS[id][i]}` : ''}
                                            </TableCell>
                                        ))}
                                    </TableRow>
                                </SortableItem>
                            );
                        })}
                    </TableBody>
                </Table>
            </SortableTree>
        </TableContainer>
    );
}
```

### Selectable

```tsx
import {
    Button,
    SelectionBar,
    Table,
    TableBody,
    TableCell,
    TableContainer,
    TableHead,
    TableHeader,
    TableRow,
    TableSelectCell,
    TableSelectHead,
    useSelection,
} from '@rinzai/zen';
import { useState } from 'react';

const ENTRIES = [
    { id: 1, label: 'Weekly shop', amount: '−$165' },
    { id: 2, label: 'Farmers market', amount: '−$42' },
    { id: 3, label: 'Train pass', amount: '−$92' },
    { id: 4, label: 'Dinner with Sam', amount: '−$78' },
    { id: 5, label: 'Birthday lunch', amount: '−$92' },
];

/** Pick rows (shift-click for a run of them), then act on them all from the bar. */
export default function Selectable() {
    const [entries, setEntries] = useState(ENTRIES);
    const selection = useSelection(entries.map((e) => e.id));
    return (
        <>
            <TableContainer label="Entries" className="w-full max-w-lg">
                <Table>
                    <TableHeader>
                        <TableRow>
                            <TableSelectHead {...selection.allProps()} />
                            <TableHead>Entry</TableHead>
                            <TableHead numeric>Amount</TableHead>
                        </TableRow>
                    </TableHeader>
                    <TableBody>
                        {entries.map((e) => (
                            <TableRow key={e.id} selected={selection.selected.has(e.id)}>
                                <TableSelectCell label={`Select ${e.label}`} {...selection.rowProps(e.id)} />
                                <TableCell>{e.label}</TableCell>
                                <TableCell numeric>{e.amount}</TableCell>
                            </TableRow>
                        ))}
                    </TableBody>
                </Table>
            </TableContainer>
            <SelectionBar count={selection.selected.size} onClear={selection.clear}>
                <Button
                    size="sm"
                    tone="negative"
                    onClick={() => setEntries((es) => es.filter((e) => !selection.selected.has(e.id)))}
                >
                    Delete
                </Button>
                {entries.length < ENTRIES.length && (
                    <Button size="sm" variant="ghost" onClick={() => setEntries(ENTRIES)}>
                        Restore all
                    </Button>
                )}
            </SelectionBar>
        </>
    );
}
```

### Swipe

```tsx
import {
    Button,
    Table,
    TableBody,
    TableCell,
    TableContainer,
    TableHead,
    TableHeader,
    TableRow,
    TableSwipeAction,
    TableSwipeRow,
} from '@rinzai/zen';
import { useState } from 'react';

const ENTRIES = [
    { id: 1, label: 'Weekly shop', amount: '−$165' },
    { id: 2, label: 'Farmers market', amount: '−$42' },
    { id: 3, label: 'Train pass', amount: '−$92' },
    { id: 4, label: 'Dinner with Sam', amount: '−$78' },
];

/** On a phone, swipe a row left for its actions; with a keyboard, tab to them. */
export default function Swipe() {
    const [entries, setEntries] = useState(ENTRIES);
    return (
        <div className="flex w-full max-w-lg flex-col gap-3">
            <TableContainer label="Entries">
                <Table>
                    <TableHeader>
                        <TableRow>
                            <TableHead>Entry</TableHead>
                            <TableHead numeric>Amount</TableHead>
                        </TableRow>
                    </TableHeader>
                    <TableBody>
                        {entries.map((e) => (
                            <TableSwipeRow
                                key={e.id}
                                actions={
                                    <TableSwipeAction
                                        tone="negative"
                                        aria-label={`Delete ${e.label}`}
                                        onClick={() => setEntries((es) => es.filter((x) => x.id !== e.id))}
                                    >
                                        Delete
                                    </TableSwipeAction>
                                }
                            >
                                <TableCell>{e.label}</TableCell>
                                <TableCell numeric>{e.amount}</TableCell>
                            </TableSwipeRow>
                        ))}
                    </TableBody>
                </Table>
            </TableContainer>
            {entries.length < ENTRIES.length && (
                <Button variant="ghost" className="self-start" onClick={() => setEntries(ENTRIES)}>
                    Bring them back
                </Button>
            )}
        </div>
    );
}
```

### Detail

```tsx
import {
    Button,
    Card,
    CardDescription,
    CardHeader,
    CardTitle,
    Table,
    TableBody,
    TableCell,
    TableContainer,
    TableHead,
    TableHeader,
    TableRow,
} from '@rinzai/zen';
import { startTransition, useState, ViewTransition } from 'react';

const ENTRIES = [
    {
        id: 'shop',
        label: 'Weekly shop',
        amount: '−$165.20',
        date: 'Oct 4',
        category: 'Groceries',
        note: 'Market and bakery.',
    },
    {
        id: 'train',
        label: 'Train pass',
        amount: '−$92.00',
        date: 'Oct 2',
        category: 'Transport',
        note: 'Monthly pass.',
    },
    { id: 'pay', label: 'Salary', amount: '+$4,200.00', date: 'Oct 1', category: 'Income', note: 'October.' },
];

/** Open an entry and its row grows into its details (a view transition, with share="zen-morph"). */
export default function Detail() {
    const [open, setOpen] = useState<string | null>(null);
    const go = (id: string | null) => startTransition(() => setOpen(id));
    const entry = ENTRIES.find((e) => e.id === open);

    if (entry)
        return (
            <ViewTransition name={`entry-${entry.id}`} share="zen-morph">
                <Card className="w-full max-w-lg">
                    <CardHeader>
                        <CardTitle>{entry.label}</CardTitle>
                        <Button size="sm" variant="ghost" onClick={() => go(null)}>
                            Back
                        </Button>
                    </CardHeader>
                    <p className="text-3xl font-semibold tabular-nums">{entry.amount}</p>
                    <CardDescription className="mt-1">
                        {entry.date} · {entry.category}
                    </CardDescription>
                    <p className="mt-4 text-sm">{entry.note}</p>
                </Card>
            </ViewTransition>
        );

    return (
        <TableContainer label="Entries" className="w-full max-w-lg">
            <Table>
                <TableHeader>
                    <TableRow>
                        <TableHead>Entry</TableHead>
                        <TableHead>Date</TableHead>
                        <TableHead numeric>Amount</TableHead>
                    </TableRow>
                </TableHeader>
                <TableBody className="rise-list">
                    {ENTRIES.map((e) => (
                        <ViewTransition key={e.id} name={`entry-${e.id}`} share="zen-morph">
                            <TableRow onClick={() => go(e.id)} className="cursor-pointer">
                                <TableCell>
                                    <button
                                        type="button"
                                        onClick={() => go(e.id)}
                                        className="text-left outline-hidden focus-visible:underline"
                                    >
                                        {e.label}
                                    </button>
                                </TableCell>
                                <TableCell className="text-muted-foreground">{e.date}</TableCell>
                                <TableCell numeric>{e.amount}</TableCell>
                            </TableRow>
                        </ViewTransition>
                    ))}
                </TableBody>
            </Table>
        </TableContainer>
    );
}
```

### Virtual

```tsx
import {
    formatMoney,
    Table,
    TableBody,
    TableCell,
    TableContainer,
    TableHead,
    TableHeader,
    TableRow,
    TableSpacerRow,
    useVirtualList,
} from '@rinzai/zen';
import { useRef } from 'react';

const ROW_HEIGHT = 40;
const PAYEES = ['Grocer', 'Metro', 'Landlord', 'Cafe', 'Pharmacy', 'Bookshop', 'Cinema', 'Utilities'];

// 10,000 transactions, generated.
const ROWS = Array.from({ length: 10000 }, (_, i) => ({
    id: i + 1,
    date: new Date(2026, 0, 1 + Math.floor(i / 28)).toLocaleDateString('en-US', { month: 'short', day: 'numeric' }),
    payee: PAYEES[(i * 7) % PAYEES.length],
    amount: ((i * 7919) % 20000) + 150,
}));

/** 10,000 rows, but only the ones in view (plus a few either side) are rendered: useVirtualList with spacer rows. */
export default function Virtual() {
    const scrollRef = useRef<HTMLDivElement>(null);
    const rows = useVirtualList({ count: ROWS.length, itemHeight: ROW_HEIGHT, scrollRef, overscan: 8 });
    return (
        <TableContainer ref={scrollRef} label="Transactions" className="h-96 w-full max-w-xl">
            <Table>
                <TableHeader>
                    <TableRow>
                        <TableHead numeric className="w-20">
                            #
                        </TableHead>
                        <TableHead>Date</TableHead>
                        <TableHead>Payee</TableHead>
                        <TableHead numeric>Amount</TableHead>
                    </TableRow>
                </TableHeader>
                <TableBody>
                    <TableSpacerRow height={rows.paddingTop} colSpan={4} />
                    {rows.items.map(({ index }) => {
                        const r = ROWS[index];
                        return (
                            <TableRow key={r.id}>
                                <TableCell numeric className="text-muted-foreground h-10 py-0">
                                    {r.id}
                                </TableCell>
                                <TableCell className="h-10 py-0">{r.date}</TableCell>
                                <TableCell className="h-10 py-0">{r.payee}</TableCell>
                                <TableCell numeric className="h-10 py-0">
                                    {formatMoney(r.amount, 'USD', 'en-US')}
                                </TableCell>
                            </TableRow>
                        );
                    })}
                    <TableSpacerRow height={rows.paddingBottom} colSpan={4} />
                </TableBody>
            </Table>
        </TableContainer>
    );
}
```

## API reference

### TableContainer

The panel a table scrolls in: glass with an edge that catches the pointer
light, like a Card. Give it a max height (className) to scroll vertically;
it scrolls sideways when the table is wider. `ref` and scroll events are the
scrolling element's. With `label`, it's a focusable region, so keyboard users
can scroll it too.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` |  | Accessible name; makes the scroll area a focusable region. |

### Table

The <table>. Put it in a TableContainer for the panel and scrolling.

No props of its own; it accepts the props of the element it renders.

### TableHead

Column heading: small spaced caps (TableHeader keeps the row at the top). With `onSort`, it's a
button that shows the direction and announces it (aria-sort).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `numeric` | `boolean` |  | Aligned to the end, for numbers. |
| `onSort` | `(() => void)` |  | Makes the heading a sort button. |
| `sortDirection` | `SortDirection` |  |  |
| `sticky` | `"start"` |  | Stay in view when the table scrolls sideways. |

### TableCell

A cell: hairline below, lit with its row on hover. `sticky="start"` keeps it in view when scrolling sideways.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `numeric` | `boolean` |  | Aligned to the end, tabular digits. |
| `sticky` | `"start"` |  | Stay in view when the table scrolls sideways. |

### TableFooter

Rows that stay at the bottom while the body scrolls (totals, balances).

No props of its own; it accepts the props of the element it renders.

### TableFooterCell

A footer cell: sits on the card, above a hairline. Use inside TableFooter.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `numeric` | `boolean` |  | Aligned to the end, tabular digits. |
| `sticky` | `"start"` |  | Stay in view when the table scrolls sideways. |

### TableSpacerRow

An empty row of a given height, standing in for rows scrolled out of view (see useVirtualList).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `colSpan` (required) | `number` |  |  |
| `height` (required) | `number` |  |  |

### TableSelectCell

A row's checkbox cell; spread `rowProps(key)` from useSelection into it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `checked` (required) | `boolean` |  |  |
| `label` (required) | `string` |  | The checkbox's name, e.g. "Select Rent". |
| `onSelect` (required) | `(on: boolean, range: boolean) => void` |  | With `range` when shift was held. |

### TableSelectHead

The header's checkbox, for every row at once; spread `allProps()` from useSelection into it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `checked` (required) | `boolean` |  |  |
| `indeterminate` (required) | `boolean` |  |  |
| `onSelect` (required) | `(on: boolean) => void` |  |  |
| `label` | `string` |  |  |

### SelectionBar

What to do with the selected rows: their count, your actions, and a × to
clear the selection. Floats at the bottom of the screen while any are
selected (move it with className).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `count` (required) | `number` |  |  |
| `onClear` (required) | `() => void` |  |  |
| `children` | `ReactNode` |  | The actions, e.g. buttons to delete or re-tag them. |
| `className` | `string` |  |  |
| `clearLabel` | `string` |  |  |
| `label` | `((count: number) => string)` |  | The count as text (default "3 selected"). |

### TableSwipeRow

A row whose actions sit behind it at its end: swipe it left to reveal them
(right, in right-to-left layouts), back (or tap the row) to put them away. They also come out when focused, so the
keyboard reaches them. Use it in a TableContainer.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `actions` (required) | `ReactNode` |  | What's behind the row: TableSwipeActions, e.g. Edit and Delete. |
| `selected` | `boolean` |  |  |

### TableSwipeAction

One of a swipe row's actions: fills the row's height, flush with its end.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tone` | `"default" \| "negative"` | `default` |  |

---

# Table of Contents

An "On this page" list that highlights the section being read.

```tsx
import { TableOfContents } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { TableOfContents } from '@rinzai/zen';

/** Point items at heading ids; the link for the section being read lights up as you scroll. */
export default function Default() {
    return (
        <TableOfContents
            className="w-48"
            items={[
                { id: 'installation', label: 'Installation' },
                { id: 'usage', label: 'Usage' },
                { id: 'theming', label: 'Theming' },
                { id: 'tokens', label: 'Tokens', depth: 2 },
            ]}
        />
    );
}
```

## API reference

### TableOfContents

"On this page": links to the page's headings, highlighting the section being
read. Items point at element ids; nested items (depth 2) are indented.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `TableOfContentsItem[]` |  |  |
| `className` | `string` |  |  |
| `title` | `string` |  | Shown above the list, and names it. Empty: no heading shown (e.g. under a trigger that says it). |

---

# Tabs

Switch between panels in place, with an underline or a glowing pill that slides to the active tab. To go to another page, use Pills.

```tsx
import { Tabs, TabList, Tab, TabPanel } from '@rinzai/zen';
```

## Examples

### Underline

```tsx
import { Tab, TabList, TabPanel, Tabs } from '@rinzai/zen';

export default function Underline() {
    return (
        <Tabs defaultValue="month" className="w-96">
            <TabList>
                <Tab value="month">Month</Tab>
                <Tab value="year">Year</Tab>
                <Tab value="all">All time</Tab>
            </TabList>
            <TabPanel value="month" className="text-muted-foreground text-sm">
                Spending for September.
            </TabPanel>
            <TabPanel value="year" className="text-muted-foreground text-sm">
                Spending for 2026 so far.
            </TabPanel>
            <TabPanel value="all" className="text-muted-foreground text-sm">
                Everything since you started.
            </TabPanel>
        </Tabs>
    );
}
```

### Pills

```tsx
import { Tab, TabList, TabPanel, Tabs } from '@rinzai/zen';

export default function Pills() {
    return (
        <Tabs defaultValue="all" className="w-96">
            <TabList variant="pills">
                <Tab value="all">All</Tab>
                <Tab value="expenses">Expenses</Tab>
                <Tab value="income">Income</Tab>
            </TabList>
            <TabPanel value="all" className="text-muted-foreground text-sm">
                Every entry this month.
            </TabPanel>
            <TabPanel value="expenses" className="text-muted-foreground text-sm">
                Money going out.
            </TabPanel>
            <TabPanel value="income" className="text-muted-foreground text-sm">
                Money coming in.
            </TabPanel>
        </Tabs>
    );
}
```

### Panels

```tsx
import { Meter, Tab, TabList, TabPanel, Tabs } from '@rinzai/zen';

const BUDGETS = [
    { name: 'Groceries', spent: 412, limit: 500 },
    { name: 'Eating out', spent: 188, limit: 150 },
    { name: 'Transport', spent: 64, limit: 120 },
];

/** The last panel slides out as the picked one slides in, and the space between eases to fit. */
export default function Panels() {
    return (
        <Tabs defaultValue="summary" className="w-full max-w-md">
            <TabList>
                <Tab value="summary">Summary</Tab>
                <Tab value="budgets">Budgets</Tab>
                <Tab value="notes">Notes</Tab>
            </TabList>
            <TabPanel value="summary" className="text-sm">
                <p className="text-2xl font-semibold tabular-nums">$1,845.11</p>
                <p className="text-muted-foreground">Spent this month, $210 less than last.</p>
            </TabPanel>
            <TabPanel value="budgets" className="flex flex-col gap-4 text-sm">
                {BUDGETS.map((b) => (
                    <Meter
                        key={b.name}
                        label={b.name}
                        value={b.spent}
                        max={b.limit}
                        detail={`$${b.spent} / $${b.limit}`}
                    />
                ))}
            </TabPanel>
            <TabPanel value="notes" className="text-muted-foreground text-sm">
                Rent goes out on the 5th.
            </TabPanel>
        </Tabs>
    );
}
```

## API reference

### Tabs

Tab set with an underline that slides to the active tab. Controlled (`value`) or not (`defaultValue`).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultValue` | `string` |  |  |
| `onValueChange` | `((value: string) => void)` |  |  |
| `value` | `string` |  |  |

### TabList

The row of tabs. `underline` (default): in-page tabs, a bar sliding under
the active tab. `pills`: the Pills look, a glowing pill sliding along a
glass track (for navigation between pages, use Pills itself).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `TabListVariant` | `underline` |  |

### Tab

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `string` |  |  |

### TabPanel

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `string` |  |  |

---

# Tag Input

A field of short values (tags, emails): Enter or a comma adds one, Backspace takes the last back.

```tsx
import { TagInput } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { Field, TagInput } from '@rinzai/zen';
import { useState } from 'react';

/** An entry's labels. Type one and press Enter or a comma; paste a list to add each. */
export default function Default() {
    const [tags, setTags] = useState(['groceries', 'weekly']);
    return (
        <Field label="Labels" hint="Press Enter or a comma after each." className="w-full max-w-sm">
            <TagInput value={tags} onValueChange={setTags} placeholder="Add a label" />
        </Field>
    );
}
```

## API reference

### TagInput

A field of short values (tags, emails, labels): typing one and pressing
Enter or a comma adds it, pasting a list adds each, Backspace in the empty
field takes the last one back. Each is removed with its ×. Values are
trimmed and kept once. Past about three rows the tags scroll, under a
typing line that stays in view (a max-h-* class sets the field's height).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultValue` | `string[]` | `[]` |  |
| `name` | `string` |  | Form field name: each tag is submitted under it. |
| `onValueChange` | `((value: string[]) => void)` |  |  |
| `removeLabel` | `((tag: string) => string)` |  | The × button's label, for screen readers. |
| `validate` | `((entry: string) => boolean)` |  | Whether an entry may be added (e.g. looks like an email). |
| `value` | `string[]` |  |  |

---

# Textarea

Multi-line text, styled like Input.

```tsx
import { Textarea } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { Textarea } from '@rinzai/zen';

export default function Default() {
    return <Textarea placeholder="Add a note…" className="w-80" />;
}
```

## API reference

### Textarea

No props of its own; it accepts the props of the element it renders.

---

# Theme Toggle

Switches between the dark and light themes, remembering the choice itself or leaving it to your app.

```tsx
import { ThemeToggle, ThemeScript } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { ThemeToggle } from '@rinzai/zen';

/** Flips the whole page between dark and light. Add <ThemeScript /> to <head> so the choice sticks on reload. */
export default function Default() {
    return (
        <div className="flex items-center gap-3 text-sm">
            <ThemeToggle />
            <span className="text-muted-foreground">Switch the theme</span>
        </div>
    );
}
```

### Your state

```tsx
import { ThemeToggle, type Appearance } from '@rinzai/zen';
import { useRef, useState } from 'react';

/**
 * The theme kept by your app (state here; an account setting, a cookie or a database in yours):
 * the toggle shows `value`, and `onValueChange` applies the new one. This one themes just its panel,
 * so `target` keeps the water inside it.
 */
export default function YourState() {
    const [theme, setTheme] = useState<Appearance>('light');
    const panel = useRef<HTMLDivElement>(null);
    return (
        <div
            ref={panel}
            className={`${theme} bg-background text-foreground flex h-96 w-full flex-col justify-between rounded-2xl border p-6 text-sm`}
        >
            <div className="flex items-center justify-between">
                <span className="font-medium">Preview</span>
                <ThemeToggle value={theme} onValueChange={setTheme} target={panel} />
            </div>
            <span className="text-muted-foreground">This panel is {theme}; the page around it stays as it is.</span>
        </div>
    );
}
```

## API reference

### ThemeToggle

Switches between the dark and light themes; the new theme spreads from the
button like a drop of water (themeWave).

On its own, it switches <html>'s class and remembers the choice (localStorage):
add ThemeScript to <head> to apply it on the next visit. Give it `value` and
`onValueChange` and the theme is yours: it shows `value` and leaves applying and
storing the choice to `onValueChange` (in your state, a database, a cookie…).
With `target` too, it switches the theme of one element (a panel, a preview),
and the water stays inside it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` |  |  |
| `onValueChange` | `((theme: Appearance) => void)` |  | Called with the theme switched to. |
| `storageKey` | `string` | `theme` | localStorage key for the choice, when the toggle keeps it. Use the same one in ThemeScript. |
| `target` | `RefObject<HTMLElement \| null>` |  | The element whose theme `onValueChange` switches, when it's not the page (a panel with its own .dark or .light): the wave plays inside it. Needs `value`. |
| `value` | `Appearance` |  | The theme, when you keep it: the toggle shows it, and `onValueChange` must apply the new one (by the end of a synchronous render and its effects). Without it, the toggle switches <html>'s class itself. |

### ThemeScript

Put in <head>: applies the remembered theme before the first paint, so a
light-theme visitor never sees a dark flash on page load.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `storageKey` | `string` | `theme` |  |

---

# Theming & styling

Your own colours from a few settings, readable in dark and light for any hue; and className overrides that always win.

```tsx
import { applyTheme, applyPreset, customize, PRESETS, DEFAULT_THEME, themeVars, cx } from '@rinzai/zen';
```

## Examples

### Theme editor

```tsx
import {
    applyPreset,
    applyTheme,
    Badge,
    Button,
    customize,
    DEFAULT_THEME,
    INTENSITIES,
    Input,
    Meter,
    type PresetId,
    PRESETS,
    Segmented,
    SegmentedItem,
    Select,
    SelectItem,
    Slider,
    type ThemeSettings,
    Toggle,
} from '@rinzai/zen';
import { useEffect, useRef, useState } from 'react';

const HUES = `linear-gradient(to right, ${Array.from({ length: 13 }, (_, i) => `oklch(0.72 0.13 ${i * 30})`).join(', ')})`;

/**
 * A few settings make every colour token, readable in dark and light for any
 * hue. Here the theme applies to the preview only (`target`); leave it out to
 * theme the whole page.
 */
export default function ThemeEditor() {
    const [theme, setTheme] = useState<ThemeSettings>(applyPreset(DEFAULT_THEME, 'ocean'));
    const preview = useRef<HTMLDivElement>(null);

    useEffect(() => {
        const root = document.documentElement;
        const apply = () =>
            preview.current &&
            applyTheme(theme, {
                appearance: root.classList.contains('light') ? 'light' : 'dark',
                target: preview.current,
            });
        apply();
        // Follow the page's dark/light switch.
        const watch = new MutationObserver(apply);
        watch.observe(root, { attributes: true, attributeFilter: ['class'] });
        return () => watch.disconnect();
    }, [theme]);

    return (
        <div className="grid w-full max-w-2xl gap-6 sm:grid-cols-2">
            <div className="flex flex-col gap-4">
                <Select
                    aria-label="Preset"
                    value={theme.preset === 'custom' ? null : theme.preset}
                    placeholder="Custom"
                    onValueChange={(id: PresetId) => setTheme((t) => applyPreset(t, id))}
                >
                    {PRESETS.map((p) => (
                        <SelectItem key={p.id} value={p.id}>
                            {p.label}
                        </SelectItem>
                    ))}
                </Select>
                <Slider
                    aria-label="Hue"
                    min={0}
                    max={359}
                    value={theme.hue}
                    onValueChange={(hue) => setTheme((t) => customize(t, { hue }))}
                    trackBackground={HUES}
                    thumbColor={`oklch(0.72 0.13 ${theme.hue})`}
                    valueText={(v) => `Hue ${v} degrees`}
                />
                <Segmented
                    label="Intensity"
                    value={theme.intensity}
                    onValueChange={(intensity) => setTheme((t) => customize(t, { intensity }))}
                >
                    {INTENSITIES.map((i) => (
                        <SegmentedItem key={i} value={i}>
                            {i[0].toUpperCase() + i.slice(1)}
                        </SegmentedItem>
                    ))}
                </Segmented>
                <label className="flex items-center justify-between gap-4 text-sm">
                    Tinted greys
                    <Toggle
                        checked={theme.tint === 'tinted'}
                        onCheckedChange={(on) => setTheme((t) => customize(t, { tint: on ? 'tinted' : 'neutral' }))}
                        aria-label="Tinted greys"
                    />
                </label>
                <label className="flex items-center justify-between gap-4 text-sm">
                    High contrast
                    <Toggle
                        checked={theme.contrast === 'high'}
                        onCheckedChange={(on) => setTheme((t) => ({ ...t, contrast: on ? 'high' : 'standard' }))}
                        aria-label="High contrast"
                    />
                </label>
            </div>

            <div
                ref={preview}
                className="bg-background text-foreground border-tint/10 flex flex-col gap-4 rounded-xl border p-5"
            >
                <div className="flex items-center justify-between">
                    <span className="font-semibold">Groceries</span>
                    <Badge>On track</Badge>
                </div>
                <Meter label="September" value={420} max={600} detail="$420 / $600" hint="$180 left" />
                <Input placeholder="Add a note" />
                <div className="flex gap-2">
                    <Button>Save</Button>
                    <Button variant="outline">Cancel</Button>
                </div>
            </div>
        </div>
    );
}
```

### Stylesheet

```tsx
import { applyPreset, CodeBlock, DEFAULT_THEME, Segmented, SegmentedItem, themeVars } from '@rinzai/zen';
import { useState } from 'react';

const css = (vars: Record<string, string>) =>
    Object.entries(vars)
        .map(([k, v]) => `    --${k}: ${v};`)
        .join('\n');

/**
 * No script needed: themeVars gives the tokens as data, so a theme can be
 * written into a stylesheet at build time or on the server.
 */
export default function Stylesheet() {
    const [preset, setPreset] = useState<'teal' | 'amber'>('teal');
    const theme = applyPreset(DEFAULT_THEME, preset);
    const code = `:root, .dark {\n${css(themeVars(theme, 'dark'))}\n}\n.light {\n${css(themeVars(theme, 'light'))}\n}`;
    return (
        <div className="flex w-full max-w-2xl flex-col gap-3">
            <Segmented label="Preset" value={preset} onValueChange={setPreset}>
                <SegmentedItem value="teal">Teal</SegmentedItem>
                <SegmentedItem value="amber">Amber</SegmentedItem>
            </Segmented>
            <CodeBlock code={code} language="css" className="max-h-72 overflow-auto" />
        </div>
    );
}
```

### Overrides

```tsx
import { Avatar, Button, cx } from '@rinzai/zen';

/**
 * className always wins: when it sets something a component already sets
 * (size, padding, radius, colour…), the component's default is dropped. Your
 * own components get the same with cx.
 */
export default function Overrides() {
    return (
        <div className="flex flex-col gap-4">
            <div className="flex flex-wrap items-center gap-3">
                <Button>Default</Button>
                <Button className="h-12 rounded-full px-8">Taller, rounder</Button>
                <Avatar name="Sam" />
                <Avatar name="Sam" className="size-14 text-xl" />
            </div>
            <code className="text-muted-foreground text-xs">
                cx(&apos;px-3 py-1 rounded-lg&apos;, &apos;p-4 rounded-full&apos;) →{' '}
                {cx('px-3 py-1 rounded-lg', 'p-4 rounded-full')}
            </code>
        </div>
    );
}
```

---

# Time Field

A time of day, typed or stepped a part at a time, in the locale’s order, digits and 12- or 24-hour clock.

```tsx
import { TimeField } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { Field, TimeField } from '@rinzai/zen';
import { useState } from 'react';

/** Type the digits, or ↑↓ each part; minutes step by 5 here. */
export default function Default() {
    const [time, setTime] = useState<string | null>('09:30');
    return (
        <div className="flex flex-col items-start gap-2">
            <Field label="Reminder at">
                <TimeField value={time} onValueChange={setTime} step={5} />
            </Field>
            <p className="text-muted-foreground mt-0! text-sm tabular-nums">Value: {time ?? 'null'}</p>
        </div>
    );
}
```

### With date

```tsx
import { DatePicker, Field, TimeField } from '@rinzai/zen';

/** A date and a time side by side: a DatePicker for the day, a TimeField for the time. */
export default function WithDate() {
    return (
        <div className="flex items-end gap-2">
            <Field label="Date" className="w-44">
                <DatePicker defaultValue="2026-10-06" />
            </Field>
            <Field label="Time">
                <TimeField defaultValue="18:45" step={15} locale="en-US" />
            </Field>
        </div>
    );
}
```

## API reference

### TimeField

A time of day, typed or stepped a part at a time: hour, minute and, where
the locale uses a 12-hour clock, AM/PM, in the locale's order and digits.
Type digits (it moves on when a part is full), ↑↓ to step (minutes by
`step`), ←→ between parts, Backspace to clear one. The value is "HH:MM"
(24-hour) once every part is set, and null until then.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultValue` | `string \| null` | `null` | The first time, when the field keeps its own. |
| `disabled` | `boolean` |  |  |
| `invalid` | `boolean` |  | Show the field in its error state. |
| `locale` | `string` |  | Defaults to the LocaleProvider's. |
| `name` | `string` |  | Form field name: the time is submitted under it as "HH:MM". |
| `onValueChange` | `((value: string \| null) => void)` |  |  |
| `size` | `"default" \| "lg" \| "sm"` | `default` | Height, matching Button's. |
| `step` | `number` | `1` | Minutes ↑↓ move by, e.g. 5 or 15. Default 1. |
| `value` | `string \| null` |  | "HH:MM" (24-hour), or null, when you keep it. |

---

# Timeline

Events in order, each on a dot joined by a line: an activity feed or a history.

```tsx
import { Timeline, TimelineItem } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { Timeline, TimelineItem } from '@rinzai/zen';

/** An entry's history, newest first; the latest is lit. */
export default function Default() {
    return (
        <Timeline className="w-full max-w-sm">
            <TimelineItem active title="Paid" time="Today, 09:12">
                $1,850 to Northside Lettings.
            </TimelineItem>
            <TimelineItem title="Amount changed" time="3 Sep">
                From $1,800 to $1,850.
            </TimelineItem>
            <TimelineItem title="Created" time="1 Aug" />
        </Timeline>
    );
}
```

## API reference

### Timeline

Events in order, each on a dot joined by a line: an activity feed, a history.

No props of its own; it accepts the props of the element it renders.

### TimelineItem

One event: its title, when (`time`), and anything more as children. `icon`
replaces the dot; `active` lights it in the accent, e.g. what's happening now.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` (required) | `ReactNode` |  |  |
| `active` | `boolean` |  | Lit in the accent: the current or latest event. |
| `icon` | `ReactNode` |  | An icon in place of the dot. |
| `time` | `ReactNode` |  | When it happened, e.g. a <time> or "2 hours ago". |

---

# Toast

Short messages that confirm an action or report a problem, with an optional action like Undo. They stack into a deck that fans out when pointed at, and swipe away.

```tsx
import { ToastProvider } from '@rinzai/zen';
```

## Examples

### Tones

```tsx
import { Button, useToast } from '@rinzai/zen';

/** Needs a <ToastProvider> above it, once near the root of your app. */
export default function Tones() {
    const toast = useToast();
    return (
        <div className="flex flex-wrap gap-3">
            <Button onClick={() => toast('Saved', { description: 'Your changes are stored.', tone: 'positive' })}>
                Success
            </Button>
            <Button
                variant="outline"
                onClick={() => toast('Entry deleted', { action: { label: 'Undo', onClick: () => {} } })}
            >
                With action
            </Button>
            <Button
                tone="negative"
                onClick={() => toast("Couldn't save", { description: 'Check your connection.', tone: 'negative' })}
            >
                Error
            </Button>
        </div>
    );
}
```

## API reference

### ToastProvider

Mount once near the root; `useToast()` works anywhere inside. Toasts stack in
a deck in the corner, newest in front with up to two peeking out behind; it
fans out while pointed at or focused, and the countdowns wait meanwhile.
Swipe a toast right to dismiss it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `offset` | `string` |  | Gap between the toasts and the bottom of the screen on phones (a CSS length, default 1rem), e.g. "5.5rem" to clear a bottom tab bar. |
| `viewportClassName` | `string` |  | Classes for the column the toasts stack in (position, width…). |

---

# Toggle

An on/off switch.

```tsx
import { Toggle } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { Toggle } from '@rinzai/zen';
import { useState } from 'react';

export default function Default() {
    const [on, setOn] = useState(true);
    return (
        <label className="flex w-64 items-center justify-between">
            Repeats every month
            <Toggle checked={on} onCheckedChange={setOn} />
        </label>
    );
}
```

## API reference

### Toggle

On/off switch. A native checkbox with the switch role underneath, so forms
and screen readers work as they do for any checkbox. Space and Enter both
flip it (Enter doesn't submit a surrounding form), as for a switch button.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onCheckedChange` | `((checked: boolean) => void)` |  |  |

---

# Toggle Group

Buttons that stay pressed, in a row: any number of them, like filters, or at most one. One stop in the tab order; the arrow keys go through them.

```tsx
import { ToggleGroup, ToggleGroupItem } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { ToggleGroup, ToggleGroupItem } from '@rinzai/zen';
import { useState } from 'react';

/** Filters: any number on at once. */
export default function Default() {
    const [kinds, setKinds] = useState<readonly string[]>(['expense', 'income']);
    return (
        <div className="flex flex-col items-center gap-3">
            <ToggleGroup multiple aria-label="Show" value={kinds} onValueChange={setKinds}>
                <ToggleGroupItem value="expense">Expenses</ToggleGroupItem>
                <ToggleGroupItem value="income">Income</ToggleGroupItem>
                <ToggleGroupItem value="transfer">Transfers</ToggleGroupItem>
            </ToggleGroup>
            <p className="text-muted-foreground mt-0! text-sm">
                {kinds.length ? `Showing ${kinds.length} of 3 kinds` : 'Showing everything'}
            </p>
        </div>
    );
}
```

### Single

```tsx
import { ToggleGroup, ToggleGroupItem } from '@rinzai/zen';
// Icons from Heroicons (https://heroicons.com): ChartBar (chart-bar), ListBullet (list-bullet), Squares (squares-2x2).

/** At most one: pressing the pressed one releases it. Icon-only items carry an aria-label. */
export default function Single() {
    return (
        <ToggleGroup aria-label="Group by" defaultValue="list">
            <ToggleGroupItem value="list" aria-label="As a list" className="px-2">
                <ListBullet className="size-4" />
            </ToggleGroupItem>
            <ToggleGroupItem value="cards" aria-label="As cards" className="px-2">
                <Squares className="size-4" />
            </ToggleGroupItem>
            <ToggleGroupItem value="chart" aria-label="As a chart" className="px-2">
                <ChartBar className="size-4" />
            </ToggleGroupItem>
        </ToggleGroup>
    );
}
```

## API reference

### ToggleGroup

Buttons that stay pressed, in a row: any number of them (`multiple`, e.g.
filters), or at most one, which can be released again. For exactly one
always chosen, use Segmented. ←→ move between them, Home and End jump to
the ends; Space or Enter presses.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` |  | The ToggleGroupItems. |
| `defaultValue` | `string \| readonly string[] \| null` |  |  |
| `multiple` | `boolean` |  | At most one pressed (the default); pressing another releases it. Any number pressed. |
| `name` | `string` |  | Form field name: each pressed item's value is submitted under it. |
| `onValueChange` | `((value: string \| null) => void) \| ((value: readonly string[]) => void)` |  |  |
| `value` | `string \| readonly string[] \| null` |  | The pressed item's value, or null for none, when you keep it. |

### ToggleGroupItem

One button of a ToggleGroup: text, an icon (give it an aria-label), or both.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `string` |  |  |

---

# Toolbar

A row of controls for one thing, like a table’s: one stop for Tab, and the arrow keys through its buttons, toggles and fields.

```tsx
import { Toolbar, ToolbarSeparator } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { Button, Toolbar, ToolbarSeparator, ToggleGroup, ToggleGroupItem } from '@rinzai/zen';
// Icons from Heroicons (https://heroicons.com): ChartBar (chart-bar), ListBullet (list-bullet), Settings (cog-6-tooth), Table (table-cells).

/** A table's controls: one stop for Tab, and ←→ through them all, the toggle group's items too. */
export default function Default() {
    return (
        <Toolbar aria-label="Entries">
            <ToggleGroup aria-label="View" defaultValue="table">
                <ToggleGroupItem value="table" aria-label="Table" className="px-2">
                    <Table className="size-4" />
                </ToggleGroupItem>
                <ToggleGroupItem value="list" aria-label="List" className="px-2">
                    <ListBullet className="size-4" />
                </ToggleGroupItem>
                <ToggleGroupItem value="chart" aria-label="Chart" className="px-2">
                    <ChartBar className="size-4" />
                </ToggleGroupItem>
            </ToggleGroup>
            <ToolbarSeparator />
            <Button variant="ghost" size="sm">
                Filter
            </Button>
            <Button variant="ghost" size="sm">
                Sort
            </Button>
            <ToolbarSeparator />
            <Button variant="ghost" size="icon-sm" aria-label="Table settings">
                <Settings className="size-4" />
            </Button>
        </Toolbar>
    );
}
```

### Vertical

```tsx
import { Button, Toolbar, ToolbarSeparator, ToggleGroup, ToggleGroupItem } from '@rinzai/zen';
// Icons from Heroicons (https://heroicons.com): ChartBar (chart-bar), MinusMicro (minus), PlusMicro (plus), Squares (squares-2x2).

/** Upright beside what it controls, e.g. a chart: ↑↓ move through it, and its toggle group stacks too. */
export default function Vertical() {
    return (
        <Toolbar aria-label="Chart" orientation="vertical">
            <Button variant="ghost" size="icon-sm" aria-label="Zoom in">
                <PlusMicro />
            </Button>
            <Button variant="ghost" size="icon-sm" aria-label="Zoom out">
                <MinusMicro />
            </Button>
            <ToolbarSeparator />
            <ToggleGroup aria-label="Chart type" defaultValue="bars">
                <ToggleGroupItem value="bars" aria-label="Bars" className="px-2">
                    <ChartBar className="size-4" />
                </ToggleGroupItem>
                <ToggleGroupItem value="tiles" aria-label="Tiles" className="px-2">
                    <Squares className="size-4" />
                </ToggleGroupItem>
            </ToggleGroup>
        </Toolbar>
    );
}
```

## API reference

### Toolbar

A row of controls for one thing, e.g. a table's or an editor's: buttons,
ToggleGroups, Selects, a search field. Tab enters it once; ←→ (↑↓ when
`orientation="vertical"`) move between its controls, Home and End jump to
the ends. Divide it with ToolbarSeparator. Give it an aria-label.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"horizontal" \| "vertical"` | `horizontal` |  |

### ToolbarSeparator

A hairline between groups of a Toolbar's controls, across its direction.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `decorative` | `boolean` |  | Only visual: hidden from screen readers. |

---

# Tooltip

A short glass hint on hover or keyboard focus, describing its trigger to screen readers; below its trigger or beside it.

```tsx
import { Tooltip, TooltipTrigger, TooltipContent } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { Badge, Tooltip, TooltipContent, TooltipTrigger } from '@rinzai/zen';

/** Shows on hover and on keyboard focus; the trigger is described by it for screen readers. */
export default function Default() {
    return (
        <Tooltip>
            <TooltipTrigger className="rounded-md">
                <Badge variant="secondary">Beta</Badge>
            </TooltipTrigger>
            <TooltipContent>
                <div className="p-3 text-sm">
                    <p className="font-medium">Beta feature</p>
                    <p className="text-muted-foreground mt-0.5!">This feature is still in preview and may change.</p>
                </div>
            </TooltipContent>
        </Tooltip>
    );
}
```

### Beside

```tsx
import { Tooltip, TooltipContent, TooltipTrigger } from '@rinzai/zen';
// Icons from Heroicons (https://heroicons.com): MusicalNote (musical-note), QueueList (queue-list), Search (magnifying-glass), Squares (squares-2x2).

const ITEMS = [
    { label: 'Home', icon: Squares },
    { label: 'Search', icon: Search },
    { label: 'Library', icon: MusicalNote },
    { label: 'Up next', icon: QueueList },
];

/**
 * An icon rail, each icon's name in a tooltip beside it (`side="beside"`), clear
 * of the icons below. The name is the button's own label, so it isn't also its description.
 */
export default function Beside() {
    return (
        <nav aria-label="Main" className="glass flex flex-col gap-1 rounded-xl p-1.5">
            {ITEMS.map(({ label, icon: Icon }) => (
                <Tooltip key={label}>
                    <TooltipTrigger
                        aria-label={label}
                        aria-describedby={undefined}
                        className="text-muted-foreground hover:text-foreground hover:bg-tint/[0.07] focus-ring grid size-10 cursor-pointer place-items-center rounded-lg transition-colors"
                    >
                        <Icon className="size-5" />
                    </TooltipTrigger>
                    <TooltipContent side="beside" offset={8}>
                        <p className="px-2.5 py-1.5 text-sm">{label}</p>
                    </TooltipContent>
                </Tooltip>
            ))}
        </nav>
    );
}
```

## API reference

### Tooltip

A short hint shown while the pointer is over its trigger or the trigger has
keyboard focus; Escape hides it. The trigger is described by it for screen
readers. Put a TooltipTrigger and a TooltipContent inside. For anything to
click or fill in, use Popover.

No props of its own; it accepts the props of the element it renders.

### TooltipTrigger

What the tooltip describes: a button by default. With `asChild`, your own focusable element instead.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `asChild` | `boolean` |  | Put the trigger's props on your own focusable element instead of rendering a button. |

### TooltipContent

The hint: glass, below the trigger (above it if there's no room), centred on
it by default. `side="beside"` puts it after the trigger instead (before it
if there's no room), as for the icons of a collapsed sidebar.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `"center" \| "end" \| "start"` | `center` | Centred on the trigger (default), or lined up with its start or end edge (beside: its top or bottom). |
| `offset` | `number` | `5` | Gap from the trigger, in px. |
| `side` | `"below" \| "beside"` | `below` | Below the trigger (default; above if there's no room), or beside it (after it; before if there's no room). |

---

# Tree Table

Rows that open into child rows, animated, built from useTree and the Table parts. With virtual rows and editable cells, enough for a budget planner.

```tsx
import { TreeRow, TreeCell, TreeLabel, TreeToggle } from '@rinzai/zen';
```

## Examples

### Basic

```tsx
import {
    Table,
    TableBody,
    TableContainer,
    TableHead,
    TableHeader,
    TableRow,
    TreeCell,
    TreeLabel,
    TreeRow,
    useTree,
} from '@rinzai/zen';

interface Node {
    name: string;
    size: string;
    children?: Node[];
}

const FILES: Node[] = [
    {
        name: 'packages',
        size: '412 kB',
        children: [
            {
                name: 'button',
                size: '6 kB',
                children: [
                    { name: 'index.tsx', size: '2 kB' },
                    { name: 'index.test.tsx', size: '4 kB' },
                ],
            },
            { name: 'table', size: '14 kB', children: [{ name: 'index.tsx', size: '9 kB' }] },
        ],
    },
    { name: 'docs', size: '88 kB', children: [{ name: 'app', size: '80 kB' }] },
    { name: 'package.json', size: '3 kB' },
];

/** Nested data in, visible rows out: useTree handles opening, closing and the animation. Start collapsed with defaultExpanded={false}. */
export default function Basic() {
    const tree = useTree({ items: FILES, getKey: (n) => n.name + n.size, getChildren: (n) => n.children });
    return (
        <TableContainer className="w-full max-w-md">
            <Table {...tree.tableProps}>
                <TableHeader>
                    <TableRow>
                        <TableHead>Name</TableHead>
                        <TableHead numeric>Size</TableHead>
                    </TableRow>
                </TableHeader>
                <TableBody>
                    {tree.rows.map((row) => (
                        <TreeRow key={row.key} row={row} tree={tree}>
                            <TreeCell className={row.hasChildren ? 'font-medium' : undefined}>
                                <TreeLabel row={row} tree={tree}>
                                    {row.item.name}
                                </TreeLabel>
                            </TreeCell>
                            <TreeCell numeric className="text-muted-foreground">
                                {row.item.size}
                            </TreeCell>
                        </TreeRow>
                    ))}
                </TableBody>
            </Table>
        </TableContainer>
    );
}
```

### Planner

```tsx
import {
    EditableCell,
    formatMoney,
    MoneyInput,
    Table,
    TableBody,
    TableContainer,
    TableFooter,
    TableFooterCell,
    TableHead,
    TableHeader,
    TableRow,
    TableSpacerRow,
    TreeCell,
    TreeLabel,
    TreeRow,
    useTree,
    useVirtualList,
} from '@rinzai/zen';
import { useRef, useState } from 'react';

const MONTHS = ['Oct', 'Nov', 'Dec', 'Jan', 'Feb', 'Mar'];
const ROW_HEIGHT = 36;

interface Line {
    key: string;
    label: string;
    /** Amount per month, in paise; groups add up their items. */
    amounts?: number[];
    items?: Line[];
}

const item = (label: string, rupees: number[]): Line => ({
    key: label.toLowerCase().replace(/\W+/g, '-'),
    label,
    amounts: rupees.map((r) => r * 100),
});

const PLAN: Line[] = [
    {
        key: 'home',
        label: 'Home',
        items: [
            item('Rent', [18500, 18500, 18500, 18500, 18500, 18500]),
            item('Electricity', [1400, 1250, 1600, 1900, 1700, 1300]),
            item('Internet', [799, 799, 799, 799, 799, 799]),
        ],
    },
    {
        key: 'food',
        label: 'Food',
        items: [
            item('Groceries', [9000, 9500, 12000, 9000, 9000, 9500]),
            item('Dining out', [3000, 2500, 6000, 2000, 2500, 3000]),
        ],
    },
    {
        key: 'transport',
        label: 'Transport',
        items: [
            item('Metro card', [1200, 1200, 1200, 1200, 1200, 1200]),
            item('Cabs', [1500, 1800, 2500, 1500, 1200, 1600]),
        ],
    },
];

const total = (line: Line, month: number): number =>
    line.items ? line.items.reduce((sum, i) => sum + total(i, month), 0) : (line.amounts?.[month] ?? 0);

/**
 * A budget grid like a planner: categories open into items, months run across,
 * and the header, first column and totals stay put while it scrolls either way.
 * Click an amount to change it. Rows are virtualized, so long plans stay fast.
 */
export default function Planner() {
    const [plan, setPlan] = useState(PLAN);
    const tree = useTree({ items: plan, getKey: (l) => l.key, getChildren: (l) => l.items, rowHeight: ROW_HEIGHT });
    const scrollRef = useRef<HTMLDivElement>(null);
    const rows = useVirtualList({ count: tree.rows.length, itemHeight: ROW_HEIGHT, scrollRef, overscan: 12 });
    const inr = (paise: number) => formatMoney(paise, 'INR', 'en-IN', { showDecimals: false });

    const setAmount = (key: string, month: number, paise: number | null) =>
        setPlan((p) =>
            p.map((group) => ({
                ...group,
                items: group.items?.map((i) =>
                    i.key === key ? { ...i, amounts: i.amounts!.map((a, m) => (m === month ? (paise ?? 0) : a)) } : i,
                ),
            })),
        );

    return (
        <TableContainer ref={scrollRef} label="Budget plan" className="max-h-80 w-full">
            <Table {...tree.tableProps} className="w-max min-w-full">
                <TableHeader>
                    <TableRow>
                        <TableHead sticky="start" className="min-w-44">
                            Budget
                        </TableHead>
                        {MONTHS.map((m) => (
                            <TableHead key={m} numeric className="min-w-28">
                                {m}
                            </TableHead>
                        ))}
                    </TableRow>
                </TableHeader>
                <TableBody>
                    <TableSpacerRow height={rows.paddingTop} colSpan={MONTHS.length + 1} />
                    {rows.items.map(({ index }) => {
                        const row = tree.rows[index];
                        const line = row.item;
                        return (
                            <TreeRow key={row.key} row={row} tree={tree}>
                                <TreeCell sticky="start" className={row.hasChildren ? 'font-medium' : undefined}>
                                    <TreeLabel row={row} tree={tree}>
                                        <span className="truncate">{line.label}</span>
                                    </TreeLabel>
                                </TreeCell>
                                {MONTHS.map((month, m) => (
                                    <TreeCell key={month} numeric>
                                        {row.hasChildren ? (
                                            <span className="text-muted-foreground px-1.5">{inr(total(line, m))}</span>
                                        ) : (
                                            <EditableCell
                                                label={`${line.label}, ${month}: ${inr(total(line, m))}`}
                                                editor={(close) => (
                                                    <MoneyInput
                                                        compact
                                                        autoFocus
                                                        allowEmpty
                                                        aria-label={`${line.label}, ${month}`}
                                                        value={total(line, m)}
                                                        currency="INR"
                                                        locale="en-IN"
                                                        className="w-28"
                                                        onValueChange={(v) => {
                                                            setAmount(line.key, m, v);
                                                            close();
                                                        }}
                                                        onCancel={close}
                                                    />
                                                )}
                                            >
                                                {inr(total(line, m))}
                                            </EditableCell>
                                        )}
                                    </TreeCell>
                                ))}
                            </TreeRow>
                        );
                    })}
                    <TableSpacerRow height={rows.paddingBottom} colSpan={MONTHS.length + 1} />
                </TableBody>
                <TableFooter>
                    <TableRow>
                        <TableFooterCell sticky="start">Total</TableFooterCell>
                        {MONTHS.map((month, m) => (
                            <TableFooterCell key={month} numeric>
                                {inr(plan.reduce((sum, g) => sum + total(g, m), 0))}
                            </TableFooterCell>
                        ))}
                    </TableRow>
                </TableFooter>
            </Table>
        </TableContainer>
    );
}
```

## API reference

### TreeRow

A table row wired to useTree: tree semantics, the keyboard and the open/close animation.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `row` (required) | `TreeRowData<T>` |  |  |
| `tree` (required) | `{ rows: TreeRowData<T>[]; toggle: (key: string) => void; isExpanded: (key: string) => boolean; expand: (key: string) => void; collapse: (key: string) => void; expandAll: () => void; ... 4 more ...; rowHeight: number; }` |  |  |

### TreeCell

A cell in a TreeRow: its content sits in a box whose height animates as groups open and close.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `numeric` | `boolean` |  | Aligned to the end, tabular digits. |
| `sticky` | `"start"` |  | Stay in view when the table scrolls sideways. |

### TreeLabel

The first column's content: indented by depth, with the row's toggle (or a spacer, so labels line up).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `row` (required) | `TreeRowData<T>` |  |  |
| `tree` (required) | `{ rows: TreeRowData<T>[]; toggle: (key: string) => void; isExpanded: (key: string) => boolean; expand: (key: string) => void; collapse: (key: string) => void; expandAll: () => void; ... 4 more ...; rowHeight: number; }` |  |  |
| `className` | `string` |  |  |
| `indent` | `number` | `20` | Indent per level, in px. |

### TreeToggle

Chevron button that opens and closes a row: points right when closed, down when open.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `expanded` (required) | `boolean` |  |  |
| `onToggle` (required) | `() => void` |  |  |

---

# Trend

A change, like +12% with an arrow, coloured by whether it is good news.

```tsx
import { Trend } from '@rinzai/zen';
```

## Examples

### Default

```tsx
import { Stat, StatRow, Trend } from '@rinzai/zen';

/** Spending going up is bad news (`good="down"`); savings going up is good. */
export default function Default() {
    return (
        <StatRow className="w-full max-w-xl">
            <Stat
                label="Spent"
                value="$1,845"
                hint={
                    <Trend value={0.12} good="down">
                        vs last month
                    </Trend>
                }
            />
            <Stat label="Saved" value="$640" hint={<Trend value={0.084}>vs last month</Trend>} />
            <Stat label="Bills" value="$1,210" hint={<Trend value={0}>vs last month</Trend>} />
        </StatRow>
    );
}
```

## API reference

### Trend

A change, e.g. "+12%" with an arrow, coloured by whether it's good news:
savings going up is, spending going up isn't (`good="down"`). `value` is
the change as a fraction (0.12 for 12%); children follow it, muted, e.g.
"vs last month".

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `number` |  | The change as a fraction: 0.12 is 12% up, -0.05 is 5% down. |
| `format` | `((value: number) => string)` |  | How the change reads, e.g. as money instead of a percent. |
| `good` | `"down" \| "up"` | `up` | Which way is good news (default `up`); spending would be `down`. |
| `locale` | `string` |  | For the default percent format. Defaults to the LocaleProvider's. |