@wtfalch/design 0.7.0 → 0.9.0

package/README.md

@@ -7,6 +7,24 @@ product can look like itself without forking the stylesheet.
 pnpm add @wtfalch/design
 ```
 
+## What is public
+
+The components, and the tokens. Not the classes.
+
+A class in this package is an implementation detail: `.card`, `.set-row`,
+`.pill` and the rest may be renamed or deleted whenever the component that
+draws them changes, and 0.9.0 did exactly that to several of them. If you
+need a card, render `<Card>`; if you need a row of your own, write it in the
+token vocabulary:
+
+```css
+.app-row { display: flex; gap: var(--space-3); align-items: center; }
+```
+
+`tokens.css` ships separately for that, and every value a theme can change is
+in it. An app that wants utilities should run Tailwind over its own source --
+this package's stylesheet is compiled and does not need it.
+
 ```ts
 import '@wtfalch/design/tokens.css'   // the vocabulary and its base values
 import '@wtfalch/design/styles.css'   // the components

package/dist/components/Button.js

@@ -69,10 +69,16 @@ const blockActivation = (event) => {
 export default function Button(props) {
     const { kind = 'default', disabled, size = 'md', busy, block, iconOnly, className } = props;
     const classes = [
+        /* Always, on both elements. Every rule that used to hang off the `button`
+           element now hangs off this class, so the styling belongs to this
+           component rather than to whatever happens to be a `<button>` -- which
+           is what let a tab, a row and a card inherit control styling and then
+           spend five declarations undoing it. */
+        'btn',
         iconOnly ? 'icon-btn' : '',
         kind === 'default' ? '' : kind,
         size === 'md' ? '' : `size-${size}`,
-        block ? 'block' : '',
+        block ? 'ctl-block' : '',
         className ?? '',
     ]
         .filter(Boolean)
@@ -108,12 +114,7 @@ export default function Button(props) {
             el.removeAttribute('aria-busy');
     }, [busy]);
     if (props.asChild) {
-        /* The one class the button form does not carry. Every rule in the
-           stylesheet is written against the `button` element, which an anchor is
-           not, so the slotted element needs a hook of its own. Adding it here
-           rather than to `classes` above keeps the button's own class list, and
-           therefore every committed baseline, exactly as it was. */
-        const slotClasses = ['btn', classes].filter(Boolean).join(' ');
+        const slotClasses = classes;
         /* Narrowed by `props.asChild`, so what is left after the component's own
            props is the DOM attribute set -- which is why an unknown `data-*`
            reaches the child untouched. */

package/dist/components/Callout.js

@@ -70,7 +70,7 @@ export default function Callout({ tone, children, icon, timed, onDismiss, classN
     return (_jsxs("div", { className: `callout${tone ? ` callout-${tone}` : ''}${running ? ' callout-timed' : ''}${className ? ` ${className}` : ''}`, 
         /* An alert interrupts whatever is being read, which is right for bad news
            and rude for "saved". */
-        role: tone === 'bad' ? 'alert' : 'status', onMouseEnter: () => running && setPaused(true), onMouseLeave: () => running && setPaused(false), onFocusCapture: () => running && setPaused(true), onBlurCapture: () => running && setPaused(false), children: [mark && (_jsx("span", { className: "callout-mark", "aria-hidden": "true", children: _jsx(Icon, { name: mark, size: 16 }) })), _jsx("div", { className: "grow", children: children }), running && (
+        role: tone === 'bad' ? 'alert' : 'status', onMouseEnter: () => running && setPaused(true), onMouseLeave: () => running && setPaused(false), onFocusCapture: () => running && setPaused(true), onBlurCapture: () => running && setPaused(false), children: [mark && (_jsx("span", { className: "callout-mark", "aria-hidden": "true", children: _jsx(Icon, { name: mark, size: 16 }) })), _jsx("div", { className: "ctl-grow", children: children }), running && (
             /* Decoration: the time remaining is not information anybody can act on,
                and a screen reader counting down a bar is noise on top of a message
                it has already read out. */

package/dist/components/Card.d.ts

@@ -2,7 +2,7 @@
  * A box with a reason to exist.
  *
  * `.card` was CSS and nothing else, so every caller assembled its own header:
- * a `<div className="row">`, a `<div className="grow">`, a title in a
+ * a `<div className="row">`, a `<div className="ctl-grow">`, a title in a
  * `truncate` span and a description in a `muted mono` div, with the spacing
  * retyped each time. Four variants of that shape existed and no two agreed on
  * the gap between the title and the line under it.

package/dist/components/Card.js

@@ -10,7 +10,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * A box with a reason to exist.
  *
  * `.card` was CSS and nothing else, so every caller assembled its own header:
- * a `<div className="row">`, a `<div className="grow">`, a title in a
+ * a `<div className="row">`, a `<div className="ctl-grow">`, a title in a
  * `truncate` span and a description in a `muted mono` div, with the spacing
  * retyped each time. Four variants of that shape existed and no two agreed on
  * the gap between the title and the line under it.
@@ -27,9 +27,26 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  */
 import Icon from './Icon.js';
 export default function Card({ icon, title, description, action, children, tone, onClick, selected, className, }) {
-    const head = (title || description || action) && (_jsxs("div", { className: "card-head", children: [icon && (_jsx("span", { className: "card-icon", "aria-hidden": "true", children: _jsx(Icon, { name: icon, size: 20 }) })), _jsxs("div", { className: "card-headings", children: [title && _jsx("strong", { className: "card-title", children: title }), description && _jsx("div", { className: "card-desc", children: description })] }), action && _jsx("div", { className: "card-action", children: action })] }));
-    const cls = `card${onClick ? ' card-pick' : ''}${selected ? ' card-on' : ''}${tone ? ` card-${tone}` : ''}${className ? ` ${className}` : ''}`;
-    const body = children && _jsx("div", { className: "card-body", children: children });
+    const body = children && _jsx("div", { className: "grid gap-3", children: children });
+    /* `mb-3` when something follows, which is what `.card-head:not(:last-child)`
+       was saying. The component knows whether there is a body; a structural
+       pseudo-class was working that out from the DOM. */
+    const head = (title || description || action) && (_jsxs("div", { className: `card-head flex items-start gap-3${body ? ' mb-3' : ''}`, children: [icon && (_jsx("span", { className: "card-icon", "aria-hidden": "true", children: _jsx(Icon, { name: icon, size: 20 }) })), _jsxs("div", { className: "min-w-0 flex-1", children: [title && _jsx("strong", { className: "card-title", children: title }), description && _jsx("div", { className: "card-desc", children: description })] }), action && _jsx("div", { className: "flex-none self-center flex items-center", children: action })] }));
+    /* `card` stays as the hook: the tones, the pick and selected states, and
+       `:has(.card-icon)` indenting an inline row past the icon, are all either
+       a `color-mix` or a relationship between elements. What is here is the
+       card's own box -- and `display: block` with `width: 100%` matter, because
+       a pressable card is a `<button>`, which shrink-wraps: a row of cards
+       became a row of labels the moment one gained an `onClick`. */
+    const cls = [
+        'card',
+        onClick ? 'card-pick' : '',
+        selected ? 'card-on' : '',
+        tone ? `card-${tone}` : '',
+        className,
+    ]
+        .filter(Boolean)
+        .join(' ');
     if (onClick) {
         return (_jsxs("button", { type: "button", className: cls, "aria-pressed": selected, onClick: onClick, children: [head, body] }));
     }

package/dist/components/Command.js

@@ -34,11 +34,11 @@ export default function Command({ open, onOpenChange, groups, placeholder = 'Sea
         }, isDismissable: true, children: _jsx(AriaModal, { className: `cmd${className ? ` ${className}` : ''}`, children: _jsx(Dialog, { className: "cmd-body", "aria-label": label, children: ({ close }) => (_jsxs(Autocomplete, { inputValue: query, onInputChange: setQuery, filter: () => true, children: [_jsxs(SearchField, { className: "cmd-field", "aria-label": label, autoFocus: true, children: [_jsx(Icon, { name: "chat", className: "cmd-mark" }), _jsx(Input, { className: "cmd-input", placeholder: placeholder })] }), empty ? (
                         /* The query, quoted. A palette that says "No results" to a
                            typo looks like a palette that is broken. */
-                        _jsxs("p", { className: "cmd-empty", children: ["Nothing matches ", _jsx("strong", { children: query }), "."] })) : (_jsx(ListBox, { className: "cmd-list", "aria-label": label, selectionMode: "none", children: shown.map((group) => (_jsxs(ListBoxSection, { className: "cmd-group", children: [_jsx(Header, { className: "cmd-group-title", children: group.title }), group.commands.map((command) => (_jsxs(ListBoxItem, { id: command.id, className: "cmd-item", textValue: command.label, isDisabled: command.disabled, onAction: () => {
+                        _jsxs("p", { className: "cmd-empty", children: ["Nothing matches ", _jsx("strong", { children: query }), "."] })) : (_jsx(ListBox, { className: "cmd-list", "aria-label": label, selectionMode: "none", children: shown.map((group) => (_jsxs(ListBoxSection, { children: [_jsx(Header, { className: "cmd-group-title", children: group.title }), group.commands.map((command) => (_jsxs(ListBoxItem, { id: command.id, className: "cmd-item", textValue: command.label, isDisabled: command.disabled, onAction: () => {
                                             command.onRun?.();
                                             /* Closing is this component's job, not every
                                                caller's. Forty `onRun`s that each remember to
                                                close is thirty-nine chances to forget. */
                                             close();
-                                        }, children: [command.icon && _jsx(Icon, { name: command.icon, className: "cmd-icon" }), _jsxs("span", { className: "cmd-text", children: [_jsx(Text, { slot: "label", className: "cmd-label", children: command.label }), command.description && (_jsx(Text, { slot: "description", className: "cmd-desc", children: command.description }))] }), command.shortcut && _jsx(Kbd, { className: "cmd-key", children: command.shortcut })] }, command.id)))] }, group.title))) }))] })) }) }) }));
+                                        }, children: [command.icon && _jsx(Icon, { name: command.icon, className: "cmd-icon" }), _jsxs("span", { className: "cmd-text", children: [_jsx(Text, { slot: "label", className: "cmd-label", children: command.label }), command.description && (_jsx(Text, { slot: "description", className: "cmd-desc", children: command.description }))] }), command.shortcut && _jsx(Kbd, { children: command.shortcut })] }, command.id)))] }, group.title))) }))] })) }) }) }));
 }

