@rinzai/zen 0.14.0 → 0.16.0

package/dist/docs/pagination.md

@@ -0,0 +1,42 @@
+# Pagination
+
+The pages a long list is split into, as buttons or links for your router.
+
+```tsx
+import { Pagination } from '@rinzai/zen';
+```
+
+## Examples
+
+### Default
+
+```tsx
+import { Pagination } from '@rinzai/zen';
+import { useState } from 'react';
+
+/** Pages as buttons. With a router, give `href` and render each with its Link through `renderLink`. */
+export default function Default() {
+    const [page, setPage] = useState(6);
+    return <Pagination page={page} count={12} onPageChange={setPage} />;
+}
+```
+
+## API reference
+
+### Pagination
+
+The pages a long list is split into: previous and next, the first and last
+pages, and those around the current one (`page`, from 1). Pages are buttons
+calling `onPageChange`, or with `href`, links (render them with your router's
+Link through `renderLink`).
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `count` (required) | `number` |  | How many pages there are. With fewer than 2, nothing is shown. |
+| `page` (required) | `number` |  | The current page, from 1. |
+| `aria-label` | `string` |  |  |
+| `className` | `string` |  |  |
+| `href` | `((page: number) => string)` |  | Pages as links: the URL of each. |
+| `onPageChange` | `((page: number) => void)` |  |  |
+| `renderLink` | `((props: DetailedHTMLProps<AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>, page: number) => ReactNode)` | `(props) => <a {...props} />` | Renders a page link, e.g. with your router's Link. |
+| `siblings` | `number` | `1` | Pages shown either side of the current one. |

package/dist/docs/pills.md

@@ -0,0 +1,85 @@
+# Pills
+
+A glass track with a glowing pill that slides to the current page. In a nav, it is site navigation; works with any router.
+
+```tsx
+import { Pills, Pill, PillIndicator } from '@rinzai/zen';
+```
+
+## Examples
+
+### Navigation
+
+```tsx
+import { Pill, PillIndicator, Pills } from '@rinzai/zen';
+import { useState } from 'react';
+
+const PAGES = ['Month', 'Planner', 'Loans', 'Goals', 'Trends'];
+
+/**
+ * Site navigation: Pills in a <nav>. With a router, pass its link as the child:
+ * <Pill asChild><NavLink to="/goals">Goals</NavLink></Pill>.
+ */
+export default function Navigation() {
+    const [current, setCurrent] = useState('Month');
+    return (
+        <nav aria-label="Main">
+            <Pills>
+                <PillIndicator />
+                {PAGES.map((page) => (
+                    <Pill
+                        key={page}
+                        href={`#${page.toLowerCase()}`}
+                        active={page === current}
+                        onClick={(e) => {
+                            e.preventDefault();
+                            setCurrent(page);
+                        }}
+                    >
+                        {page}
+                    </Pill>
+                ))}
+            </Pills>
+        </nav>
+    );
+}
+```
+
+## API reference
+
+### Pills
+
+A glass track of pills, with an optional glowing pill that slides to the
+active one: whichever has aria-current="page" (router links such as React
+Router's NavLink set it themselves) or aria-selected="true". It adds no role
+of its own; what you wrap it in says what it is. Site navigation:
+
+  <nav aria-label="Main">
+      <Pills>
+          <PillIndicator />
+          <Pill href="/month" active>Month</Pill>
+          <Pill asChild><NavLink to="/goals">Goals</NavLink></Pill>
+      </Pills>
+  </nav>
+
+For tabs that switch panels in place, use Tabs with `<TabList variant="pills">`.
+
+No props of its own; it accepts the props of the element it renders.
+
+### Pill
+
+One pill: a link. `active` marks the current page. With `asChild`, the
+styles go onto your own element instead (a router's Link or NavLink).
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `active` | `boolean` |  | This pill is the current page (aria-current="page"). |
+| `asChild` | `boolean` |  | Style the single child element (e.g. a router link) instead of rendering an <a>. |
+
+### PillIndicator
+
+The glowing pill under the active item. Place it inside Pills; hidden while none is active.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className` | `string` |  |  |

package/dist/docs/player-bar.md

