@rinzai/zen 0.14.0 → 0.16.0

package/dist/docs/spinner.md

@@ -0,0 +1,69 @@
+# Spinner
+
+A small loading spinner in the current text colour, announced to screen readers when labelled.
+
+```tsx
+import { Spinner } from '@rinzai/zen';
+```
+
+## Examples
+
+### Default
+
+```tsx
+import { Spinner } from '@rinzai/zen';
+
+/** Sized and coloured with className; it follows the text colour. */
+export default function Default() {
+    return (
+        <div className="flex items-center gap-6">
+            <Spinner />
+            <Spinner className="size-6" />
+            <Spinner className="text-primary size-8 border-[3px]" />
+            <Spinner className="text-muted-foreground size-5" />
+        </div>
+    );
+}
+```
+
+### Loading
+
+```tsx
+import { Button, Card, CardHeader, CardTitle, Spinner } from '@rinzai/zen';
+import { useState } from 'react';
+
+/** Standing on its own, a spinner needs a label so screen readers announce what is loading. */
+export default function Loading() {
+    const [loading, setLoading] = useState(true);
+    return (
+        <Card className="w-80">
+            <CardHeader>
+                <CardTitle>Entries</CardTitle>
+            </CardHeader>
+            {loading ? (
+                <div className="text-muted-foreground flex items-center gap-3 py-6 text-sm">
+                    <Spinner label="Loading entries" />
+                    Loading entries…
+                </div>
+            ) : (
+                <p className="py-6 text-sm">12 entries this month.</p>
+            )}
+            <Button variant="outline" size="sm" onClick={() => setLoading((l) => !l)}>
+                {loading ? 'Finish loading' : 'Load again'}
+            </Button>
+        </Card>
+    );
+}
+```
+
+## API reference
+
+### Spinner
+
+Small circular spinner in the current text colour; size it with className
+(default size-4). Decorative by default (e.g. inside a loading Button). Give
+it a `label` when it stands on its own, and screen readers announce it.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `label` | `string` |  | What is loading, e.g. "Loading entries". Makes the spinner announce itself. |

package/dist/docs/status-pill.md

@@ -0,0 +1,81 @@
+# Status Pill
+
+A small status that changes in place, such as Saving…, Saved or Not saved with a Retry, and fades back once the news is old.
+
+```tsx
+import { StatusPill, StatusPillAction } from '@rinzai/zen';
+```
+
+## Examples
+
+### Save
+
+```tsx
+import { Button, Spinner, StatusPill, StatusPillAction } from '@rinzai/zen';
+import { useEffect, useState } from 'react';
+// Icons from Heroicons (https://heroicons.com): AlertTriangle (exclamation-triangle), Check (check).
+
+type Save = 'saving' | 'saved' | 'error';
+
+/** A save indicator: saving spins, saved checks and then quietens, a failure is red and offers a retry. */
+export default function Save() {
+    const [state, setState] = useState<Save>('saved');
+    const [quiet, setQuiet] = useState(false);
+    useEffect(() => {
+        setQuiet(false);
+        if (state !== 'saved') return;
+        const t = window.setTimeout(() => setQuiet(true), 2500);
+        return () => window.clearTimeout(t);
+    }, [state]);
+    const save = (ok: boolean) => {
+        setState('saving');
+        window.setTimeout(() => setState(ok ? 'saved' : 'error'), 1200);
+    };
+
+    return (
+        <div className="flex flex-col items-center gap-4">
+            {state === 'error' ? (
+                <StatusPill tone="negative">
+                    <AlertTriangle />
+                    Not saved
+                    <StatusPillAction onClick={() => save(true)}>Retry</StatusPillAction>
+                </StatusPill>
+            ) : (
+                <StatusPill tone={state === 'saved' ? 'positive' : 'default'} quiet={state === 'saved' && quiet}>
+                    {state === 'saving' ? <Spinner /> : <Check />}
+                    {state === 'saving' ? 'Saving…' : 'Saved'}
+                </StatusPill>
+            )}
+            <div className="flex gap-2">
+                <Button variant="outline" size="sm" onClick={() => save(true)}>
+                    Save
+                </Button>
+                <Button variant="outline" size="sm" onClick={() => save(false)}>
+                    Save and fail
+                </Button>
+            </div>
+        </div>
+    );
+}
+```
+
+## API reference
+
+### StatusPill
+
+A small rounded status that changes in place, e.g. an app's "Saving…",
+"Saved", "Not saved · Retry": an icon (a Spinner, a Check) and a few words.
+`quiet` fades it back once the news is old (a save a few seconds ago).
+Changes are read out politely (role="status"). For an action inside it,
+such as Retry, use StatusPillAction. For a fixed label or count, use Badge.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `quiet` | `boolean` | `false` | Faded back into the page: the news is old. |
+| `tone` | `"default" \| "negative" \| "positive"` | `default` | `positive` in the accent colour (done), `negative` in red (failed); `default` is muted (in progress). |
+
+### StatusPillAction
+
+A text button inside a StatusPill, e.g. Retry, in the pill's colour.
+
+No props of its own; it accepts the props of the element it renders.

package/dist/docs/stepper.md

