@wtfalch/design 0.7.0 → 0.8.0

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,7 +48,18 @@ 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' : '',
@@ -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 ? ' 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 ghost 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, 
                 /* 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 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: glyph }) })] }));
 });
 export default Input;

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
@@ -59,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, 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", 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/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))) })] }));
+}

package/dist/components/fieldWiring.d.ts

@@ -0,0 +1,44 @@
+/**
+ * What a `Field` tells the control inside it.
+ *
+ * Its own module for the reason `iconNames.ts` and `tourMarker.ts` are:
+ * `fastRefresh.test.ts` holds every component module to exporting its
+ * component and nothing else, because a module exporting a value beside a
+ * component loses its Fast Refresh boundary and editing it re-runs every
+ * importer instead of swapping the component in place.
+ *
+ * The context exists so `Field`'s children can be elements rather than a
+ * function. A function cannot cross the server boundary, so the render prop
+ * made every page with a form a client component whether or not it needed to
+ * be -- which is the line all three consuming apps have in their
+ * `design.ts`.
+ */
+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 `Field` exists to
+     *  prevent, so: pass this as `aria-labelledby` and there is one string. */
+    labelId: string;
+}
+/** `null` outside a `Field`, so a control can tell "no field around me" from
+ *  "a field that wired me with nothing". */
+export declare const FieldWiringContext: import("react").Context<FieldWiring | null>;
+/**
+ * What the `Field` above this control wired, if there is one.
+ *
+ * For the package's own controls, which apply it when the caller has not
+ * named an `id` themselves. A consumer building its own control can use it
+ * for the same reason: it is how a control gets a label without the caller
+ * threading four attributes by hand.
+ */
+export declare function useFieldWiring(): FieldWiring | null;

package/dist/components/fieldWiring.js

@@ -0,0 +1,30 @@
+/**
+ * What a `Field` tells the control inside it.
+ *
+ * Its own module for the reason `iconNames.ts` and `tourMarker.ts` are:
+ * `fastRefresh.test.ts` holds every component module to exporting its
+ * component and nothing else, because a module exporting a value beside a
+ * component loses its Fast Refresh boundary and editing it re-runs every
+ * importer instead of swapping the component in place.
+ *
+ * The context exists so `Field`'s children can be elements rather than a
+ * function. A function cannot cross the server boundary, so the render prop
+ * made every page with a form a client component whether or not it needed to
+ * be -- which is the line all three consuming apps have in their
+ * `design.ts`.
+ */
+import { createContext, useContext } from 'react';
+/** `null` outside a `Field`, so a control can tell "no field around me" from
+ *  "a field that wired me with nothing". */
+export const FieldWiringContext = createContext(null);
+/**
+ * What the `Field` above this control wired, if there is one.
+ *
+ * For the package's own controls, which apply it when the caller has not
+ * named an `id` themselves. A consumer building its own control can use it
+ * for the same reason: it is how a control gets a label without the caller
+ * threading four attributes by hand.
+ */
+export function useFieldWiring() {
+    return useContext(FieldWiringContext);
+}

package/dist/index.d.ts

@@ -36,7 +36,10 @@ export { DangerAction, default as DangerZone } from './components/DangerZone.js'
 export { default as Dialog } from './components/Dialog.js';
 export { default as Empty } from './components/Empty.js';
 export { default as Field } from './components/Field.js';
-export type { FieldWiring } from './components/Field.js';
+/** The wiring a `Field` hands its control, and the hook that reads it —
+ *  its own module, so `Field.tsx` keeps its Fast Refresh boundary. */
+export { useFieldWiring } from './components/fieldWiring.js';
+export type { FieldWiring } from './components/fieldWiring.js';
 export { default as Icon } from './components/Icon.js';
 /** A person in one line -- initials, name, address -- and the two pure
  *  functions behind the disc, exported so a caller colouring something else
@@ -72,6 +75,8 @@ export { default as ScrollArea } from './components/ScrollArea.js';
 export type { Props as ScrollAreaProps } from './components/ScrollArea.js';
 export { default as Select } from './components/Select.js';
 export { default as SizeGrid } from './components/SizeGrid.js';
+/** The frame a signed-in surface stands in. Gates nothing, on purpose. */
+export { default as Shell } from './components/Shell.js';
 export { default as Skeleton } from './components/Skeleton.js';
 /** One figure, with what it counts over it. Three apps drew this before it
  *  was here. */
