@rinzai/zen 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -0,0 +1,138 @@
+# Changelog
+
+## 0.15.0
+
+### New components
+
+- **PlayerBar**: what's playing, in a glass bar along the bottom of the screen, laid out as you like. On phones it sits on the TabBar beside it.
+- **SeekBar**: where playback is, filled to the time played and shaded on to what's loaded, between the time played and the length. Pass `playing` and it glides between the player's time updates, moved by the browser's compositor rather than per-frame renders. Dragging doesn't interrupt playback; letting go seeks; the arrow keys seek 5 seconds.
+- **Marquee**: one line of text cut off with an ellipsis that scrolls to show the rest: on hover or keyboard focus of itself or of its `data-zen-marquee-host` (a row, a tile), or always (`trigger="always"`, for what's playing). Only text that doesn't fit moves, at the same speed whatever its length, with fades at the edges. Stays an ellipsis for reduced motion; the accessible name is the text.
+- **useMediaPlayer**: drives your own `<audio>` or `<video>` (`const [ref, player] = useMediaPlayer()`, then `<audio ref={ref} />`) and keeps its state: playing, waiting, time, duration, buffered, volume. With `play`, `pause`, `toggle`, `seek`, `setVolume` and `setMuted`.
+- **useMediaSession**: puts what's playing on the lock screen and the OS media controls (title, artist, cover, position), and lets play, pause, seek, previous, next and the media keys control your player.
+- **formatDuration**: seconds as a clock reads them (3:07, 1:02:07).
+
+### Renamed
+
+- **TextArea** is now **Textarea** (and `TextAreaProps` is `TextareaProps`), like the element. The old names still work, marked deprecated, until the next breaking release.
+
+### Added to existing components
+
+- **TabBar**: its height is kept in `--zen-tab-bar-height` on its parent (0px while hidden), for a PlayerBar to sit on and the page to pad its end by. PlayerBar keeps `--zen-player-bar-height` the same way.
+- **Segmented**, **RadioCards**: `label` is optional. Without it, name the group with `aria-label` or `aria-labelledby`, as on RadioGroup.
+- **Slider**: `step="any"` for no snapping.
+
+### Fixes
+
+- **SegmentedItem**: an icon and its text sit side by side; they stacked.
+- **Popover, Menu, Select and every anchored popup**: with no room below the trigger, a centred popup wider than its trigger stayed below it, off screen (Chrome) or over the trigger (Firefox), instead of flipping above. It flips now, and a popup lined up with an edge also switches edges when there's no room beside it.
+- **Carousel**: where the slides don't fill the view evenly, Next stopped short of the end, the last slide cut off. The end is now the last stop, with its own dot.
+- **TabBarItem**, **MenuItem**: with `asChild`, `icon` was dropped; it now goes ahead of your link's content, also when that content is a render function (a NavLink's).
+
+### Docs
+
+- The docs ship in the package as markdown, for AI agents: `node_modules/@rinzai/zen/dist/docs` has a page per component with every example's source, and the CHANGELOG is included. The site serves the same pages at `/docs/<component>.md`, with `/llms.txt` and `/llms-full.txt`.
+- Props tables cover parts kept outside a package's `index.tsx`, such as SortableTree, SortableItem, DonutChart and the table's selection and swipe parts.
+- The package's markdown pages have the props tables too, the same as the site's. Their README and `llms.txt` carry the README's guide: setup, the props every component takes, values and forms, languages, theming, overlays and browser support. The README now says Zen exports no icons.
+
+## 0.14.0
+
+### Added to existing components
+
+- **NumberField**: `onValueChange` gets a second argument saying how the number changed: `{ reason: 'step', delta }` for − +, ↑↓ and Page Up/Down, `'input'` for typing, `'limit'` for Home and End. `onValueCommit` fires once per finished change: each step, and what's typed on Enter or on leaving the field. So a step can be sent on as a step to whatever keeps the number (see Number Field → Steps).
+
+## 0.13.0
+
+Since 0.12.0. This release renames things. Every breaking change is listed first, with what to change.
+
+### Breaking changes
+
+#### Callbacks are named for what they change
+
+| Before                                             | After                                                                                                                                                                                                                                                                       |
+| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `onChange`                                         | `onValueChange` on Select, Segmented, RadioGroup, RadioCards, Calendar, DatePicker, DateRangePicker, MonthPicker, MoneyInput, ColorPicker, ColorPanel, IconPicker, RepeatPicker and SortableList (Combobox, Keypad, Slider, RangeSlider, TagInput and Tabs already used it) |
+| `onChange(checked)` on Checkbox, Toggle            | `onCheckedChange(checked)`; `onChange` is the native event again                                                                                                                                                                                                            |
+| Canvas `onChange` / `onChangeEnd` / `onSelect`     | `onItemsChange` / `onItemsChangeEnd` / `onSelectedChange`                                                                                                                                                                                                                   |
+| CalendarHeatmap `onSelect`                         | `onSelectedChange`                                                                                                                                                                                                                                                          |
+| DatePicker, DateRangePicker, MonthPicker `onClear` | `clearable`; clearing calls `onValueChange(null)`                                                                                                                                                                                                                           |
+
+`value` is optional wherever it was required. Leave it out and pass `defaultValue` to let the control keep its own.
+
+#### One tone scale: `default`, `positive`, `negative`
+
+| Before                                                          | After                                      |
+| --------------------------------------------------------------- | ------------------------------------------ |
+| `destructive` (Button, Badge, ChartReference, TableSwipeAction) | `tone="negative"`                          |
+| `danger` (Meter), `error` (Toast, FormMessage)                  | `negative`                                 |
+| `success`                                                       | `positive`                                 |
+| `info` (Toast, FormMessage), `primary` (Sparkline)              | `default`                                  |
+| MenuItem, ConfirmDialog `destructive`                           | `tone="negative"`                          |
+| Button `variant="destructive"`                                  | `tone="negative"` (on the default variant) |
+| Button `variant="icon"`                                         | `variant="ghost"` with an icon size        |
+
+#### Sizes
+
+- Icon buttons line up with fields and buttons of the same size: `icon-sm` is 32px, `icon` is 40px (was 36), `icon-lg` is 44px. The old 24px `icon-sm` is now `icon-xs`.
+- ThemeToggle is 40px.
+- Input's `size` is `"sm" | "lg"` (Button's heights). It no longer passes through the native `size` attribute.
+
+#### Right to left
+
+- Table: `sticky="left"` is `sticky="start"`.
+- TableContainer's `data-under-left` attribute is `data-under-start`.
+- The `.zen__sticky-left` class is `.zen__sticky-start`.
+- Spacing, corners and positions use logical sides, so a class you override may now be `ps-*`/`pe-*`/`start-*`/`end-*`/`text-start` rather than `pl-*`/`left-*`/`text-left`.
+
+#### Forms
+
+- MoneyInput with `name` submits the amount in minor units, from a hidden input (e.g. `123450` for $1,234.50). It used to submit the visible text.
+
+#### Words
+
+- `ICON_COLORS` entries no longer have English labels: `IconColor.label` is optional, and the names come from the messages.
+- `ImageCropError` takes a `reason` code first, `new ImageCropError(reason, message)`, so you can show the error in your own words.
+- `describeRepeat` takes the words as an optional last argument.
+
+### New components
+
+- **Accordion**: disclosures where one or several (`multiple`) open at a time, with ↑↓, Home and End between headings.
+- **Separator**: across or upright, and `decorative` when it's only visual.
+- **ToggleGroup**: buttons that stay pressed, one or several (`multiple`).
+- **Toolbar**: one Tab stop, with arrow keys through its controls, a ToggleGroup's items included. Runs across or upright.
+- **ButtonGroup**: buttons joined into one control, a split button's menu included.
+- **HoverCard**: a glass preview of what a link points to, on hover or keyboard focus.
+- **NumberField**: a number with − and + buttons and arrow keys (PageUp/PageDown for larger steps). Typed and shown in the locale's format, including percent.
+- **TimeField**: hours, minutes and AM/PM as segments, in the locale's order and clock.
+- **Carousel**: native scroll snapping, with glass previous/next buttons and dots in CarouselControls, and the arrow keys.
+- **Resizable** (ResizablePanelGroup, ResizablePanel, ResizableHandle): drag a handle or use the arrow keys, within each panel's limits. Groups nest, and `onLayout` reports the sizes.
+- **Menubar**: a row of menus with one Tab stop. ←→ move between them; with one open, ←→ open the next and hover switches.
+- **NavigationMenu**: site navigation with panels of links that open on hover or click.
+- **SortableTree**: drag-and-drop for groups and nested items. Drop into another group, into an open sub-item, or under another item; `accepts` says what goes where. Keyboard: ↑↓ through every allowed place, ←→ a level out or in, each step announced. Works on table rows (see Table → Reorder).
+- **LocaleProvider**: the locale and every word Zen shows or announces. Pass a partial `messages` to translate or reword any of them (`ENGLISH` lists them all).
+
+### Added to existing components
+
+- **Menu**:
+    - Submenus (MenuSub, MenuSubTrigger, MenuSubContent).
+    - MenuCheckboxItem, and MenuRadioGroup with MenuRadioItem.
+    - ↓ or ↑ on a MenuTrigger opens the menu at its first or last item.
+- **SortableList**: `asChild` on the list and its items, to sort your own elements, such as a TableBody's rows.
+- **Fields** (Input, InputGroup, MoneyInput, Select, Combobox, DatePicker, DateRangePicker, MonthPicker, ColorPicker): `size="sm" | "lg"`, at Button's heights.
+- **Form submission and reset**: custom controls with a `name` are submitted with their form and reset with it. These are Combobox, the date and month pickers, MoneyInput, ColorPicker, TagInput, RepeatPicker, RangeSlider and IconPicker.
+- **Props and refs**: `id`, `data-*`, `aria-*`, `style`, handlers and `ref` reach every component's element. Where a component keeps its own ref, yours is merged with it.
+- **Exported props types**: every component's props type is exported (`ButtonProps`, `TabsProps`…).
+- **Server components**: `'use client'` marks only modules that use React. Money, dates, `cx`, colours and the package entry can be called from server components.
+- **Right to left**: layout, arrow keys, chevrons and slider fills follow `dir`. Calendar, CalendarHeatmap and Pagination use the locale's digits.
+- **Focus**: every control uses the same keyboard focus ring (the `focus-ring` utility).
+
+### Fixes
+
+- Calendar marks today only once hydrated, so server and client render the same.
+- Combobox's list is named after its field.
+- Tabs without panels no longer point `aria-controls` at nothing.
+- Closed popovers and dialogs stay hidden whatever `className` lays them out with.
+- HoverCard and Tooltip are placed against their trigger in browsers without CSS anchor positioning.
+
+### Tests
+
+- Behaviour tests now run in Chromium, Firefox and WebKit, with new keyboard tests and accessibility checks of open popups in both themes. CI runs them.