package/dist/components/Empty.js

@@ -31,5 +31,26 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import Icon from './Icon.js';
 import Illustration from './Illustration.js';
 export default function Empty({ icon, illustration, children, action, className, }) {
-    return (_jsxs("div", { className: `nothing${illustration ? ' nothing-surface' : ''}${className ? ` ${className}` : ''}`, children: [illustration ? (_jsx(Illustration, { name: illustration, size: 160, className: "nothing-figure" })) : (icon && (_jsx("span", { className: "nothing-mark", "aria-hidden": "true", children: _jsx(Icon, { name: icon, size: 20 }) }))), _jsx("p", { className: "nothing-said", children: children }), action && _jsx("div", { className: "nothing-act", children: action })] }));
+    return (_jsxs("div", { className: [
+            'nothing-surface-or-slot grid justify-items-center text-center rounded-md',
+            /* Dashed rather than solid: a solid border reads as a thing, and the
+               point of this box is that there is no thing -- it marks out where
+               the list will be. */
+            illustration
+                ? /* A whole surface rather than a slot in a card. The outline goes,
+                     because a window-sized dashed rectangle reads as a layout that
+                     failed rather than a view with nothing on it, and the box
+                     centres itself in whatever it was dropped into. */
+                    'gap-3 py-10 px-4 m-auto'
+                : 'gap-2 py-5 px-4 border border-dashed border-border-strong',
+            className,
+        ]
+            .filter(Boolean)
+            .join(' '), children: [illustration ? (
+            /* `currentColor` reaches the figure through the two rules the
+               illustrations ship with, so the colour is set here and the drawing
+               follows it -- the same grey as the sentence under it, in every
+               theme. `.illo` sets `color: inherit`, so this has to out-rank a
+               single class: `text-muted` on the element itself does. */
+            _jsx(Illustration, { name: illustration, size: 160, className: "nothing-figure" })) : (icon && (_jsx("span", { className: "text-muted leading-[0]", "aria-hidden": "true", children: _jsx(Icon, { name: icon, size: 20 }) }))), _jsx("p", { className: "m-0 text-muted text-sm leading-[1.5] max-w-[46ch]", children: children }), action && _jsx("div", { className: "mt-1", children: action })] }));
 }