@@ -86,6 +91,10 @@ export type { Column } from './components/Table.js';
 export { default as Tabs } from './components/Tabs.js';
 export type { Tab, TabGroup } from './components/Tabs.js';
 export { default as Textarea } from './components/Textarea.js';
+/** The theme control, and the blocking script that beats it to the paint. */
+export { default as ThemeSwitch } from './components/ThemeSwitch.js';
+export { THEME_STORAGE_KEY, themeChoiceScript, themeChoices, storedTheme } from './themes/choice.js';
+export type { ThemeChoice } from './themes/choice.js';
 export type { Props as TextareaProps } from './components/Textarea.js';
 /** `ToastHost` nests: one inside another renders through, so a package can
  *  wrap itself and still leave an application with a single region. */

package/dist/index.js

@@ -33,6 +33,9 @@ export { DangerAction, default as DangerZone } from './components/DangerZone.js'
 export { default as Dialog } from './components/Dialog.js';
 export { default as Empty } from './components/Empty.js';
 export { default as Field } from './components/Field.js';
+/** The wiring a `Field` hands its control, and the hook that reads it —
+ *  its own module, so `Field.tsx` keeps its Fast Refresh boundary. */
+export { useFieldWiring } from './components/fieldWiring.js';
 export { default as Icon } from './components/Icon.js';
 /** A person in one line -- initials, name, address -- and the two pure
  *  functions behind the disc, exported so a caller colouring something else
@@ -64,6 +67,8 @@ export { Row, Rows } from './components/Rows.js';
 export { default as ScrollArea } from './components/ScrollArea.js';
 export { default as Select } from './components/Select.js';
 export { default as SizeGrid } from './components/SizeGrid.js';
+/** The frame a signed-in surface stands in. Gates nothing, on purpose. */
+export { default as Shell } from './components/Shell.js';
 export { default as Skeleton } from './components/Skeleton.js';
 /** One figure, with what it counts over it. Three apps drew this before it
  *  was here. */
@@ -75,6 +80,9 @@ export { default as SplitPane } from './components/SplitPane.js';
 export { default as Table } from './components/Table.js';
 export { default as Tabs } from './components/Tabs.js';
 export { default as Textarea } from './components/Textarea.js';
+/** The theme control, and the blocking script that beats it to the paint. */
+export { default as ThemeSwitch } from './components/ThemeSwitch.js';
+export { THEME_STORAGE_KEY, themeChoiceScript, themeChoices, storedTheme } from './themes/choice.js';
 /** `ToastHost` nests: one inside another renders through, so a package can
  *  wrap itself and still leave an application with a single region. */
 export { ToastHost, useHasToastHost, useToast } from './components/Toast.js';

package/dist/styles/index.css

@@ -3118,6 +3118,70 @@ input[type='range'].slider:disabled::-moz-range-thumb { opacity: 0; }
 
 .secret-lg > .secret-eye { padding: var(--space-2); }
 
