@rinzai/zen 0.13.0 → 0.15.0

package/dist/docs/combobox.md

@@ -0,0 +1,208 @@
+# Combobox
+
+Search and pick one or several items of any shape, composed from parts: field, panel, search, a virtualized list, empty and create rows.
+
+```tsx
+import { Combobox, ComboboxTrigger, ComboboxSearch, ComboboxList, ComboboxItem, ComboboxEmpty, ComboboxCreate } from '@rinzai/zen';
+```
+
+## Examples
+
+### Accounts
+
+```tsx
+import {
+    Combobox,
+    ComboboxEmpty,
+    ComboboxItem,
+    ComboboxList,
+    ComboboxPopup,
+    ComboboxSearch,
+    ComboboxTrigger,
+} from '@rinzai/zen';
+import { useState } from 'react';
+
+interface Account {
+    id: string;
+    name: string;
+    number: string;
+}
+
+const ACCOUNTS: Account[] = [
+    { id: 'chk', name: 'Everyday checking', number: '•• 4821' },
+    { id: 'sav', name: 'Rainy-day savings', number: '•• 0937' },
+    { id: 'crd', name: 'Travel credit card', number: '•• 1150' },
+    { id: 'brk', name: 'Brokerage', number: '•• 7302' },
+];
+
+/** Any shape of item (itemKey, itemText), your own rows, your own empty message. ↑↓ and Enter work in the search. */
+export default function Accounts() {
+    const [account, setAccount] = useState<string | null>('chk');
+    return (
+        <Combobox
+            items={ACCOUNTS}
+            itemKey={(a) => a.id}
+            itemText={(a) => a.name}
+            value={account}
+            onValueChange={setAccount}
+        >
+            <ComboboxTrigger aria-label="Account" placeholder="Pick an account" className="w-72" />
+            <ComboboxPopup>
+                <ComboboxSearch placeholder="Search accounts" />
+                <ComboboxList<Account>
+                    renderItem={(a) => (
+                        <ComboboxItem item={a}>
+                            <span className="flex justify-between gap-3">
+                                {a.name}
+                                <span className="text-muted-foreground tabular-nums">{a.number}</span>
+                            </span>
+                        </ComboboxItem>
+                    )}
+                >
+                    <ComboboxEmpty>No account by that name</ComboboxEmpty>
+                </ComboboxList>
+            </ComboboxPopup>
+        </Combobox>
+    );
+}
+```
+
+### Tags
+
+```tsx
+import { Combobox, ComboboxCreate, ComboboxList, ComboboxPopup, ComboboxSearch, ComboboxTrigger } from '@rinzai/zen';
+import { useState } from 'react';
+
+const asText = (tag: string) => tag;
+
+/** Several at once (chips, removable), and typing a new name offers to add it: ComboboxCreate (Enter works too). */
+export default function Tags() {
+    const [tags, setTags] = useState(['Essential', 'Shared', 'Work', 'Treat', 'Annual']);
+    const [chosen, setChosen] = useState(['Essential', 'Shared']);
+    return (
+        <Combobox multiple items={tags} itemKey={asText} itemText={asText} value={chosen} onValueChange={setChosen}>
+            <ComboboxTrigger aria-label="Tags" placeholder="No tags" className="w-80" />
+            <ComboboxPopup>
+                <ComboboxSearch />
+                <ComboboxList>
+                    <ComboboxCreate
+                        onCreate={(tag) => {
+                            setTags((all) => [...all, tag]);
+                            setChosen((c) => [...c, tag]);
+                        }}
+                    />
+                </ComboboxList>
+            </ComboboxPopup>
+        </Combobox>
+    );
+}
+```
+
+### Many items
+
+```tsx
+import { Combobox, ComboboxEmpty, ComboboxList, ComboboxPopup, ComboboxSearch, ComboboxTrigger } from '@rinzai/zen';
+import { useState } from 'react';
+
+const ACCOUNTS = Array.from({ length: 2000 }, (_, i) => ({
+    key: String(i + 1),
+    text: `Account ${String(i + 1).padStart(4, '0')}`,
+}));
+
+/** 2,000 items: the list renders only the rows in view, so it opens and scrolls instantly. Type to filter. */
+export default function ManyItems() {
+    const [account, setAccount] = useState<string | null>('1');
+    return (
+        <Combobox items={ACCOUNTS} value={account} onValueChange={setAccount}>
+            <ComboboxTrigger aria-label="Account" className="w-64" />
+            <ComboboxPopup>
+                <ComboboxSearch />
+                <ComboboxList>
+                    <ComboboxEmpty />
+                </ComboboxList>
+            </ComboboxPopup>
+        </Combobox>
+    );
+}
+```
+
+## API reference
+
+### Combobox
+
+Pick one or several items from a list you can search: a field that opens a
+panel with a search box and the matching items. Compose it from
+ComboboxTrigger, ComboboxPopup, ComboboxSearch, ComboboxList (virtualized,
+for long lists), ComboboxItem, ComboboxEmpty and ComboboxCreate. Keyboard:
+Enter, Space or ↓ on the field opens it, typing searches, ↑↓ move, Enter
+chooses, Escape closes. Items can be any shape: say how to read a key and
+text from one with `itemKey` and `itemText`.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `items` (required) | `readonly T[]` |  |  |
+| `defaultValue` | `string \| readonly string[] \| null` |  |  |
+| `filter` | `((item: T, query: string) => boolean)` |  | Whether an item matches the search (default: its text contains it, any case). |
+| `itemKey` | `((item: T) => string)` |  | How to read an item's unique key (default: its `key`). |
+| `itemText` | `((item: T) => string)` |  | How to read an item's text, shown and searched (default: its `text`). |
+| `multiple` | `boolean` |  |  |
+| `name` | `string` |  | Form field name: the chosen key is submitted with the form (with `multiple`, each key). |
+| `onValueChange` | `((key: string) => void) \| ((keys: string[]) => void)` |  |  |
+| `selectedItems` | `readonly T[]` |  | Chosen items that aren't in `items` (e.g. just created), so the field can still show them. |
+| `value` | `string \| readonly string[] \| null` |  |  |
+
+### ComboboxTrigger
+
+The field: shows the choice (text, or chips when `multiple`) or the
+placeholder, and opens the panel. Pass children to show the value your own way.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` |  | Your own display of the value (default: its text, or chips). |
+| `disabled` | `boolean` |  |  |
+| `placeholder` | `string` |  | Shown while nothing is chosen. |
+| `size` | `"default" \| "lg" \| "sm"` | `default` | Height, matching Button's: sm (32px), default (40px) or lg (44px). |
+
+### ComboboxSearch
+
+The search box: focused when the panel opens; ↑↓ move through the matches and Enter chooses.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `aria-label` | `string` |  |  |
+| `placeholder` | `string` |  |  |
+
+### ComboboxList
+
+The matching items, rendered only while in view (so thousands stay fast).
+Rows are `itemHeight` px tall; `renderItem` draws each (default: a
+ComboboxItem). Put ComboboxEmpty or ComboboxCreate inside for no matches.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `itemHeight` | `number` | `35` | Height of every row, in px (default 35). |
+| `renderItem` | `((item: T) => ReactNode)` |  |  |
+
+### ComboboxItem
+
+One item in a ComboboxList: a check when chosen, then its text (or your own content).
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `item` (required) | `T` |  |  |
+| `className` | `string` |  |  |
+
+### ComboboxEmpty
+
+Shown when the search matches nothing.
+
+No props of its own; it accepts the props of the element it renders.
+
+### ComboboxCreate
+
+Offered when the search matches nothing: adds what was typed (Enter works
+too). `children` renders the row from the text (default "Add …").
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `onCreate` (required) | `(text: string) => void` |  |  |

package/dist/docs/command-palette.md

@@ -0,0 +1,65 @@
+# Command Palette
+
+Search everything and act on it from the keyboard: a field over a list that narrows as you type, opened with ⌘K.
+
+```tsx
+import { CommandPalette, useCommandPaletteShortcut } from '@rinzai/zen';
+```
+
+## Examples
+
+### Default
+
+```tsx
+import { Button, CommandPalette, Kbd, useCommandPaletteShortcut, type CommandItem } from '@rinzai/zen';
+import { useState } from 'react';
+// Icons from Heroicons (https://heroicons.com): ChartBar (chart-bar), ListBullet (list-bullet), Settings (cog-6-tooth).
+
+/** Pages and actions in one search. Open it with the button, or ⌘K / Ctrl+K. */
+export default function Default() {
+    const [open, setOpen] = useState(false);
+    const [last, setLast] = useState<string>();
+    useCommandPaletteShortcut(() => setOpen(true));
+    const go = (label: string) => () => setLast(label);
+    const items: CommandItem[] = [
+        { label: 'Overview', group: 'Pages', icon: <ChartBar />, onSelect: go('Overview') },
+        { label: 'Entries', group: 'Pages', icon: <ListBullet />, keywords: ['transactions'], onSelect: go('Entries') },
+        { label: 'Settings', group: 'Pages', icon: <Settings />, keywords: ['preferences'], onSelect: go('Settings') },
+        { label: 'Add entry', group: 'Actions', hint: 'N', onSelect: go('Add entry') },
+        { label: 'Import a statement', group: 'Actions', keywords: ['csv', 'bank'], onSelect: go('Import') },
+        { label: 'Export to CSV', group: 'Actions', onSelect: go('Export') },
+    ];
+    return (
+        <div className="flex flex-col items-center gap-3">
+            <Button variant="outline" onClick={() => setOpen(true)}>
+                Search…
+                <span className="ml-2 flex gap-0.5">
+                    <Kbd>⌘</Kbd>
+                    <Kbd>K</Kbd>
+                </span>
+            </Button>
+            {last && <p className="text-muted-foreground mt-0! text-sm">Ran: {last}</p>}
+            <CommandPalette open={open} onOpenChange={setOpen} items={items} placeholder="Search pages and actions…" />
+        </div>
+    );
+}
+```
+
+## API reference
+
+### CommandPalette
+
+Search everything and act on it (pages, commands, records): a field over a
+list that narrows as you type. Arrow keys move, Enter runs the item and
+closes. Open it from a button, or anywhere with ⌘K / Ctrl+K
+(useCommandPaletteShortcut).
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `items` (required) | `CommandItem[]` |  |  |
+| `onOpenChange` (required) | `(open: boolean) => void` |  |  |
+| `open` (required) | `boolean` |  |  |
+| `className` | `string` |  |  |
+| `empty` | `ReactNode` |  | Shown when nothing matches. |
+| `label` | `string` |  | Names the palette and its list, for screen readers. |
+| `placeholder` | `string` |  |  |

package/dist/docs/date-picker.md

@@ -0,0 +1,167 @@
+# Date Picker
+
+A field that opens a calendar: one date, or a range previewed as you point. Dates are "YYYY-MM-DD" strings, so they never shift with time zones.
+
+```tsx
+import { DatePicker, DateRangePicker } from '@rinzai/zen';
+```
+
+## Examples
+
+### Default
+
+```tsx
+import { DatePicker } from '@rinzai/zen';
+import { useState } from 'react';
+
+/** Opens on the chosen date, ready for the keyboard; picking a day closes it. With onClear, it can be emptied. */
+export default function Default() {
+    const [date, setDate] = useState<string | null>('2026-09-30');
+    return (
+        <DatePicker
+            aria-label="Due date"
+            value={date}
+            onValueChange={setDate}
+            clearable
+            locale="en-IN"
+            className="w-56"
+        />
+    );
+}
+```
+
+### Range
+
+```tsx
+import { type DateRange, DateRangePicker } from '@rinzai/zen';
+import { useState } from 'react';
+
+/** A trip: the start, then the end, across two months. Closes once both are picked. */
+export default function Range() {
+    const [trip, setTrip] = useState<DateRange | null>(null);
+    return (
+        <DateRangePicker
+            aria-label="Trip dates"
+            value={trip}
+            onValueChange={setTrip}
+            clearable
+            months={2}
+            locale="en-US"
+            className="w-64"
+        />
+    );
+}
+```
+
+### Presets
+
+```tsx
+import { commonRanges, type DateRange, DateRangePicker, today } from '@rinzai/zen';
+import { useState } from 'react';
+
+/** The ranges people pick most, one tap each, beside the calendar. */
+export default function Presets() {
+    const r = commonRanges(today());
+    const [range, setRange] = useState<DateRange | null>(r.thisMonth);
+    return (
+        <DateRangePicker
+            aria-label="Entries between"
+            value={range}
+            onValueChange={setRange}
+            locale="en-US"
+            className="w-64"
+            presets={[
+                { label: 'This week', range: r.thisWeek },
+                { label: 'Last 7 days', range: r.last7Days },
+                { label: 'Last 30 days', range: r.last30Days },
+                { label: 'This month', range: r.thisMonth },
+                { label: 'Last month', range: r.lastMonth },
+                { label: 'This year', range: r.thisYear },
+            ]}
+        />
+    );
+}
+```
+
+### In field
+
+```tsx
+import { addDays, DatePicker, Field, today } from '@rinzai/zen';
+import { useState } from 'react';
+
+/** In a Field: the label, hint and error are wired to the picker. Only dates from today on. */
+export default function InField() {
+    const [date, setDate] = useState<string | null>(null);
+    const [touched, setTouched] = useState(false);
+    return (
+        <Field
+            label="Start date"
+            hint="When the plan begins."
+            error={touched && !date ? 'Pick a start date.' : undefined}
+            className="w-64"
+        >
+            <DatePicker
+                value={date}
+                onValueChange={setDate}
+                onBlur={() => setTouched(true)}
+                locale="en-US"
+                min={today()}
+                max={addDays(today(), 365)}
+            />
+        </Field>
+    );
+}
+```
+
+## API reference
+
+### DatePicker
+
+Date field: shows the date ("Sep 30, 2026" for the locale) and opens a
+Calendar to pick one, focused on the chosen date so the keyboard works at
+once. Dates are "YYYY-MM-DD" strings. When `clearable`, the popup also offers
+`clearLabel` to empty it. With `name`, it's submitted with a form.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className` | `string` |  | Classes for the trigger (e.g. a width, instead of the default full width). |
+| `clearable` | `boolean` | `false` | Offers a clear option in the popup (shown when a value is set); clearing reports null. |
+| `clearLabel` | `string` |  |  |
+| `defaultValue` | `string \| null` | `null` | The first date, when the picker keeps its own. |
+| `isDisabled` | `((date: string) => boolean)` |  | Dates that can't be picked, e.g. weekends or booked days. |
+| `locale` | `string` |  | Decides the date format, month and weekday names, and the first day of the week, e.g. "en-IN". Defaults to the LocaleProvider's. |
+| `max` | `string` |  | Latest date that can be picked. |
+| `min` | `string` |  | Earliest date that can be picked ("YYYY-MM-DD"). |
+| `name` | `string` |  | Form field name: the value is submitted with the form ("YYYY-MM-DD", a range as "start/end"). |
+| `onValueChange` | `((date: string \| null) => void)` |  |  |
+| `placeholder` | `string` |  |  |
+| `size` | `"default" \| "lg" \| "sm"` |  | Height, matching Button's: sm (32px), default (40px) or lg (44px). |
+| `value` | `string \| null` |  | "YYYY-MM-DD", or null for none, when you keep it. |
+| `weekStartsOn` | `number` |  | 0 for Sunday … 6 for Saturday. Defaults to the locale's. |
+
+### DateRangePicker
+
+Date range field: pick a start and then an end in a Calendar (the days
+between are previewed while pointing); it closes once the range is complete.
+Shows the range the locale's way, e.g. "Sep 3 – 10, 2026". With `presets`,
+common ranges ("Last 30 days") sit beside the calendar, one tap each (see
+commonRanges).
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className` | `string` |  | Classes for the trigger (e.g. a width, instead of the default full width). |
+| `clearable` | `boolean` | `false` | Offers a clear option in the popup (shown when a value is set); clearing reports null. |
+| `clearLabel` | `string` |  |  |
+| `defaultValue` | `DateRange \| null` | `null` | The first range, when the picker keeps its own. |
+| `isDisabled` | `((date: string) => boolean)` |  | Dates that can't be picked, e.g. weekends or booked days. |
+| `locale` | `string` |  | Decides the date format, month and weekday names, and the first day of the week, e.g. "en-IN". Defaults to the LocaleProvider's. |
+| `max` | `string` |  | Latest date that can be picked. |
+| `min` | `string` |  | Earliest date that can be picked ("YYYY-MM-DD"). |
+| `months` | `number` | `1` | Months shown side by side (2 suits wide screens). |
+| `name` | `string` |  | Form field name: the value is submitted with the form ("YYYY-MM-DD", a range as "start/end"). |
+| `onValueChange` | `((range: DateRange \| null) => void)` |  |  |
+| `placeholder` | `string` |  |  |
+| `presets` | `DateRangePreset[]` |  | Ranges picked in one tap, beside the calendar. |
+| `size` | `"default" \| "lg" \| "sm"` |  | Height, matching Button's: sm (32px), default (40px) or lg (44px). |
+| `value` | `DateRange \| null` |  | The range when you keep it; `end` is null while only the start is picked. |
+| `weekStartsOn` | `number` |  | 0 for Sunday … 6 for Saturday. Defaults to the locale's. |