package/dist/components/Field.d.ts

@@ -1,21 +1,5 @@
-export interface FieldWiring {
-    id: string;
-    'aria-describedby': string | undefined;
-    'aria-invalid': boolean | undefined;
-    /** The label element's own id, for a control a `<label for>` cannot name.
-     *
-     *  `htmlFor` is enough for an `<input>`, which is what almost every caller
-     *  wraps. It is not enough for `Select`, or for anything else built on a
-     *  `<button>`: a button takes its accessible name from its *contents*, and
-     *  a `<label for>` pointing at one is ignored by the name computation. A
-     *  caller that put a `Select` in a `Field` got a label on screen and a
-     *  control announcing only its current value — and the workaround was an
-     *  `aria-label` repeating the label string, which is two literals and two
-     *  chances to drift apart. That drift is exactly the bug this component
-     *  exists to prevent, so: pass this as `aria-labelledby` and there is one
-     *  string in one place. */
-    labelId: string;
-}
+import { type FieldWiring } from './fieldWiring.js';
+export type { FieldWiring } from './fieldWiring.js';
 export default function Field({ label, hint, error, required, children, labelHidden, layout, className, }: {
     /** What the field is. Always given -- there is no unlabelled case, only
      *  fields whose label is hidden. */
@@ -35,6 +19,25 @@ export default function Field({ label, hint, error, required, children, labelHid
      *  form to fill in. Same element, same wiring, same guarantees -- the only
      *  thing that changes is where the label sits. */
     layout?: 'stack' | 'row';
-    children: (field: FieldWiring) => React.ReactNode;
+    /**
+     * The control.
+     *
+     * **Elements, or a function.** Elements are the shape to reach for: a
+     * function cannot cross the server boundary, so a render prop made every
+     * page with a form a client component whether or not it needed to be, and
+     * all three apps' `design.ts` say so in the same sentence. Plain children
+     * read the wiring from context instead, and the package's own controls
+     * apply it when the caller has not named an `id`:
+     *
+     *     <Field label="Region" hint="Cannot be changed later">
+     *       <Select name="region" defaultValue="sg">…</Select>
+     *     </Field>
+     *
+     * The function form stays, unchanged and not deprecated. It is still the
+     * answer for a control the package does not own, or for a caller that
+     * needs the ids for something else -- a `<datalist>` to point at, a label
+     * rendered somewhere the provider does not reach.
+     */
+    children: React.ReactNode | ((field: FieldWiring) => React.ReactNode);
     className?: string;
 }): import("react").JSX.Element;

package/dist/components/Field.js

@@ -38,18 +38,20 @@ import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
  * are breaking it.
  */
 import { useId } from 'react';
+import { FieldWiringContext } from './fieldWiring.js';
 export default function Field({ label, hint, error, required, children, labelHidden, layout = 'stack', className, }) {
     const id = useId();
     const hintId = `${id}-hint`;
     const errorId = `${id}-error`;
     const labelId = `${id}-label`;
-    return (_jsxs("div", { className: `field field-${layout}-layout${error ? ' field-bad' : ''}${className ? ` ${className}` : ''}`, children: [_jsxs("label", { id: labelId, className: labelHidden ? 'sr-only' : 'field-label', htmlFor: id, children: [label, required && (_jsxs("span", { className: "field-required", "aria-label": "required", children: [' ', "*"] }))] }), hint && (_jsx("p", { className: "field-hint", id: hintId, children: hint })), children({
-                id,
-                labelId,
-                /* Both, in reading order, when both are there. A field that has a rule
-                   and has broken it needs to say the rule too -- "must be a URL" on its
-                   own does not tell you what shape of URL. */
-                'aria-describedby': [hint && hintId, error && errorId].filter(Boolean).join(' ') || undefined,
-                'aria-invalid': error ? true : undefined,
-            }), error && (_jsx("p", { className: "field-error", id: errorId, role: "alert", children: error }))] }));
+    const wiring = {
+        id,
+        labelId,
+        /* Both, in reading order, when both are there. A field that has a rule
+           and has broken it needs to say the rule too -- "must be a URL" on its
+           own does not tell you what shape of URL. */
+        'aria-describedby': [hint && hintId, error && errorId].filter(Boolean).join(' ') || undefined,
+        'aria-invalid': error ? true : undefined,
+    };
+    return (_jsxs("div", { className: `field field-${layout}-layout${error ? ' field-bad' : ''}${className ? ` ${className}` : ''}`, children: [_jsxs("label", { id: labelId, className: labelHidden ? 'sr-only' : 'field-label', htmlFor: id, children: [label, required && (_jsxs("span", { className: "field-required", "aria-label": "required", children: [' ', "*"] }))] }), hint && (_jsx("p", { className: "field-hint", id: hintId, children: hint })), typeof children === 'function' ? (children(wiring)) : (_jsx(FieldWiringContext.Provider, { value: wiring, children: children })), error && (_jsx("p", { className: "field-error", id: errorId, role: "alert", children: error }))] }));
 }

package/dist/components/Input.d.ts

@@ -1,3 +1,4 @@
+import { type IconName } from './Icon.js';
 export interface Props extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'size' | 'className'> {
     /** The same three every control takes, so a row of mixed controls lines up
      *  without anyone measuring. */
@@ -8,6 +9,15 @@ export interface Props extends Omit<React.InputHTMLAttributes<HTMLInputElement>,
     /** Full width of whatever holds it. Inputs already are, by default; this is
      *  for the `size`d ones, which are not. */
     block?: boolean;
+    /** A glyph inside the left edge. Decorative: it is `aria-hidden`, because
+     *  a magnifier beside a field called "Search" is the label said twice. */
+    icon?: IconName;
+    /** Empty it. Given, a clear button appears inside the right edge whenever
+     *  the field has a value; the caller owns the value and does the clearing. */
+    onClear?: () => void;
+    /** Inside the right edge, before the clear button. A `Kbd` saying what
+     *  opens this, which is what the mail client's `.mail-search-key` was. */
+    trailing?: React.ReactNode;
     className?: string;
 }
 declare const Input: import("react").ForwardRefExoticComponent<Props & import("react").RefAttributes<HTMLInputElement>>;

package/dist/components/Input.js

@@ -48,11 +48,22 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { forwardRef, useState } from 'react';
 import { ToggleButton } from 'react-aria-components';
 import Icon from './Icon.js';
-const Input = forwardRef(function Input({ size = 'md', mono, block, className, type = 'text', ...rest }, ref) {
+import { useFieldWiring } from './fieldWiring.js';
+const Input = forwardRef(function Input({ size = 'md', mono, block, className, type = 'text', icon, onClear, trailing, ...rest }, ref) {
+    /* What the `Field` above wired, when the caller did not thread it by hand.
+       Explicit props win: a caller that named an `id` meant that id, and a
+       render-prop `Field` spreading its wiring is passing the same values in
+       anyway. This is the fallback, not an override. */
+    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'],
+    };
     const classes = [
         size === 'md' ? '' : `size-${size}`,
         mono ? 'mono' : '',
-        block ? 'block' : '',
+        block ? 'ctl-block' : '',
         className ?? '',
     ]
         .filter(Boolean)
@@ -61,12 +72,22 @@ const Input = forwardRef(function Input({ size = 'md', mono, block, className, t
        run time does not remount it -- a hook count that changes with a prop is a
        React error, and a remount would drop the caret. */
     const [shown, setShown] = useState(false);
+    const glyph = { sm: 14, md: 16, lg: 18 }[size];
     if (type !== 'password') {
-        return _jsx("input", { ref: ref, type: type, className: classes || undefined, ...rest });
+        const box = (_jsx("input", { ref: ref, type: type, className: classes || undefined, ...rest, ...wired }));
+        if (!icon && !onClear && !trailing)
+            return box;
+        /* Something to clear, rather than something that could be cleared: a
+           clear button over an empty field is a control that does nothing. Both
+           shapes of value are checked because either may be the caller's. */
+        const filled = rest.value !== undefined
+            ? String(rest.value).length > 0
+            : String(rest.defaultValue ?? '').length > 0;
+        return (_jsxs("span", { className: `adorned adorned-${size}${block ? ' ctl-block' : ''}${icon ? ' adorned-icon' : ''}`, children: [icon && _jsx(Icon, { name: icon, size: glyph, className: "adorned-mark", "aria-hidden": true }), box, (trailing || (onClear && filled)) && (_jsxs("span", { className: "adorned-end", children: [trailing, onClear && filled && (_jsx("button", { type: "button", className: "icon-btn adorned-clear", "aria-label": "Clear", onClick: onClear, disabled: rest.disabled, children: _jsx(Icon, { name: "close", size: glyph }) }))] }))] }));
     }
-    return (_jsxs("span", { className: `secret secret-${size}${block ? ' block' : ''}`, children: [_jsx("input", { ref: ref, type: shown ? 'text' : 'password', className: classes || undefined, 
+    return (_jsxs("span", { className: `secret secret-${size}${block ? ' ctl-block' : ''}`, children: [_jsx("input", { ref: ref, type: shown ? 'text' : 'password', className: classes || undefined, 
                 /* Only while revealed: as a password these are moot, and setting them
                    on a password field makes some browsers stop offering to fill it. */
-                autoCapitalize: shown ? 'off' : undefined, autoCorrect: shown ? 'off' : undefined, spellCheck: shown ? false : undefined, ...rest }), _jsx(ToggleButton, { className: `icon-btn ghost secret-eye${size === 'md' ? '' : ` size-${size}`}`, "aria-label": "Show password", isSelected: shown, onChange: setShown, isDisabled: rest.disabled, children: _jsx(Icon, { name: shown ? 'eye-off' : 'eye', size: { sm: 14, md: 16, lg: 18 }[size] }) })] }));
+                autoCapitalize: shown ? 'off' : undefined, autoCorrect: shown ? 'off' : undefined, spellCheck: shown ? false : undefined, ...rest, ...wired }), _jsx(ToggleButton, { className: `icon-btn secret-eye${size === 'md' ? '' : ` size-${size}`}`, "aria-label": "Show password", isSelected: shown, onChange: setShown, isDisabled: rest.disabled, children: _jsx(Icon, { name: shown ? 'eye-off' : 'eye', size: glyph }) })] }));
 });
 export default Input;

package/dist/components/Kbd.js

@@ -23,6 +23,11 @@ import { jsx as _jsx } from "react/jsx-runtime";
  * carries the slot wiring that lets `Menu` and `Command` place it, so this is
  * that component with the package's class on it rather than a new one.
  *
+ * **Drawn with utilities.** Its five declarations were a `.kbd` rule that
+ * `Menu` and `Command` reached for by class name; they are on the element
+ * now, so the component carries its own appearance and nothing else has to
+ * know the class exists.
+ *
  * **It draws the reminder; it does not bind anything.** Same contract as
  * `Menu`'s `shortcut` and `Command`'s: what actually listens for the chord is
  * the app's business, and a component that both drew a key and bound it would
@@ -30,5 +35,10 @@ import { jsx as _jsx } from "react/jsx-runtime";
  */
 import { Keyboard } from 'react-aria-components';
 export default function Kbd({ children, className, }) {
-    return _jsx(Keyboard, { className: ['kbd', className].filter(Boolean).join(' '), children: children });
+    /* Utilities rather than a `.kbd` rule. Five declarations, each of which
+       reads as what it is at the call site: it never shrinks in a flex row, it
+       is the theme's mono face at the smallest step, and it is quiet. */
+    return (_jsx(Keyboard, { className: ['flex-none font-mono text-2xs text-muted tracking-normal', className]
+            .filter(Boolean)
+            .join(' '), children: children }));
 }

package/dist/components/Menu.js

@@ -17,12 +17,12 @@ 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(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);
+        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, { 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 surface-panel border border-border rounded-md min-w-[12rem] max-w-[min(20rem,calc(100vw-var(--space-6)))] max-h-[24rem] overflow-auto overscroll-contain z-[60]", children: _jsx(AriaMenu, { className: "p-1 outline-none grid gap-[var(--border-width)]", children: item.items.map(renderItem) }) })] }, item.id)) : (row);
     if (!item.separated)
         return body;
     return [_jsx(Separator, { className: "menu-rule" }, `${item.id}-rule`), body];
 }
 export default function Menu({ trigger, items, placement = 'bottom start', label, className, }) {
-    return (_jsxs(MenuTrigger, { children: [trigger, _jsx(AriaPopover, { className: `menu-sheet${className ? ` ${className}` : ''}`, placement: placement, offset: 6, children: _jsx(AriaMenu, { className: "menu-list", "aria-label": label, children: items.map((entry) => isSection(entry) ? (_jsxs(MenuSection, { className: "menu-section", children: [_jsx(Header, { className: "menu-section-title", children: entry.title }), entry.items.map(renderItem)] }, entry.title)) : (renderItem(entry))) }) })] }));
+    return (_jsxs(MenuTrigger, { children: [trigger, _jsx(AriaPopover, { className: `menu-sheet${className ? ` ${className}` : ''}`, placement: placement, offset: 6, children: _jsx(AriaMenu, { className: "p-1 outline-none grid gap-[var(--border-width)]", "aria-label": label, children: items.map((entry) => isSection(entry) ? (_jsxs(MenuSection, { children: [_jsx(Header, { className: "menu-section-title", children: entry.title }), entry.items.map(renderItem)] }, entry.title)) : (renderItem(entry))) }) })] }));
 }

package/dist/components/Modal.js

@@ -75,7 +75,7 @@ export default function Modal({ title, description, subtitle, head, children, fo
     return (_jsx(ModalOverlay, { className: `backdrop${edge ? ` sheeted from-${edge}` : ''}`, isOpen: true, isDismissable: canClose && dismissOnScrim, isKeyboardDismissDisabled: !canClose, onOpenChange: (open) => {
             if (!open && canClose)
                 onClose?.();
-        }, children: _jsx(AriaModal, { className: `modal${edge ? ` sheet from-${edge}` : ''}${className ? ` ${className}` : ''}`, style: width ? { width } : undefined, children: _jsxs(Dialog, { ref: dialogRef, className: "modal-dialog", "aria-labelledby": labelledBy ?? (title ? headingId : undefined), children: [(title || head || (onClose && closeButton)) && (_jsxs("header", { className: "modal-head", children: [title && (
+        }, children: _jsx(AriaModal, { className: `modal${edge ? ` sheet from-${edge}` : ''}${className ? ` ${className}` : ''}`, style: width ? { width } : undefined, children: _jsxs(Dialog, { ref: dialogRef, className: "modal-dialog flex flex-col min-h-0 flex-1", "aria-labelledby": labelledBy ?? (title ? headingId : undefined), children: [(title || head || (onClose && closeButton)) && (_jsxs("header", { className: "modal-head", children: [title && (
                             /* `Heading` is what React Aria labels the dialog by, and it
                                renders an `<h2>` -- which the browser gives its own margins
                                and its own size (17px above and below, 21px type). The old
@@ -83,5 +83,5 @@ export default function Modal({ title, description, subtitle, head, children, fo
                                takes them back off so the `<strong>` inside draws exactly as
                                it did; without it every window opened with its title
                                floating in a band twice the height of the head. */
-                            _jsx(Heading, { slot: "title", id: headingId, level: 2, className: "modal-title", children: _jsx("strong", { children: title }) })), subtitle, head, onClose && closeButton && (_jsx(Button, { iconOnly: true, className: "x", "aria-label": "Close", isDisabled: closeDisabled, onPress: () => onClose(), children: _jsx(Icon, { name: "close", size: 16 }) }))] })), description && _jsx("p", { className: "modal-desc", children: description }), _jsx("div", { className: `modal-body${bodyClass ? ` ${bodyClass}` : ''}`, children: children }), footer && (_jsx("footer", { className: `set-actions${footerClass ? ` ${footerClass}` : ''}`, children: footer }))] }) }) }));
+                            _jsx(Heading, { slot: "title", id: headingId, level: 2, className: "modal-title m-0 [font:inherit]", children: _jsx("strong", { children: title }) })), subtitle, head, onClose && closeButton && (_jsx(Button, { iconOnly: true, className: "x", "aria-label": "Close", isDisabled: closeDisabled, onPress: () => onClose(), children: _jsx(Icon, { name: "close", size: 16 }) }))] })), description && _jsx("p", { className: "m-0 px-4 pb-3 text-muted text-sm", children: description }), _jsx("div", { className: `modal-body${bodyClass ? ` ${bodyClass}` : ''}`, children: children }), footer && (_jsx("footer", { className: `set-actions${footerClass ? ` ${footerClass}` : ''}`, children: footer }))] }) }) }));
 }

package/dist/components/Pagination.js

@@ -99,7 +99,12 @@ export default function Pagination({ position, limit, total, count, onChange, la
        exactly once, on a list whose length is a multiple of the limit, and costs
        one empty page rather than a hidden remainder. */
     const canGoOn = pages === undefined ? shown >= limit : page < pages;
-    return (_jsxs("nav", { className: `pager${className ? ` ${className}` : ''}`, "aria-label": label, children: [_jsx("p", { className: "pager-count", children: shown === 0 ? (`No ${unit}`) : (_jsxs(_Fragment, { children: [_jsxs("strong", { children: [group(first), "\u2013", group(last)] }), total === undefined ? ` ${unit}` : ` of ${group(total)} ${unit}`] })) }), _jsxs("div", { className: "pager-controls", children: [_jsx("button", { type: "button", className: "pager-step", onClick: () => onChange(Math.max(0, position - limit)), disabled: !canGoBack, "aria-label": "Previous page", children: _jsx(Chevron, { back: true }) }), pages !== undefined && (_jsx("ol", { className: "pager-pages", children: pageWindow(page, pages).map((slot, index, slots) => slot === 'gap' ? (
+    return (_jsxs("nav", { className: [
+            'flex items-center justify-between gap-4 flex-wrap py-2 text-xs text-muted',
+            className,
+        ]
+            .filter(Boolean)
+            .join(' '), "aria-label": label, children: [_jsx("p", { className: "pager-count m-0", children: shown === 0 ? (`No ${unit}`) : (_jsxs(_Fragment, { children: [_jsxs("strong", { children: [group(first), "\u2013", group(last)] }), total === undefined ? ` ${unit}` : ` of ${group(total)} ${unit}`] })) }), _jsxs("div", { className: "flex items-center gap-1", children: [_jsx("button", { type: "button", className: "pager-step", onClick: () => onChange(Math.max(0, position - limit)), disabled: !canGoBack, "aria-label": "Previous page", children: _jsx(Chevron, { back: true }) }), pages !== undefined && (_jsx("ol", { className: "pager-pages", children: pageWindow(page, pages).map((slot, index, slots) => slot === 'gap' ? (
                         /* Keyed by the page it follows rather than by its index: a
                            window holds at most two gaps and they elide different runs,
                            and an index key makes React reuse the wrong one -- which

package/dist/components/Progress.js

@@ -23,5 +23,12 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 export default function Progress({ value, max, label, detail, tone, className, }) {
     const indeterminate = value === undefined || !max;
     const pct = indeterminate ? 0 : Math.max(0, Math.min(100, (value / max) * 100));
-    return (_jsxs("div", { className: `progress${className ? ` ${className}` : ''}`, children: [(label || detail) && (_jsxs("div", { className: "progress-head", children: [_jsx("span", { className: "progress-label", children: label }), _jsx("span", { className: "grow" }), detail && _jsx("span", { className: "progress-detail mono", children: detail })] })), _jsx("div", { className: `bar${tone ? ` bar-${tone}` : ''}${indeterminate ? ' bar-indeterminate' : ''}`, role: "progressbar", "aria-label": label, "aria-valuenow": indeterminate ? undefined : Math.round(pct), "aria-valuemin": indeterminate ? undefined : 0, "aria-valuemax": indeterminate ? undefined : 100, "aria-valuetext": detail, children: _jsx("i", { style: indeterminate ? undefined : { width: `${pct}%` } }) })] }));
+    return (
+    /* `progress` stays as a hook: `card.css` spaces a bar that follows a
+       card's contents, which is a relationship between two elements. The rest
+       is this component's own shape and reads better here. */
+    _jsxs("div", { className: ['progress grid gap-1', className].filter(Boolean).join(' '), children: [(label || detail) && (
+            /* Baseline, not centre: the label and the detail are one line of text
+               with two weights, and centring them puts the smaller one adrift. */
+            _jsxs("div", { className: "flex items-baseline gap-2 text-sm", children: [_jsx("span", { children: label }), _jsx("span", { className: "ctl-grow" }), detail && _jsx("span", { className: "text-muted text-xs font-mono", children: detail })] })), _jsx("div", { className: `bar${tone ? ` bar-${tone}` : ''}${indeterminate ? ' bar-indeterminate' : ''}`, role: "progressbar", "aria-label": label, "aria-valuenow": indeterminate ? undefined : Math.round(pct), "aria-valuemin": indeterminate ? undefined : 0, "aria-valuemax": indeterminate ? undefined : 100, "aria-valuetext": detail, children: _jsx("i", { style: indeterminate ? undefined : { width: `${pct}%` } }) })] }));
 }

package/dist/components/Rows.d.ts

@@ -5,7 +5,7 @@
  * hand:
  *
  *     <div className="set-row">
- *       <span className="grow" style={{ minWidth: 0 }}>
+ *       <span className="ctl-grow" style={{ minWidth: 0 }}>
  *         <span className="named">
  *           <span className="truncate">{name}</span>
  *           …pills…

package/dist/components/Rows.js

@@ -13,7 +13,7 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
  * hand:
  *
  *     <div className="set-row">
- *       <span className="grow" style={{ minWidth: 0 }}>
+ *       <span className="ctl-grow" style={{ minWidth: 0 }}>
  *         <span className="named">
  *           <span className="truncate">{name}</span>
  *           …pills…

package/dist/components/Select.d.ts

@@ -12,6 +12,8 @@ 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;
@@ -29,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, name, form, 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

@@ -29,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, name, form, 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)
@@ -45,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
@@ -56,8 +78,8 @@ export default function Select({ block = false, size, className, children, value
        `sel-value` and the caret are the same markup as before, so the closed
        control is pixel-identical; the list is the same markup with React Aria's
        state attributes where the classes were. */
-    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) => {
+    return (_jsxs(AriaSelect, { className: `sel${block ? ' ctl-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, name: name, form: form, "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 flex-1 min-w-0 overflow-hidden text-ellipsis whitespace-nowrap", children: ({ selectedText, defaultChildren }) => selectedText ?? defaultChildren }), _jsx("svg", { className: "sel-caret flex-none opacity-60", 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 z-[60] max-h-[280px] overflow-y-auto m-0 p-1 list-none border border-border-strong rounded-md surface-panel", placement: "bottom start", offset: 4, maxHeight: 280, children: _jsx(ListBox, { children: options.map((o) => (_jsxs(ListBoxItem, { id: o.value, textValue: o.text, isDisabled: o.disabled, className: "sel-item flex items-center gap-2 p-2 rounded-sm cursor-pointer whitespace-nowrap", children: [_jsx("span", { className: "flex-1 min-w-0 overflow-hidden text-ellipsis", children: o.label }), _jsx("svg", { className: "sel-tick flex-none opacity-0", 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;