package/README.md

@@ -57,18 +57,33 @@ export default function App() {
 }
 ```
 
+## For AI agents
+
+Every docs page ships with the package as markdown, matching the installed version: `node_modules/@rinzai/zen/dist/docs` (README.md lists them), with the CHANGELOG at the package root. Point your agent there from your `AGENTS.md` or `CLAUDE.md`:
+
+```md
+UI components come from @rinzai/zen. Its docs, with every example's source, are in node_modules/@rinzai/zen/dist/docs; start at README.md there.
+```
+
+The site has them too: [llms.txt](https://zen.rinzai.dev/llms.txt), [llms-full.txt](https://zen.rinzai.dev/llms-full.txt) (everything in one file) and `/docs/<component>.md`.
+
 ## What's inside
 
 - **Surfaces:** Card, Inset, Alert, Stat, Dialog (and sheets from an edge), ConfirmDialog, Popover, Tooltip, HoverCard, Toast (a stacked deck), Disclosure, Accordion, Separator, Resizable panels, Carousel, Backdrop (aurora, contours or dots, and a pointer light)
-- **Inputs:** Button, ButtonGroup, Toggle, ToggleGroup, Toolbar, Input, TextArea, InputGroup, NumberField, TimeField, MoneyInput (with currency conversion), Select, Combobox, Calendar, DatePicker, DateRangePicker, MonthPicker, ColorPicker, Checkbox, RadioGroup, RadioCards, Segmented, Slider, Chip, Field
+- **Inputs:** Button, ButtonGroup, Toggle, ToggleGroup, Toolbar, Input, Textarea, InputGroup, NumberField, TimeField, MoneyInput (with currency conversion), Select, Combobox, Calendar, DatePicker, DateRangePicker, MonthPicker, ColorPicker, Checkbox, RadioGroup, RadioCards, Segmented, Slider, Chip, Field
 - **Data:** Chart (areas, lines, bars) and DonutChart in plain SVG, composable Table with sticky edges, sorting and rows reordered by drag and drop, tree rows, editable cells, virtual rows, SortableList and SortableTree, Meter, ProgressRing, AnimatedNumber, Badge, StatusPill (a live save status), Skeleton, Spinner, Canvas (items placed freely, with snapping)
 - **Navigation:** Header, NavigationMenu, Pills, Tabs, TabBar, SideNav, TableOfContents, Menu (with submenus, checkbox and radio items, and context menus), Menubar
+- **Media:** PlayerBar (sits on a TabBar), SeekBar, Marquee (cut-off titles that scroll to show the rest), `useMediaPlayer` for your own `<audio>` or `<video>`, `useMediaSession` for the lock screen and media keys, `formatDuration`
 - **Theming:** dark and light, OKLCH tokens, and a theme generator (presets or any hue) that keeps contrast readable
 - **Languages:** LocaleProvider for the locale and every word, and right-to-left layout
 - **Hooks and utilities:** `themeWave` (the theme spreads from the switch like a drop falling into water: ripples, glints and a rainbow edge, drawn on the GPU; `prepareThemeWave` readies it when the pointer reaches your own switch), `useAnchoredPopup`, `useVirtualList`, `useTree`, `useSort`, `useCopyToClipboard`, money, currency, month and date helpers, `hexToOklch` and `oklchToHex`, `cx` (Tailwind-aware class merging), `cva`
 
+## 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.

package/dist/carousel/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../packages/carousel/index.tsx"],"names":[],"mappings":"AAMA,OAAO,EACH,cAAc,EASjB,MAAM,OAAO,CAAC;AA8Bf;;;;;;GAMG;AACH,MAAM,CAAC,OAAO,UAAU,QAAQ,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,EAAE,aAAa,+BAoE/E;AAED,mCAAmC;AACnC,wBAAgB,eAAe,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,EAAE,cAAc,CAAC,KAAK,CAAC,+BAiBjF;AAED,sDAAsD;AACtD,wBAAgB,YAAY,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,EAAE,cAAc,CAAC,KAAK,CAAC,+BAoB9E;AAKD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,EAAE,cAAc,CAAC,QAAQ,CAAC,+BAoBzF;AAED,mEAAmE;AACnE,wBAAgB,YAAY,CAAC,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,EAAE,cAAc,CAAC,QAAQ,CAAC,+BAmBrF;AAED,sGAAsG;AACtG,wBAAgB,YAAY,CAAC,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,EAAE,cAAc,CAAC,KAAK,CAAC,sCA6BzE;AAED,8GAA8G;AAC9G,wBAAgB,gBAAgB,CAAC,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,EAAE,cAAc,CAAC,KAAK,CAAC,+BAE7E;AAED,MAAM,MAAM,aAAa,GAAG,cAAc,CAAC,SAAS,CAAC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../packages/carousel/index.tsx"],"names":[],"mappings":"AAMA,OAAO,EACH,cAAc,EASjB,MAAM,OAAO,CAAC;AA8Bf;;;;;;GAMG;AACH,MAAM,CAAC,OAAO,UAAU,QAAQ,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,EAAE,aAAa,+BA0E/E;AAED,mCAAmC;AACnC,wBAAgB,eAAe,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,EAAE,cAAc,CAAC,KAAK,CAAC,+BAiBjF;AAED,sDAAsD;AACtD,wBAAgB,YAAY,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,EAAE,cAAc,CAAC,KAAK,CAAC,+BAoB9E;AAKD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,EAAE,cAAc,CAAC,QAAQ,CAAC,+BAoBzF;AAED,mEAAmE;AACnE,wBAAgB,YAAY,CAAC,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,EAAE,cAAc,CAAC,QAAQ,CAAC,+BAmBrF;AAED,sGAAsG;AACtG,wBAAgB,YAAY,CAAC,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,EAAE,cAAc,CAAC,KAAK,CAAC,sCA6BzE;AAED,8GAA8G;AAC9G,wBAAgB,gBAAgB,CAAC,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,EAAE,cAAc,CAAC,KAAK,CAAC,+BAE7E;AAED,MAAM,MAAM,aAAa,GAAG,cAAc,CAAC,SAAS,CAAC,CAAC"}

package/dist/carousel/index.js

@@ -26,11 +26,11 @@ function v({ className: t, children: i, ...a }) {
 	}), g = s(() => {
 		let e = c.current;
 		if (!e) return;
-		let t = Array.from(e.children), n = Math.abs(e.scrollLeft), r = e.scrollWidth - e.clientWidth, i = t[0] ? _(t[0], e) : 0, a = t.map((t) => _(t, e) - i), o = Math.max(1, a.filter((e) => e <= r + 1).length), s = 0;
+		let t = Array.from(e.children), n = Math.abs(e.scrollLeft), r = e.scrollWidth - e.clientWidth, i = t[0] ? _(t[0], e) : 0, a = t.map((t) => _(t, e) - i), o = a.filter((e) => e < r - 1).length + 1, s = (e) => Math.min(a[e], r), l = 0;
 		a.forEach((e, t) => {
-			t < o && Math.abs(e - n) < Math.abs(a[s] - n) && (s = t);
-		}), r > 0 && n >= r - 1 && (s = o - 1), u((e) => e.index === s && e.stops === o && e.count === t.length ? e : {
-			index: s,
+			t < o && Math.abs(s(t) - n) < Math.abs(s(l) - n) && (l = t);
+		}), r > 0 && n >= r - 1 && (l = o - 1), u((e) => e.index === l && e.stops === o && e.count === t.length ? e : {
+			index: l,
 			stops: o,
 			count: t.length
 		});
@@ -55,7 +55,7 @@ function v({ className: t, children: i, ...a }) {
 	let v = s((e) => {
 		let t = c.current, n = t?.children[e];
 		if (!t || !n) return;
-		let i = t.children[0], a = _(n, t) - _(i, t), o = getComputedStyle(t).direction === "rtl";
+		let i = t.children[0], a = Math.min(_(n, t) - _(i, t), t.scrollWidth - t.clientWidth), o = getComputedStyle(t).direction === "rtl";
 		t.scrollTo({
 			left: o ? -a : a,
 			behavior: r() ? "instant" : "smooth"

package/dist/docs/README.md

@@ -0,0 +1,205 @@
+# 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.
+
+Breaking changes and additions by version are in ../../CHANGELOG.md.
+
+## Components
+
+- [Accordion](./accordion.md): Sections under headings that open one at a time, or several: questions and answers, or groups of settings.
+- [Alert](./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](./animated-number.md): Numbers and amounts that count smoothly to each new value.
+- [Avatar](./avatar.md): A round picture, or the name's initial on the glowing accent. With an in-browser crop for uploads.
+- [Backdrop](./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](./badge.md): A small label for status, counts and tags.
+- [Breadcrumbs](./breadcrumbs.md): Where a page sits: its parents as links, then the page itself. Works with any router.
+- [Button](./button.md): Actions, from the one glowing primary action to quiet ghost buttons.
+- [Button Group](./button-group.md): Buttons joined into one, rounded only at the ends: a split button, or Previous, Today and Next.
+- [Calendar](./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](./calendar-heatmap.md): A month of days shaded by their value, like spending per day.
+- [Canvas](./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](./card.md): Glass panels for grouping content, and stats for single figures.
+- [Carousel](./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](./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](./checkbox.md): A native checkbox whose tick draws itself in, with a label, a description and a mixed state.
+- [Chip](./chip.md): Small pressable buttons for quick picks beside a field, like common tenures.
+- [Code Block](./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](./code-input.md): A one-time code, a box per character, that types, pastes and autofills from a text message like any field.
+- [Collapse](./collapse.md): Shows as many items as fit on one line, and the rest behind "+N".
+- [Color Picker](./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](./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](./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](./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](./dialog.md): Modal dialogs on the native <dialog> element, sheets that slide in from an edge, and a confirmation for destructive actions.
+- [Disclosure](./disclosure.md): A button that shows and hides a section, like finished goals under a list.
+- [Editable Cell](./editable-cell.md): A value edited in place: shows the value, swaps in any editor on click or Enter.
+- [Empty State](./empty-state.md): What a list or page shows when there's nothing in it yet, and the action that fills it.
+- [Field](./field.md): A label, hint and error wired to their control for screen readers, and messages for a whole form.
+- [File Drop](./file-drop.md): Somewhere to drop files, or click to choose them, that lights up as files are dragged over it.
+- [Filter Bar](./filter-bar.md): The filters in effect, each removed with its ×, and Clear all.
+- [Header](./header.md): A sticky glass bar across the top of the page.
+- [Hover Card](./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](./icon-picker.md): An icon and a colour for something, like a spending category, from a grid in a popover.
+- [Input](./input.md): Text fields in faint glass that glow on focus.
+- [Input Group](./input-group.md): A field with slots: put symbols, icons, units, buttons or menus before and after the input.
+- [Inset](./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](./kbd.md): Keys on the keyboard, for shortcuts in hints and tooltips.
+- [Keypad](./keypad.md): A number pad for typing an amount on a phone.
+- [Load More](./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](./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](./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](./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, and a menubar of menus.
+- [Meter](./meter.md): A measure against a limit, like spend against a budget: warm near it, red past it.
+- [Money Input](./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](./month-picker.md): A field showing a month that opens a year and a 12-month grid, with optional limits and clearing.
+- [Navigation Menu](./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](./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](./page-header.md): Eyebrow, aurora title and lead paragraph for the top of a page.
+- [Page Transition](./page-transition.md): The old page fades out as the new one rises in, when your router changes page in a view transition.
+- [Pagination](./pagination.md): The pages a long list is split into, as buttons or links for your router.
+- [Pills](./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](./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](./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](./progress-ring.md): Circular progress with room for a label in the middle.
+- [Radio Cards](./radio-cards.md): Choose one of a few cards that each show their option, like a colour palette.
+- [Radio Group](./radio-group.md): Choose one of a list, each option with a label and a description; native radios, so arrow keys work.
+- [Range Slider](./range-slider.md): Two thumbs on one track, for a span like an amount from $50 to $500.
+- [Repeat Picker](./repeat-picker.md): How often something recurs, like a bill, said in words, with the next dates it falls on.
+- [Resizable](./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](./seek-bar.md): Where playback is in a track, and the way to move it: played and loaded on one track, between the time played and the length.
+- [Segmented](./segmented.md): A pill row for a few mutually exclusive options.
+- [Select](./select.md): Pick one value from a short list, fully keyboard-driven. For long or searchable lists, use Combobox.
+- [Separator](./separator.md): A hairline between groups of content, across or upright.
+- [Side Nav](./side-nav.md): Vertical navigation in titled groups, for docs and settings sidebars. Works with any router.
+- [Skeleton & Spinner](./skeleton.md): Placeholders for content on its way.
+- [Slider](./slider.md): A native range input with a glowing thumb and any track you like.
+- [Sortable List](./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.
+- [Sparkline](./sparkline.md): A small line of how a number has moved, with no axes, for beside a figure. It draws itself in.
+- [Spinner](./spinner.md): A small loading spinner in the current text colour, announced to screen readers when labelled.
+- [Status Pill](./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](./stepper.md): The steps of a flow and where you are in it; the line between them fills in as you go.
+- [Tab Bar](./tab-bar.md): Phone navigation fixed to the bottom of the screen. Works with any router.
+- [Table](./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](./table-of-contents.md): An "On this page" list that highlights the section being read.
+- [Tabs](./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](./tag-input.md): A field of short values (tags, emails): Enter or a comma adds one, Backspace takes the last back.
+- [Textarea](./textarea.md): Multi-line text, styled like Input.
+- [Theme Toggle](./theme-toggle.md): Switches between the dark and light themes, remembering the choice itself or leaving it to your app.
+- [Theming & styling](./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](./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](./timeline.md): Events in order, each on a dot joined by a line: an activity feed or a history.
+- [Toast](./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](./toggle.md): An on/off switch.
+- [Toggle Group](./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](./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](./tooltip.md): A short glass hint on hover or keyboard focus, describing its trigger to screen readers.
+- [Tree Table](./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](./trend.md): A change, like +12% with an arrow, coloured by whether it is good news.

package/dist/docs/accordion.md

@@ -0,0 +1,122 @@
+# 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.

package/dist/docs/alert.md

@@ -0,0 +1,69 @@
+# 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. |