@@ -0,0 +1,158 @@
+# Player Bar
+
+What's playing, along the bottom of the screen, sitting on a TabBar on phones. useMediaPlayer drives your own <audio> or <video>; useMediaSession puts it on the lock screen and the media keys.
+
+```tsx
+import { PlayerBar, useMediaPlayer, useMediaSession } from '@rinzai/zen';
+```
+
+## Examples
+
+### Default
+
+```tsx
+import { Button, PlayerBar, SeekBar, Slider, useMediaPlayer, useMediaSession } from '@rinzai/zen';
+
+import { useDemoTrack } from './demo-track';
+// Icons from Heroicons (https://heroicons.com): Backward (backward), Pause (pause), Play (play), SpeakerWave (speaker-wave), SpeakerXMark (speaker-x-mark).
+
+/**
+ * Your own <audio>, driven by useMediaPlayer: the cover and title, the controls
+ * over a SeekBar, and the volume. useMediaSession puts it on the lock screen
+ * and the media keys. Fixed to the bottom of the screen; here it sits in a frame.
+ */
+export default function Default() {
+    const src = useDemoTrack();
+    const [audioRef, player] = useMediaPlayer();
+    useMediaSession(player, { title: 'Glass Aurora', artist: 'Zen' });
+    return (
+        <div className="border-tint/10 relative h-48 w-full [transform:translateZ(0)] overflow-hidden rounded-2xl border">
+            <audio ref={audioRef} src={src} preload="metadata" />
+            <PlayerBar aria-label="Now playing" className="absolute! justify-between rounded-b-[15px]">
+                <div className="flex min-w-0 flex-1 items-center gap-3">
+                    <div className="from-primary size-11 shrink-0 rounded-lg bg-linear-135 to-fuchsia-400" />
+                    <div className="min-w-0">
+                        <p className="truncate text-sm font-medium">Glass Aurora</p>
+                        <p className="text-muted-foreground truncate text-xs">Zen</p>
+                    </div>
+                </div>
+                <div className="flex flex-[2] flex-col items-center gap-1">
+                    <div className="flex items-center gap-2">
+                        <Button variant="ghost" size="icon-sm" aria-label="Restart" onClick={() => player.seek(0)}>
+                            <Backward className="size-4" />
+                        </Button>
+                        <Button
+                            size="icon"
+                            className="rounded-full"
+                            aria-label={player.playing ? 'Pause' : 'Play'}
+                            disabled={!src}
+                            onClick={() => player.toggle()}
+                        >
+                            {player.playing ? <Pause className="size-5" /> : <Play className="size-5" />}
+                        </Button>
+                    </div>
+                    <SeekBar
+                        className="w-full"
+                        currentTime={player.currentTime}
+                        playing={player.playing && !player.waiting}
+                        playbackRate={player.playbackRate}
+                        duration={player.duration}
+                        buffered={player.buffered}
+                        onSeek={player.seek}
+                    />
+                </div>
+                <div className="hidden flex-1 items-center justify-end gap-2 sm:flex">
+                    <Button
+                        variant="ghost"
+                        size="icon-sm"
+                        aria-label={player.muted ? 'Unmute' : 'Mute'}
+                        onClick={() => player.setMuted(!player.muted)}
+                    >
+                        {player.muted ? <SpeakerXMark className="size-4" /> : <SpeakerWave className="size-4" />}
+                    </Button>
+                    <Slider
+                        aria-label="Volume"
+                        className="w-24"
+                        value={player.muted ? 0 : Math.round(player.volume * 100)}
+                        onValueChange={(v) => {
+                            player.setVolume(v / 100);
+                            if (v > 0 && player.muted) player.setMuted(false);
+                        }}
+                    />
+                </div>
+            </PlayerBar>
+        </div>
+    );
+}
+```
+
+### On tab bar
+
+```tsx
+import { Button, PlayerBar, TabBar, TabBarItem, useMediaPlayer } from '@rinzai/zen';
+
+import { useDemoTrack } from './demo-track';
+// Icons from Heroicons (https://heroicons.com): Pause (pause), Play (play), Search (magnifying-glass), Squares (squares-2x2), ListBullet (list-bullet).
+
+/**
+ * On a phone, it sits on the TabBar beside it, and the page pads its end by
+ * both bars' heights (--zen-tab-bar-height and --zen-player-bar-height).
+ */
+export default function OnTabBar() {
+    const src = useDemoTrack();
+    const [audioRef, player] = useMediaPlayer();
+    const progress = player.duration ? (player.currentTime / player.duration) * 100 : 0;
+    return (
+        <div className="border-tint/10 relative h-96 w-80 [transform:translateZ(0)] overflow-hidden rounded-2xl border">
+            <audio ref={audioRef} src={src} preload="metadata" />
+            <div className="h-full overflow-y-auto p-4 pb-[calc(var(--zen-tab-bar-height,0px)+var(--zen-player-bar-height,0px))]">
+                <p className="text-muted-foreground text-sm">Home</p>
+            </div>
+            <PlayerBar aria-label="Now playing" className="absolute! gap-3 px-3 pt-2 pb-2">
+                <div className="from-primary size-9 shrink-0 rounded-md bg-linear-135 to-fuchsia-400" />
+                <div className="min-w-0 flex-1">
+                    <p className="truncate text-sm font-medium">Glass Aurora</p>
+                    <p className="text-muted-foreground truncate text-xs">Zen</p>
+                </div>
+                <Button
+                    variant="ghost"
+                    size="icon-sm"
+                    aria-label={player.playing ? 'Pause' : 'Play'}
+                    disabled={!src}
+                    onClick={() => player.toggle()}
+                >
+                    {player.playing ? <Pause className="size-5" /> : <Play className="size-5" />}
+                </Button>
+                <span
+                    aria-hidden
+                    className="bg-primary absolute start-0 bottom-0 h-0.5 shadow-[0_0_8px_oklch(var(--glow)/calc(0.8*var(--glow-k)))]"
+                    style={{ width: `${progress}%` }}
+                />
+            </PlayerBar>
+            <TabBar aria-label="Main" hideFrom={false} className="absolute! rounded-b-[15px]">
+                <TabBarItem href="#home" icon={<Squares />} active onClick={(e) => e.preventDefault()}>
+                    Home
+                </TabBarItem>
+                <TabBarItem href="#search" icon={<Search />} onClick={(e) => e.preventDefault()}>
+                    Search
+                </TabBarItem>
+                <TabBarItem href="#library" icon={<ListBullet />} onClick={(e) => e.preventDefault()}>
+                    Library
+                </TabBarItem>
+            </TabBar>
+        </div>
+    );
+}
+```
+
+## API reference
+
+### PlayerBar
+
+What's playing, along the bottom of the screen: a glass bar for the cover,
+the title, the controls and a SeekBar, laid out as you like. It sits on a
+TabBar beside it (in the same parent), and clears the home indicator where
+there's none. Its height is kept in `--zen-player-bar-height` on that
+parent, for the page to pad its end by. Name it with an aria-label ("Now playing"). Drive it with useMediaPlayer.
+
+No props of its own; it accepts the props of the element it renders.

