@rinzai/zen 0.14.0 → 0.15.0

package/dist/docs/dialog.md

@@ -0,0 +1,271 @@
+# Dialog
+
+Modal dialogs on the native <dialog> element, sheets that slide in from an edge, and a confirmation for destructive actions.
+
+```tsx
+import { Dialog, DialogFooter, DialogClose, ConfirmDialog } from '@rinzai/zen';
+```
+
+## Examples
+
+### Form
+
+```tsx
+import { Button, Dialog, DialogClose, DialogFooter, Input } from '@rinzai/zen';
+import { useState } from 'react';
+
+export default function Form() {
+    const [open, setOpen] = useState(false);
+    return (
+        <>
+            <Button onClick={() => setOpen(true)}>Rename</Button>
+            <Dialog
+                open={open}
+                onOpenChange={setOpen}
+                title="Rename category"
+                description="Entries in this category keep their history."
+            >
+                <label className="flex flex-col gap-2">
+                    Name
+                    <Input defaultValue="Groceries" />
+                </label>
+                <DialogFooter>
+                    <DialogClose variant="outline">Cancel</DialogClose>
+                    <DialogClose>Save</DialogClose>
+                </DialogFooter>
+            </Dialog>
+        </>
+    );
+}
+```
+
+### Sheets
+
+```tsx
+import { Button, Checkbox, Dialog, DialogClose, DialogFooter } from '@rinzai/zen';
+import { useState } from 'react';
+
+/** With side, a dialog slides in from an edge: a bottom sheet (phones) or a side panel (filters, details). */
+export default function Sheets() {
+    const [open, setOpen] = useState(false);
+    const [side, setSide] = useState<'bottom' | 'right'>('bottom');
+    const show = (from: 'bottom' | 'right') => {
+        setSide(from);
+        setOpen(true);
+    };
+    return (
+        <div className="flex flex-wrap gap-2">
+            <Button variant="outline" onClick={() => show('bottom')}>
+                Bottom sheet
+            </Button>
+            <Button variant="outline" onClick={() => show('right')}>
+                Side panel
+            </Button>
+            <Dialog
+                open={open}
+                onOpenChange={setOpen}
+                side={side}
+                title="Filters"
+                description="Show only what you need."
+            >
+                <div className="flex flex-col gap-3">
+                    <Checkbox defaultChecked>Income</Checkbox>
+                    <Checkbox defaultChecked>Spending</Checkbox>
+                    <Checkbox>Transfers</Checkbox>
+                </div>
+                <DialogFooter className="mt-auto">
+                    <DialogClose variant="ghost">Cancel</DialogClose>
+                    <DialogClose>Apply</DialogClose>
+                </DialogFooter>
+            </Dialog>
+        </div>
+    );
+}
+```
+
+### Pickers
+
+```tsx
+import {
+    Button,
+    Dialog,
+    DialogClose,
+    DialogFooter,
+    Combobox,
+    DatePicker,
+    ComboboxEmpty,
+    ComboboxList,
+    ComboboxPopup,
+    ComboboxSearch,
+    ComboboxTrigger,
+    MonthPicker,
+    Select,
+    SelectItem,
+    useToast,
+} from '@rinzai/zen';
+import { useState } from 'react';
+
+const CATEGORIES = [
+    { value: 'groceries', label: 'Groceries' },
+    { value: 'rent', label: 'Rent' },
+    { value: 'transport', label: 'Transport' },
+    { value: 'dining', label: 'Dining out' },
+] as const;
+const TAGS = ['Essential', 'Shared', 'Work', 'Treat'];
+const asText = (tag: string) => tag;
+
+/** Selects, pickers and menus open above the dialog, and toasts show over it (try Save draft). */
+export default function Pickers() {
+    const toast = useToast();
+    const [open, setOpen] = useState(false);
+    const [category, setCategory] = useState<(typeof CATEGORIES)[number]['value'] | null>('groceries');
+    const [month, setMonth] = useState<string | null>('2026-09');
+    const [start, setStart] = useState<string | null>('2026-09-30');
+    const [tags, setTags] = useState<string[]>([TAGS[0]]);
+    return (
+        <>
+            <Button onClick={() => setOpen(true)}>Add budget</Button>
+            <Dialog open={open} onOpenChange={setOpen} title="Add budget">
+                <div className="grid gap-3 sm:grid-cols-2">
+                    <label className="flex flex-col gap-2 text-sm">
+                        Category
+                        <Select aria-label="Category" value={category} onValueChange={setCategory}>
+                            {CATEGORIES.map((c) => (
+                                <SelectItem key={c.value} value={c.value}>
+                                    {c.label}
+                                </SelectItem>
+                            ))}
+                        </Select>
+                    </label>
+                    <label className="flex flex-col gap-2 text-sm">
+                        From
+                        <MonthPicker aria-label="From" value={month} onValueChange={setMonth} locale="en-IN" />
+                    </label>
+                </div>
+                <label className="flex flex-col gap-2 text-sm">
+                    Starts on
+                    <DatePicker aria-label="Starts on" value={start} onValueChange={setStart} locale="en-IN" />
+                </label>
+                <div className="flex flex-col gap-2 text-sm">
+                    <span>Tags</span>
+                    <Combobox
+                        multiple
+                        items={TAGS}
+                        itemKey={asText}
+                        itemText={asText}
+                        value={tags}
+                        onValueChange={setTags}
+                    >
+                        <ComboboxTrigger className="w-full" />
+                        <ComboboxPopup>
+                            <ComboboxSearch />
+                            <ComboboxList>
+                                <ComboboxEmpty />
+                            </ComboboxList>
+                        </ComboboxPopup>
+                    </Combobox>
+                </div>
+                <DialogFooter>
+                    <Button
+                        variant="ghost"
+                        className="mr-auto"
+                        onClick={() => toast('Draft saved', { tone: 'default' })}
+                    >
+                        Save draft
+                    </Button>
+                    <DialogClose variant="outline">Cancel</DialogClose>
+                    <DialogClose onClick={() => toast('Budget added', { tone: 'positive' })}>Add</DialogClose>
+                </DialogFooter>
+            </Dialog>
+        </>
+    );
+}
+```
+
+### Confirm
+
+```tsx
+import { Button, ConfirmDialog } from '@rinzai/zen';
+import { useState } from 'react';
+
+export default function Confirm() {
+    const [open, setOpen] = useState(false);
+    return (
+        <>
+            <Button tone="negative" onClick={() => setOpen(true)}>
+                Delete goal
+            </Button>
+            <ConfirmDialog
+                open={open}
+                onOpenChange={setOpen}
+                title="Delete this goal?"
+                description="Its progress history is removed too. This can't be undone."
+                confirmLabel="Delete"
+                tone="negative"
+                onConfirm={() => {}}
+            />
+        </>
+    );
+}
+```
+
+## API reference
+
+### Dialog
+
+Modal dialog on the native <dialog> element: focus is trapped and restored,
+the page behind is inert, and Escape closes it. `dismissible={false}` is for
+flows the user must finish (no Escape, outside-click or close button). With `side`,
+it's a sheet that slides in from that edge: a bottom sheet on phones, a side
+panel for filters or details. On touch, a sheet swipes back to its edge to close.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `open` (required) | `boolean` |  |  |
+| `title` (required) | `ReactNode` |  |  |
+| `closeLabel` | `string` |  | The close button's accessible name. |
+| `description` | `ReactNode` |  |  |
+| `dismissible` | `boolean` | `true` |  |
+| `initialFocus` | `RefObject<HTMLElement \| null>` |  | Element to focus when the dialog opens (default: the first focusable one). |
+| `onOpenChange` | `((open: boolean) => void)` |  |  |
+| `side` | `"bottom" \| "left" \| "right"` |  | Slide in from this edge as a sheet, instead of appearing in the middle. |
+| `size` | `"lg" \| "md"` | `md` | "lg" for dialogs holding a whole tool rather than a short form. |
+
+### DialogFooter
+
+The row of actions at the end of a dialog, right-aligned.
+
+No props of its own; it accepts the props of the element it renders.
+
+### DialogClose
+
+A button that closes its dialog (after its own onClick, unless that calls
+preventDefault). Takes every Button prop: variant, size, asChild…
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` |  | Put the button's styles on the single child element (e.g. a link) instead of a <button>. |
+| `loading` | `boolean` |  | 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` |  |  |
+
+### ConfirmDialog
+
+Confirmation for destructive or irreversible actions. Cancel has focus, so Enter is the safe choice.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `confirmLabel` (required) | `string` |  |  |
+| `onConfirm` (required) | `() => void` |  |  |
+| `onOpenChange` (required) | `(open: boolean) => void` |  |  |
+| `open` (required) | `boolean` |  |  |
+| `title` (required) | `ReactNode` |  |  |
+| `cancelLabel` | `string` |  |  |
+| `closeLabel` | `string` |  | The close button's accessible name. |
+| `description` | `ReactNode` |  |  |
+| `dismissible` | `boolean` |  |  |
+| `initialFocus` | `RefObject<HTMLElement \| null>` |  | Element to focus when the dialog opens (default: the first focusable one). |
+| `side` | `"bottom" \| "left" \| "right"` |  | Slide in from this edge as a sheet, instead of appearing in the middle. |
+| `size` | `"lg" \| "md"` |  | "lg" for dialogs holding a whole tool rather than a short form. |
+| `tone` | `"default" \| "negative"` | `default` | `negative` for a destructive action: the confirm button is red. |

