@rinzai/zen 0.14.0 → 0.15.0

package/dist/docs/marquee.md

@@ -0,0 +1,86 @@
+# Marquee
+
+One line of text cut off with an ellipsis, that scrolls to show the rest on hover or focus (of itself or of its row), or all the time. Only text that doesn't fit moves.
+
+```tsx
+import { Marquee } from '@rinzai/zen';
+```
+
+## Examples
+
+### Default
+
+```tsx
+import { Marquee } from '@rinzai/zen';
+
+const TRACKS = [
+    { title: 'Glass Aurora', artist: 'Halcyon Drift' },
+    {
+        title: 'The Long Way Home Through the Harbour Lights (Extended Night Mix)',
+        artist: 'Mira Vale and the Quiet Hours Orchestra',
+    },
+    { title: 'Paper Moons', artist: 'Mira Vale' },
+];
+
+/**
+ * Hover a row, or Tab to it: names too long for it scroll, the rest stay put.
+ * `data-zen-marquee-host` makes the whole row the trigger.
+ */
+export default function Default() {
+    return (
+        <ul className="flex w-72 flex-col gap-1">
+            {TRACKS.map((t) => (
+                <li key={t.title}>
+                    <a
+                        href="#play"
+                        data-zen-marquee-host
+                        onClick={(e) => e.preventDefault()}
+                        className="focus-ring hover:bg-tint/[0.06] flex flex-col rounded-lg px-3 py-2"
+                    >
+                        <Marquee className="text-sm font-medium">{t.title}</Marquee>
+                        <Marquee className="text-muted-foreground text-xs">{t.artist}</Marquee>
+                    </a>
+                </li>
+            ))}
+        </ul>
+    );
+}
+```
+
+### Always
+
+```tsx
+import { Marquee } from '@rinzai/zen';
+
+/** `trigger="always"` keeps it moving, for what's playing: to the end, a pause, and back. */
+export default function Always() {
+    return (
+        <div className="border-tint/10 flex w-56 items-center gap-3 rounded-xl border p-3">
+            <div className="from-primary size-10 shrink-0 rounded-md bg-linear-135 to-fuchsia-400" />
+            <div className="min-w-0">
+                <Marquee trigger="always" className="text-sm font-medium">
+                    The Long Way Home Through the Harbour Lights
+                </Marquee>
+                <Marquee trigger="always" className="text-muted-foreground text-xs">
+                    Mira Vale
+                </Marquee>
+            </div>
+        </div>
+    );
+}
+```
+
+## API reference
+
+### Marquee
+
+One line of text that's cut off with an ellipsis, and scrolls to show the
+rest: to the end, a pause, and back. Only text that doesn't fit moves.
+With `trigger="hover"` (the default) it moves while it, or the closest
+element marked `data-zen-marquee-host` (a row, a tile, a link), is hovered
+or holds focus; `"always"` keeps it moving, e.g. for what's playing. Stays
+an ellipsis for reduced motion. Set the type and colour with className.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `trigger` | `"always" \| "hover"` | `hover` | `'hover'` (default): moves while it or its `data-zen-marquee-host` is hovered or focused. `'always'`: keeps moving. |

package/dist/docs/menu.md

