@rinzai/zen 0.13.0 → 0.15.0

package/dist/docs/tabs.md

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

package/dist/docs/tag-input.md

@@ -0,0 +1,45 @@
+# 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[]` |  |  |

package/dist/docs/textarea.md

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

package/dist/docs/theme-toggle.md

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

package/dist/docs/theming.md

@@ -0,0 +1,193 @@
+# 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>
+    );
+}
+```

package/dist/docs/time-field.md

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

package/dist/docs/timeline.md

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

package/dist/docs/toast.md

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