+/* An input with something inside its edges: a glyph on the left, a hint or a
+   clear button on the right. Same arrangement as `.secret` above, and for the
+   same reason -- one grid cell with everything stacked in it, and the room
+   reserved in the input's own padding, so nothing is positioned against a
+   height that changes with `size`. */
+.adorned { display: grid; align-items: center; }
+
+.adorned > input,
+.adorned > .adorned-mark,
+.adorned > .adorned-end { grid-area: 1 / 1; }
+
+.adorned.block { width: 100%; }
+
+.adorned > .adorned-mark {
+  justify-self: start;
+  margin-left: var(--space-2);
+  color: var(--muted);
+  /* The glyph is decoration over the box; clicks belong to the input under
+     it, which is otherwise unreachable in its own left edge. */
+  pointer-events: none;
+  /* Over the input, not under it. Both share one grid cell, the input has an
+     opaque `--control` background, and it comes later in the DOM -- so
+     without this the glyph is painted and then covered, which looks exactly
+     like an icon that failed to render. `.secret` never hit this because its
+     button is written after the input. */
+  z-index: 1;
+}
+
+/* Room for the glyph, on the scale, so a density change moves the text with
+   the mark rather than leaving one behind. `--space-8` is what `.secret`
+   reserves on the right for the same reason; the scale has no 7, and an
+   undefined custom property does not fall back -- the declaration computes
+   to 0 and the text sits under the glyph. */
+.adorned-icon > input { padding-left: var(--space-8); }
+
+/* No `--space-12` on the scale; two steps that are, added. Same arithmetic
+   as `.secret-lg`. */
+.adorned-icon.adorned-lg > input { padding-left: calc(var(--space-10) + var(--space-1)); }
+
+.adorned > .adorned-end {
+  justify-self: end;
+  display: flex;
+  align-items: center;
+  gap: var(--space-1);
+  margin-right: var(--space-1);
+}
+
+/* `:has`, not a sibling combinator: the input comes *before* the end cap in
+   the DOM, so `~` reads the wrong way and matches nothing. */
+.adorned:has(> .adorned-end) > input { padding-right: var(--space-8); }
+.adorned-lg:has(> .adorned-end) > input {
+  padding-right: calc(var(--space-10) + var(--space-1));
+}
+
+/* Sized from its glyph, not `.icon-btn`'s 34px tile, which would be taller
+   than a small input -- the note above `.secret-eye` in full. */
+.adorned-clear {
+  width: auto; height: auto;
+  padding: var(--space-1);
+  opacity: 1;
+}
+
+.adorned-lg .adorned-clear { padding: var(--space-2); }
+
 /* ---- ./tour.css ---- */
 /* tour ----------------------------------------------------------------- */
 
@@ -3251,6 +3315,84 @@ input[type='range'].slider:disabled::-moz-range-thumb { opacity: 0; }
 .stat[data-tone='warn'] .stat-value { color: var(--warn); }
 .stat[data-tone='bad'] .stat-value { color: var(--bad); }
 
