@rinzai/zen 0.14.0 → 0.15.0

package/dist/docs/table.md

@@ -0,0 +1,714 @@
+# Table
+
+Composable tables: a glass panel that scrolls, sticky headers, first column and totals, sortable columns, rows reordered by drag and drop (into groups and under other rows), and virtual rows for long lists.
+
+```tsx
+import { TableContainer, Table, TableHead, TableCell, TableFooter, TableFooterCell, TableSpacerRow, TableSelectCell, TableSelectHead, SelectionBar, TableSwipeRow, TableSwipeAction } from '@rinzai/zen';
+```
+
+## Examples
+
+### Default
+
+```tsx
+import { Badge, Table, TableBody, TableCell, TableContainer, TableHead, TableHeader, TableRow } from '@rinzai/zen';
+
+const ENTRIES = [
+    { label: 'Rent', category: 'Housing', amount: -1850, recurring: true },
+    { label: 'Paycheck', category: 'Salary', amount: 8450, recurring: true },
+    { label: 'Weekly shop', category: 'Groceries', amount: -164, recurring: false },
+];
+
+export default function Default() {
+    return (
+        <TableContainer className="w-full max-w-xl">
+            <Table>
+                <TableHeader>
+                    <TableRow>
+                        <TableHead>Entry</TableHead>
+                        <TableHead>Category</TableHead>
+                        <TableHead numeric>Amount</TableHead>
+                    </TableRow>
+                </TableHeader>
+                <TableBody className="rise-list">
+                    {ENTRIES.map((e) => (
+                        <TableRow key={e.label}>
+                            <TableCell className="font-medium">
+                                {e.label} {e.recurring && <Badge variant="outline">Monthly</Badge>}
+                            </TableCell>
+                            <TableCell className="text-muted-foreground">{e.category}</TableCell>
+                            <TableCell numeric className={e.amount > 0 ? 'text-primary' : undefined}>
+                                {e.amount > 0 ? '+' : '−'}${Math.abs(e.amount).toLocaleString('en-US')}
+                            </TableCell>
+                        </TableRow>
+                    ))}
+                </TableBody>
+            </Table>
+        </TableContainer>
+    );
+}
+```
+
+### Sortable
+
+```tsx
+import {
+    Table,
+    TableBody,
+    TableCell,
+    TableContainer,
+    TableEmpty,
+    TableHead,
+    TableHeader,
+    TableRow,
+    useSort,
+} from '@rinzai/zen';
+
+interface Payment {
+    month: string;
+    principal: number;
+    interest: number;
+    balance: number;
+}
+
+// An amortization schedule: 240 000 over 12 months at 9%.
+const SCHEDULE: Payment[] = (() => {
+    let balance = 240000;
+    const rate = 0.09 / 12;
+    const emi = (balance * rate) / (1 - (1 + rate) ** -12);
+    return Array.from({ length: 12 }, (_, i) => {
+        const interest = balance * rate;
+        const principal = emi - interest;
+        balance -= principal;
+        return {
+            month: new Date(2026, 9 + i).toLocaleString('en-US', { month: 'short', year: 'numeric' }),
+            principal,
+            interest,
+            balance: Math.max(0, balance),
+        };
+    });
+})();
+
+const COMPARE = {
+    principal: (a: Payment, b: Payment) => a.principal - b.principal,
+    interest: (a: Payment, b: Payment) => a.interest - b.interest,
+    balance: (a: Payment, b: Payment) => a.balance - b.balance,
+};
+
+const money = (n: number) => n.toLocaleString('en-US', { maximumFractionDigits: 0 });
+
+/** Click a heading to sort by it, again to reverse, a third time to clear. The header stays put as the rows scroll. */
+export default function Sortable() {
+    const { rows, headProps } = useSort(SCHEDULE, COMPARE);
+    return (
+        <TableContainer label="Repayment schedule" className="max-h-80 w-full max-w-xl">
+            <Table>
+                <TableHeader>
+                    <TableRow>
+                        <TableHead>Month</TableHead>
+                        <TableHead numeric {...headProps('principal')}>
+                            Principal
+                        </TableHead>
+                        <TableHead numeric {...headProps('interest')}>
+                            Interest
+                        </TableHead>
+                        <TableHead numeric {...headProps('balance')}>
+                            Balance
+                        </TableHead>
+                    </TableRow>
+                </TableHeader>
+                <TableBody>
+                    {rows.length === 0 && <TableEmpty colSpan={4} />}
+                    {rows.map((p) => (
+                        <TableRow key={p.month}>
+                            <TableCell>{p.month}</TableCell>
+                            <TableCell numeric>{money(p.principal)}</TableCell>
+                            <TableCell numeric className="text-muted-foreground">
+                                {money(p.interest)}
+                            </TableCell>
+                            <TableCell numeric>{money(p.balance)}</TableCell>
+                        </TableRow>
+                    ))}
+                </TableBody>
+            </Table>
+        </TableContainer>
+    );
+}
+```
+
+### Reorder
+
+```tsx
+import {
+    flattenTree,
+    SortableHandle,
+    SortableItem,
+    type SortableNode,
+    SortableTree,
+    Table,
+    TableBody,
+    TableCell,
+    TableContainer,
+    TableHead,
+    TableHeader,
+    TableRow,
+} from '@rinzai/zen';
+import { useState } from 'react';
+// Icons from Heroicons (https://heroicons.com): ChevronRightMicro (chevron-right).
+
+const NAMES: Record<string, string> = {
+    home: 'Home',
+    rent: 'Rent',
+    power: 'Electricity',
+    internet: 'Internet',
+    food: 'Food',
+    groceries: 'Groceries',
+    dining: 'Eating out',
+    coffee: 'Coffee',
+    takeaway: 'Takeaway',
+};
+
+const AMOUNTS: Record<string, number[]> = {
+    rent: [1800, 1800, 1800, 1800],
+    power: [92, 88, 75, 70],
+    internet: [60, 60, 60, 60],
+    groceries: [420, 395, 410, 430],
+    dining: [180, 150, 210, 160],
+    coffee: [42, 38, 45, 40],
+    takeaway: [64, 50, 80, 55],
+};
+
+const MONTHS = ['Jul', 'Aug', 'Sep', 'Oct'];
+const CATEGORIES = new Set(['home', 'food']);
+
+/**
+ * Rows reordered by drag and drop (SortableTree, with asChild on the table and
+ * its rows). Drag a row by its grip within its category, into the other one,
+ * into an open sub-item (Eating out), or under another row (drag sideways a
+ * level in or out); or Tab to a grip and use Space and the arrow keys.
+ * Categories stay at the top level and can be reordered too. The first column
+ * stays in view as it scrolls sideways.
+ */
+export default function Reorder() {
+    const [tree, setTree] = useState<SortableNode[]>([
+        { id: 'home', children: [{ id: 'rent' }, { id: 'power' }, { id: 'internet' }] },
+        {
+            id: 'food',
+            children: [{ id: 'groceries' }, { id: 'dining', children: [{ id: 'coffee' }, { id: 'takeaway' }] }],
+        },
+    ]);
+    const [closed, setClosed] = useState(new Set<string>());
+    const toggle = (id: string) =>
+        setClosed((now) => {
+            const next = new Set(now);
+            if (!next.delete(id)) next.add(id);
+            return next;
+        });
+    const childrenOf = (id: string, nodes = tree): SortableNode[] | undefined => {
+        for (const node of nodes) {
+            if (node.id === id) return node.children;
+            const found = node.children && childrenOf(id, node.children);
+            if (found) return found;
+        }
+    };
+    return (
+        <TableContainer label="Planner" className="w-full max-w-xl">
+            <SortableTree
+                asChild
+                value={tree}
+                onValueChange={setTree}
+                accepts={(id, parent) => (CATEGORIES.has(id) ? parent === null : parent !== null)}
+            >
+                <Table className="min-w-[36rem]">
+                    <TableHeader>
+                        <TableRow>
+                            <TableHead sticky="start">Item</TableHead>
+                            {MONTHS.map((m) => (
+                                <TableHead key={m} numeric>
+                                    {m}
+                                </TableHead>
+                            ))}
+                        </TableRow>
+                    </TableHeader>
+                    <TableBody>
+                        {flattenTree(tree, (id) => !closed.has(id)).map(({ id, depth }) => {
+                            const category = CATEGORIES.has(id);
+                            const kids = childrenOf(id);
+                            return (
+                                <SortableItem key={id} id={id} label={NAMES[id]} asChild>
+                                    <TableRow>
+                                        <TableCell sticky="start" className="py-1.5">
+                                            <span
+                                                className="flex items-center gap-1"
+                                                style={{ paddingInlineStart: Math.max(0, depth - 1) * 24 }}
+                                            >
+                                                <SortableHandle id={id} label={NAMES[id]} />
+                                                {!category && kids?.length ? (
+                                                    <button
+                                                        type="button"
+                                                        aria-expanded={!closed.has(id)}
+                                                        aria-label={NAMES[id]}
+                                                        onClick={() => toggle(id)}
+                                                        className="text-muted-foreground hover:text-foreground -ms-1 grid size-6 cursor-pointer place-items-center rounded-md"
+                                                    >
+                                                        <ChevronRightMicro
+                                                            className={`size-4 transition-transform rtl:-scale-x-100 ${closed.has(id) ? '' : 'rotate-90'}`}
+                                                        />
+                                                    </button>
+                                                ) : null}
+                                                <span
+                                                    className={
+                                                        category
+                                                            ? 'text-muted-foreground text-xs font-medium tracking-wide uppercase'
+                                                            : ''
+                                                    }
+                                                >
+                                                    {NAMES[id]}
+                                                </span>
+                                            </span>
+                                        </TableCell>
+                                        {MONTHS.map((m, i) => (
+                                            <TableCell key={m} numeric className="py-1.5">
+                                                {AMOUNTS[id] ? `$${AMOUNTS[id][i]}` : ''}
+                                            </TableCell>
+                                        ))}
+                                    </TableRow>
+                                </SortableItem>
+                            );
+                        })}
+                    </TableBody>
+                </Table>
+            </SortableTree>
+        </TableContainer>
+    );
+}
+```
+
+### Selectable
+
+```tsx
+import {
+    Button,
+    SelectionBar,
+    Table,
+    TableBody,
+    TableCell,
+    TableContainer,
+    TableHead,
+    TableHeader,
+    TableRow,
+    TableSelectCell,
+    TableSelectHead,
+    useSelection,
+} from '@rinzai/zen';
+import { useState } from 'react';
+
+const ENTRIES = [
+    { id: 1, label: 'Weekly shop', amount: '−$165' },
+    { id: 2, label: 'Farmers market', amount: '−$42' },
+    { id: 3, label: 'Train pass', amount: '−$92' },
+    { id: 4, label: 'Dinner with Sam', amount: '−$78' },
+    { id: 5, label: 'Birthday lunch', amount: '−$92' },
+];
+
+/** Pick rows (shift-click for a run of them), then act on them all from the bar. */
+export default function Selectable() {
+    const [entries, setEntries] = useState(ENTRIES);
+    const selection = useSelection(entries.map((e) => e.id));
+    return (
+        <>
+            <TableContainer label="Entries" className="w-full max-w-lg">
+                <Table>
+                    <TableHeader>
+                        <TableRow>
+                            <TableSelectHead {...selection.allProps()} />
+                            <TableHead>Entry</TableHead>
+                            <TableHead numeric>Amount</TableHead>
+                        </TableRow>
+                    </TableHeader>
+                    <TableBody>
+                        {entries.map((e) => (
+                            <TableRow key={e.id} selected={selection.selected.has(e.id)}>
+                                <TableSelectCell label={`Select ${e.label}`} {...selection.rowProps(e.id)} />
+                                <TableCell>{e.label}</TableCell>
+                                <TableCell numeric>{e.amount}</TableCell>
+                            </TableRow>
+                        ))}
+                    </TableBody>
+                </Table>
+            </TableContainer>
+            <SelectionBar count={selection.selected.size} onClear={selection.clear}>
+                <Button
+                    size="sm"
+                    tone="negative"
+                    onClick={() => setEntries((es) => es.filter((e) => !selection.selected.has(e.id)))}
+                >
+                    Delete
+                </Button>
+                {entries.length < ENTRIES.length && (
+                    <Button size="sm" variant="ghost" onClick={() => setEntries(ENTRIES)}>
+                        Restore all
+                    </Button>
+                )}
+            </SelectionBar>
+        </>
+    );
+}
+```
+
+### Swipe
+
+```tsx
+import {
+    Button,
+    Table,
+    TableBody,
+    TableCell,
+    TableContainer,
+    TableHead,
+    TableHeader,
+    TableRow,
+    TableSwipeAction,
+    TableSwipeRow,
+} from '@rinzai/zen';
+import { useState } from 'react';
+
+const ENTRIES = [
+    { id: 1, label: 'Weekly shop', amount: '−$165' },
+    { id: 2, label: 'Farmers market', amount: '−$42' },
+    { id: 3, label: 'Train pass', amount: '−$92' },
+    { id: 4, label: 'Dinner with Sam', amount: '−$78' },
+];
+
+/** On a phone, swipe a row left for its actions; with a keyboard, tab to them. */
+export default function Swipe() {
+    const [entries, setEntries] = useState(ENTRIES);
+    return (
+        <div className="flex w-full max-w-lg flex-col gap-3">
+            <TableContainer label="Entries">
+                <Table>
+                    <TableHeader>
+                        <TableRow>
+                            <TableHead>Entry</TableHead>
+                            <TableHead numeric>Amount</TableHead>
+                        </TableRow>
+                    </TableHeader>
+                    <TableBody>
+                        {entries.map((e) => (
+                            <TableSwipeRow
+                                key={e.id}
+                                actions={
+                                    <TableSwipeAction
+                                        tone="negative"
+                                        aria-label={`Delete ${e.label}`}
+                                        onClick={() => setEntries((es) => es.filter((x) => x.id !== e.id))}
+                                    >
+                                        Delete
+                                    </TableSwipeAction>
+                                }
+                            >
+                                <TableCell>{e.label}</TableCell>
+                                <TableCell numeric>{e.amount}</TableCell>
+                            </TableSwipeRow>
+                        ))}
+                    </TableBody>
+                </Table>
+            </TableContainer>
+            {entries.length < ENTRIES.length && (
+                <Button variant="ghost" className="self-start" onClick={() => setEntries(ENTRIES)}>
+                    Bring them back
+                </Button>
+            )}
+        </div>
+    );
+}
+```
+
+### Detail
+
+```tsx
+import {
+    Button,
+    Card,
+    CardDescription,
+    CardHeader,
+    CardTitle,
+    Table,
+    TableBody,
+    TableCell,
+    TableContainer,
+    TableHead,
+    TableHeader,
+    TableRow,
+} from '@rinzai/zen';
+import { startTransition, useState, ViewTransition } from 'react';
+
+const ENTRIES = [
+    {
+        id: 'shop',
+        label: 'Weekly shop',
+        amount: '−$165.20',
+        date: 'Oct 4',
+        category: 'Groceries',
+        note: 'Market and bakery.',
+    },
+    {
+        id: 'train',
+        label: 'Train pass',
+        amount: '−$92.00',
+        date: 'Oct 2',
+        category: 'Transport',
+        note: 'Monthly pass.',
+    },
+    { id: 'pay', label: 'Salary', amount: '+$4,200.00', date: 'Oct 1', category: 'Income', note: 'October.' },
+];
+
+/** Open an entry and its row grows into its details (a view transition, with share="zen-morph"). */
+export default function Detail() {
+    const [open, setOpen] = useState<string | null>(null);
+    const go = (id: string | null) => startTransition(() => setOpen(id));
+    const entry = ENTRIES.find((e) => e.id === open);
+
+    if (entry)
+        return (
+            <ViewTransition name={`entry-${entry.id}`} share="zen-morph">
+                <Card className="w-full max-w-lg">
+                    <CardHeader>
+                        <CardTitle>{entry.label}</CardTitle>
+                        <Button size="sm" variant="ghost" onClick={() => go(null)}>
+                            Back
+                        </Button>
+                    </CardHeader>
+                    <p className="text-3xl font-semibold tabular-nums">{entry.amount}</p>
+                    <CardDescription className="mt-1">
+                        {entry.date} · {entry.category}
+                    </CardDescription>
+                    <p className="mt-4 text-sm">{entry.note}</p>
+                </Card>
+            </ViewTransition>
+        );
+
+    return (
+        <TableContainer label="Entries" className="w-full max-w-lg">
+            <Table>
+                <TableHeader>
+                    <TableRow>
+                        <TableHead>Entry</TableHead>
+                        <TableHead>Date</TableHead>
+                        <TableHead numeric>Amount</TableHead>
+                    </TableRow>
+                </TableHeader>
+                <TableBody className="rise-list">
+                    {ENTRIES.map((e) => (
+                        <ViewTransition key={e.id} name={`entry-${e.id}`} share="zen-morph">
+                            <TableRow onClick={() => go(e.id)} className="cursor-pointer">
+                                <TableCell>
+                                    <button
+                                        type="button"
+                                        onClick={() => go(e.id)}
+                                        className="text-left outline-hidden focus-visible:underline"
+                                    >
+                                        {e.label}
+                                    </button>
+                                </TableCell>
+                                <TableCell className="text-muted-foreground">{e.date}</TableCell>
+                                <TableCell numeric>{e.amount}</TableCell>
+                            </TableRow>
+                        </ViewTransition>
+                    ))}
+                </TableBody>
+            </Table>
+        </TableContainer>
+    );
+}
+```
+
+### Virtual
+
+```tsx
+import {
+    formatMoney,
+    Table,
+    TableBody,
+    TableCell,
+    TableContainer,
+    TableHead,
+    TableHeader,
+    TableRow,
+    TableSpacerRow,
+    useVirtualList,
+} from '@rinzai/zen';
+import { useRef } from 'react';
+
+const ROW_HEIGHT = 40;
+const PAYEES = ['Grocer', 'Metro', 'Landlord', 'Cafe', 'Pharmacy', 'Bookshop', 'Cinema', 'Utilities'];
+
+// 10,000 transactions, generated.
+const ROWS = Array.from({ length: 10000 }, (_, i) => ({
+    id: i + 1,
+    date: new Date(2026, 0, 1 + Math.floor(i / 28)).toLocaleDateString('en-US', { month: 'short', day: 'numeric' }),
+    payee: PAYEES[(i * 7) % PAYEES.length],
+    amount: ((i * 7919) % 20000) + 150,
+}));
+
+/** 10,000 rows, but only the ones in view (plus a few either side) are rendered: useVirtualList with spacer rows. */
+export default function Virtual() {
+    const scrollRef = useRef<HTMLDivElement>(null);
+    const rows = useVirtualList({ count: ROWS.length, itemHeight: ROW_HEIGHT, scrollRef, overscan: 8 });
+    return (
+        <TableContainer ref={scrollRef} label="Transactions" className="h-96 w-full max-w-xl">
+            <Table>
+                <TableHeader>
+                    <TableRow>
+                        <TableHead numeric className="w-20">
+                            #
+                        </TableHead>
+                        <TableHead>Date</TableHead>
+                        <TableHead>Payee</TableHead>
+                        <TableHead numeric>Amount</TableHead>
+                    </TableRow>
+                </TableHeader>
+                <TableBody>
+                    <TableSpacerRow height={rows.paddingTop} colSpan={4} />
+                    {rows.items.map(({ index }) => {
+                        const r = ROWS[index];
+                        return (
+                            <TableRow key={r.id}>
+                                <TableCell numeric className="text-muted-foreground h-10 py-0">
+                                    {r.id}
+                                </TableCell>
+                                <TableCell className="h-10 py-0">{r.date}</TableCell>
+                                <TableCell className="h-10 py-0">{r.payee}</TableCell>
+                                <TableCell numeric className="h-10 py-0">
+                                    {formatMoney(r.amount, 'USD', 'en-US')}
+                                </TableCell>
+                            </TableRow>
+                        );
+                    })}
+                    <TableSpacerRow height={rows.paddingBottom} colSpan={4} />
+                </TableBody>
+            </Table>
+        </TableContainer>
+    );
+}
+```
+
+## API reference
+
+### TableContainer
+
+The panel a table scrolls in: glass with an edge that catches the pointer
+light, like a Card. Give it a max height (className) to scroll vertically;
+it scrolls sideways when the table is wider. `ref` and scroll events are the
+scrolling element's. With `label`, it's a focusable region, so keyboard users
+can scroll it too.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `label` | `string` |  | Accessible name; makes the scroll area a focusable region. |
+
+### Table
+
+The <table>. Put it in a TableContainer for the panel and scrolling.
+
+No props of its own; it accepts the props of the element it renders.
+
+### TableHead
+
+Column heading: small spaced caps (TableHeader keeps the row at the top). With `onSort`, it's a
+button that shows the direction and announces it (aria-sort).
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `numeric` | `boolean` |  | Aligned to the end, for numbers. |
+| `onSort` | `(() => void)` |  | Makes the heading a sort button. |
+| `sortDirection` | `SortDirection` |  |  |
+| `sticky` | `"start"` |  | Stay in view when the table scrolls sideways. |
+
+### TableCell
+
+A cell: hairline below, lit with its row on hover. `sticky="start"` keeps it in view when scrolling sideways.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `numeric` | `boolean` |  | Aligned to the end, tabular digits. |
+| `sticky` | `"start"` |  | Stay in view when the table scrolls sideways. |
+
+### TableFooter
+
+Rows that stay at the bottom while the body scrolls (totals, balances).
+
+No props of its own; it accepts the props of the element it renders.
+
+### TableFooterCell
+
+A footer cell: sits on the card, above a hairline. Use inside TableFooter.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `numeric` | `boolean` |  | Aligned to the end, tabular digits. |
+| `sticky` | `"start"` |  | Stay in view when the table scrolls sideways. |
+
+### TableSpacerRow
+
+An empty row of a given height, standing in for rows scrolled out of view (see useVirtualList).
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `colSpan` (required) | `number` |  |  |
+| `height` (required) | `number` |  |  |
+
+### TableSelectCell
+
+A row's checkbox cell; spread `rowProps(key)` from useSelection into it.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `checked` (required) | `boolean` |  |  |
+| `label` (required) | `string` |  | The checkbox's name, e.g. "Select Rent". |
+| `onSelect` (required) | `(on: boolean, range: boolean) => void` |  | With `range` when shift was held. |
+
+### TableSelectHead
+
+The header's checkbox, for every row at once; spread `allProps()` from useSelection into it.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `checked` (required) | `boolean` |  |  |
+| `indeterminate` (required) | `boolean` |  |  |
+| `onSelect` (required) | `(on: boolean) => void` |  |  |
+| `label` | `string` |  |  |
+
+### SelectionBar
+
+What to do with the selected rows: their count, your actions, and a × to
+clear the selection. Floats at the bottom of the screen while any are
+selected (move it with className).
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `count` (required) | `number` |  |  |
+| `onClear` (required) | `() => void` |  |  |
+| `children` | `ReactNode` |  | The actions, e.g. buttons to delete or re-tag them. |
+| `className` | `string` |  |  |
+| `clearLabel` | `string` |  |  |
+| `label` | `((count: number) => string)` |  | The count as text (default "3 selected"). |
+
+### TableSwipeRow
+
+A row whose actions sit behind it at its end: swipe it left to reveal them
+(right, in right-to-left layouts), back (or tap the row) to put them away. They also come out when focused, so the
+keyboard reaches them. Use it in a TableContainer.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `actions` (required) | `ReactNode` |  | What's behind the row: TableSwipeActions, e.g. Edit and Delete. |
+| `selected` | `boolean` |  |  |
+
+### TableSwipeAction
+
+One of a swipe row's actions: fills the row's height, flush with its end.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `tone` | `"default" \| "negative"` | `default` |  |