@@ -0,0 +1,403 @@
+# Menu
+
+A button that opens a menu, or a context menu from a right-click or long press, with your own trigger, a header, icons, groups, destructive items, checkbox and radio items, submenus, and a menubar of menus.
+
+```tsx
+import { Menu, MenuTrigger, MenuContextTrigger, MenuContent, MenuItem, MenuCheckboxItem, MenuRadioGroup, MenuRadioItem, MenuSub, MenuSubTrigger, MenuSubContent, MenuSeparator, MenuHeader, Menubar } from '@rinzai/zen';
+```
+
+## Examples
+
+### Account
+
+```tsx
+import { Avatar, Menu, MenuContent, MenuHeader, MenuItem, MenuSeparator, MenuTrigger, useToast } from '@rinzai/zen';
+// Icons from Heroicons (https://heroicons.com): Lock (lock-closed), Logout (arrow-right-start-on-rectangle), Settings (cog-6-tooth).
+
+/** Your own trigger (an avatar), a header that isn't a choice, icons, groups, and a destructive item. */
+export default function Account() {
+    const toast = useToast();
+    const email = 'rin@example.com';
+    return (
+        <Menu>
+            <MenuTrigger
+                aria-label="Account menu"
+                className="focus-visible:ring-ring/50 data-popup-open:ring-ring/40 rounded-full outline-hidden transition-transform duration-200 hover:scale-105 focus-visible:ring-2 data-popup-open:ring-2"
+            >
+                <Avatar name={email} />
+            </MenuTrigger>
+            <MenuContent offset={10} className="w-64 shadow-[0_20px_60px_-20px_oklch(0_0_0/0.8)]">
+                <MenuHeader>
+                    <Avatar name={email} className="size-10" />
+                    <div className="min-w-0">
+                        <div className="text-muted-foreground text-xs">Signed in as</div>
+                        <div className="truncate text-sm font-medium" title={email}>
+                            {email}
+                        </div>
+                    </div>
+                </MenuHeader>
+                <MenuSeparator />
+                <MenuItem icon={<Settings className="size-4" />} onSelect={() => toast('Settings')}>
+                    Settings
+                </MenuItem>
+                <MenuItem icon={<Lock className="size-4" />} onSelect={() => toast('Locked', { tone: 'positive' })}>
+                    Lock now
+                </MenuItem>
+                <MenuSeparator />
+                <MenuItem tone="negative" icon={<Logout className="size-4" />} onSelect={() => toast('Logged out')}>
+                    Log out
+                </MenuItem>
+            </MenuContent>
+        </Menu>
+    );
+}
+```
+
+### Actions
+
+```tsx
+import { buttonVariants, Menu, MenuContent, MenuItem, MenuTrigger, useToast } from '@rinzai/zen';
+// Icons from Heroicons (https://heroicons.com): Ellipsis (ellipsis-horizontal).
+
+/** The usual "⋯" menu of actions for one thing: an icon button as the trigger, and a destructive item last. */
+export default function Actions() {
+    const toast = useToast();
+    return (
+        <Menu>
+            <MenuTrigger aria-label="Goal actions" className={buttonVariants({ variant: 'ghost', size: 'icon' })}>
+                <Ellipsis />
+            </MenuTrigger>
+            <MenuContent>
+                <MenuItem onSelect={() => toast('Edit')}>Edit</MenuItem>
+                <MenuItem onSelect={() => toast('Duplicated', { tone: 'positive' })}>Duplicate</MenuItem>
+                <MenuItem tone="negative" onSelect={() => toast('Deleted', { tone: 'negative' })}>
+                    Delete
+                </MenuItem>
+            </MenuContent>
+        </Menu>
+    );
+}
+```
+
+### Context
+
+```tsx
+import { Menu, MenuContent, MenuContextTrigger, MenuItem, MenuSeparator, useToast } from '@rinzai/zen';
+import { useState } from 'react';
+
+const ENTRIES = [
+    { id: 1, label: 'Weekly shop', amount: '−$165' },
+    { id: 2, label: 'Train pass', amount: '−$92' },
+    { id: 3, label: 'Salary', amount: '+$4,200' },
+];
+
+/** Right-click an entry (or press and hold on a phone) for its actions. One menu serves the whole list. */
+export default function Context() {
+    const toast = useToast();
+    const [entry, setEntry] = useState(ENTRIES[0]);
+    return (
+        <Menu>
+            <ul className="glass glow-edge divide-tint/[0.06] w-full max-w-sm divide-y rounded-xl">
+                {ENTRIES.map((e) => (
+                    <MenuContextTrigger
+                        key={e.id}
+                        asChild
+                        onContextMenu={() => setEntry(e)}
+                        onPointerDown={() => setEntry(e)}
+                    >
+                        <li
+                            tabIndex={0}
+                            className="focus-visible:ring-ring/40 data-popup-open:bg-primary/12 flex justify-between px-4 py-3 text-sm outline-hidden transition-colors select-none first:rounded-t-xl last:rounded-b-xl focus-visible:ring-2"
+                        >
+                            <span>{e.label}</span>
+                            <span className="tabular-nums">{e.amount}</span>
+                        </li>
+                    </MenuContextTrigger>
+                ))}
+            </ul>
+            <MenuContent aria-label={`${entry.label} actions`}>
+                <MenuItem onSelect={() => toast(`Editing ${entry.label}`)}>Edit</MenuItem>
+                <MenuItem onSelect={() => toast(`Duplicated ${entry.label}`, { tone: 'positive' })}>Duplicate</MenuItem>
+                <MenuSeparator />
+                <MenuItem tone="negative" onSelect={() => toast(`Deleted ${entry.label}`, { tone: 'negative' })}>
+                    Delete
+                </MenuItem>
+            </MenuContent>
+        </Menu>
+    );
+}
+```
+
+### Options
+
+```tsx
+import {
+    buttonVariants,
+    Menu,
+    MenuCheckboxItem,
+    MenuContent,
+    MenuItem,
+    MenuRadioGroup,
+    MenuRadioItem,
+    MenuSeparator,
+    MenuSub,
+    MenuSubContent,
+    MenuSubTrigger,
+    MenuTrigger,
+    useToast,
+} from '@rinzai/zen';
+import { useState } from 'react';
+// Icons from Heroicons (https://heroicons.com): Settings (cog-6-tooth).
+
+/**
+ * Settings that stay put while you change them: checkbox items turn columns on
+ * and off, radio items pick the order, and a submenu holds the less used
+ * exports. Hover, or use the arrow keys, to open it.
+ */
+export default function Options() {
+    const toast = useToast();
+    const [sort, setSort] = useState('date');
+    return (
+        <Menu>
+            <MenuTrigger className={buttonVariants({ variant: 'outline' })}>
+                <Settings className="size-4" />
+                View
+            </MenuTrigger>
+            <MenuContent className="w-56">
+                <MenuCheckboxItem defaultChecked>Category</MenuCheckboxItem>
+                <MenuCheckboxItem defaultChecked>Account</MenuCheckboxItem>
+                <MenuCheckboxItem>Notes</MenuCheckboxItem>
+                <MenuSeparator />
+                <MenuRadioGroup aria-label="Sort by" value={sort} onValueChange={setSort}>
+                    <MenuRadioItem value="date">Newest first</MenuRadioItem>
+                    <MenuRadioItem value="amount">Largest first</MenuRadioItem>
+                </MenuRadioGroup>
+                <MenuSeparator />
+                <MenuSub>
+                    <MenuSubTrigger>Export</MenuSubTrigger>
+                    <MenuSubContent>
+                        <MenuItem onSelect={() => toast('Exported as CSV')}>CSV</MenuItem>
+                        <MenuItem onSelect={() => toast('Exported as PDF')}>PDF</MenuItem>
+                        <MenuItem onSelect={() => toast('Exported as JSON')}>JSON</MenuItem>
+                    </MenuSubContent>
+                </MenuSub>
+            </MenuContent>
+        </Menu>
+    );
+}
+```
+
+### Bar
+
+```tsx
+import {
+    Menu,
+    Menubar,
+    MenuCheckboxItem,
+    MenuContent,
+    MenuItem,
+    MenuRadioGroup,
+    MenuRadioItem,
+    MenuSeparator,
+    MenuSub,
+    MenuSubContent,
+    MenuSubTrigger,
+    MenuTrigger,
+    useToast,
+} from '@rinzai/zen';
+import { useState } from 'react';
+
+/**
+ * A row of menus, as at the top of an app. Tab to it once: ←→ move between
+ * the menus and ↓ opens one; with one open, ←→ go to the next and pointing at
+ * another label switches to it.
+ */
+export default function Bar() {
+    const toast = useToast();
+    const [period, setPeriod] = useState('month');
+    return (
+        <Menubar aria-label="Ledger">
+            <Menu>
+                <MenuTrigger>File</MenuTrigger>
+                <MenuContent>
+                    <MenuItem onSelect={() => toast('New entry')}>New entry</MenuItem>
+                    <MenuItem onSelect={() => toast('Imported')}>Import…</MenuItem>
+                    <MenuSub>
+                        <MenuSubTrigger>Export</MenuSubTrigger>
+                        <MenuSubContent>
+                            <MenuItem onSelect={() => toast('Exported as CSV')}>CSV</MenuItem>
+                            <MenuItem onSelect={() => toast('Exported as PDF')}>PDF</MenuItem>
+                        </MenuSubContent>
+                    </MenuSub>
+                </MenuContent>
+            </Menu>
+            <Menu>
+                <MenuTrigger>Edit</MenuTrigger>
+                <MenuContent>
+                    <MenuItem onSelect={() => toast('Undone')}>Undo</MenuItem>
+                    <MenuItem onSelect={() => toast('Redone')}>Redo</MenuItem>
+                    <MenuSeparator />
+                    <MenuItem tone="negative" onSelect={() => toast('Deleted', { tone: 'negative' })}>
+                        Delete entry
+                    </MenuItem>
+                </MenuContent>
+            </Menu>
+            <Menu>
+                <MenuTrigger>View</MenuTrigger>
+                <MenuContent className="w-52">
+                    <MenuRadioGroup aria-label="Period" value={period} onValueChange={setPeriod}>
+                        <MenuRadioItem value="week">Week</MenuRadioItem>
+                        <MenuRadioItem value="month">Month</MenuRadioItem>
+                        <MenuRadioItem value="year">Year</MenuRadioItem>
+                    </MenuRadioGroup>
+                    <MenuSeparator />
+                    <MenuCheckboxItem defaultChecked>Show categories</MenuCheckboxItem>
+                </MenuContent>
+            </Menu>
+        </Menubar>
+    );
+}
+```
+
+## API reference
+
+### Menu
+
+A list of actions that opens from a button: a native popover, so outside
+clicks and Escape close it and focus returns to the button. Arrow keys, Home
+and End move between items. Put a MenuTrigger (its content is yours: an icon,
+an avatar, a label) and a MenuContent inside; fill the content with MenuItem,
+MenuSeparator and MenuHeader. For a context menu, put a MenuContextTrigger
+around what it's for instead of a MenuTrigger.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `onOpenChange` | `((open: boolean) => void)` |  | Every open and close: the trigger, choosing an item, outside clicks, Escape. |
+
+### MenuTrigger
+
+The button that opens the menu (↓ or ↑ opens it at its first or last item).
+Give it an `aria-label` when it shows only an icon or avatar; the menu is
+named after it. In a Menubar it's one of the bar's items, and looks it. With
+`asChild`, your own button instead.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` |  | Put the trigger's props on your own button element instead of rendering one. |
+
+### MenuContextTrigger
+
+What a context menu is for, e.g. a row or a card: right-click (or the
+keyboard's menu key, or Shift+F10) opens the Menu where the pointer is, and
+so does a long press on a phone. While its menu is open it has
+`data-popup-open`, to show what the menu is for. With `asChild`, your own
+element instead of a div.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` |  | Put its props on your own element (the single child) instead of a div. |
+| `disabled` | `boolean` |  | Leave the browser's own context menu. |
+
+### MenuContent
+
+The menu panel: glass, below the button (above it if there's no room), lined
+up with its end edge by default (its start edge in a Menubar). A context menu opens from the pointer
+instead; name it with `aria-label`.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `align` | `"center" \| "end" \| "start"` |  | Which edge of the button the menu lines up with (default end; a context menu starts at the pointer), or centred on it. |
+| `offset` | `number` |  | Gap between the button and the menu, in px. |
+
+### MenuItem
+
+One choice in a Menu: closes the menu, then runs `onSelect`. An `icon` sits
+before the label (muted, or red with the label when `tone` is negative). With
+`asChild`, the item's role and styles go onto your own element instead, such
+as a router's Link.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` |  | Put the item's role and styles on the single child element (a link) instead of a button. |
+| `icon` | `ReactNode` |  | Shown before the label; size it yourself (e.g. size-4). |
+| `onSelect` | `(() => void)` |  | Runs after the menu closes. |
+| `tone` | `"default" \| "negative"` | `default` | `negative` for a destructive choice: red. |
+
+### MenuCheckboxItem
+
+A choice that's on or off, e.g. a column to show: choosing it flips
+`checked` and leaves the menu open, so several can be set at once. A tick
+shows while it's on.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `checked` | `boolean` |  | On (ticked); give it to control the item, or `defaultChecked` to start it. |
+| `defaultChecked` | `boolean` | `false` |  |
+| `onCheckedChange` | `((checked: boolean) => void)` |  |  |
+
+### MenuRadioGroup
+
+One choice out of several, e.g. how to sort: put MenuRadioItems inside. Choosing one leaves the menu open.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `defaultValue` | `string \| null` | `null` |  |
+| `onValueChange` | `((value: string) => void)` |  |  |
+| `value` | `string \| null` |  | The chosen item's `value`; give it to control the group, or `defaultValue` to start it. |
+
+### MenuRadioItem
+
+One of a MenuRadioGroup's choices; a dot marks the chosen one.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` (required) | `string` |  |  |
+
+### MenuSub
+
+A menu inside a menu, opening beside its item: on hover, or with Enter,
+Space or the arrow towards it; the arrow back (or Escape) closes it. Put a
+MenuSubTrigger and a MenuSubContent inside, in a MenuContent.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `onOpenChange` | `((open: boolean) => void)` |  | Every open and close: the trigger, choosing an item, outside clicks, Escape. |
+
+### MenuSubTrigger
+
+The item a submenu opens from; a chevron after its label points the way.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `icon` | `ReactNode` |  | Shown before the label; size it yourself (e.g. size-4). |
+
+### MenuSubContent
+
+The submenu's panel, beside its item (on the other side if there's no room), its first item level with it.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `offset` | `number` | `8` | Gap between the item and the submenu, in px (counting the menu's own padding). |
+
+### MenuSeparator
+
+A hairline between groups of items.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className` | `string` |  |  |
+
+### MenuHeader
+
+Content at the top of a menu that isn't a choice, e.g. who is signed in.
+
+No props of its own; it accepts the props of the element it renders.
+
+### Menubar
+
+A row of menus, as at the top of an app (File, Edit, View): put a Menu for
+each inside, its MenuTrigger a label. One Tab stop: ←→ move between the
+menus, ↓ or Enter opens one; while one is open, ←→ open the one beside it
+and pointing at another switches to it. Name it with `aria-label`.
+
+No props of its own; it accepts the props of the element it renders.

package/dist/docs/meter.md

@@ -0,0 +1,102 @@
+# Meter
+
+A measure against a limit, like spend against a budget: warm near it, red past it.
+
+```tsx
+import { Meter } from '@rinzai/zen';
+```
+
+## Examples
+
+### Budget
+
+```tsx
+import { formatMoney, Meter } from '@rinzai/zen';
+
+const inr = (paise: number) => formatMoney(paise, 'INR', 'en-IN', { showDecimals: false });
+
+/** Spend against a budget: the bar warms near the limit and turns red past it. */
+export default function Budget() {
+    const budgets = [
+        { label: 'Groceries', spent: 620000, budget: 1000000 },
+        { label: 'Dining out', spent: 270000, budget: 300000 },
+        { label: 'Transport', spent: 410000, budget: 350000 },
+    ];
+    return (
+        <div className="flex w-80 flex-col gap-5">
+            {budgets.map(({ label, spent, budget }) => {
+                const over = spent > budget;
+                const status = over ? `${inr(spent - budget)} over` : `${inr(budget - spent)} left`;
+                return (
+                    <Meter
+                        key={label}
+                        label={label}
+                        value={spent}
+                        max={budget}
+                        detail={`${inr(spent)} / ${inr(budget)}`}
+                        hint={status}
+                        valueText={`${inr(spent)} of ${inr(budget)}, ${status}`}
+                    />
+                );
+            })}
+        </div>
+    );
+}
+```
+
+### Milestones
+
+```tsx
+import { Button, formatMoney, Meter } from '@rinzai/zen';
+import { useState } from 'react';
+
+const money = (cents: number) => formatMoney(cents, 'USD', 'en-US', { showDecimals: false });
+
+/** A savings goal with milestones at each quarter: the ones passed are notched into the fill. */
+export default function Milestones() {
+    const [saved, setSaved] = useState(420000);
+    const goal = 1000000;
+    return (
+        <div className="flex w-full max-w-sm flex-col gap-4">
+            <Meter
+                label="Emergency fund"
+                value={saved}
+                max={goal}
+                marks={[goal / 4, goal / 2, (goal * 3) / 4]}
+                tone="default"
+                detail={`${money(saved)} / ${money(goal)}`}
+                hint={`${Math.floor((saved / goal) * 4)} of 4 milestones`}
+                valueText={`${money(saved)} of ${money(goal)}`}
+            />
+            <Button
+                variant="outline"
+                className="self-start"
+                onClick={() => setSaved((s) => Math.min(goal, s + 100000))}
+            >
+                Add $1,000
+            </Button>
+        </div>
+    );
+}
+```
+
+## API reference
+
+### Meter
+
+A measure against a limit, e.g. spend against a budget: a bar with a label,
+a figure and a note. Over the limit it turns red; near it, warm. Announced
+as a meter, with `valueText` read out instead of the bare number.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` (required) | `number` |  |  |
+| `className` | `string` |  |  |
+| `detail` | `ReactNode` |  | Top right, e.g. "₹8,200 / ₹10,000". |
+| `hint` | `ReactNode` |  | Below the bar, e.g. "₹1,800 left". |
+| `label` | `ReactNode` |  |  |
+| `marks` | `number[]` |  | Milestones along the bar, in the same units as value: e.g. [2500, 5000, 7500] of 10000. |
+| `max` | `number` | `100` | The limit (default 100). Values past it fill the bar and turn it red. |
+| `tone` | `"auto" \| "default" \| "negative" \| "warning"` | `auto` | `auto` picks warning past `warnAt` of max and negative past max. |
+| `valueText` | `string` |  | What screen readers say for the value, e.g. "₹8,200 of ₹10,000, ₹1,800 left". |
+| `warnAt` | `number` | `0.85` | Fraction of max where `auto` turns to warning (default 0.85). |