+/* ---- ./shell.css ---- */
+/* The frame. Layout only: every colour and every step is a token, and the
+   page inside it owns its own spacing. */
+.shell {
+  display: flex;
+  flex-direction: column;
+  min-height: 100vh;
+  background: var(--bg);
+  color: var(--text);
+}
+
+.shell-head {
+  border-bottom: var(--border-width) solid var(--border);
+  background: var(--panel);
+  /* `flex: none` so a long page does not squeeze the header. */
+  flex: none;
+}
+
+/* The measure, said once. `--shell-measure` rather than a literal so an app
+   with a different one sets a variable instead of overriding three rules and
+   missing the fourth -- which is how manage ended up with `head-inner-wide`
+   and `main-wide` as separate classes. */
+.shell {
+  --shell-measure: 64rem;
+  --shell-measure-wide: 90rem;
+}
+
+.shell-head-inner,
+.shell-nav,
+.shell-main {
+  width: 100%;
+  max-width: var(--shell-measure);
+  margin-inline: auto;
+  padding-inline: var(--space-4);
+}
+
+.shell-wide { max-width: var(--shell-measure-wide); }
+
+.shell-head-inner {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--space-4);
+  padding-block: var(--space-3);
+  min-width: 0;
+}
+
+.shell-who {
+  display: flex;
+  align-items: center;
+  gap: var(--space-3);
+  min-width: 0;
+}
+
+.shell-nav { padding-bottom: var(--space-2); }
+
+.shell-main {
+  flex: 1;
+  padding-block: var(--space-6);
+  /* `min-width: 0` because a flex child will not shrink below its content,
+     and one wide table inside then pushes the whole page sideways. */
+  min-width: 0;
+}
+
+/* The label beside the theme control, when it is drawn. */
+.theme-switch {
+  display: flex;
+  align-items: center;
+  gap: var(--space-2);
+  min-width: 0;
+}
+
+.theme-switch-label {
+  color: var(--muted);
+  font-size: var(--text-sm);
+  white-space: nowrap;
+}
+
 /* ---- ./scrollarea.css ---- */
 /* A box that scrolls, with its edges drawn.
    

package/dist/tf.css

@@ -3388,6 +3388,70 @@ input[type='range'].slider:disabled::-moz-range-thumb { opacity: 0; }
 
 .secret-lg > .secret-eye { padding: var(--space-2); }
 
+/* An input with something inside its edges: a glyph on the left, a hint or a
+   clear button on the right. Same arrangement as `.secret` above, and for the
+   same reason -- one grid cell with everything stacked in it, and the room
+   reserved in the input's own padding, so nothing is positioned against a
+   height that changes with `size`. */
+.adorned { display: grid; align-items: center; }
+
+.adorned > input,
+.adorned > .adorned-mark,
+.adorned > .adorned-end { grid-area: 1 / 1; }
+
+.adorned.block { width: 100%; }
+
+.adorned > .adorned-mark {
+  justify-self: start;
+  margin-left: var(--space-2);
+  color: var(--muted);
+  /* The glyph is decoration over the box; clicks belong to the input under
+     it, which is otherwise unreachable in its own left edge. */
+  pointer-events: none;
+  /* Over the input, not under it. Both share one grid cell, the input has an
+     opaque `--control` background, and it comes later in the DOM -- so
+     without this the glyph is painted and then covered, which looks exactly
+     like an icon that failed to render. `.secret` never hit this because its
+     button is written after the input. */
+  z-index: 1;
+}
+
+/* Room for the glyph, on the scale, so a density change moves the text with
+   the mark rather than leaving one behind. `--space-8` is what `.secret`
+   reserves on the right for the same reason; the scale has no 7, and an
+   undefined custom property does not fall back -- the declaration computes
+   to 0 and the text sits under the glyph. */
+.adorned-icon > input { padding-left: var(--space-8); }
+
+/* No `--space-12` on the scale; two steps that are, added. Same arithmetic
+   as `.secret-lg`. */
+.adorned-icon.adorned-lg > input { padding-left: calc(var(--space-10) + var(--space-1)); }
+
+.adorned > .adorned-end {
+  justify-self: end;
+  display: flex;
+  align-items: center;
+  gap: var(--space-1);
+  margin-right: var(--space-1);
+}
+
+/* `:has`, not a sibling combinator: the input comes *before* the end cap in
+   the DOM, so `~` reads the wrong way and matches nothing. */
+.adorned:has(> .adorned-end) > input { padding-right: var(--space-8); }
+.adorned-lg:has(> .adorned-end) > input {
+  padding-right: calc(var(--space-10) + var(--space-1));
+}
+
+/* Sized from its glyph, not `.icon-btn`'s 34px tile, which would be taller
+   than a small input -- the note above `.secret-eye` in full. */
+.adorned-clear {
+  width: auto; height: auto;
+  padding: var(--space-1);
+  opacity: 1;
+}
+
+.adorned-lg .adorned-clear { padding: var(--space-2); }
+
 /* ---- ./tour.css ---- */
 /* tour ----------------------------------------------------------------- */
 