package/dist/docs/popover.md

@@ -0,0 +1,200 @@
+# Popover
+
+A glass panel that opens from a button, on the native Popover API: small forms, cards and settings. For hints use Tooltip; for actions, Menu.
+
+```tsx
+import { Popover, PopoverTrigger, PopoverContent, PopoverClose } from '@rinzai/zen';
+```
+
+## Examples
+
+### Profile card
+
+```tsx
+import { Badge, Button, Popover, PopoverContent, PopoverTrigger } from '@rinzai/zen';
+
+/** Your own trigger: here an avatar button. */
+export default function ProfileCard() {
+    return (
+        <Popover>
+            <PopoverTrigger
+                aria-label="Alex Johnson"
+                className="bg-primary text-primary-foreground flex size-9 items-center justify-center rounded-full text-sm font-bold"
+            >
+                AJ
+            </PopoverTrigger>
+            <PopoverContent aria-label="Alex Johnson">
+                <div className="flex w-64 flex-col gap-3 p-4">
+                    <div className="flex items-center gap-3">
+                        <div className="bg-primary text-primary-foreground flex size-10 items-center justify-center rounded-full text-sm font-bold">
+                            AJ
+                        </div>
+                        <div className="flex flex-col">
+                            <span className="text-sm font-semibold">Alex Johnson</span>
+                            <span className="text-muted-foreground text-xs">alex@example.com</span>
+                        </div>
+                    </div>
+                    <div className="flex gap-2">
+                        <Badge>Admin</Badge>
+                        <Badge variant="outline">Pro</Badge>
+                    </div>
+                    <div className="border-tint/10 flex flex-col gap-1 border-t pt-3">
+                        <Button variant="ghost" size="sm" className="justify-start">
+                            View profile
+                        </Button>
+                        <Button variant="ghost" size="sm" className="justify-start">
+                            Settings
+                        </Button>
+                        <Button variant="ghost" size="sm" className="text-destructive justify-start">
+                            Sign out
+                        </Button>
+                    </div>
+                </div>
+            </PopoverContent>
+        </Popover>
+    );
+}
+```
+
+### Feedback form
+
+```tsx
+import { Button, Input, Popover, PopoverClose, PopoverContent, PopoverTrigger, Textarea } from '@rinzai/zen';
+
+export default function FeedbackForm() {
+    return (
+        <Popover>
+            <PopoverTrigger asChild>
+                <Button variant="outline">Give feedback</Button>
+            </PopoverTrigger>
+            <PopoverContent aria-labelledby="feedback-title">
+                <div className="flex w-72 flex-col gap-3 p-4">
+                    <p id="feedback-title" className="text-sm font-semibold">
+                        Send feedback
+                    </p>
+                    <Input placeholder="Subject" />
+                    <Textarea placeholder="Describe your feedback…" className="resize-none" />
+                    <div className="flex justify-end gap-2">
+                        <PopoverClose variant="outline" size="sm">
+                            Cancel
+                        </PopoverClose>
+                        <Button size="sm">Submit</Button>
+                    </div>
+                </div>
+            </PopoverContent>
+        </Popover>
+    );
+}
+```
+
+### Settings
+
+```tsx
+import { Button, Popover, PopoverContent, PopoverTrigger, Toggle } from '@rinzai/zen';
+import { useState } from 'react';
+
+export default function Settings() {
+    const [settings, setSettings] = useState({ notifications: true, sounds: false, autoSave: true });
+    const rows = [
+        { key: 'notifications', label: 'Notifications' },
+        { key: 'sounds', label: 'Sounds' },
+        { key: 'autoSave', label: 'Auto-save' },
+    ] as const;
+    return (
+        <Popover>
+            <PopoverTrigger asChild>
+                <Button variant="outline">Preferences</Button>
+            </PopoverTrigger>
+            <PopoverContent aria-label="Preferences">
+                <div className="flex w-60 flex-col gap-3 p-4">
+                    <p className="text-sm font-semibold">Preferences</p>
+                    {rows.map(({ key, label }) => (
+                        <label key={key} className="flex items-center justify-between font-normal">
+                            {label}
+                            <Toggle
+                                checked={settings[key]}
+                                onCheckedChange={(on) => setSettings((s) => ({ ...s, [key]: on }))}
+                            />
+                        </label>
+                    ))}
+                </div>
+            </PopoverContent>
+        </Popover>
+    );
+}
+```
+
+### Controlled
+
+```tsx
+import { Button, Popover, PopoverClose, PopoverContent, PopoverTrigger } from '@rinzai/zen';
+import { useState } from 'react';
+
+/** Follow your own state with `open`; `onOpenChange` hears every open and close (outside clicks, Escape…). */
+export default function Controlled() {
+    const [open, setOpen] = useState(false);
+    return (
+        <Popover open={open} onOpenChange={setOpen}>
+            <PopoverTrigger asChild>
+                <Button>{open ? 'Hide' : 'Show'} popover</Button>
+            </PopoverTrigger>
+            <PopoverContent aria-label="Controlled">
+                <div className="flex flex-col gap-2 p-3 text-sm">
+                    <p className="font-medium">Manually controlled</p>
+                    <PopoverClose size="sm" variant="secondary">
+                        Close
+                    </PopoverClose>
+                </div>
+            </PopoverContent>
+        </Popover>
+    );
+}
+```
+
+## API reference
+
+### Popover
+
+A panel that opens from a button: a small form, a profile card, settings. A
+native popover, so outside clicks and Escape close it and focus returns to
+the button. Put a PopoverTrigger and a PopoverContent inside. Opens and closes
+on its own, or follows `open` (with `onOpenChange` to hear the user close it).
+For a hint on hover or focus, use Tooltip; for a list of actions, Menu.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `defaultOpen` | `boolean` | `false` | Open when it first appears. |
+| `onOpenChange` | `((open: boolean) => void)` |  | Every open and close: the trigger, outside clicks, Escape, PopoverClose. |
+| `open` | `boolean` |  | Open or close it from your state; leave it out to let the trigger do it. |
+
+### PopoverTrigger
+
+The button that opens and closes the popover. With `asChild`, your own button (e.g. a Button) instead.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `asChild` | `boolean` |  | Put the trigger's props on your own button element instead of rendering one. |
+
+### PopoverContent
+
+The panel: glass, below the trigger (above it if there's no room), centred on
+it by default. A dialog to assistive tech; give it `aria-label` or a heading
+it's labelled by when it holds a form.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `align` | `"center" \| "end" \| "start"` | `center` | Centred on the trigger (default), or lined up with its start or end edge. |
+| `offset` | `number` | `5` | Gap from the trigger, in px. |
+
+### PopoverClose
+
+A button that closes its popover (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` |  |  |

package/dist/docs/progress-ring.md

@@ -0,0 +1,70 @@
+# Progress Ring
+
+Circular progress with room for a label in the middle.
+
+```tsx
+import { ProgressRing } from '@rinzai/zen';
+```
+
+## Examples
+
+### Default
+
+```tsx
+import { ProgressRing } from '@rinzai/zen';
+
+export default function Default() {
+    return (
+        <div className="flex items-center gap-6">
+            {[0.28, 0.64, 1].map((value) => (
+                <ProgressRing key={value} value={value} label={`${Math.round(value * 100)}% saved`}>
+                    <span className="text-sm font-semibold tabular-nums">{Math.round(value * 100)}%</span>
+                </ProgressRing>
+            ))}
+        </div>
+    );
+}
+```
+
+### Goal
+
+```tsx
+import { Button, ProgressRing } from '@rinzai/zen';
+import { useState } from 'react';
+
+/** Reaching the goal sends out a ring of glow. */
+export default function Goal() {
+    const [saved, setSaved] = useState(120);
+    const goal = 200;
+    return (
+        <div className="flex items-center gap-6">
+            <ProgressRing value={saved / goal} label="Holiday fund">
+                <span className="text-sm font-semibold tabular-nums">${saved}</span>
+            </ProgressRing>
+            <div className="flex flex-col gap-2">
+                <Button variant="outline" onClick={() => setSaved((s) => Math.min(s + 40, goal))}>
+                    Save $40
+                </Button>
+                <Button variant="ghost" onClick={() => setSaved(120)}>
+                    Reset
+                </Button>
+            </div>
+        </div>
+    );
+}
+```
+
+## API reference
+
+### ProgressRing
+
+Circular progress, 0–1, with optional content in the middle. Reaching 1
+while shown sends out a ring of glow, once.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `label` (required) | `string` |  | Accessible name, e.g. "Savings goal". |
+| `value` (required) | `number` |  | Progress from 0 to 1; values outside are clamped. |
+| `className` | `string` |  |  |
+| `size` | `number` | `84` |  |
+| `stroke` | `number` | `7` |  |

package/dist/docs/radio-cards.md

@@ -0,0 +1,82 @@
+# Radio Cards
+
+Choose one of a few cards that each show their option, like a colour palette.
+
+```tsx
+import { RadioCards, RadioCard } from '@rinzai/zen';
+```
+
+## Examples
+
+### Default
+
+```tsx
+import { RadioCard, RadioCards } from '@rinzai/zen';
+import { useState } from 'react';
+
+const PALETTES = [
+    { id: 'violet', label: 'Violet', hue: 295 },
+    { id: 'ocean', label: 'Ocean', hue: 250 },
+    { id: 'teal', label: 'Teal', hue: 195 },
+    { id: 'amber', label: 'Amber', hue: 75 },
+];
+
+/** Each card shows what it picks; the whole card is the click target, and arrow keys move the choice. */
+export default function Default() {
+    const [palette, setPalette] = useState('violet');
+    return (
+        <RadioCards
+            label="Palette"
+            value={palette}
+            onValueChange={setPalette}
+            className="grid grid-cols-2 gap-2 sm:grid-cols-4"
+        >
+            {PALETTES.map((p) => (
+                <RadioCard key={p.id} value={p.id}>
+                    <span
+                        aria-hidden
+                        className="size-7 shrink-0 rounded-full"
+                        style={{
+                            background: `oklch(0.72 0.13 ${p.hue})`,
+                            boxShadow: `0 0 14px -2px oklch(0.7 0.13 ${p.hue})`,
+                        }}
+                    />
+                    <span className="font-medium">{p.label}</span>
+                </RadioCard>
+            ))}
+        </RadioCards>
+    );
+}
+```
+
+## API reference
+
+### RadioCards
+
+A choice of one among a few cards, each showing what it picks (a palette, a
+plan). Native radio inputs underneath, so arrow keys and forms work as for any
+radio group. Lay the cards out with className (e.g. a grid); fill it with
+RadioCard. For short text options, use Segmented.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` (required) | `ReactNode` |  | The RadioCards. |
+| `className` | `string` |  | Classes for the cards' container: its layout (e.g. a grid). |
+| `defaultValue` | `string` |  | The first chosen card, when the group keeps its own. |
+| `label` | `string` |  | Shown above the cards, naming the group. Without it, give the group an aria-label or aria-labelledby. |
+| `name` | `string` |  | Form field name; defaults to a generated one. |
+| `onValueChange` | `((value: V) => void)` |  |  |
+| `value` | `string` |  | The chosen card, when you keep it. |
+
+### RadioCard
+
+One card: a native radio covering whatever you put inside, so the whole card
+is the click target. Outlined, lit when chosen; style it further with
+className and style (e.g. a background showing the choice).
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` (required) | `string` |  |  |
+| `className` | `string` |  |  |
+| `disabled` | `boolean` |  | Can't be chosen (and the arrow keys skip it). |
+| `style` | `CSSProperties` |  |  |