@rinzai/zen 0.14.0 → 0.15.0

package/dist/docs/header.md

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

package/dist/docs/hover-card.md

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

package/dist/docs/icon-picker.md

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

package/dist/docs/input-group.md

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

package/dist/docs/input.md

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

package/dist/docs/inset.md

@@ -0,0 +1,57 @@
+# 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` |  |

package/dist/docs/kbd.md

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

package/dist/docs/keypad.md

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

package/dist/docs/load-more.md

@@ -0,0 +1,66 @@
+# 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` |  |  |

package/dist/docs/locale-provider.md

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