@@ -3521,6 +3585,84 @@ input[type='range'].slider:disabled::-moz-range-thumb { opacity: 0; }
 .stat[data-tone='warn'] .stat-value { color: var(--warn); }
 .stat[data-tone='bad'] .stat-value { color: var(--bad); }
 
+/* ---- ./shell.css ---- */
+/* The frame. Layout only: every colour and every step is a token, and the
+   page inside it owns its own spacing. */
+.shell {
+  display: flex;
+  flex-direction: column;
+  min-height: 100vh;
+  background: var(--bg);
+  color: var(--text);
+}
+
+.shell-head {
+  border-bottom: var(--border-width) solid var(--border);
+  background: var(--panel);
+  /* `flex: none` so a long page does not squeeze the header. */
+  flex: none;
+}
+
+/* The measure, said once. `--shell-measure` rather than a literal so an app
+   with a different one sets a variable instead of overriding three rules and
+   missing the fourth -- which is how manage ended up with `head-inner-wide`
+   and `main-wide` as separate classes. */
+.shell {
+  --shell-measure: 64rem;
+  --shell-measure-wide: 90rem;
+}
+
+.shell-head-inner,
+.shell-nav,
+.shell-main {
+  width: 100%;
+  max-width: var(--shell-measure);
+  margin-inline: auto;
+  padding-inline: var(--space-4);
+}
+
+.shell-wide { max-width: var(--shell-measure-wide); }
+
+.shell-head-inner {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--space-4);
+  padding-block: var(--space-3);
+  min-width: 0;
+}
+
+.shell-who {
+  display: flex;
+  align-items: center;
+  gap: var(--space-3);
+  min-width: 0;
+}
+
+.shell-nav { padding-bottom: var(--space-2); }
+
+.shell-main {
+  flex: 1;
+  padding-block: var(--space-6);
+  /* `min-width: 0` because a flex child will not shrink below its content,
+     and one wide table inside then pushes the whole page sideways. */
+  min-width: 0;
+}
+
+/* The label beside the theme control, when it is drawn. */
+.theme-switch {
+  display: flex;
+  align-items: center;
+  gap: var(--space-2);
+  min-width: 0;
+}
+
+.theme-switch-label {
+  color: var(--muted);
+  font-size: var(--text-sm);
+  white-space: nowrap;
+}
+
 /* ---- ./scrollarea.css ---- */
 /* A box that scrolls, with its edges drawn.
    

package/dist/themes/choice.d.ts

@@ -0,0 +1,71 @@
+/**
+ * A person's theme, remembered, and applied before the page is drawn.
+ *
+ * **Three apps wrote this and two of them wrote it identically.**
+ * `src/theme/first-paint.ts` is byte-for-byte the same file in
+ * wtfalch-manage and app-template; valet's is the same script with the
+ * comment rewritten. Each also keeps a `themes.ts` listing ids and labels the
+ * package already knows -- a `Theme` carries the `name` a picker shows, and a
+ * `Product` carries its themes and which one it wears by default -- so the
+ * app-side list was a second copy of a fact, kept in step by hand.
+ *
+ * **The script is a string, and it has to be.** It runs before the bundle, in
+ * a blocking `<script>` in `<head>`, because a theme applied after hydration
+ * means a person who chose Paper sees Night for a frame. That is the whole
+ * reason this is not simply a `useEffect`.
+ *
+ * **It sets `data-theme` and nothing else.** The palettes ship as CSS from
+ * `productCss`, generated from the same objects the contrast test measures,
+ * so the attribute is the entire mechanism. `applyTheme` writes custom
+ * properties instead and is for the case with no stylesheet to lean on --
+ * theming a subtree, or a product whose CSS is not the one loaded.
+ *
+ * A copy of this shipped with a bug worth keeping: a stored id the app no
+ * longer offers has to fall back, or a browser that remembers `sepia` from a
+ * palette you dropped renders unthemed. The list is inlined into the script
+ * for that check.
+ */
+import type { BrandName } from '../components/brandMarks.js';
+import { type Product } from '../products/index.js';
+/** Where the choice lives. One key across the estate, so a person who picked
+ *  Night on one app is not asked again on the next one under the same
+ *  origin. The README has used this name since 0.1.0. */
+export declare const THEME_STORAGE_KEY = "theme";
+export interface ThemeChoice {
+    id: string;
+    /** What the picker calls it -- the theme's own `name`. */
+    label: string;
+    /** The line under it, where a picker has room. */
+    note: string;
+}
+/**
+ * What this product offers, in the order it declared them.
+ *
+ * `only` narrows to a subset, for an app that ships a product's palette
+ * without all of its themes. An id the product does not have is dropped
+ * rather than thrown on: the list is presentation, and a picker missing a row
+ * is better than a page that will not render.
+ */
+export declare function themeChoices(product: BrandName | Product, only?: readonly string[]): ThemeChoice[];
+/**
+ * The blocking script, as a string to put in a `<script>` in `<head>`.
+ *
+ * `dangerouslySetInnerHTML={{ __html: themeChoiceScript('tf') }}` in a Next
+ * root layout, above everything. It reads the stored id, checks it against
+ * what this app offers, and writes `data-theme` on `<html>`.
+ *
+ * Wrapped in try/catch because `localStorage` throws outright in a browser
+ * set to block site data, and an exception here happens before anything is
+ * drawn -- so the page that fails to read a preference would otherwise fail
+ * to render at all.
+ */
+export declare function themeChoiceScript(product: BrandName | Product, options?: {
+    only?: readonly string[];
+    storageKey?: string;
+}): string;
+/** What the script would have written, for code that needs the same answer
+ *  after hydration. Reads the same key and applies the same fallback. */
+export declare function storedTheme(product: BrandName | Product, options?: {
+    only?: readonly string[];
+    storageKey?: string;
+}): string;

