@rinzai/zen 0.14.0 → 0.16.0

package/dist/docs/checkbox.md

@@ -0,0 +1,88 @@
+# Checkbox
+
+A native checkbox whose tick draws itself in, with a label, a description and a mixed state.
+
+```tsx
+import { Checkbox } from '@rinzai/zen';
+```
+
+## Examples
+
+### Default
+
+```tsx
+import { Checkbox } from '@rinzai/zen';
+import { useState } from 'react';
+
+/** With a label and a description; the tick draws itself in. */
+export default function Default() {
+    const [remind, setRemind] = useState(true);
+    const [share, setShare] = useState(false);
+    return (
+        <div className="flex flex-col gap-4">
+            <Checkbox checked={remind} onCheckedChange={setRemind} description="A nudge on the 1st of each month.">
+                Remind me to log spending
+            </Checkbox>
+            <Checkbox checked={share} onCheckedChange={setShare}>
+                Share anonymous usage data
+            </Checkbox>
+            <Checkbox disabled>Sync to the cloud (coming soon)</Checkbox>
+        </div>
+    );
+}
+```
+
+### Select all
+
+```tsx
+import { Checkbox } from '@rinzai/zen';
+import { useState } from 'react';
+
+const ACCOUNTS = ['Salary account', 'Credit card', 'Savings'];
+
+/** A "select all" that shows a dash while only some are checked. */
+export default function SelectAll() {
+    const [picked, setPicked] = useState<string[]>(['Credit card']);
+    const all = picked.length === ACCOUNTS.length;
+    return (
+        <div className="flex flex-col gap-3">
+            <Checkbox
+                checked={all}
+                indeterminate={picked.length > 0 && !all}
+                onCheckedChange={() => setPicked(all ? [] : ACCOUNTS)}
+                className="font-medium"
+            >
+                All accounts
+            </Checkbox>
+            <div className="flex flex-col gap-3 pl-7">
+                {ACCOUNTS.map((a) => (
+                    <Checkbox
+                        key={a}
+                        checked={picked.includes(a)}
+                        onCheckedChange={(on) => setPicked((p) => (on ? [...p, a] : p.filter((x) => x !== a)))}
+                    >
+                        {a}
+                    </Checkbox>
+                ))}
+            </div>
+        </div>
+    );
+}
+```
+
+## API reference
+
+### Checkbox
+
+A checkbox: a native one, styled, so forms, the keyboard and screen readers
+work as usual. The tick draws itself in when checked; `indeterminate` shows a
+dash (e.g. "some selected"). With children, they're its label (and
+`description` a line under it); without, label it yourself or put it in a Field.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` |  | The label. |
+| `className` | `string` |  | Classes for the label (or, without one, the box). |
+| `description` | `ReactNode` |  | A muted line under the label. |
+| `indeterminate` | `boolean` | `false` | Shows a dash instead of the tick, e.g. when some of a group are checked. |
+| `onCheckedChange` | `((checked: boolean) => void)` |  |  |

package/dist/docs/chip.md

@@ -0,0 +1,52 @@
+# Chip
+
+Small pressable buttons for quick picks beside a field, like common tenures.
+
+```tsx
+import { Chip } from '@rinzai/zen';
+```
+
+## Examples
+
+### Default
+
+```tsx
+import { Chip, Input } from '@rinzai/zen';
+import { useState } from 'react';
+
+const YEARS = [5, 10, 15, 20, 30];
+
+/** Quick picks beside a field: the chip matching the field's value shows pressed. */
+export default function Default() {
+    const [years, setYears] = useState('20');
+    return (
+        <div className="flex flex-col gap-3">
+            <Input
+                aria-label="Tenure in years"
+                value={years}
+                onChange={(e) => setYears(e.target.value)}
+                className="w-24"
+            />
+            <div role="group" aria-label="Common tenures" className="flex flex-wrap gap-1.5">
+                {YEARS.map((y) => (
+                    <Chip key={y} pressed={years === String(y)} onClick={() => setYears(String(y))}>
+                        {y} yrs
+                    </Chip>
+                ))}
+            </div>
+        </div>
+    );
+}
+```
+
+## API reference
+
+### Chip
+
+A small rounded button that can be pressed in, for quick picks beside a
+field (e.g. common tenures): `pressed` marks the one matching the field.
+For choosing exactly one of a few options, use Segmented.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `pressed` | `boolean` |  | Shown pressed in (aria-pressed). |

package/dist/docs/code-block.md

@@ -0,0 +1,116 @@
+# Code Block
+
+Code with a copy button; bring your own highlighter for colours. The copy button runs on useCopyToClipboard, which you can use for copy buttons anywhere.
+
+```tsx
+import { CodeBlock, useCopyToClipboard } from '@rinzai/zen';
+```
+
+## Examples
+
+### Highlighted
+
+```tsx
+import { CodeBlock } from '@rinzai/zen';
+import { highlight } from 'sugar-high';
+
+const CODE = `import { Button } from '@rinzai/zen';
+
+export default function Save() {
+    return <Button loading>Saving…</Button>;
+}`;
+
+/** Colours come from any highlighter that turns code into HTML; here sugar-high. Hover to copy. */
+export default function Highlighted() {
+    return (
+        <CodeBlock
+            code={CODE}
+            language="typescript"
+            highlight={(code) => highlight(code)}
+            className="w-full max-w-xl"
+        />
+    );
+}
+```
+
+### Plain
+
+```tsx
+import { CodeBlock } from '@rinzai/zen';
+
+/** Without a highlighter, the code shows as plain text. */
+export default function Plain() {
+    return <CodeBlock code="pnpm add @rinzai/zen" language="shell" className="w-full max-w-xl" />;
+}
+```
+
+### In card
+
+```tsx
+import { Card, CardHeader, CardTitle, CodeBlock } from '@rinzai/zen';
+
+/** Inside a card or panel that already has a surface, `variant="plain"` drops the block's own. */
+export default function InCard() {
+    return (
+        <Card className="w-full max-w-xl overflow-hidden p-0!">
+            <CardHeader className="mb-0 px-5 pt-5">
+                <CardTitle>Install</CardTitle>
+            </CardHeader>
+            <CodeBlock variant="plain" code="pnpm add @rinzai/zen" language="shell" />
+        </Card>
+    );
+}
+```
+
+### Copy button
+
+```tsx
+import { Button, InputGroup, InputGroupAddon, InputGroupInput, useCopyToClipboard } from '@rinzai/zen';
+import { useRef } from 'react';
+
+const LINK = 'https://zen.rinzai.dev/components/code-block/';
+
+/**
+ * A copy button of your own, with the hook CodeBlock copies with: `copy` resolves false when the
+ * browser won't copy, and here the link is then selected to copy by hand.
+ */
+export default function CopyButton() {
+    const { copy, copied } = useCopyToClipboard();
+    const input = useRef<HTMLInputElement>(null);
+    return (
+        <InputGroup className="w-full max-w-sm pr-1">
+            <InputGroupInput ref={input} value={LINK} readOnly aria-label="Link" />
+            <InputGroupAddon>
+                <Button
+                    variant="ghost"
+                    size="sm"
+                    className="h-7"
+                    onClick={async () => {
+                        if (await copy(LINK)) return;
+                        input.current?.focus();
+                        input.current?.select();
+                    }}
+                >
+                    {copied ? 'Copied' : 'Copy'}
+                </Button>
+            </InputGroupAddon>
+        </InputGroup>
+    );
+}
+```
+
+## API reference
+
+### CodeBlock
+
+Code on a glass panel whose edge catches the pointer light, with a copy
+button. Give it a max height (className) and the code scrolls inside. Zen ships no highlighter: pass `highlight` (code → HTML string, e.g.
+sugar-high's `highlight`) for colours.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `code` (required) | `string` |  |  |
+| `copyable` | `boolean` | `true` | Show the copy button (on hover and focus). |
+| `highlight` | `((code: string, language?: string) => string)` |  | Turns the code into HTML with coloured tokens. Without it, plain text. |
+| `language` | `string` |  | Passed to `highlight`, and set as data-language. |
+| `variant` | `"glass" \| "plain"` | `glass` | `glass` (default): its own lit glass panel. `plain`: no surface, for code inside a card or panel. |

package/dist/docs/code-input.md

@@ -0,0 +1,52 @@
+# Code Input
+
+A one-time code, a box per character, that types, pastes and autofills from a text message like any field.
+
+```tsx
+import { CodeInput } from '@rinzai/zen';
+```
+
+## Examples
+
+### Default
+
+```tsx
+import { CodeInput, Field } from '@rinzai/zen';
+import { useState } from 'react';
+
+/** A six-digit sign-in code, checked as soon as it's complete. */
+export default function Default() {
+    const [code, setCode] = useState('');
+    const [checked, setChecked] = useState<string>();
+    return (
+        <Field label="Sign-in code" hint={checked ? `Checking ${checked}…` : 'We sent it to your phone.'}>
+            <CodeInput
+                value={code}
+                onValueChange={(next) => {
+                    setCode(next);
+                    setChecked(undefined);
+                }}
+                onComplete={setChecked}
+            />
+        </Field>
+    );
+}
+```
+
+## API reference
+
+### CodeInput
+
+A one-time code (sign-in, verification): a box per character. It's one real
+field under the boxes, so typing, pasting, deleting and the phone's
+autofill from a text message all work as in any field. `onComplete` gets the
+code once every box is filled.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `allowed` | `RegExp` | `/\d/` | Which characters count (one at a time); digits by default. Others typed or pasted are dropped. |
+| `defaultValue` | `string` |  |  |
+| `length` | `number` | `6` | How many characters (boxes). |
+| `onComplete` | `((code: string) => void)` |  | Called with the code when the last box is filled. |
+| `onValueChange` | `((value: string) => void)` |  |  |
+| `value` | `string` |  |  |

package/dist/docs/collapse.md

@@ -0,0 +1,46 @@
+# Collapse
+
+Shows as many items as fit on one line, and the rest behind "+N".
+
+```tsx
+import { Collapse } from '@rinzai/zen';
+```
+
+## Examples
+
+### Default
+
+```tsx
+import { Badge, Collapse } from '@rinzai/zen';
+
+const TAGS = ['Groceries', 'Rent', 'Transport', 'Dining out', 'Subscriptions', 'Travel', 'Gifts', 'Health', 'Books'];
+
+/** Shows as many tags as fit on one line, and the rest behind "+N". Resize the window to see it adapt. */
+export default function Default() {
+    return (
+        <Collapse items={TAGS} className="w-full max-w-md gap-1">
+            {(tag) => <Badge variant="secondary">{tag}</Badge>}
+        </Collapse>
+    );
+}
+```
+
+## API reference
+
+### Collapse
+
+A row showing as many items as fit on one line, and the rest behind a "+N"
+button that opens them in a popover. It measures the items as rendered (any
+content, font or style), and fits again whenever the row resizes. Its width
+is the room it's given, not its items': size the row with className (e.g.
+w-full, max-w-md, gap-1).
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` (required) | `(item: string, index: number, itemData?: TData \| undefined) => ReactNode` |  | Renders one item (in the row, or in the popover when it doesn't fit). |
+| `items` (required) | `string[]` |  |  |
+| `badgeClassName` | `string` |  | Classes for the "+N" badge. |
+| `badgeVariant` | `"default" \| "outline" \| "secondary" \| null` | `secondary` |  |
+| `className` | `string` |  | Classes for the row: its width, and the gap between items. |
+| `data` | `TData[]` |  | Extra data per item, passed to `children` with it. |
+| `moreLabel` | `string` |  | Text after the count on the "+N" button, e.g. "tags". |

package/dist/docs/color-picker.md

@@ -0,0 +1,145 @@
+# Color Picker
+
+Pick a colour by eye or by hex: a saturation and brightness area, hue and opacity, and your own swatches. With hexToOklch to give a colour to the theme engine.
+
+```tsx
+import { ColorPicker, ColorPanel, hexToOklch, oklchToHex } from '@rinzai/zen';
+```
+
+## Examples
+
+### Default
+
+```tsx
+import { ColorPicker, Field } from '@rinzai/zen';
+import { useState } from 'react';
+
+export default function Default() {
+    const [color, setColor] = useState('#7c5cff');
+    return (
+        <Field label="Title colour" className="w-64">
+            <ColorPicker value={color} onValueChange={setColor} />
+        </Field>
+    );
+}
+```
+
+### Swatches
+
+```tsx
+import { ColorPicker, Field } from '@rinzai/zen';
+import { useState } from 'react';
+
+const SWATCHES = [
+    { label: 'Violet', value: '#7c5cff' },
+    { label: 'Teal', value: '#2bb3a3' },
+    { label: 'Amber', value: '#f0a83a' },
+    { label: 'Rose', value: '#ef5a7a' },
+    { label: 'White', value: '#ffffff' },
+    { label: 'Black', value: '#000000' },
+];
+
+/** With `alpha`, an opacity slider, and values like "#7c5cff99". Swatches are yours, such as your brand's colours. */
+export default function Swatches() {
+    const [color, setColor] = useState('#2bb3a3cc');
+    return (
+        <Field label="Card background" className="w-64">
+            <ColorPicker value={color} onValueChange={setColor} alpha swatches={SWATCHES} />
+        </Field>
+    );
+}
+```
+
+### Inline
+
+```tsx
+import { Card, ColorPanel } from '@rinzai/zen';
+import { useState } from 'react';
+
+/** ColorPanel is the picker's panel on its own, for a sidebar or an inspector. `onValueCommit` fires once a change is made, the moment to save. */
+export default function Inline() {
+    const [color, setColor] = useState('#ef5a7a');
+    const [saved, setSaved] = useState(color);
+    return (
+        <Card className="flex flex-col gap-3 p-4!">
+            <ColorPanel value={color} onValueChange={setColor} onValueCommit={setSaved} />
+            <p className="text-muted-foreground mt-0! text-xs">
+                Saved: <span className="text-foreground font-mono">{saved}</span>
+            </p>
+        </Card>
+    );
+}
+```
+
+### Accent
+
+```tsx
+import { applyTheme, Badge, Button, ColorPicker, customize, DEFAULT_THEME, Field, hexToOklch } from '@rinzai/zen';
+import { useEffect, useRef, useState } from 'react';
+
+/** `hexToOklch` gives a picked colour's hue to the theme engine, which keeps it readable in dark and light. */
+export default function Accent() {
+    const [color, setColor] = useState('#2bb3a3');
+    const preview = useRef<HTMLDivElement>(null);
+    useEffect(() => {
+        const oklch = hexToOklch(color);
+        const root = document.documentElement;
+        const apply = () =>
+            oklch &&
+            preview.current &&
+            applyTheme(customize(DEFAULT_THEME, { hue: Math.round(oklch.h) }), {
+                appearance: root.classList.contains('light') ? 'light' : 'dark',
+                target: preview.current,
+            });
+        apply();
+        const watch = new MutationObserver(apply);
+        watch.observe(root, { attributes: true, attributeFilter: ['class'] });
+        return () => watch.disconnect();
+    }, [color]);
+    return (
+        <div className="flex flex-wrap items-end gap-6">
+            <Field label="Accent" className="w-56">
+                <ColorPicker value={color} onValueChange={setColor} />
+            </Field>
+            <div ref={preview} className="flex items-center gap-3">
+                <Button>Save</Button>
+                <Badge>New</Badge>
+            </div>
+        </div>
+    );
+}
+```
+
+## API reference
+
+### ColorPicker
+
+A field showing a colour and its hex that opens a ColorPanel: drag or use
+the arrow keys in the area, slide the hue (and opacity, with `alpha`), type
+a hex or pick a swatch. Works in a Field like any input.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `alpha` | `boolean` |  | Offer opacity; values may then be "#rrggbbaa". |
+| `defaultValue` | `string` | `#000000` | The first colour, when the picker keeps its own. Black by default. |
+| `name` | `string` |  | Form field name: the hex is submitted with the form. |
+| `onValueChange` | `((value: string) => void)` |  | Every change, while dragging too. |
+| `onValueCommit` | `((value: string) => void)` |  | Once a change is made: let go of the area or a slider, a key, a hex entered, a swatch picked. |
+| `size` | `"default" \| "lg" \| "sm"` | `default` | Height, matching Button's: sm (32px), default (40px) or lg (44px). |
+| `swatches` | `ColorSwatch[]` |  | Colours to pick in one press, such as your theme's. |
+| `value` | `string` |  | "#rrggbb", or "#rrggbbaa" with `alpha`, when you keep it. |
+
+### ColorPanel
+
+Everything ColorPicker opens: a saturation and brightness area, hue and
+alpha sliders, the hex, and your swatches. Use it inline, or in a popup of
+your own. Values are hex: "#rrggbb", or "#rrggbbaa" with `alpha`.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `alpha` | `boolean` | `false` | Offer opacity; values may then be "#rrggbbaa". |
+| `defaultValue` | `string` | `#000000` | The first colour, when the picker keeps its own. Black by default. |
+| `onValueChange` | `((value: string) => void)` |  | Every change, while dragging too. |
+| `onValueCommit` | `((value: string) => void)` |  | Once a change is made: let go of the area or a slider, a key, a hex entered, a swatch picked. |
+| `swatches` | `ColorSwatch[]` |  | Colours to pick in one press, such as your theme's. |
+| `value` | `string` |  | "#rrggbb", or "#rrggbbaa" with `alpha`, when you keep it. |