@rinzai/zen 0.14.0 → 0.15.0

package/dist/docs/side-nav.md

@@ -0,0 +1,75 @@
+# Side Nav
+
+Vertical navigation in titled groups, for docs and settings sidebars. Works with any router.
+
+```tsx
+import { SideNav, SideNavGroup, SideNavLink } from '@rinzai/zen';
+```
+
+## Examples
+
+### Default
+
+```tsx
+import { SideNav, SideNavGroup, SideNavLink } from '@rinzai/zen';
+import { useState } from 'react';
+
+const GROUPS = [
+    { title: 'Account', links: ['Profile', 'Security', 'Passkeys'] },
+    { title: 'Workspace', links: ['Members', 'Billing', 'Integrations'] },
+];
+
+/** With a router, pass its link as the child: <SideNavLink asChild><NavLink to="/billing">Billing</NavLink></SideNavLink>. */
+export default function Default() {
+    const [current, setCurrent] = useState('Security');
+    return (
+        <SideNav aria-label="Settings" className="w-56">
+            {GROUPS.map((group) => (
+                <SideNavGroup key={group.title} title={group.title}>
+                    {group.links.map((link) => (
+                        <SideNavLink
+                            key={link}
+                            href={`#${link.toLowerCase()}`}
+                            active={link === current}
+                            onClick={(e) => {
+                                e.preventDefault();
+                                setCurrent(link);
+                            }}
+                        >
+                            {link}
+                        </SideNavLink>
+                    ))}
+                </SideNavGroup>
+            ))}
+        </SideNav>
+    );
+}
+```
+
+## API reference
+
+### SideNav
+
+Vertical navigation, e.g. a docs or settings sidebar. Give it an aria-label.
+
+No props of its own; it accepts the props of the element it renders.
+
+### SideNavGroup
+
+A titled group of links.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className` | `string` |  |  |
+| `title` | `ReactNode` |  |  |
+
+### SideNavLink
+
+One link. `active` marks the current page. With `asChild`, the styles go onto
+your own link element instead (a router's Link or NavLink, which may set
+aria-current itself).
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `active` | `boolean` |  | This link is the current page. |
+| `asChild` | `boolean` |  | Style the single child element (e.g. a router link) instead of rendering an <a>. |

package/dist/docs/skeleton.md