package/dist/docs/disclosure.md

@@ -0,0 +1,88 @@
+# Disclosure
+
+A button that shows and hides a section, like finished goals under a list.
+
+```tsx
+import { Disclosure, DisclosureTrigger, DisclosureContent } from '@rinzai/zen';
+```
+
+## Examples
+
+### Default
+
+```tsx
+import { Card, CardHeader, CardTitle, Disclosure, DisclosureContent, DisclosureTrigger, Meter } from '@rinzai/zen';
+
+const ACTIVE = [
+    { name: 'New phone', saved: 42000, target: 60000 },
+    { name: 'Emergency fund', saved: 180000, target: 300000 },
+];
+const PAST = ['Laptop', 'Trip to Goa', 'Wedding gift'];
+
+/** Finished goals folded away under the active ones; the section grows open and folds shut. */
+export default function Default() {
+    return (
+        <Card className="w-full max-w-sm gap-4">
+            <CardHeader>
+                <CardTitle>Goals</CardTitle>
+            </CardHeader>
+            <ul className="flex flex-col gap-3 text-sm">
+                {ACTIVE.map((g) => (
+                    <li key={g.name} className="flex flex-col gap-1.5">
+                        <div className="flex justify-between">
+                            <span>{g.name}</span>
+                            <span className="text-muted-foreground tabular-nums">
+                                {Math.round((g.saved / g.target) * 100)}%
+                            </span>
+                        </div>
+                        <Meter value={g.saved} max={g.target} aria-label={g.name} />
+                    </li>
+                ))}
+            </ul>
+            <Disclosure>
+                <DisclosureTrigger className="mt-2">Past ({PAST.length})</DisclosureTrigger>
+                <DisclosureContent>
+                    <ul className="border-tint/[0.07] flex flex-col gap-2 border-l pl-4 text-sm">
+                        {PAST.map((g) => (
+                            <li key={g} className="text-muted-foreground flex items-center justify-between">
+                                {g}
+                                <span className="text-xs">Done</span>
+                            </li>
+                        ))}
+                    </ul>
+                </DisclosureContent>
+            </Disclosure>
+        </Card>
+    );
+}
+```
+
+## API reference
+
+### Disclosure
+
+A section that a button shows and hides, e.g. "Past (3)" under a list. Put
+a DisclosureTrigger and a DisclosureContent inside (it adds no element of its
+own). Opens and closes on its own, or follows `open`/`onOpenChange`.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `defaultOpen` | `boolean` | `false` |  |
+| `onOpenChange` | `((open: boolean) => void)` |  |  |
+| `open` | `boolean` |  | Show or hide it from your state; leave it out to let the trigger do it. |
+
+### DisclosureTrigger
+
+The button: your label after a chevron that turns down as the section opens. Brightens on hover and while open.
+
+No props of its own; it accepts the props of the element it renders.
+
+### DisclosureContent
+
+What the trigger shows and hides. It grows open and folds shut (the height
+animates, the content fades and settles). While closed it isn't rendered at
+all, so what's inside costs nothing and can't be found, focused or read; it
+mounts as it opens and unmounts once it has folded shut. className goes on
+the content itself.
+
+No props of its own; it accepts the props of the element it renders.

