@rinzai/zen 0.13.0 → 0.15.0

package/dist/docs/animated-number.md

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

package/dist/docs/avatar.md

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

package/dist/docs/backdrop.md

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

package/dist/docs/badge.md

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

package/dist/docs/breadcrumbs.md

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

package/dist/docs/button-group.md

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

package/dist/docs/button.md

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

package/dist/docs/calendar-heatmap.md

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