@@ -0,0 +1,89 @@
+# Skeleton & Spinner
+
+Placeholders for content on its way.
+
+```tsx
+import { Skeleton, Spinner } from '@rinzai/zen';
+```
+
+## Examples
+
+### Loading card
+
+```tsx
+import { Skeleton } from '@rinzai/zen';
+
+export default function LoadingCard() {
+    return (
+        <div className="glass glow-edge flex w-80 flex-col gap-3 rounded-xl p-4">
+            <Skeleton className="h-3 w-24" />
+            <Skeleton className="h-7 w-40" />
+            <Skeleton className="h-3 w-full" />
+        </div>
+    );
+}
+```
+
+### Reveal
+
+```tsx
+import { Button, Skeleton } from '@rinzai/zen';
+import { useState } from 'react';
+
+export default function Reveal() {
+    const [loading, setLoading] = useState(true);
+    return (
+        <div className="flex flex-col items-start gap-4">
+            <div className="glass glow-edge flex w-80 flex-col gap-3 rounded-xl p-4">
+                <Skeleton loading={loading} className="h-3 w-24">
+                    <p className="text-muted-foreground text-xs">Balance</p>
+                </Skeleton>
+                <Skeleton loading={loading} className="h-7 w-40">
+                    <p className="text-2xl font-semibold tabular-nums">$4,280.15</p>
+                </Skeleton>
+            </div>
+            <Button variant="outline" onClick={() => setLoading((l) => !l)}>
+                {loading ? 'Load' : 'Reload'}
+            </Button>
+        </div>
+    );
+}
+```
+
+### With spinner
+
+```tsx
+import { Spinner } from '@rinzai/zen';
+
+export default function WithSpinner() {
+    return (
+        <div className="text-muted-foreground flex items-center gap-2 text-sm">
+            <Spinner /> Loading…
+        </div>
+    );
+}
+```
+
+## API reference
+
+### Skeleton
+
+Shimmering placeholder in the shape of content that's on its way. Size it with className.
+
+Give it the content as its child and `loading`: the placeholder shows while
+loading, then the content fades in where it was.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` |  | The content this stands in for, a single element. |
+| `loading` | `boolean` |  | With children: show the placeholder instead of them while true. |
+
+### Spinner
+
+Small circular spinner in the current text colour; size it with className
+(default size-4). Decorative by default (e.g. inside a loading Button). Give
+it a `label` when it stands on its own, and screen readers announce it.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `label` | `string` |  | What is loading, e.g. "Loading entries". Makes the spinner announce itself. |

package/dist/docs/slider.md

@@ -0,0 +1,87 @@
+# Slider
+
+A native range input with a glowing thumb and any track you like.
+
+```tsx
+import { Slider } from '@rinzai/zen';
+```
+
+## Examples
+
+### Default
+
+```tsx
+import { Slider } from '@rinzai/zen';
+import { useState } from 'react';
+
+/** Filled up to the value; arrow keys and Home/End work as on any range input. */
+export default function Default() {
+    const [savings, setSavings] = useState(30);
+    return (
+        <div className="flex w-72 flex-col gap-2">
+            <div className="flex justify-between text-sm">
+                <span className="font-medium">Save each month</span>
+                <span className="text-muted-foreground tabular-nums">{savings}%</span>
+            </div>
+            <Slider
+                aria-label="Save each month"
+                value={savings}
+                onValueChange={setSavings}
+                valueText={(v) => `${v} percent`}
+            />
+        </div>
+    );
+}
+```
+
+### Hue
+
+```tsx
+import { Slider } from '@rinzai/zen';
+import { useState } from 'react';
+
+/** A custom track (every hue) and thumb (the chosen colour); onValueCommit fires once, when you let go. */
+export default function Hue() {
+    const [hue, setHue] = useState(295);
+    const [saved, setSaved] = useState(295);
+    const gradient = `linear-gradient(to right, ${Array.from({ length: 13 }, (_, i) => `oklch(0.72 0.13 ${i * 30})`).join(', ')})`;
+    return (
+        <div className="flex w-72 flex-col gap-2">
+            <Slider
+                aria-label="Accent hue"
+                min={0}
+                max={359}
+                value={hue}
+                onValueChange={setHue}
+                onValueCommit={setSaved}
+                trackBackground={gradient}
+                thumbColor={`oklch(0.72 0.13 ${hue})`}
+                valueText={(v) => `Hue ${v} degrees`}
+            />
+            <p className="text-muted-foreground mt-0! text-xs">Saved: {saved}°</p>
+        </div>
+    );
+}
+```
+
+## API reference
+
+### Slider
+
+A range slider on the native <input type="range"> (keyboard, forms and
+screen readers work as usual): a rounded track, filled up to the value in
+the accent unless you give it your own `trackBackground` (e.g. a hue
+gradient), and a glowing thumb.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `defaultValue` | `number` |  | The first value, when the slider keeps its own (default `min`). |
+| `max` | `number` | `100` |  |
+| `min` | `number` | `0` |  |
+| `onValueChange` | `((value: number) => void)` |  | While dragging (every step). |
+| `onValueCommit` | `((value: number) => void)` |  | Once the user lets go: the moment to save. |
+| `step` | `"any" \| number` | `1` | `'any'` for no snapping; the arrow keys then move by the browser's own amount. |
+| `thumbColor` | `string` |  | CSS colour for the thumb (default: the accent). |
+| `trackBackground` | `string` |  | CSS background for the track, e.g. a gradient of hues. |
+| `value` | `number` |  | The value, when you keep it. |
+| `valueText` | `((value: number) => string)` |  | Spoken value, e.g. (v) => `Hue ${v} degrees`. |

package/dist/docs/sortable.md

@@ -0,0 +1,182 @@
+# Sortable List
+
+Put a list in order, or a tree of groups (a table’s rows, say), by dragging items by a grip or with the keyboard, each step announced: into other groups, open sub-items, or under another item.
+
+```tsx
+import { SortableList, SortableTree, SortableItem, SortableHandle, flattenTree } from '@rinzai/zen';
+```
+
+## Examples
+
+### Default
+
+```tsx
+import { Meter, SortableHandle, SortableItem, SortableList } from '@rinzai/zen';
+import { useState } from 'react';
+
+const BUDGETS: Record<string, { name: string; spent: number; limit: number }> = {
+    rent: { name: 'Rent', spent: 1800, limit: 1800 },
+    groceries: { name: 'Groceries', spent: 412, limit: 500 },
+    transport: { name: 'Transport', spent: 64, limit: 120 },
+    dining: { name: 'Eating out', spent: 188, limit: 150 },
+    fun: { name: 'Fun', spent: 40, limit: 100 },
+};
+
+/** Drag a budget by its grip to put them in your order (or Tab to a grip, Space, arrows, Space). */
+export default function Default() {
+    const [order, setOrder] = useState(Object.keys(BUDGETS));
+    return (
+        <SortableList value={order} onValueChange={setOrder} aria-label="Budgets" className="w-full max-w-md gap-2">
+            {order.map((id) => {
+                const b = BUDGETS[id];
+                return (
+                    <SortableItem
+                        key={id}
+                        id={id}
+                        className="glass glow-edge flex items-center gap-2 rounded-xl py-2 pr-4 pl-1.5"
+                    >
+                        <SortableHandle id={id} label={b.name} />
+                        <Meter
+                            label={b.name}
+                            value={b.spent}
+                            max={b.limit}
+                            detail={`$${b.spent} / $${b.limit}`}
+                            className="flex-1"
+                        />
+                    </SortableItem>
+                );
+            })}
+        </SortableList>
+    );
+}
+```
+
+### Groups
+
+```tsx
+import { flattenTree, SortableHandle, SortableItem, type SortableNode, SortableTree } from '@rinzai/zen';
+import { useState } from 'react';
+
+const NAMES: Record<string, string> = {
+    bills: 'Bills',
+    rent: 'Rent',
+    phone: 'Phone',
+    streaming: 'Streaming',
+    life: 'Lifestyle',
+    gym: 'Gym',
+    books: 'Books',
+};
+const GROUPS = new Set(['bills', 'life']);
+const AMOUNTS: Record<string, string> = {
+    rent: '$1,800',
+    phone: '$45',
+    streaming: '$32',
+    gym: '$60',
+    books: '$25',
+};
+
+/**
+ * Budgets in groups, with SortableTree: drag one within its group, into the
+ * other, or sideways to tuck it under another budget. Groups stay at the top
+ * and take budgets; budgets never sit at the top on their own.
+ */
+export default function Groups() {
+    const [tree, setTree] = useState<SortableNode[]>([
+        { id: 'bills', children: [{ id: 'rent' }, { id: 'phone' }, { id: 'streaming' }] },
+        { id: 'life', children: [{ id: 'gym' }, { id: 'books' }] },
+    ]);
+    return (
+        <SortableTree
+            aria-label="Budgets"
+            value={tree}
+            onValueChange={setTree}
+            accepts={(id, parent) => (GROUPS.has(id) ? parent === null : parent !== null)}
+            className="w-full max-w-sm gap-1.5"
+        >
+            {flattenTree(tree).map(({ id, depth }) => (
+                <SortableItem key={id} id={id} style={{ marginInlineStart: Math.max(0, depth - 1) * 24 }}>
+                    {GROUPS.has(id) ? (
+                        <div className="flex items-center gap-1 pt-2">
+                            <SortableHandle id={id} label={NAMES[id]} />
+                            <span className="text-muted-foreground text-xs font-medium tracking-wide uppercase">
+                                {NAMES[id]}
+                            </span>
+                        </div>
+                    ) : (
+                        <div className="glass glow-edge flex items-center gap-1 rounded-xl py-1.5 ps-1.5 pe-4">
+                            <SortableHandle id={id} label={NAMES[id]} />
+                            <span className="flex-1 text-sm">{NAMES[id]}</span>
+                            <span className="text-muted-foreground text-sm tabular-nums">{AMOUNTS[id]}</span>
+                        </div>
+                    )}
+                </SortableItem>
+            ))}
+        </SortableTree>
+    );
+}
+```
+
+## API reference
+
+### SortableList
+
+A list put in order by dragging, e.g. budget categories: drag an item by its
+SortableHandle and the others make way (a phone taps lightly at each new
+place); it settles into place when let go.
+From the keyboard, Space or Enter on a handle picks the item up, the arrow
+keys move it, Space or Enter drops it and Escape puts it back; each step is
+announced. `value` is the ids in order; render a SortableItem for each.
+With `asChild` (and `asChild` on the items), your own elements instead: a
+TableBody of TableRows, say, one per group, each sorted on its own.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `onValueChange` (required) | `(value: string[]) => void` |  |  |
+| `value` (required) | `readonly string[]` |  | The items' ids, in order. |
+| `asChild` | `boolean` |  | Put the list's props on your own element (the single child, e.g. a TableBody) instead of a ul. |
+
+### SortableTree
+
+Items in groups, and groups in groups, put in order by dragging: an item
+can go anywhere in its group, into another group (or one open inside it),
+or under another item. While dragging, a glowing line shows where it will
+land, set in as deep as it'll go, and the group it would join is lit; drag
+sideways to go a level in or out. From the keyboard, Space or Enter on a
+handle picks it up, the up and down arrows move it through every place it
+can go, left and right a level out or in, Space or Enter drops it and
+Escape puts it back; each step is announced.
+
+`value` is the tree of ids. Render a SortableItem for each row shown, in
+order (flattenTree lists them, with their depths): what's under a closed
+one isn't shown, and moves with it. `accepts` says which group takes which
+item. With `asChild`, your own element (a Table, its rows SortableItems with
+asChild on TableRows) instead of a ul.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `onValueChange` (required) | `(value: SortableNode[]) => void` |  |  |
+| `value` (required) | `readonly SortableNode[]` |  | The tree of ids, in order. |
+| `accepts` | `((id: string, parentId: string \| null) => boolean)` |  | Whether `parentId` (null: the top level) takes item `id`; by default, everything goes anywhere. |
+| `asChild` | `boolean` |  | Put its props on your own element (the single child, e.g. a Table) instead of a ul. |
+| `indent` | `number` | `24` | How far in a level is set, in px: the drop line is set in this far, and dragging this far sideways goes a level in or out. |
+
+### SortableItem
+
+One item in a SortableList or SortableTree; give it the `id` it has in the list's value. With `asChild`, your own element (a TableRow).
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `id` (required) | `string` |  |  |
+| `asChild` | `boolean` |  | Put the item's props on your own element (the single child, e.g. a TableRow) instead of an li. |
+| `label` | `string` |  | Its name, for one without a SortableHandle (a group others go into), to say "2 of 3 in Food". |
+
+### SortableHandle
+
+What an item is dragged by: a grip button. `label` names the item ("Rent");
+the button reads "Reorder Rent". It takes no scroll gestures, so dragging it
+never scrolls the page.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `id` (required) | `string` |  | The item's id, as in the list's value. |
+| `label` (required) | `string` |  | The item's name, e.g. "Rent". |

package/dist/docs/sparkline.md

@@ -0,0 +1,56 @@
+# Sparkline
+
+A small line of how a number has moved, with no axes, for beside a figure. It draws itself in.
+
+```tsx
+import { Sparkline } from '@rinzai/zen';
+```
+
+## Examples
+
+### Default
+
+```tsx
+import { Sparkline, Stat, StatRow } from '@rinzai/zen';
+
+/** Beside the figures they explain: a balance over the month, and spending by week. */
+export default function Default() {
+    return (
+        <StatRow className="w-full max-w-lg">
+            <Stat
+                label="Balance"
+                value={
+                    <span className="flex items-center justify-between gap-3">
+                        $6,908
+                        <Sparkline values={[4100, 4300, 3900, 5200, 5600, 5400, 6100, 6908]} />
+                    </span>
+                }
+            />
+            <Stat
+                label="Spent"
+                tone="negative"
+                value={
+                    <span className="flex items-center justify-between gap-3">
+                        $2,742
+                        <Sparkline tone="negative" values={[620, 540, 810, 772]} />
+                    </span>
+                }
+            />
+        </StatRow>
+    );
+}
+```
+
+## API reference
+
+### Sparkline
+
+A small line of how a number has moved (a balance over a month, spending by
+week), with no axes: for beside a figure in a Stat or a table row. It takes
+its size from className (e.g. h-8 w-24) and draws itself in.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `values` (required) | `number[]` |  |  |
+| `area` | `boolean` | `true` | A soft fill under the line. |
+| `tone` | `"default" \| "muted" \| "negative"` | `default` | The accent (`primary`), red (`negative`), or grey (`muted`). |

package/dist/docs/spinner.md

@@ -0,0 +1,69 @@
+# Spinner
+
+A small loading spinner in the current text colour, announced to screen readers when labelled.
+
+```tsx
+import { Spinner } from '@rinzai/zen';
+```
+
+## Examples
+
+### Default
+
+```tsx
+import { Spinner } from '@rinzai/zen';
+
+/** Sized and coloured with className; it follows the text colour. */
+export default function Default() {
+    return (
+        <div className="flex items-center gap-6">
+            <Spinner />
+            <Spinner className="size-6" />
+            <Spinner className="text-primary size-8 border-[3px]" />
+            <Spinner className="text-muted-foreground size-5" />
+        </div>
+    );
+}
+```
+
+### Loading
+
+```tsx
+import { Button, Card, CardHeader, CardTitle, Spinner } from '@rinzai/zen';
+import { useState } from 'react';
+
+/** Standing on its own, a spinner needs a label so screen readers announce what is loading. */
+export default function Loading() {
+    const [loading, setLoading] = useState(true);
+    return (
+        <Card className="w-80">
+            <CardHeader>
+                <CardTitle>Entries</CardTitle>
+            </CardHeader>
+            {loading ? (
+                <div className="text-muted-foreground flex items-center gap-3 py-6 text-sm">
+                    <Spinner label="Loading entries" />
+                    Loading entries…
+                </div>
+            ) : (
+                <p className="py-6 text-sm">12 entries this month.</p>
+            )}
+            <Button variant="outline" size="sm" onClick={() => setLoading((l) => !l)}>
+                {loading ? 'Finish loading' : 'Load again'}
+            </Button>
+        </Card>
+    );
+}
+```
+
+## API reference
+
+### Spinner
+
+Small circular spinner in the current text colour; size it with className
+(default size-4). Decorative by default (e.g. inside a loading Button). Give
+it a `label` when it stands on its own, and screen readers announce it.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `label` | `string` |  | What is loading, e.g. "Loading entries". Makes the spinner announce itself. |

package/dist/docs/status-pill.md

@@ -0,0 +1,81 @@
+# Status Pill
+
+A small status that changes in place, such as Saving…, Saved or Not saved with a Retry, and fades back once the news is old.
+
+```tsx
+import { StatusPill, StatusPillAction } from '@rinzai/zen';
+```
+
+## Examples
+
+### Save
+
+```tsx
+import { Button, Spinner, StatusPill, StatusPillAction } from '@rinzai/zen';
+import { useEffect, useState } from 'react';
+// Icons from Heroicons (https://heroicons.com): AlertTriangle (exclamation-triangle), Check (check).
+
+type Save = 'saving' | 'saved' | 'error';
+
+/** A save indicator: saving spins, saved checks and then quietens, a failure is red and offers a retry. */
+export default function Save() {
+    const [state, setState] = useState<Save>('saved');
+    const [quiet, setQuiet] = useState(false);
+    useEffect(() => {
+        setQuiet(false);
+        if (state !== 'saved') return;
+        const t = window.setTimeout(() => setQuiet(true), 2500);
+        return () => window.clearTimeout(t);
+    }, [state]);
+    const save = (ok: boolean) => {
+        setState('saving');
+        window.setTimeout(() => setState(ok ? 'saved' : 'error'), 1200);
+    };
+
+    return (
+        <div className="flex flex-col items-center gap-4">
+            {state === 'error' ? (
+                <StatusPill tone="negative">
+                    <AlertTriangle />
+                    Not saved
+                    <StatusPillAction onClick={() => save(true)}>Retry</StatusPillAction>
+                </StatusPill>
+            ) : (
+                <StatusPill tone={state === 'saved' ? 'positive' : 'default'} quiet={state === 'saved' && quiet}>
+                    {state === 'saving' ? <Spinner /> : <Check />}
+                    {state === 'saving' ? 'Saving…' : 'Saved'}
+                </StatusPill>
+            )}
+            <div className="flex gap-2">
+                <Button variant="outline" size="sm" onClick={() => save(true)}>
+                    Save
+                </Button>
+                <Button variant="outline" size="sm" onClick={() => save(false)}>
+                    Save and fail
+                </Button>
+            </div>
+        </div>
+    );
+}
+```
+
+## API reference
+
+### StatusPill
+
+A small rounded status that changes in place, e.g. an app's "Saving…",
+"Saved", "Not saved · Retry": an icon (a Spinner, a Check) and a few words.
+`quiet` fades it back once the news is old (a save a few seconds ago).
+Changes are read out politely (role="status"). For an action inside it,
+such as Retry, use StatusPillAction. For a fixed label or count, use Badge.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `quiet` | `boolean` | `false` | Faded back into the page: the news is old. |
+| `tone` | `"default" \| "negative" \| "positive"` | `default` | `positive` in the accent colour (done), `negative` in red (failed); `default` is muted (in progress). |
+
+### StatusPillAction
+
+A text button inside a StatusPill, e.g. Retry, in the pill's colour.
+
+No props of its own; it accepts the props of the element it renders.