package/dist/docs/editable-cell.md

@@ -0,0 +1,90 @@
+# Editable Cell
+
+A value edited in place: shows the value, swaps in any editor on click or Enter.
+
+```tsx
+import { EditableCell } from '@rinzai/zen';
+```
+
+## Examples
+
+### Default
+
+```tsx
+import { EditableCell, formatMoney, Input, MoneyInput } from '@rinzai/zen';
+import { useState } from 'react';
+
+/** Click a value (or Tab to it and press Enter) to edit; Enter or blur saves, Escape cancels. */
+export default function Default() {
+    const [amount, setAmount] = useState<number | null>(1850000);
+    const [note, setNote] = useState('Due on the 5th');
+    return (
+        <div className="grid w-80 grid-cols-[auto_1fr] items-center gap-x-4 gap-y-2 text-sm">
+            <span className="text-muted-foreground">Rent</span>
+            <EditableCell
+                label={`Rent: ${amount === null ? 'none' : formatMoney(amount, 'INR', 'en-IN')}`}
+                editor={(close) => (
+                    <MoneyInput
+                        compact
+                        autoFocus
+                        allowEmpty
+                        aria-label="Rent"
+                        value={amount}
+                        currency="INR"
+                        locale="en-IN"
+                        onValueChange={(v) => {
+                            setAmount(v);
+                            close();
+                        }}
+                        onCancel={close}
+                    />
+                )}
+            >
+                {amount === null ? '–' : formatMoney(amount, 'INR', 'en-IN', { showDecimals: false })}
+            </EditableCell>
+            <span className="text-muted-foreground">Note</span>
+            <EditableCell
+                label={`Note: ${note}`}
+                className="text-left"
+                editor={(close) => (
+                    <Input
+                        autoFocus
+                        aria-label="Note"
+                        defaultValue={note}
+                        className="h-7"
+                        onBlur={(e) => {
+                            setNote(e.target.value);
+                            close();
+                        }}
+                        onKeyDown={(e) => {
+                            if (e.key === 'Enter') e.currentTarget.blur();
+                            if (e.key === 'Escape') close();
+                        }}
+                    />
+                )}
+            >
+                {note}
+            </EditableCell>
+        </div>
+    );
+}
+```
+
+## API reference
+
+### EditableCell
+
+A value edited in place, e.g. in a table cell: shows `children` as a button,
+and on click (or Enter) swaps in your editor. Call `close()` from the editor
+when it's done (committed or cancelled). Works with any editor: a compact
+MoneyInput, an Input, a Select. A value changed by an edit glows briefly
+when the editor closes.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` (required) | `ReactNode` |  | What the cell shows when not editing. |
+| `editor` (required) | `(close: () => void) => ReactNode` |  | The editor to show while editing; call `close` when it's done. |
+| `editing` | `boolean` |  | Control the editing state yourself (with onEditingChange). |
+| `label` | `string` |  | Accessible name of the value, e.g. "Rent, Oct 2026: ₹18,500"; " Edit" is added for the button. |
+| `onEditingChange` | `((editing: boolean) => void)` |  |  |
+| `readOnly` | `boolean` | `false` | Show the value without making it editable. |

package/dist/docs/empty-state.md

@@ -0,0 +1,46 @@
+# Empty State
+
+What a list or page shows when there's nothing in it yet, and the action that fills it.
+
+```tsx
+import { EmptyState } from '@rinzai/zen';
+```
+
+## Examples
+
+### Default
+
+```tsx
+import { Button, Card, EmptyState } from '@rinzai/zen';
+// Icons from Heroicons (https://heroicons.com): ListBullet (list-bullet).
+
+/** A month with no entries yet: what's missing, and the action that adds the first one. */
+export default function Default() {
+    return (
+        <Card className="w-full max-w-md">
+            <EmptyState
+                icon={<ListBullet />}
+                title="No entries this month"
+                description="Add your income and spending, or bring them in from a bank statement."
+            >
+                <Button>Add entry</Button>
+                <Button variant="outline">Import</Button>
+            </EmptyState>
+        </Card>
+    );
+}
+```
+
+## API reference
+
+### EmptyState
+
+What a list, table or page shows when there's nothing in it yet: an icon on
+a soft glow, a title, a line on what to do, and the action that does it
+(children, e.g. a Button).
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` (required) | `ReactNode` |  |  |
+| `description` | `ReactNode` |  |  |
+| `icon` | `ReactNode` |  | An icon, shown on the accent's glow. |