@@ -0,0 +1,59 @@
+# Stepper
+
+The steps of a flow and where you are in it; the line between them fills in as you go.
+
+```tsx
+import { Stepper, Step } from '@rinzai/zen';
+```
+
+## Examples
+
+### Default
+
+```tsx
+import { Button, Step, Stepper } from '@rinzai/zen';
+import { useState } from 'react';
+
+/** Importing a statement in three steps. */
+export default function Default() {
+    const [step, setStep] = useState(1);
+    return (
+        <div className="flex w-full max-w-lg flex-col items-center gap-8">
+            <Stepper value={step}>
+                <Step description="CSV or Excel">Upload</Step>
+                <Step description="Match the columns">Map</Step>
+                <Step description="Check and import">Review</Step>
+            </Stepper>
+            <div className="flex gap-2">
+                <Button variant="outline" disabled={step === 0} onClick={() => setStep(step - 1)}>
+                    Back
+                </Button>
+                <Button disabled={step === 3} onClick={() => setStep(step + 1)}>
+                    {step >= 2 ? 'Import' : 'Next'}
+                </Button>
+            </div>
+        </div>
+    );
+}
+```
+
+## API reference
+
+### Stepper
+
+The steps of a flow (sign-up, checkout, import), with where you are: steps
+before `value` (from 0) are done, the one at it is current. The line between
+them fills in as you go.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` (required) | `number` |  | The current step, from 0. Steps before it are done; past the last, all are. |
+
+### Step
+
+One step's label, and optionally a line under it (`description`).
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className` | `string` |  |  |
+| `description` | `ReactNode` |  |  |

package/dist/docs/tab-bar.md

@@ -0,0 +1,78 @@
+# Tab Bar
+
+Phone navigation fixed to the bottom of the screen. Works with any router.
+
+```tsx
+import { TabBar, TabBarItem } from '@rinzai/zen';
+```
+
+## Examples
+
+### Default
+
+```tsx
+import { TabBar, TabBarItem } from '@rinzai/zen';
+import { useState } from 'react';
+// Icons from Heroicons (https://heroicons.com): CalendarIcon (calendar), Flag (flag), Settings (cog-6-tooth), TableIcon (table-cells).
+
+const TABS = [
+    { label: 'Month', icon: <CalendarIcon /> },
+    { label: 'Planner', icon: <TableIcon /> },
+    { label: 'Goals', icon: <Flag /> },
+    { label: 'Settings', icon: <Settings /> },
+];
+
+/** Phone navigation. Fixed to the bottom of the screen; here it sits in a phone-sized frame. */
+export default function Default() {
+    const [current, setCurrent] = useState('Month');
+    return (
+        <div className="border-tint/10 relative h-72 w-80 [transform:translateZ(0)] overflow-hidden rounded-2xl border">
+            <p className="text-muted-foreground p-4 text-sm">{current}</p>
+            <TabBar aria-label="Main" hideFrom={false} className="absolute! rounded-b-[15px]">
+                {TABS.map((t) => (
+                    <TabBarItem
+                        key={t.label}
+                        href={`#${t.label.toLowerCase()}`}
+                        icon={t.icon}
+                        active={t.label === current}
+                        onClick={(e) => {
+                            e.preventDefault();
+                            setCurrent(t.label);
+                        }}
+                    >
+                        {t.label}
+                    </TabBarItem>
+                ))}
+            </TabBar>
+        </div>
+    );
+}
+```
+
+## API reference
+
+### TabBar
+
+Phone navigation: a glass bar fixed to the bottom, clear of the home
+indicator, hidden from `hideFrom` up (default md). Fill it with TabBarItems.
+Its height is kept in `--zen-tab-bar-height` on its parent (0px while
+hidden): a PlayerBar beside it sits on it, and the page can pad its end by it.
+Inside a rounded frame, round the bar to match (className, e.g.
+rounded-b-[15px]): with GPU compositing, Chrome doesn't clip a blurred
+backdrop to an ancestor's rounded corners, only to the element's own.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `hideFrom` | `"lg" \| "md" \| "sm" \| false` | `md` | Hide the bar from this breakpoint up (false: always show). |
+
+### TabBarItem
+
+One destination: an icon over a label. `active` marks the current page; with
+`asChild`, the styles go onto your own link (e.g. a router's NavLink, which
+sets aria-current itself).
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `active` | `boolean` |  |  |
+| `asChild` | `boolean` |  | Style the single child element (a router link holding the label) instead of rendering an <a>; `icon` goes inside it. |
+| `icon` | `ReactNode` |  |  |

package/dist/docs/table-of-contents.md

@@ -0,0 +1,43 @@
+# Table of Contents
+
+An "On this page" list that highlights the section being read.
+
+```tsx
+import { TableOfContents } from '@rinzai/zen';
+```
+
+## Examples
+
+### Default
+
+```tsx
+import { TableOfContents } from '@rinzai/zen';
+
+/** Point items at heading ids; the link for the section being read lights up as you scroll. */
+export default function Default() {
+    return (
+        <TableOfContents
+            className="w-48"
+            items={[
+                { id: 'installation', label: 'Installation' },
+                { id: 'usage', label: 'Usage' },
+                { id: 'theming', label: 'Theming' },
+                { id: 'tokens', label: 'Tokens', depth: 2 },
+            ]}
+        />
+    );
+}
+```
+
+## API reference
+
+### TableOfContents
+
+"On this page": links to the page's headings, highlighting the section being
+read. Items point at element ids; nested items (depth 2) are indented.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `items` (required) | `TableOfContentsItem[]` |  |  |
+| `className` | `string` |  |  |
+| `title` | `string` |  | Shown above the list, and names it. Empty: no heading shown (e.g. under a trigger that says it). |