package/dist/themes/choice.js

@@ -0,0 +1,81 @@
+/**
+ * A person's theme, remembered, and applied before the page is drawn.
+ *
+ * **Three apps wrote this and two of them wrote it identically.**
+ * `src/theme/first-paint.ts` is byte-for-byte the same file in
+ * wtfalch-manage and app-template; valet's is the same script with the
+ * comment rewritten. Each also keeps a `themes.ts` listing ids and labels the
+ * package already knows -- a `Theme` carries the `name` a picker shows, and a
+ * `Product` carries its themes and which one it wears by default -- so the
+ * app-side list was a second copy of a fact, kept in step by hand.
+ *
+ * **The script is a string, and it has to be.** It runs before the bundle, in
+ * a blocking `<script>` in `<head>`, because a theme applied after hydration
+ * means a person who chose Paper sees Night for a frame. That is the whole
+ * reason this is not simply a `useEffect`.
+ *
+ * **It sets `data-theme` and nothing else.** The palettes ship as CSS from
+ * `productCss`, generated from the same objects the contrast test measures,
+ * so the attribute is the entire mechanism. `applyTheme` writes custom
+ * properties instead and is for the case with no stylesheet to lean on --
+ * theming a subtree, or a product whose CSS is not the one loaded.
+ *
+ * A copy of this shipped with a bug worth keeping: a stored id the app no
+ * longer offers has to fall back, or a browser that remembers `sepia` from a
+ * palette you dropped renders unthemed. The list is inlined into the script
+ * for that check.
+ */
+import { PRODUCTS } from '../products/index.js';
+/** Where the choice lives. One key across the estate, so a person who picked
+ *  Night on one app is not asked again on the next one under the same
+ *  origin. The README has used this name since 0.1.0. */
+export const THEME_STORAGE_KEY = 'theme';
+function resolve(product) {
+    return typeof product === 'string' ? PRODUCTS[product] : product;
+}
+/**
+ * What this product offers, in the order it declared them.
+ *
+ * `only` narrows to a subset, for an app that ships a product's palette
+ * without all of its themes. An id the product does not have is dropped
+ * rather than thrown on: the list is presentation, and a picker missing a row
+ * is better than a page that will not render.
+ */
+export function themeChoices(product, only) {
+    const p = resolve(product);
+    const ids = only ? only.filter((id) => id in p.themes) : Object.keys(p.themes);
+    return ids.map((id) => ({ id, label: p.themes[id].name, note: p.themes[id].note }));
+}
+/**
+ * The blocking script, as a string to put in a `<script>` in `<head>`.
+ *
+ * `dangerouslySetInnerHTML={{ __html: themeChoiceScript('tf') }}` in a Next
+ * root layout, above everything. It reads the stored id, checks it against
+ * what this app offers, and writes `data-theme` on `<html>`.
+ *
+ * Wrapped in try/catch because `localStorage` throws outright in a browser
+ * set to block site data, and an exception here happens before anything is
+ * drawn -- so the page that fails to read a preference would otherwise fail
+ * to render at all.
+ */
+export function themeChoiceScript(product, options = {}) {
+    const p = resolve(product);
+    const ids = themeChoices(product, options.only).map((c) => c.id);
+    const key = JSON.stringify(options.storageKey ?? THEME_STORAGE_KEY);
+    const fallback = JSON.stringify(ids.includes(p.defaultTheme) ? p.defaultTheme : (ids[0] ?? p.defaultTheme));
+    return `(function(){try{var t=localStorage.getItem(${key});document.documentElement.dataset.theme=${JSON.stringify(ids)}.indexOf(t)>=0?t:${fallback}}catch(e){}})()`;
+}
+/** What the script would have written, for code that needs the same answer
+ *  after hydration. Reads the same key and applies the same fallback. */
+export function storedTheme(product, options = {}) {
+    const p = resolve(product);
+    const ids = themeChoices(product, options.only).map((c) => c.id);
+    const fallback = ids.includes(p.defaultTheme) ? p.defaultTheme : (ids[0] ?? p.defaultTheme);
+    try {
+        const stored = localStorage.getItem(options.storageKey ?? THEME_STORAGE_KEY);
+        return stored && ids.includes(stored) ? stored : fallback;
+    }
+    catch {
+        return fallback;
+    }
+}