package/dist/docs/field.md

@@ -0,0 +1,82 @@
+# Field
+
+A label, hint and error wired to their control for screen readers, and messages for a whole form.
+
+```tsx
+import { Field, FormMessage } from '@rinzai/zen';
+```
+
+## Examples
+
+### Default
+
+```tsx
+import { Button, Field, FormMessage, Input } from '@rinzai/zen';
+import { FormEvent, useState } from 'react';
+
+/** Field links the label, hint and error to its control; FormMessage speaks for the whole form. */
+export default function Default() {
+    const [email, setEmail] = useState('');
+    const [submitted, setSubmitted] = useState(false);
+    const invalid = submitted && !email.includes('@');
+    return (
+        <form
+            className="flex w-80 flex-col gap-4"
+            noValidate
+            onSubmit={(e: FormEvent) => {
+                e.preventDefault();
+                setSubmitted(true);
+            }}
+        >
+            <Field
+                label="Email"
+                hint="We'll send a sign-in link."
+                error={invalid ? 'Enter an email address.' : undefined}
+            >
+                <Input
+                    type="email"
+                    value={email}
+                    onChange={(e) => setEmail(e.target.value)}
+                    placeholder="you@example.com"
+                />
+            </Field>
+            {submitted && !invalid && <FormMessage tone="positive">Check your inbox for the link.</FormMessage>}
+            <Button type="submit" className="self-start">
+                Send link
+            </Button>
+        </form>
+    );
+}
+```
+
+## API reference
+
+### Field
+
+A labelled form control with an optional hint and error. Links them for
+screen readers: the control gets an id (if it has none), aria-describedby
+for the hint or error, and aria-invalid while there's an error. The error
+shows in place of the hint until it's fixed.
+
+The direct child gets these as props. When the control sits inside other
+markup (e.g. an amount beside a unit select), give it an id and pass the
+same id as `htmlFor`: Zen's controls with that id pick them up themselves.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` (required) | `ReactNode` |  | One control (Input, Select, MoneyInput…), or anything else (then link it yourself). |
+| `label` (required) | `ReactNode` |  |  |
+| `className` | `string` |  |  |
+| `error` | `ReactNode` |  | Error under the control, in place of the hint; marks it invalid. |
+| `hint` | `ReactNode` |  | Help text under the control. |
+| `htmlFor` | `string` |  | The control's id, when it isn't the direct child (it's inside other markup). |
+
+### FormMessage
+
+A message for a form as a whole: an error or success in a tinted box, or a quiet note. An Alert, set for forms.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `icon` | `ReactNode` |  | Replaces the tone's icon (info, check, warning); `null` for none. |
+| `title` | `ReactNode` |  | A first line in the tone's colour; the text under it is quieter. |
+| `tone` | `"default" \| "negative" \| "positive"` | `default` |  |

package/dist/docs/file-drop.md

@@ -0,0 +1,44 @@
+# File Drop
+
+Somewhere to drop files, or click to choose them, that lights up as files are dragged over it.
+
+```tsx
+import { FileDrop } from '@rinzai/zen';
+```
+
+## Examples
+
+### Default
+
+```tsx
+import { FileDrop } from '@rinzai/zen';
+import { useState } from 'react';
+
+/** A bank statement to import: CSV or Excel, one at a time. */
+export default function Default() {
+    const [file, setFile] = useState<File>();
+    return (
+        <FileDrop accept=".csv,.xlsx" onFiles={([f]) => setFile(f)} className="w-full max-w-md">
+            <span className="text-foreground font-medium">{file ? file.name : 'Drop a statement here'}</span>
+            <span className="text-xs">
+                {file ? `${Math.ceil(file.size / 1024)} KB · choose another` : 'CSV or Excel, or click to choose'}
+            </span>
+        </FileDrop>
+    );
+}
+```
+
+## API reference
+
+### FileDrop
+
+Somewhere to drop files, or click (or press Enter) to choose them: it lights
+up while files are dragged over it. `onFiles` gets those that `accept` allows
+(one, unless `multiple`). Children are what it says, e.g. "Drop a CSV here".
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `onFiles` (required) | `(files: File[]) => void` |  |  |
+| `accept` | `string` |  | As an <input type="file">'s accept: ".csv,.xlsx", "image/*". Dropped files are held to it too. |
+| `disabled` | `boolean` | `false` |  |
+| `multiple` | `boolean` | `false` |  |

package/dist/docs/filter-bar.md

@@ -0,0 +1,66 @@
+# Filter Bar
+
+The filters in effect, each removed with its ×, and Clear all.
+
+```tsx
+import { FilterBar, FilterChip } from '@rinzai/zen';
+```
+
+## Examples
+
+### Default
+
+```tsx
+import { Button, FilterBar, FilterChip } from '@rinzai/zen';
+import { useState } from 'react';
+
+const ALL = { amount: 'Amount: $50–$500', category: 'Category: Dining out', tag: 'Tag: Shared' };
+type Key = keyof typeof ALL;
+
+/** The filters on a list of entries; remove one, or all at once. */
+export default function Default() {
+    const [on, setOn] = useState<Key[]>(['amount', 'category', 'tag']);
+    return (
+        <div className="flex min-h-16 w-full max-w-md flex-col items-start gap-3">
+            <FilterBar onClear={() => setOn([])}>
+                {on.map((key) => (
+                    <FilterChip
+                        key={key}
+                        onRemove={() => setOn((keys) => keys.filter((k) => k !== key))}
+                        removeLabel={`Remove ${key} filter`}
+                    >
+                        {ALL[key]}
+                    </FilterChip>
+                ))}
+            </FilterBar>
+            {on.length === 0 && (
+                <Button variant="outline" size="sm" onClick={() => setOn(['amount', 'category', 'tag'])}>
+                    Filter again
+                </Button>
+            )}
+        </div>
+    );
+}
+```
+
+## API reference
+
+### FilterBar
+
+The filters in effect, as chips each removed with its ×, and "Clear all"
+once there are two or more. Renders nothing when no filter is set.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `clearLabel` | `ReactNode` |  |  |
+| `onClear` | `(() => void)` |  | Removes every filter; shown as "Clear all" once there are two or more. |
+
+### FilterChip
+
+One filter in a FilterBar: what it is (e.g. "Amount: $50–$500"), and its × to remove it.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `onRemove` (required) | `() => void` |  |  |
+| `className` | `string` |  |  |
+| `removeLabel` | `string` |  | The × button's name for screen readers, e.g. "Remove amount filter". |