@wtfalch/design 0.6.0 → 0.8.0

package/dist/components/Menu.js

@@ -1,5 +1,13 @@
+'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Menu as AriaMenu, Popover as AriaPopover, Header, Keyboard, MenuItem, MenuSection, MenuTrigger, Separator, SubmenuTrigger, Text, } from 'react-aria-components';
+/* Client, because this module's own JSX attaches handlers or calls hooks. A
+   server component may still import it -- that is the point -- it simply
+   renders on the client. The ones without this line (Brand, Empty, Icon,
+   Illustration, Pill, Progress, Skeleton, Stat, Textarea, Table) render on
+   the server, which is why the directive is per component rather than one
+   line at the package's front door. */
+import { Menu as AriaMenu, Popover as AriaPopover, Header, MenuItem, MenuSection, MenuTrigger, Separator, SubmenuTrigger, Text, } from 'react-aria-components';
+import Kbd from './Kbd.js';
 import Icon from './Icon.js';
 function isSection(entry) {
     return 'title' in entry && Array.isArray(entry.items);
@@ -9,7 +17,7 @@ function renderItem(item) {
         /* Typeahead needs a string, and `label` may be a node. Without this,
            typing the first letter of an item whose label is markup matches
            nothing and the menu looks broken. */
-        textValue: typeof item.label === 'string' ? item.label : item.id, children: [item.icon && _jsx(Icon, { name: item.icon, className: "menu-icon" }), _jsxs("span", { className: "menu-text", children: [_jsx(Text, { slot: "label", className: "menu-label", children: item.label }), item.description && (_jsx(Text, { slot: "description", className: "menu-desc", children: item.description }))] }), item.shortcut && _jsx(Keyboard, { className: "menu-key", children: item.shortcut }), item.items && (_jsx("svg", { className: "menu-more", viewBox: "0 0 24 24", width: "12", height: "12", "aria-hidden": "true", children: _jsx("path", { fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", d: "m9 6 6 6-6 6" }) }))] }, item.id));
+        textValue: typeof item.label === 'string' ? item.label : item.id, children: [item.icon && _jsx(Icon, { name: item.icon, className: "menu-icon" }), _jsxs("span", { className: "menu-text", children: [_jsx(Text, { slot: "label", className: "menu-label", children: item.label }), item.description && (_jsx(Text, { slot: "description", className: "menu-desc", children: item.description }))] }), item.shortcut && _jsx(Kbd, { className: "menu-key", children: item.shortcut }), item.items && (_jsx("svg", { className: "menu-more", viewBox: "0 0 24 24", width: "12", height: "12", "aria-hidden": "true", children: _jsx("path", { fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", d: "m9 6 6 6-6 6" }) }))] }, item.id));
     const body = item.items ? (_jsxs(SubmenuTrigger, { children: [row, _jsx(AriaPopover, { className: "menu-sheet", children: _jsx(AriaMenu, { className: "menu-list", children: item.items.map(renderItem) }) })] }, item.id)) : (row);
     if (!item.separated)
         return body;

package/dist/components/Modal.d.ts

@@ -1,36 +1,3 @@
-/**
- * A window over the app, and the behaviour every one of them was missing.
- *
- * There are eight of these -- Settings, FirstRun, ViewSettings, DownloadModal,
- * ModelSettings, AppletSettings, AppletReview, the studio -- and all eight were
- * built by hand from `.backdrop` and `.modal`. Not one of them trapped focus.
- *
- * **That is not a detail.** Everything behind a modal is still in the tab
- * order: still focusable, still clickable by a keyboard, and completely
- * invisible under the scrim. Tab past the last button in Settings and you are
- * somewhere on the dashboard you cannot see, operating controls you cannot
- * read. Shift-Tab from the first does the same going the other way. The mouse
- * never finds this, which is why it survived eight implementations.
- *
- * So: focus moves in, is kept in, and goes back where it came from when the
- * window closes -- to the button that opened it, not to the top of the page.
- * `role="dialog"` and `aria-modal` say the same thing to a screen reader, which
- * otherwise reads the page underneath as though it were still there.
- *
- * **This is the workspace shape.** A title, a body, optionally a footer, sized
- * to its content. `Dialog` is the narrow two-answer version and is built on
- * this -- same trap, same restore, stricter about the scrim, because for "may
- * this applet write to your files" a stray click on the background is a way of
- * answering by accident.
- *
- * **A sheet is this with `edge` set, not a second component.** A drawer from
- * the side of the window differs from a window in the middle of it by where it
- * is anchored and which way it slides -- and in nothing else. Same focus trap,
- * same restore, same scrim, same header, body and footer. Writing a `Sheet`
- * that duplicates all of that to change two CSS properties is how a design
- * system ends up with two windows that drift: one of them gets the fix and
- * nobody notices which.
- */
 export default function Modal({ title, description, subtitle, head, children, footer, footerClass, onClose, closeDisabled, width, edge, bodyClass, className, dismissOnScrim, closeButton, labelledBy, }: {
     /** The window's name. Rendered as the heading and announced on open. */
     title?: React.ReactNode;

package/dist/components/Modal.js

@@ -1,4 +1,11 @@
+'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/* Client, because this module's own JSX attaches handlers or calls hooks. A
+   server component may still import it -- that is the point -- it simply
+   renders on the client. The ones without this line (Brand, Empty, Icon,
+   Illustration, Pill, Progress, Skeleton, Stat, Textarea, Table) render on
+   the server, which is why the directive is per component rather than one
+   line at the package's front door. */
 /**
  * A window over the app, and the behaviour every one of them was missing.
  *

package/dist/components/Pagination.d.ts

@@ -1,36 +1,3 @@
-/**
- * Moving through a list that does not fit.
- *
- * **It counts in items, not in pages**, because that is what the server
- * answers and what the reader asks. A JMAP query returns a position, a limit
- * and a total; a mailbox is "51–100 of 1,284", not "page 2 of 26". Page
- * numbers are this component's arithmetic, done once here rather than at every
- * call site -- which is where the off-by-one lives, and where it becomes an
- * empty last page.
- *
- * **The count is the point, and it is said out loud.** "51–100 of 1,284" tells
- * you how far in you are and how much is left; two arrows tell you neither. A
- * pager with no count is a pager you navigate by feel.
- *
- * **A total is optional, because a server may refuse to count.** JMAP's
- * `calculateTotal` is a request, not a promise, and a large mailbox is exactly
- * where it gets declined. Without one this shows the range and keeps Next
- * enabled while a full page came back, which is the only honest thing it can
- * do: a page shorter than the limit is the end.
- *
- * **The ellipsis is a field, not punctuation.** It stands for the pages you
- * cannot see, so it is where you say which one you want: type a number, press
- * Enter, and you are there. Drawn as a ghost -- no border, no background, the
- * `…` as its placeholder -- so at rest the row looks exactly like a row of
- * page buttons with an elision in it, and it becomes a control when you touch
- * it. Without this, reaching page 17 of 26 is eleven presses of Next, and the
- * middle of a row of live buttons is a dead spot.
- *
- * **`nav` with a name**, so a screen reader can jump to it and so two pagers
- * on a page are distinguishable. The current page's button is
- * `aria-current="page"`, which is what tells a reader where they are without
- * relying on the colour that says it visually.
- */
 export interface Props {
     /** Index of the first item shown, counting from zero -- the same number the
      *  query was given, so caller and component never disagree about the origin. */

package/dist/components/Pagination.js

@@ -1,4 +1,11 @@
+'use client';
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/* Client, because this module's own JSX attaches handlers or calls hooks. A
+   server component may still import it -- that is the point -- it simply
+   renders on the client. The ones without this line (Brand, Empty, Icon,
+   Illustration, Pill, Progress, Skeleton, Stat, Textarea, Table) render on
+   the server, which is why the directive is per component rather than one
+   line at the package's front door. */
 /**
  * Moving through a list that does not fit.
  *

package/dist/components/Popover.js

@@ -1,4 +1,11 @@
+'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/* Client, because this module's own JSX attaches handlers or calls hooks. A
+   server component may still import it -- that is the point -- it simply
+   renders on the client. The ones without this line (Brand, Empty, Icon,
+   Illustration, Pill, Progress, Skeleton, Stat, Textarea, Table) render on
+   the server, which is why the directive is per component rather than one
+   line at the package's front door. */
 import { Popover as AriaPopover, Dialog, DialogTrigger, } from 'react-aria-components';
 export default function Popover({ trigger, children, placement = 'bottom start', label, offset = 6, open, onOpenChange, className, }) {
     return (_jsxs(DialogTrigger, { isOpen: open, onOpenChange: onOpenChange, children: [trigger, _jsx(AriaPopover, { className: `pop${className ? ` ${className}` : ''}`, placement: placement, offset: offset, children: _jsx(Dialog, { className: "pop-body", "aria-label": label, children: ({ close }) => (typeof children === 'function' ? children(close) : children) }) })] }));

package/dist/components/Rows.js

@@ -1,4 +1,11 @@
+'use client';
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/* Client, because this module's own JSX attaches handlers or calls hooks. A
+   server component may still import it -- that is the point -- it simply
+   renders on the client. The ones without this line (Brand, Empty, Icon,
+   Illustration, Pill, Progress, Skeleton, Stat, Textarea, Table) render on
+   the server, which is why the directive is per component rather than one
+   line at the package's front door. */
 /**
  * A list of things, each with a name, some qualifiers and something to do.
  *

package/dist/components/ScrollArea.js

@@ -1,4 +1,11 @@
+'use client';
 import { jsx as _jsx } from "react/jsx-runtime";
+/* Client, because this module's own JSX attaches handlers or calls hooks. A
+   server component may still import it -- that is the point -- it simply
+   renders on the client. The ones without this line (Brand, Empty, Icon,
+   Illustration, Pill, Progress, Skeleton, Stat, Textarea, Table) render on
+   the server, which is why the directive is per component rather than one
+   line at the package's front door. */
 import { useCallback, useEffect, useRef } from 'react';
 export default function ScrollArea({ axis = 'y', fade = true, hideBar = false, className, children, ref, label, }) {
     const own = useRef(null);

package/dist/components/Select.d.ts

@@ -12,6 +12,13 @@ interface Props {
     'aria-label'?: string;
     'aria-labelledby'?: string;
     disabled?: boolean;
+    'aria-describedby'?: string;
+    'aria-invalid'?: boolean;
+    /** What the form submits this under. Without it there is nothing to post,
+     *  which is what sent callers back to a mirrored hidden input. */
+    name?: string;
+    /** The form to submit with, when the control sits outside it. */
+    form?: string;
     value?: string | number;
     defaultValue?: string | number;
     /** Native-select-shaped on purpose -- `e.target.value` -- because that is
@@ -24,5 +31,5 @@ interface Props {
     /** Something to the right of an option -- a play button beside a voice. */
     aside?: (value: string) => ReactNode;
 }
-export default function Select({ block, size, className, children, value, defaultValue, onChange, disabled, id, title, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, aside, }: Props): import("react").JSX.Element;
+export default function Select({ block, size, className, children, value, defaultValue, onChange, disabled, name, form, id, title, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, aside, 'aria-describedby': ariaDescribedBy, 'aria-invalid': ariaInvalid, }: Props): import("react").JSX.Element;
 export {};

package/dist/components/Select.js

@@ -1,4 +1,11 @@
+'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/* Client, because this module's own JSX attaches handlers or calls hooks. A
+   server component may still import it -- that is the point -- it simply
+   renders on the client. The ones without this line (Brand, Empty, Icon,
+   Illustration, Pill, Progress, Skeleton, Stat, Textarea, Table) render on
+   the server, which is why the directive is per component rather than one
+   line at the package's front door. */
 import { Children, isValidElement, useEffect, useRef } from 'react';
 /** Read `<option>` children into a list this can render itself. */
 function readOptions(children) {
@@ -22,13 +29,26 @@ function readOptions(children) {
    free when that element was a `<select>` and is wrong now that it is a
    `<button>` -- `onCopy` alone is typed against a different element. Call sites
    pass five things between them, so five is what this takes. */
+import { useFieldWiring } from './fieldWiring.js';
 import { Select as AriaSelect, Button, ListBox, ListBoxItem, Popover, SelectValue, } from 'react-aria-components';
-export default function Select({ block = false, size, className, children, value, defaultValue, onChange, disabled, id, title, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, aside, }) {
+export default function Select({ block = false, size, className, children, value, defaultValue, onChange, disabled, name, form, id, title, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, aside, 'aria-describedby': ariaDescribedBy, 'aria-invalid': ariaInvalid, }) {
     const options = readOptions(children);
-    /* `title`, set on the element: React Aria's `Button` takes `id` and the
-       `aria-*` labelling props and filters the rest, the same `filterDOMProps`
-       that dropped `aria-busy` on `Button` and `aria-modal` on `Modal`. */
+    /* A `Select` is a `<button>`, and a button takes its accessible name from
+       its contents -- so `Field`'s `htmlFor` does not name it and the caller
+       used to repeat the label in an `aria-label`. Reading the wiring here is
+       what removes the second literal. Explicit props win throughout. */
+    const field = useFieldWiring();
+    const wiredId = id ?? field?.id;
+    const wiredLabelledBy = ariaLabelledBy ?? (ariaLabel ? undefined : field?.labelId);
+    /* `title` and `aria-invalid`, set on the element: React Aria's `Button`
+       takes `id` and the *labelling* aria props -- label, labelledby,
+       describedby, details -- and filters the rest, the same `filterDOMProps`
+       that dropped `aria-busy` on `Button` and `aria-modal` on `Modal`.
+       `aria-invalid` is not on that list, so passing it as a prop typechecks,
+       reads correctly and does nothing at all. That is the third time this
+       has caught someone, which is why it is written down here too. */
     const control = useRef(null);
+    const invalid = ariaInvalid ?? field?.['aria-invalid'];
     useEffect(() => {
         const el = control.current;
         if (!el)
@@ -38,6 +58,15 @@ export default function Select({ block = false, size, className, children, value
         else
             el.removeAttribute('title');
     }, [title]);
+    useEffect(() => {
+        const el = control.current;
+        if (!el)
+            return;
+        if (invalid)
+            el.setAttribute('aria-invalid', 'true');
+        else
+            el.removeAttribute('aria-invalid');
+    }, [invalid]);
     /* React Aria owns what was 13 KB of hand-rolled behaviour: the popover is
        positioned against the button and flips when the edge is near, which the
        measured-rectangle `top`/`left` could not; typeahead, Home and End, the
@@ -52,5 +81,5 @@ export default function Select({ block = false, size, className, children, value
     return (_jsxs(AriaSelect, { className: `sel${block ? ' block' : ''}${className ? ` ${className}` : ''}`, selectedKey: value !== undefined ? String(value) : undefined, defaultSelectedKey: defaultValue !== undefined ? String(defaultValue) : (options[0]?.value ?? undefined), onSelectionChange: (key) => {
             if (key !== null)
                 onChange?.({ target: { value: String(key) } });
-        }, isDisabled: disabled, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, children: [_jsxs(Button, { ref: control, id: id, className: `sel-control${size ? ` size-${size}` : ''}`, children: [_jsx(SelectValue, { className: "sel-value", children: ({ selectedText, defaultChildren }) => selectedText ?? defaultChildren }), _jsx("svg", { className: "sel-caret", viewBox: "0 0 24 24", width: "14", height: "14", "aria-hidden": "true", children: _jsx("path", { fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", d: "m6 9 6 6 6-6" }) })] }), _jsx(Popover, { className: "sel-list", placement: "bottom start", offset: 4, maxHeight: 280, children: _jsx(ListBox, { className: "sel-listbox", children: options.map((o) => (_jsxs(ListBoxItem, { id: o.value, textValue: o.text, isDisabled: o.disabled, className: "sel-item", children: [_jsx("span", { className: "sel-item-label", children: o.label }), _jsx("svg", { className: "sel-tick", viewBox: "0 0 24 24", width: "13", height: "13", "aria-hidden": "true", children: _jsx("path", { fill: "none", stroke: "currentColor", strokeWidth: "2.5", strokeLinecap: "round", strokeLinejoin: "round", d: "m5 13 4 4 10-10" }) }), aside?.(o.value)] }, o.value))) }) })] }));
+        }, isDisabled: disabled, name: name, form: form, "aria-label": ariaLabel, "aria-labelledby": wiredLabelledBy, children: [_jsxs(Button, { ref: control, id: wiredId, "aria-describedby": ariaDescribedBy ?? field?.['aria-describedby'], className: `sel-control${size ? ` size-${size}` : ''}`, children: [_jsx(SelectValue, { className: "sel-value", children: ({ selectedText, defaultChildren }) => selectedText ?? defaultChildren }), _jsx("svg", { className: "sel-caret", viewBox: "0 0 24 24", width: "14", height: "14", "aria-hidden": "true", children: _jsx("path", { fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", d: "m6 9 6 6 6-6" }) })] }), _jsx(Popover, { className: "sel-list", placement: "bottom start", offset: 4, maxHeight: 280, children: _jsx(ListBox, { className: "sel-listbox", children: options.map((o) => (_jsxs(ListBoxItem, { id: o.value, textValue: o.text, isDisabled: o.disabled, className: "sel-item", children: [_jsx("span", { className: "sel-item-label", children: o.label }), _jsx("svg", { className: "sel-tick", viewBox: "0 0 24 24", width: "13", height: "13", "aria-hidden": "true", children: _jsx("path", { fill: "none", stroke: "currentColor", strokeWidth: "2.5", strokeLinecap: "round", strokeLinejoin: "round", d: "m5 13 4 4 10-10" }) }), aside?.(o.value)] }, o.value))) }) })] }));
 }

package/dist/components/Shell.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The frame a signed-in surface stands in: a header, and the page under it.
+ *
+ * Three apps have one, all called `shell.tsx`, all the same six elements. The
+ * differences were a wider variant in manage and where each put the theme
+ * control, which is a prop and a slot, not three components.
+ *
+ * **It gates nothing, and that is worth stating because a frame looks like
+ * the place to.** A layout cannot reliably stop the page beneath it
+ * rendering, so every page decides for itself who may see it. Putting a check
+ * here would read as protection and provide none. All three app docblocks say
+ * this; it moves with the component.
+ *
+ * **A `<header>` and a `<main>`, so the landmarks exist.** Hand-built
+ * versions reached for `<div>` often enough that this is the second reason to
+ * have one: "skip to content" and a screen reader's landmark list both come
+ * from the elements, and neither is visible to the person who wrote the div.
+ *
+ * Server-renderable: no hooks, no handlers. `who` and `brand` are slots, so
+ * the client parts an app needs -- a user menu, the theme switch -- are the
+ * app's to pass and stay its own client boundaries.
+ */
+export default function Shell({ brand, who, nav, wide, children, className, }: {
+    /** Top left: the product's name or mark, usually a link home. */
+    brand?: React.ReactNode;
+    /** Top right: who is signed in, the theme, whatever else is chrome. */
+    who?: React.ReactNode;
+    /** A row under the header, for an app whose pages hang off a context --
+     *  manage's organisation nav is this. */
+    nav?: React.ReactNode;
+    /** A wider measure, for a page that is a table rather than a form. */
+    wide?: boolean;
+    children: React.ReactNode;
+    className?: string;
+}): import("react").JSX.Element;

package/dist/components/Shell.js

@@ -0,0 +1,26 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The frame a signed-in surface stands in: a header, and the page under it.
+ *
+ * Three apps have one, all called `shell.tsx`, all the same six elements. The
+ * differences were a wider variant in manage and where each put the theme
+ * control, which is a prop and a slot, not three components.
+ *
+ * **It gates nothing, and that is worth stating because a frame looks like
+ * the place to.** A layout cannot reliably stop the page beneath it
+ * rendering, so every page decides for itself who may see it. Putting a check
+ * here would read as protection and provide none. All three app docblocks say
+ * this; it moves with the component.
+ *
+ * **A `<header>` and a `<main>`, so the landmarks exist.** Hand-built
+ * versions reached for `<div>` often enough that this is the second reason to
+ * have one: "skip to content" and a screen reader's landmark list both come
+ * from the elements, and neither is visible to the person who wrote the div.
+ *
+ * Server-renderable: no hooks, no handlers. `who` and `brand` are slots, so
+ * the client parts an app needs -- a user menu, the theme switch -- are the
+ * app's to pass and stay its own client boundaries.
+ */
+export default function Shell({ brand, who, nav, wide = false, children, className, }) {
+    return (_jsxs("div", { className: ['shell', className].filter(Boolean).join(' '), children: [_jsxs("header", { className: "shell-head", children: [_jsxs("div", { className: `shell-head-inner${wide ? ' shell-wide' : ''}`, children: [brand, who && _jsx("div", { className: "shell-who", children: who })] }), nav && _jsx("div", { className: `shell-nav${wide ? ' shell-wide' : ''}`, children: nav })] }), _jsx("main", { className: `shell-main${wide ? ' shell-wide' : ''}`, children: children })] }));
+}

package/dist/components/SizeGrid.js

@@ -1,4 +1,11 @@
+'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/* Client, because this module's own JSX attaches handlers or calls hooks. A
+   server component may still import it -- that is the point -- it simply
+   renders on the client. The ones without this line (Brand, Empty, Icon,
+   Illustration, Pill, Progress, Skeleton, Stat, Textarea, Table) render on
+   the server, which is why the directive is per component rather than one
+   line at the package's front door. */
 import { useState } from 'react';
 /**
  * Pick a tile size by sweeping a grid, the way a spreadsheet asks for table

package/dist/components/Slider.js

@@ -1,4 +1,11 @@
+'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/* Client, because this module's own JSX attaches handlers or calls hooks. A
+   server component may still import it -- that is the point -- it simply
+   renders on the client. The ones without this line (Brand, Empty, Icon,
+   Illustration, Pill, Progress, Skeleton, Stat, Textarea, Table) render on
+   the server, which is why the directive is per component rather than one
+   line at the package's front door. */
 import { useEffect, useId, useRef, useState } from 'react';
 /**
  * A number chosen from a range, by dragging.

package/dist/components/SplitPane.js

@@ -1,4 +1,11 @@
+'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/* Client, because this module's own JSX attaches handlers or calls hooks. A
+   server component may still import it -- that is the point -- it simply
+   renders on the client. The ones without this line (Brand, Empty, Icon,
+   Illustration, Pill, Progress, Skeleton, Stat, Textarea, Table) render on
+   the server, which is why the directive is per component rather than one
+   line at the package's front door. */
 import { useCallback, useEffect, useId, useRef, useState } from 'react';
 function clamp(value, min, max) {
     return Math.min(max, Math.max(min, value));

package/dist/components/Stat.d.ts

@@ -0,0 +1,45 @@
+/**
+ * One figure, with what it counts over it and what it means under it.
+ *
+ * **Drawn three times before it was a component.** valet's portal overview
+ * and its organisation page under `/admin` each had their own, and the same
+ * account's numbers rendered in two shapes on the two surfaces read as two
+ * products rather than as two views of one thing. Folding them into one local
+ * `Stat` fixed that inside valet and left the next app to rediscover it;
+ * valet's own docblock says so ("a candidate for the package, once a second
+ * product wants one"). The mail client's counts are the second product.
+ *
+ * **`tabular-nums`, and that is the reason this is not a `Card`.** Figures
+ * are read down a row, and proportional digits put the same magnitude in
+ * different places on every tile, so a column of numbers stops being
+ * comparable at a glance. A tile is not a card with a big number in it: it is
+ * a number with furniture, and the furniture exists to make the number
+ * legible next to the one beside it.
+ *
+ * **The label goes over the value.** A figure read before you know what it
+ * counts is a figure you read twice. This is the one place in the package
+ * where the caption leads.
+ *
+ * **`look="bare"` is the compact form**, for a figure inside a row that
+ * already has a border around it -- valet's `.v-figure`, in the admin table.
+ * A bordered tile inside a bordered row is two boxes saying one thing.
+ */
+export default function Stat({ label, value, note, tone, look, className, }: {
+    /** What is being counted. Over the value, not under it. */
+    label: React.ReactNode;
+    /** The figure. A string, because the formatting -- locale, unit, precision
+     *  -- is the caller's: this component cannot know whether 1024 should read
+     *  as `1,024`, `1.0k` or `1 KiB`. */
+    value: React.ReactNode;
+    /** The sentence under the figure. What it excludes, when it was measured,
+     *  what it is a fraction of. */
+    note?: React.ReactNode;
+    /** Semantic colour on the value, the same four words as `Callout` and
+     *  `Pill`. Left off, a figure is just a figure -- which is right for most
+     *  of them, and a row where every tile is coloured says nothing. */
+    tone?: 'info' | 'good' | 'warn' | 'bad';
+    /** `tile` has a border and a panel behind it. `bare` is the figure alone,
+     *  for a cell in something already bordered. */
+    look?: 'tile' | 'bare';
+    className?: string;
+}): import("react").JSX.Element;

package/dist/components/Stat.js

@@ -0,0 +1,31 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * One figure, with what it counts over it and what it means under it.
+ *
+ * **Drawn three times before it was a component.** valet's portal overview
+ * and its organisation page under `/admin` each had their own, and the same
+ * account's numbers rendered in two shapes on the two surfaces read as two
+ * products rather than as two views of one thing. Folding them into one local
+ * `Stat` fixed that inside valet and left the next app to rediscover it;
+ * valet's own docblock says so ("a candidate for the package, once a second
+ * product wants one"). The mail client's counts are the second product.
+ *
+ * **`tabular-nums`, and that is the reason this is not a `Card`.** Figures
+ * are read down a row, and proportional digits put the same magnitude in
+ * different places on every tile, so a column of numbers stops being
+ * comparable at a glance. A tile is not a card with a big number in it: it is
+ * a number with furniture, and the furniture exists to make the number
+ * legible next to the one beside it.
+ *
+ * **The label goes over the value.** A figure read before you know what it
+ * counts is a figure you read twice. This is the one place in the package
+ * where the caption leads.
+ *
+ * **`look="bare"` is the compact form**, for a figure inside a row that
+ * already has a border around it -- valet's `.v-figure`, in the admin table.
+ * A bordered tile inside a bordered row is two boxes saying one thing.
+ */
+export default function Stat({ label, value, note, tone, look = 'tile', className, }) {
+    const classes = ['stat', look === 'bare' ? 'stat-bare' : '', className].filter(Boolean).join(' ');
+    return (_jsxs("div", { className: classes, "data-tone": tone, children: [_jsx("p", { className: "stat-label", children: label }), _jsx("p", { className: "stat-value", children: value }), note && _jsx("p", { className: "stat-note", children: note })] }));
+}

package/dist/components/Tabs.d.ts

@@ -39,6 +39,27 @@ export interface Tab {
     label: string;
     /** Shown after the label, for a count or a state. */
     badge?: string;
+    /**
+     * What the badge means, on hover and to a screen reader.
+     *
+     * A badge is one or two characters by design, and a mark that terse either
+     * explains itself or does not. valet had two on its admin strip that did
+     * not, and moved them out of the badge into a visible line rather than ship
+     * a glyph nobody could resolve -- which is a page working around a
+     * component, not a page making a choice.
+     *
+     * On `title` plus `aria-label`, not `title` alone: `title` never appears on
+     * a touch screen and is inconsistently announced, so the accessible name is
+     * set explicitly. The badge becomes a labelled `<abbr>`-shaped thing rather
+     * than decoration, which is what it always was.
+     *
+     * Additive, deliberately. Without this the badge's own text stays part of
+     * the tab's accessible name, which is right for the count case the prop
+     * above was written for -- "Keys 3" is a useful thing to hear. Hiding an
+     * untitled badge would have been the tidier rule and would have taken that
+     * count away from everyone already relying on it.
+     */
+    badgeTitle?: string;
     /** A line under the label, for a rail with room for one. Ignored in a
      *  horizontal strip, where there is none, and under a group, where the
      *  group's hint is the context. */

package/dist/components/Tabs.js

@@ -1,4 +1,11 @@
+'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/* Client, because this module's own JSX attaches handlers or calls hooks. A
+   server component may still import it -- that is the point -- it simply
+   renders on the client. The ones without this line (Brand, Empty, Icon,
+   Illustration, Pill, Progress, Skeleton, Stat, Textarea, Table) render on
+   the server, which is why the directive is per component rather than one
+   line at the package's front door. */
 /**
  * One row of choices where only one is showing.
  *
@@ -78,5 +85,5 @@ export default function Tabs({ tabs, value, onChange, label, orientation = 'hori
                                 e.preventDefault();
                                 move(tabs.length, -1);
                             }
-                        }, children: [_jsx("span", { className: "tab-label", children: t.label }), t.badge && _jsx("span", { className: "tab-badge", children: t.badge }), t.hint && orientation === 'vertical' && !(grouped && t.group) && (_jsx("span", { className: "tab-hint", children: t.hint }))] })] }, t.id))), _jsx("span", { className: "tabs-rule", "aria-hidden": "true" })] }));
+                        }, children: [_jsx("span", { className: "tab-label", children: t.label }), t.badge && (_jsx("span", { className: "tab-badge", title: t.badgeTitle, "aria-label": t.badgeTitle, children: t.badge })), t.hint && orientation === 'vertical' && !(grouped && t.group) && (_jsx("span", { className: "tab-hint", children: t.hint }))] })] }, t.id))), _jsx("span", { className: "tabs-rule", "aria-hidden": "true" })] }));
 }

package/dist/components/Textarea.js

@@ -8,15 +8,25 @@ import { jsx as _jsx } from "react/jsx-runtime";
  * this component keeps it by rendering the element.
  *
  * Same contract as `Input`: a plain `<textarea>` so every element rule in the
- * stylesheet keeps working, and its `id`, `aria-describedby` and `aria-invalid`
- * come from `Field`'s render prop rather than from a context. On its own it
- * needs an `aria-label`, for the same reason `Input` does.
+ * stylesheet keeps working, and its `id`, `aria-describedby` and
+ * `aria-invalid` come from the `Field` above it -- handed in by a render
+ * prop, or read from context when the caller passed plain children. On its
+ * own it needs an `aria-label`, for the same reason `Input` does.
  */
 import { forwardRef } from 'react';
+import { useFieldWiring } from './fieldWiring.js';
 const Textarea = forwardRef(function Textarea({ size = 'md', mono, className, ...rest }, ref) {
     const classes = [size === 'md' ? '' : `size-${size}`, mono ? 'mono' : '', className ?? '']
         .filter(Boolean)
         .join(' ');
-    return _jsx("textarea", { ref: ref, className: classes || undefined, ...rest });
+    /* Explicit props win; this is the fallback. After `rest` in the spread,
+       because a key present with an undefined value still overwrites. */
+    const field = useFieldWiring();
+    const wired = {
+        id: rest.id ?? field?.id,
+        'aria-describedby': rest['aria-describedby'] ?? field?.['aria-describedby'],
+        'aria-invalid': rest['aria-invalid'] ?? field?.['aria-invalid'],
+    };
+    return _jsx("textarea", { ref: ref, className: classes || undefined, ...rest, ...wired });
 });
 export default Textarea;

package/dist/components/ThemeSwitch.d.ts

@@ -0,0 +1,19 @@
+import type { Product } from '../products/index.js';
+import type { BrandName } from './brandMarks.js';
+export default function ThemeSwitch({ product, only, label, labelHidden, size, storageKey, onChange, className, }: {
+    /** Whose themes to offer. A registered name, or a `Product` from
+     *  `defineProduct` for an app with its own palette. */
+    product: BrandName | Product;
+    /** A subset of the product's themes, in the order to show them. */
+    only?: readonly string[];
+    label?: string;
+    /** The label becomes the accessible name and is not drawn, for a header
+     *  where the control's meaning is obvious from its contents. */
+    labelHidden?: boolean;
+    size?: 'sm' | 'md' | 'lg';
+    storageKey?: string;
+    /** For an app that has something else to update. The theme is already
+     *  applied by the time this runs. */
+    onChange?: (theme: string) => void;
+    className?: string;
+}): import("react").JSX.Element;

package/dist/components/ThemeSwitch.js

@@ -0,0 +1,65 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/* Client, because this module's own JSX attaches handlers or calls hooks. */
+/**
+ * The control that changes the theme.
+ *
+ * All three apps have one and the first forty lines are the same in each: the
+ * guarded `localStorage` read, the guarded write, the assignment to
+ * `document.documentElement.dataset.theme`. What differed was the wrapper and
+ * the label -- one says "Appearance", one says "Theme" -- which is drift, not
+ * design.
+ *
+ * **The choice lives in the browser, not the account.** It is a preference
+ * about this screen rather than a fact about the person: the same account on
+ * a laptop in a bright room and a phone at night wants two answers. That is
+ * also why it needs no server round trip and no session.
+ *
+ * **The default is not stored.** A browser that never chose follows whatever
+ * the default becomes, so changing a product's default reaches everyone who
+ * never expressed an opinion, rather than only new visitors.
+ *
+ * **It writes `data-theme` and does not call `applyTheme`.** The palettes are
+ * already on the page as CSS from `productCss`; the attribute is the switch.
+ * `applyTheme` writes custom properties one by one and is for the case with
+ * no stylesheet to lean on.
+ *
+ * **`aria-labelledby`, or an `aria-label`, but never both and never neither.**
+ * The apps passed `aria-label="Appearance"` beside a visible "Appearance"
+ * span, which is the same string written twice -- exactly the drift `Field`
+ * exists to stop. Given `label`, this renders it and points the control at
+ * it; given `labelHidden`, the string becomes the accessible name and is not
+ * drawn.
+ */
+import { useEffect, useId, useState } from 'react';
+import { THEME_STORAGE_KEY, storedTheme, themeChoices } from '../themes/choice.js';
+import Select from './Select.js';
+export default function ThemeSwitch({ product, only, label = 'Appearance', labelHidden = false, size = 'sm', storageKey = THEME_STORAGE_KEY, onChange, className, }) {
+    const choices = themeChoices(product, only);
+    const labelId = useId();
+    /* The server cannot know what this browser stored, so the first render has
+       to match what the server sent -- the attribute the blocking script wrote
+       is on `<html>` already, and reading `localStorage` during render would
+       be a hydration mismatch. The effect catches the control up. */
+    const [choice, setChoice] = useState(() => choices[0]?.id ?? '');
+    useEffect(() => {
+        setChoice(storedTheme(product, { only, storageKey }));
+        // The product object is rebuilt per render when passed inline; its
+        // identity is not the dependency, what it resolves to is.
+    }, [product, only, storageKey]);
+    const choose = (next) => {
+        if (!choices.some((c) => c.id === next))
+            return;
+        setChoice(next);
+        try {
+            localStorage.setItem(storageKey, next);
+        }
+        catch {
+            /* A browser blocking site data still gets the theme, just not the
+               memory of it. Failing the change over the storage would be worse. */
+        }
+        document.documentElement.dataset.theme = next;
+        onChange?.(next);
+    };
+    return (_jsxs("div", { className: ['theme-switch', className].filter(Boolean).join(' '), children: [_jsx("span", { className: "theme-switch-label", id: labelId, hidden: labelHidden, children: label }), _jsx(Select, { "aria-labelledby": labelHidden ? undefined : labelId, "aria-label": labelHidden ? label : undefined, size: size, value: choice, onChange: (e) => choose(e.target.value), children: choices.map((c) => (_jsx("option", { value: c.id, children: c.label }, c.id))) })] }));
+}