package/dist/valet.css

@@ -3392,6 +3392,70 @@ input[type='range'].slider:disabled::-moz-range-thumb { opacity: 0; }
 
 .secret-lg > .secret-eye { padding: var(--space-2); }
 
+/* An input with something inside its edges: a glyph on the left, a hint or a
+   clear button on the right. Same arrangement as `.secret` above, and for the
+   same reason -- one grid cell with everything stacked in it, and the room
+   reserved in the input's own padding, so nothing is positioned against a
+   height that changes with `size`. */
+.adorned { display: grid; align-items: center; }
+
+.adorned > input,
+.adorned > .adorned-mark,
+.adorned > .adorned-end { grid-area: 1 / 1; }
+
+.adorned.block { width: 100%; }
+
+.adorned > .adorned-mark {
+  justify-self: start;
+  margin-left: var(--space-2);
+  color: var(--muted);
+  /* The glyph is decoration over the box; clicks belong to the input under
+     it, which is otherwise unreachable in its own left edge. */
+  pointer-events: none;
+  /* Over the input, not under it. Both share one grid cell, the input has an
+     opaque `--control` background, and it comes later in the DOM -- so
+     without this the glyph is painted and then covered, which looks exactly
+     like an icon that failed to render. `.secret` never hit this because its
+     button is written after the input. */
+  z-index: 1;
+}
+
+/* Room for the glyph, on the scale, so a density change moves the text with
+   the mark rather than leaving one behind. `--space-8` is what `.secret`
+   reserves on the right for the same reason; the scale has no 7, and an
+   undefined custom property does not fall back -- the declaration computes
+   to 0 and the text sits under the glyph. */
+.adorned-icon > input { padding-left: var(--space-8); }
+
+/* No `--space-12` on the scale; two steps that are, added. Same arithmetic
+   as `.secret-lg`. */
+.adorned-icon.adorned-lg > input { padding-left: calc(var(--space-10) + var(--space-1)); }
+
+.adorned > .adorned-end {
+  justify-self: end;
+  display: flex;
+  align-items: center;
+  gap: var(--space-1);
+  margin-right: var(--space-1);
+}
+
+/* `:has`, not a sibling combinator: the input comes *before* the end cap in
+   the DOM, so `~` reads the wrong way and matches nothing. */
+.adorned:has(> .adorned-end) > input { padding-right: var(--space-8); }
+.adorned-lg:has(> .adorned-end) > input {
+  padding-right: calc(var(--space-10) + var(--space-1));
+}
+
+/* Sized from its glyph, not `.icon-btn`'s 34px tile, which would be taller
+   than a small input -- the note above `.secret-eye` in full. */
+.adorned-clear {
+  width: auto; height: auto;
+  padding: var(--space-1);
+  opacity: 1;
+}
+
+.adorned-lg .adorned-clear { padding: var(--space-2); }
+
 /* ---- ./tour.css ---- */
 /* tour ----------------------------------------------------------------- */
 
@@ -3525,6 +3589,84 @@ input[type='range'].slider:disabled::-moz-range-thumb { opacity: 0; }
 .stat[data-tone='warn'] .stat-value { color: var(--warn); }
 .stat[data-tone='bad'] .stat-value { color: var(--bad); }
 
+/* ---- ./shell.css ---- */
+/* The frame. Layout only: every colour and every step is a token, and the
+   page inside it owns its own spacing. */
+.shell {
+  display: flex;
+  flex-direction: column;
+  min-height: 100vh;
+  background: var(--bg);
+  color: var(--text);
+}
+
+.shell-head {
+  border-bottom: var(--border-width) solid var(--border);
+  background: var(--panel);
+  /* `flex: none` so a long page does not squeeze the header. */
+  flex: none;
+}
+
+/* The measure, said once. `--shell-measure` rather than a literal so an app
+   with a different one sets a variable instead of overriding three rules and
+   missing the fourth -- which is how manage ended up with `head-inner-wide`
+   and `main-wide` as separate classes. */
+.shell {
+  --shell-measure: 64rem;
+  --shell-measure-wide: 90rem;
+}
+
+.shell-head-inner,
+.shell-nav,
+.shell-main {
+  width: 100%;
+  max-width: var(--shell-measure);
+  margin-inline: auto;
+  padding-inline: var(--space-4);
+}
+
+.shell-wide { max-width: var(--shell-measure-wide); }
+
+.shell-head-inner {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--space-4);
+  padding-block: var(--space-3);
+  min-width: 0;
+}
+
+.shell-who {
+  display: flex;
+  align-items: center;
+  gap: var(--space-3);
+  min-width: 0;
+}
+
+.shell-nav { padding-bottom: var(--space-2); }
+
+.shell-main {
+  flex: 1;
+  padding-block: var(--space-6);
+  /* `min-width: 0` because a flex child will not shrink below its content,
+     and one wide table inside then pushes the whole page sideways. */
+  min-width: 0;
+}
+
+/* The label beside the theme control, when it is drawn. */
+.theme-switch {
+  display: flex;
+  align-items: center;
+  gap: var(--space-2);
+  min-width: 0;
+}
+
+.theme-switch-label {
+  color: var(--muted);
+  font-size: var(--text-sm);
+  white-space: nowrap;
+}
+
 /* ---- ./scrollarea.css ---- */
 /* A box that scrolls, with its edges drawn.
    

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/design",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "wtfalch's design system: themeable components on a fixed token vocabulary.",
   "keywords": [
     "design-system",