@usableapp/cardds 0.7.14 → 0.7.16

package/dist/choice/Mood.d.ts

@@ -1,11 +1,16 @@
 import type { ComponentProps } from 'react';
-export interface MoodProps extends Omit<ComponentProps<'fieldset'>, 'onChange'> {
+type MoodValue = 1 | 2 | 3 | 4 | 5;
+export interface MoodProps extends Omit<ComponentProps<'fieldset'>, 'onChange' | 'defaultValue'> {
     /** the radio group name */
     name?: string;
-    /** the picked dot, 1 (worst) to 5 (best) */
-    value?: 1 | 2 | 3 | 4 | 5;
+    /** CONTROLLED: the picked dot, 1 (worst) to 5 (best) — with `onChange`; or `defaultValue` */
+    value?: MoodValue;
+    /** UNCONTROLLED: the dot picked on arrival; the Mood then keeps its own */
+    defaultValue?: MoodValue;
     label?: string;
-    onChange?: React.ChangeEventHandler<HTMLInputElement>;
+    /** the dot the member tapped */
+    onChange?: (value: MoodValue) => void;
 }
 /** Mood — five dots in a pill from bad to good; the picked one grows. */
-export declare function Mood({ name, value, label, onChange, className, ...rest }: MoodProps): import("react").JSX.Element;
+export declare function Mood({ name, value, defaultValue, label, onChange, className, ...rest }: MoodProps): import("react").JSX.Element;
+export {};

package/dist/choice/Mood.js

@@ -1,6 +1,8 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cx } from '../cx.js';
+import { useControlled } from '../state.js';
 /** Mood — five dots in a pill from bad to good; the picked one grows. */
-export function Mood({ name = 'mood', value, label = 'Mood', onChange, className, ...rest }) {
-    return (_jsx("fieldset", { className: cx('mood', className), "aria-label": label, ...rest, children: [1, 2, 3, 4, 5].map((n) => (_jsxs("label", { className: "mood__opt", children: [_jsx("input", { type: "radio", name: name, value: n, defaultChecked: n === value, onChange: onChange }), _jsx("span", { className: "mood__dot" })] }, n))) }));
+export function Mood({ name = 'mood', value, defaultValue, label = 'Mood', onChange, className, ...rest }) {
+    const [picked, setOwn] = useControlled(value, defaultValue);
+    return (_jsx("fieldset", { className: cx('mood', className), "aria-label": label, ...rest, children: [1, 2, 3, 4, 5].map((n) => (_jsxs("label", { className: "mood__opt", children: [_jsx("input", { type: "radio", name: name, value: n, checked: n === picked, onChange: () => { setOwn(n); onChange?.(n); } }), _jsx("span", { className: "mood__dot" })] }, n))) }));
 }

package/dist/forms/Pin.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useEffect, useRef, useState } from 'react';
+import { useControlled } from '../state.js';
 import { cx } from '../cx.js';
 import { useCheck } from './check.js';
 const RESET_MS = 900; // a code that does not match: red + shake this long, then the cells empty for a new try
@@ -11,12 +12,12 @@ const RESET_MS = 900; // a code that does not match: red + shake this long, then
  */
 export function Pin({ length = 6, value, defaultValue = '', label = 'Digit', onChange, autoFocus, error, match, formatError, secret, className, onAnimationEnd, ...rest }) {
     const ref = useRef(null);
-    const [inner, setInner] = useState(defaultValue);
-    const code = (value ?? inner).replace(/\D/g, '').slice(0, length);
+    const [typed, setOwn] = useControlled(value, defaultValue);
+    const code = typed.replace(/\D/g, '').slice(0, length);
     const cell = (i) => ref.current?.querySelectorAll('.pin__cell')[i];
     /* a miss — a match that failed, or the app's error: shake, red, then the cells empty for a new try on the same step */
-    const latest = useRef({ value, onChange, error });
-    latest.current = { value, onChange, error };
+    const latest = useRef({ setOwn, onChange, error });
+    latest.current = { setOwn, onChange, error };
     const miss = () => {
         restart.current = true;
         setShake(true);
@@ -25,8 +26,7 @@ export function Pin({ length = 6, value, defaultValue = '', label = 'Digit', onC
             setBad(false);
             setCleared(latest.current.error);
             restart.current = false;
-            if (latest.current.value === undefined)
-                setInner('');
+            latest.current.setOwn('');
             latest.current.onChange?.('', false);
             cell(0)?.focus();
         }, RESET_MS);
@@ -46,8 +46,7 @@ export function Pin({ length = 6, value, defaultValue = '', label = 'Digit', onC
             said.current = true;
             miss();
         }
-        if (value === undefined)
-            setInner(next);
+        setOwn(next);
         if (next !== code)
             onChange?.(next, next.length === length);
     };

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export { cx } from './cx.js';
 export * from './type/Icon.js';
 export { ICON_NAMES } from './type/icons.js';
 export * from './type/Text.js';
+export { setTextScale } from './type/textScale.js';
 export * from './scaffold/Screen.js';
 export * from './scaffold/AppBar.js';
 export * from './scaffold/TopBar.js';
@@ -72,7 +73,6 @@ export * from './media/Tile.js';
 export * from './media/Mosaic.js';
 export * from './layover/Banner.js';
 export * from './layover/Callout.js';
-export * from './layover/Deck.js';
 export * from './journey/Route.js';
 export * from './journey/TileBadge.js';
 export * from './journey/NoteRow.js';

package/dist/index.js

@@ -8,6 +8,7 @@ export { cx } from './cx.js';
 export * from './type/Icon.js';
 export { ICON_NAMES } from './type/icons.js';
 export * from './type/Text.js';
+export { setTextScale } from './type/textScale.js';
 export * from './scaffold/Screen.js';
 export * from './scaffold/AppBar.js';
 export * from './scaffold/TopBar.js';
@@ -76,7 +77,6 @@ export * from './media/Tile.js';
 export * from './media/Mosaic.js';
 export * from './layover/Banner.js';
 export * from './layover/Callout.js';
-export * from './layover/Deck.js';
 export * from './journey/Route.js';
 export * from './journey/TileBadge.js';
 export * from './journey/NoteRow.js';

package/dist/lists/Row.d.ts

@@ -41,7 +41,8 @@ export interface RowProps extends Omit<ComponentProps<'div'>, 'title'> {
  */
 export declare function Row({ lead, leadIcon, title, meta, body, end, endValue, endCaption, lg, done, as, href, more, open, defaultOpen, onOpenChange, className, children, ...rest }: RowProps): import("react").JSX.Element;
 export interface RowsProps extends ComponentProps<'div'> {
-    /** the group's name, above its rows (Today · Tomorrow · Later): a long list is GROUPED, not spaced out — several Rows one after another */
+    /** the group's name, above its rows (Today · Tomorrow · Later): a long list is GROUPED, not spaced out — several Rows one after another.
+     *  Words = the small label; an ELEMENT (`<Text level="title" as="h3">`) is used as the heading itself — the group is labelled by it. */
     heading?: ReactNode;
 }
 /** Rows — a list of Rows separated by hairlines; `heading` names the group (a `role="group"` labelled by it). */

package/dist/lists/Row.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { createElement, useId } from 'react';
+import { cloneElement, createElement, isValidElement, useId } from 'react';
 import { cx } from '../cx.js';
 import { Icon } from '../type/Icon.js';
 /**
@@ -22,5 +22,5 @@ export function Row({ lead, leadIcon, title, meta, body, end, endValue, endCapti
 export function Rows({ heading, className, children, ...rest }) {
     const id = useId();
     const named = heading != null;
-    return (_jsxs("div", { className: cx('rows', className), role: named ? 'group' : undefined, "aria-labelledby": named ? id : undefined, ...rest, children: [named && _jsx("span", { className: "rows__head", id: id, children: heading }), children] }));
+    return (_jsxs("div", { className: cx('rows', className), role: named ? 'group' : undefined, "aria-labelledby": named ? id : undefined, ...rest, children: [named && (isValidElement(heading) ? cloneElement(heading, { id }) : _jsx("span", { className: "rows__head", id: id, children: heading })), children] }));
 }

package/dist/media/Postcard.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useState } from 'react';
+import { useControlled } from '../state.js';
 import { cx } from '../cx.js';
 import { IconBtn } from '../actions/IconBtn.js';
 /**
@@ -9,10 +9,8 @@ import { IconBtn } from '../actions/IconBtn.js';
  * Who else liked it, a voice note, a reply go OUTSIDE it — a Row under it (`Row more` expands the list).
  */
 export function Postcard({ photo, alt = '', name, line, caption, voice, flipped, defaultFlipped = false, onFlip, liked, onLike, likeLabel = 'ถูกใจ', frontLabel = 'พลิกดูด้านหลัง', backLabel = 'พลิกดูด้านหน้า', className, ...rest }) {
-    const [inner, setInner] = useState(defaultFlipped);
-    const back = flipped ?? inner;
-    const turn = () => { if (flipped === undefined)
-        setInner(!back); onFlip?.(!back); };
+    const [back, setOwn] = useControlled(flipped, defaultFlipped);
+    const turn = () => { setOwn(!back); onFlip?.(!back); };
     const words = (_jsxs("div", { className: "postcard__words", children: [_jsx("span", { className: "t-h1", children: name }), line != null && _jsx("span", { className: "t-body", children: line })] }));
     return (_jsxs("div", { className: cx('postcard', back && 'is-flipped', className), ...rest, children: [_jsxs("div", { className: "postcard__face postcard__front", children: [_jsx("button", { className: "postcard__turn", type: "button", "aria-label": frontLabel, onClick: turn, children: photo ? _jsx("img", { src: photo, alt: alt }) : alt ? _jsx("div", { className: "ph", role: "img", "aria-label": alt }) : _jsx("div", { className: "ph" }) }), _jsxs("div", { className: "postcard__band", children: [words, (liked !== undefined || onLike) && _jsx(IconBtn, { invert: true, icon: "heart", label: likeLabel, "aria-pressed": !!liked, onClick: () => onLike?.(!liked) })] })] }), _jsxs("div", { className: "postcard__face postcard__back", children: [_jsxs("button", { className: "postcard__turn", type: "button", "aria-label": backLabel, onClick: turn, children: [words, caption != null && _jsx("p", { className: "postcard__caption", children: caption })] }), voice != null && _jsx("div", { className: "postcard__voice", children: voice })] })] }));
 }

package/dist/media/Tile.d.ts

@@ -32,7 +32,7 @@ export interface TileProps extends Omit<ComponentProps<'div'>, 'onChange'> {
     /** spans the whole grid */
     wide?: boolean;
     /** a slot tint */
-    tone?: 2 | 3;
+    tone?: 2 | 3 | 4 | 5;
     /** div (default), button for a tap tile — pick tiles render as a label */
     as?: 'div' | 'button';
 }

package/dist/numbers/Band.d.ts

@@ -6,7 +6,7 @@ export interface BandProps extends ComponentProps<'article'> {
     num: ReactNode;
     /** the footnote under the label */
     foot?: ReactNode;
-    tone?: 1 | 2 | 3;
+    tone?: 1 | 2 | 3 | 4 | 5;
 }
 /** Band — a data card: 2-line label · giant number · footnote. Stack several in a BandStack for one boundary with hairlines. */
 export declare function Band({ label, num, foot, tone, className, ...rest }: BandProps): import("react").JSX.Element;

package/dist/numbers/Picker.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { createContext, useContext, useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { createContext, useContext, useEffect, useLayoutEffect, useRef } from 'react';
+import { useControlled } from '../state.js';
 import { cx } from '../cx.js';
 const PickerContext = createContext(null);
 /**
@@ -9,16 +10,14 @@ const PickerContext = createContext(null);
  * settled in the centre. The CSS lights the centred item by scroll position; the app never reads the DOM to know what was picked.
  */
 export function Picker({ value, defaultValue, onChange, unit, label, className, children, ...rest }) {
-    const [inner, setInner] = useState(defaultValue);
-    const current = value ?? inner;
+    const [current, setOwn] = useControlled(value, defaultValue);
     const rail = useRef(null);
     const mounted = useRef(false);
     const settle = useRef(null);
     const pick = (next) => {
         if (next === current)
             return;
-        if (value === undefined)
-            setInner(next);
+        setOwn(next);
         onChange?.(next);
     };
     const items = () => [...(rail.current?.querySelectorAll(':scope > .picker__item') ?? [])];

package/dist/numbers/Track.d.ts

@@ -7,6 +7,8 @@ export declare function Track({ label, className, ...rest }: TrackProps): import
 export interface TrackStepProps extends ComponentProps<'li'> {
     /** this step (and the connector into it) is done */
     done?: boolean;
+    /** the step's NUMBER in the round instead of an Icon (1, 2, 3…) — a walk whose steps are counted, not pictured */
+    num?: number;
 }
-/** TrackStep — one step of a Track: an Icon in a round; lit when done. */
-export declare function TrackStep({ done, className, ...rest }: TrackStepProps): import("react").JSX.Element;
+/** TrackStep — one step of a Track: an Icon (children) or its number (`num`) in a round; lit when done. */
+export declare function TrackStep({ done, num, className, children, ...rest }: TrackStepProps): import("react").JSX.Element;

package/dist/numbers/Track.js

@@ -4,7 +4,7 @@ import { cx } from '../cx.js';
 export function Track({ label = 'Progress', className, ...rest }) {
     return _jsx("ol", { className: cx('track', className), "aria-label": label, ...rest });
 }
-/** TrackStep — one step of a Track: an Icon in a round; lit when done. */
-export function TrackStep({ done, className, ...rest }) {
-    return _jsx("li", { className: cx('track__step', done && 'is-done', className), ...rest });
+/** TrackStep — one step of a Track: an Icon (children) or its number (`num`) in a round; lit when done. */
+export function TrackStep({ done, num, className, children, ...rest }) {
+    return _jsx("li", { className: cx('track__step', done && 'is-done', className), ...rest, children: num != null ? _jsx("span", { className: "track__dot", children: num }) : children });
 }

package/dist/people/AvatarPick.d.ts

@@ -13,6 +13,8 @@ export interface AvatarPickItemProps extends Omit<ComponentProps<'button'>, 'nam
     role?: ReactNode;
     /** the Avatar (lg) */
     children?: ReactNode;
+    /** this person is the one picked (aria-pressed; the app keeps which) */
+    selected?: boolean;
 }
 /** AvatarPickItem — one person in an AvatarPick: an `Avatar size="lg"`, a name, a role. */
-export declare function AvatarPickItem({ name, role, className, children, ...rest }: AvatarPickItemProps): import("react").JSX.Element;
+export declare function AvatarPickItem({ name, role, selected, className, children, ...rest }: AvatarPickItemProps): import("react").JSX.Element;

package/dist/people/AvatarPick.js

@@ -5,6 +5,6 @@ export function AvatarPick({ bleed, label, className, ...rest }) {
     return _jsx("div", { className: cx('avatar-pick', bleed && 'bleed', className), "aria-label": label, ...rest });
 }
 /** AvatarPickItem — one person in an AvatarPick: an `Avatar size="lg"`, a name, a role. */
-export function AvatarPickItem({ name, role, className, children, ...rest }) {
-    return (_jsxs("button", { type: "button", className: cx('avatar-pick__item', className), ...rest, children: [children, _jsx("span", { className: "avatar-pick__name", children: name }), role != null && _jsx("span", { className: "avatar-pick__role", children: role })] }));
+export function AvatarPickItem({ name, role, selected, className, children, ...rest }) {
+    return (_jsxs("button", { type: "button", className: cx('avatar-pick__item', className), "aria-pressed": selected, ...rest, children: [children, _jsx("span", { className: "avatar-pick__name", children: name }), role != null && _jsx("span", { className: "avatar-pick__role", children: role })] }));
 }

package/dist/scaffold/Centre.d.ts

@@ -3,7 +3,7 @@ export interface CentreProps extends ComponentProps<'div'> {
 }
 /**
  * Centre — the centred group: ONE thing to read at the human centre of the screen, when that thing is not a lone
- * card: an EmptyState; a Card with its quiet second Btn and the PagerAt under it; a Deck with its DeckActions.
+ * card: an EmptyState; a Card with its quiet second Btn and the PagerAt under it.
  * On a plain `Screen` (the usual case, Lh 2026-09-12) it is in flow: the column is one phone tall, the group takes
  * the room after the TopBar and centres a short card; a long card makes the page longer and scrolls up under the
  * bar — nothing is capped, nothing shrinks. On a `Screen fill` it floats at 40% down (`--screen-centre`), capped

package/dist/scaffold/Centre.js

@@ -3,7 +3,7 @@ import { flushSync } from 'react-dom';
 import { cx } from '../cx.js';
 /**
  * Centre — the centred group: ONE thing to read at the human centre of the screen, when that thing is not a lone
- * card: an EmptyState; a Card with its quiet second Btn and the PagerAt under it; a Deck with its DeckActions.
+ * card: an EmptyState; a Card with its quiet second Btn and the PagerAt under it.
  * On a plain `Screen` (the usual case, Lh 2026-09-12) it is in flow: the column is one phone tall, the group takes
  * the room after the TopBar and centres a short card; a long card makes the page longer and scrolls up under the
  * bar — nothing is capped, nothing shrinks. On a `Screen fill` it floats at 40% down (`--screen-centre`), capped

package/dist/scaffold/Screen.d.ts

@@ -1,5 +1,5 @@
 import { type ComponentProps, type ReactNode, type Ref } from 'react';
-export type Palette = 'clay' | 'shine' | 'field' | 'roast' | 'hydro';
+export type Palette = 'clay' | 'roast' | 'hydro' | 'orchard' | 'vers';
 export interface ScreenProps extends ComponentProps<'div'> {
     /** exactly one phone height (100dvh), clipped: the box a Step or a SheetStack fills — an app screen, not a scrolling page */
     fill?: boolean;

package/dist/scaffold/Screen.js

@@ -1,6 +1,6 @@
 import { createElement, useEffect, useRef } from 'react';
+import { warnOnce } from '../state.js';
 import { cx } from '../cx.js';
-let warnedSheetBar = false;
 /**
  * Screen — the mobile screen in THREE parts: **top** and **content** (the children) in one flex column, the content down to the
  * screen's foot; **bottom** a LAYER over it there (Lh 2026-09-23). Top = `TopBar` / `AppBar`, or `top="lead"` (no bar, the words start
@@ -12,10 +12,9 @@ export function Screen({ fill, palette, as = 'div', top, bottom, className, chil
     const own = useRef(null);
     useEffect(() => {
         const el = own.current;
-        if (warnedSheetBar || !el || !el.querySelector(':scope > .action-bar') || !el.querySelector(':scope > .step > .sheet'))
+        if (!el || !el.querySelector(':scope > .action-bar') || !el.querySelector(':scope > .step > .sheet'))
             return;
-        warnedSheetBar = true;
-        console.warn('cardds Screen: a bottom bar on a screen with a Sheet — the sheet finishes on its own foot (CardFoot); drop the bar.');
+        warnOnce('screen-sheet-bar', 'cardds Screen: a bottom bar on a screen with a Sheet — the sheet finishes on its own foot (CardFoot); drop the bar.');
     });
     /* the BOTTOM layer's height, published on the screen as --bottom-h (Lh 2026-09-23): the walk's pages end with that much room
        more, so every last word scrolls up clear of the layer. Measured, because the layer is as tall as its rows and the text size. */

package/dist/scaffold/TopBar.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useRef } from 'react';
+import { warnOnce } from '../state.js';
 import { cx } from '../cx.js';
 /**
  * TopBar — the screen's title bar: back · TITLE · actions. Same 60px floor as the AppBar.
@@ -9,12 +10,9 @@ export function TopBar({ title, back, actions, className, children, ...rest }) {
     const acts = useRef(null);
     useEffect(() => {
         const n = acts.current?.childElementCount ?? 0;
-        if (n > MAX_ACTIONS && !warned) {
-            warned = true;
-            console.warn(`cardds TopBar: ${n} actions — at most ${MAX_ACTIONS} are drawn; put the rest in a Menu behind one button`);
-        }
+        if (n > MAX_ACTIONS)
+            warnOnce('topbar', `cardds TopBar: ${n} actions — at most ${MAX_ACTIONS} are drawn; put the rest in a Menu behind one button`);
     });
     return (_jsxs("header", { className: cx('topbar', className), ...rest, children: [back, _jsx("h1", { className: "t-h1", children: title }), children, actions != null && _jsx("div", { className: "topbar__actions", ref: acts, children: actions })] }));
 }
 const MAX_ACTIONS = 2;
-let warned = false;

package/dist/sheets/Sheet.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useCallback, useEffect, useRef, useState } from 'react';
+import { useCallback, useEffect, useRef } from 'react';
+import { useControlled } from '../state.js';
 import { cx } from '../cx.js';
 const ORDER = ['peek', 'half', '3q', 'full']; // low → high; `away` is below them all and outside them
 const TAP_REM = 0.5; // = --sp-2: a move shorter than this is a tap, not a drag
@@ -16,9 +17,7 @@ const TAP_REM = 0.5; // = --sp-2: a move shorter than this is a tap, not a drag
  * climbs until the focused control has room above the foot.
  */
 export function Sheet({ state, defaultState = 'half', onStateChange, states, handle = true, className, children, onFocus, ...rest }) {
-    const [inner, setInner] = useState(defaultState);
-    const current = state ?? inner;
-    const controlled = state !== undefined;
+    const [current, setOwn] = useControlled(state, defaultState);
     const ref = useRef(null);
     const handleRef = useRef(null);
     const home = useRef(current !== 'peek' && current !== 'away' ? current : 'half'); // where a tap from peek returns to
@@ -32,10 +31,9 @@ export function Sheet({ state, defaultState = 'half', onStateChange, states, han
     const request = useCallback((next, reason) => {
         if (next === current)
             return;
-        if (!controlled)
-            setInner(next);
+        setOwn(next);
         onStateChange?.(next, reason);
-    }, [current, controlled, onStateChange]);
+    }, [current, setOwn, onStateChange]);
     useEffect(() => {
         if (current !== 'peek' && current !== 'away')
             home.current = current;

package/dist/sheets/SheetStack.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useLayoutEffect, useRef, useState } from 'react';
+import { useLayoutEffect, useRef } from 'react';
+import { useControlled } from '../state.js';
 import { cx } from '../cx.js';
 const PHASE = 380; // ms before the before-pack un-tucks on close, so the after-pack is clear first
 /* the stack's sheets, in slot order: its direct children — or, where a host wraps each child in one box of its own, the first .card in
@@ -23,16 +24,14 @@ const sheetsOf = (stack) => [...stack.children]
  * before tuck under nearest-first; closing reverses in two beats. Only `translate` (stack.css); it sets classes, never a size.
  */
 export function SheetStack({ mode = 'tap', open, defaultOpen = null, onOpenChange, fanned, closed, base, className, children, onClick, ...rest }) {
-    const [inner, setInner] = useState(defaultOpen);
-    const current = open !== undefined ? open : inner;
+    const [current, setOwn] = useControlled(open, defaultOpen);
     const ref = useRef(null);
     const was = useRef(null);
     const untuck = useRef(null);
     const request = (next) => {
         if (next === current)
             return;
-        if (open === undefined)
-            setInner(next);
+        setOwn(next);
         onOpenChange?.(next);
     };
     /* paint the state onto the sheets — after every render, so a re-rendered Card never loses its place */

package/dist/sheets/SheetSteps.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Children, cloneElement, createContext, isValidElement, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import { useControlled, reducedMotion } from '../state.js';
 import { cx } from '../cx.js';
 import { Icon } from '../type/Icon.js';
 import { Link } from '../actions/Link.js';
@@ -17,8 +18,7 @@ const StepCtx = createContext(null);
  * The sheet may be dragged down to peek and back — the body keeps where it was scrolled.
  */
 export function SheetSteps({ at, reached, defaultAt = 0, onAtChange, reversible = false, numbered = false, finish, className, style, children, onFocus, onBlur, onPointerDown, onPointerUp, onPointerCancel, ...rest }) {
-    const [inner, setInner] = useState(defaultAt);
-    const current = at ?? inner;
+    const [current, setOwn] = useControlled(at, defaultAt);
     const steps = Children.toArray(children).filter(isValidElement);
     const count = steps.length;
     /* how far the member has come: a step before it was DONE (its work, or skipped) — it stays done when they go back to look */
@@ -41,8 +41,7 @@ export function SheetSteps({ at, reached, defaultAt = 0, onAtChange, reversible
     const go = (i, reason) => {
         if (i === current || i < 0 || i > count)
             return;
-        if (at === undefined)
-            setInner(i);
+        setOwn(i);
         onAtChange?.(i, reason);
     };
     /* how far the body is scrolled when a step opens or a field in it takes the keyboard: the TWO latest done rows always show
@@ -72,7 +71,7 @@ export function SheetSteps({ at, reached, defaultAt = 0, onAtChange, reversible
         if (Math.abs(to - body.scrollTop) <= 1)
             return;
         // the pile SCROLLS there, animated (Lh 2026-09-24) — the browser's own smooth scroll; its frames are not replayed as jumps
-        const smooth = !matchMedia('(prefers-reduced-motion: reduce)').matches;
+        const smooth = !reducedMotion();
         own.current = performance.now() + (smooth ? 700 : 0);
         body.scrollTo({ top: to, behavior: smooth ? 'smooth' : 'auto' });
     };
@@ -127,7 +126,7 @@ export function SheetSteps({ at, reached, defaultAt = 0, onAtChange, reversible
         const onScroll = () => {
             const d = body.scrollTop - last.current;
             last.current = body.scrollTop;
-            if (!d || performance.now() > glide.current || performance.now() < own.current || matchMedia('(prefers-reduced-motion: reduce)').matches)
+            if (!d || performance.now() > glide.current || performance.now() < own.current || reducedMotion())
                 return;
             const from = parseFloat(el.style.translate.split(' ')[1] || '0') || 0;
             el.style.transition = 'none';

package/dist/sheets/StackSheet.d.ts

@@ -12,7 +12,7 @@ export interface StackSheetProps extends Omit<ComponentProps<'article'>, 'title'
     /** the SHEET HEAD's title — an h2 (the page's h1 is its own) */
     title: ReactNode;
     /** the paper: 1 light · 2 tinted · 3 dark */
-    tone?: 1 | 2 | 3;
+    tone?: 1 | 2 | 3 | 4 | 5;
     /** the head's end when the sheet has no tabs: an Icon, an IconRow */
     icon?: ReactNode;
     /** TABS in the head: icon buttons at the end — the sheet's pages. A tap on one in a peeked head opens the sheet on it */

package/dist/sheets/StackSheet.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useRef, useState } from 'react';
+import { useEffect, useRef } from 'react';
+import { useControlled } from '../state.js';
 import { cx } from '../cx.js';
 import { Card } from '../cards/Card.js';
 import { CardHead } from '../cards/CardHead.js';
@@ -16,10 +17,8 @@ import { Badge } from '../numbers/Badge.js';
  * is closed — see `Home`). A direct child of `SheetStack`.
  */
 export function StackSheet({ title, tone, icon, tabs, tab: tabProp, defaultTab, onTabChange, foot, backLabel = 'Back', className, children, ...rest }) {
-    const [own, setOwn] = useState(defaultTab ?? tabs?.[0]?.id);
-    const tab = tabProp ?? own;
-    const pick = (id) => { if (tabProp === undefined)
-        setOwn(id); onTabChange?.(id); };
+    const [tab, setOwn] = useControlled(tabProp, defaultTab ?? tabs?.[0]?.id);
+    const pick = (id) => { setOwn(id); onTabChange?.(id); };
     // a title longer than its room does not wrap: it runs sideways, like a song title in a short slot — the room it overflows by
     // is measured here (the tabs may grow with the text size) and handed to the CSS as --_over
     const titleRef = useRef(null);

package/dist/state.d.ts

@@ -0,0 +1,7 @@
+/** controlled like an input: `value` given = the app owns it; undefined = the component keeps its own, starting at `initial`.
+ *  Returns the value shown and a setter that only moves the component's own copy — the caller still ASKS the app (onXChange). */
+export declare function useControlled<T>(value: T | undefined, initial: T): [T, (next: T) => void];
+/** a dev hint said once per key, never again */
+export declare const warnOnce: (key: string, text: string) => void;
+/** the member asked for less motion (false where there is no window, e.g. a server render) */
+export declare const reducedMotion: () => boolean;

package/dist/state.js

@@ -0,0 +1,17 @@
+import { useState } from 'react';
+/** controlled like an input: `value` given = the app owns it; undefined = the component keeps its own, starting at `initial`.
+ *  Returns the value shown and a setter that only moves the component's own copy — the caller still ASKS the app (onXChange). */
+export function useControlled(value, initial) {
+    const [own, setOwn] = useState(initial);
+    const controlled = value !== undefined;
+    return [controlled ? value : own, (next) => { if (!controlled)
+            setOwn(next); }];
+}
+const warned = new Set();
+/** a dev hint said once per key, never again */
+export const warnOnce = (key, text) => { if (!warned.has(key)) {
+    warned.add(key);
+    console.warn(text);
+} };
+/** the member asked for less motion (false where there is no window, e.g. a server render) */
+export const reducedMotion = () => typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;

package/dist/templates/CallSheet.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useState } from 'react';
+import { useControlled } from '../state.js';
 import { Screen } from '../scaffold/Screen.js';
 import { Step } from '../sheets/Step.js';
 import { Page, CtaPack } from '../scaffold/Page.js';
@@ -18,11 +19,9 @@ const index = (o) => (o === true ? 0 : typeof o === 'number' ? o : null);
  */
 export function CallSheet({ media, heading, body, action, sheet, ways, open: openProp, defaultOpen = null, onOpenChange, states = 'peek full', children, ...rest }) {
     const list = ways ?? (sheet ? [{ action, sheet }] : []);
-    const [own, setOwn] = useState(index(defaultOpen));
-    const on = openProp === undefined ? own : index(openProp);
+    const [on, setOwn] = useControlled(openProp === undefined ? undefined : index(openProp), index(defaultOpen));
     const [at, setAt] = useState('full');
-    const set = (next) => { if (openProp === undefined)
-        setOwn(next); onOpenChange?.(next !== null, next); };
+    const set = (next) => { setOwn(next); onOpenChange?.(next !== null, next); };
     return (_jsxs(Screen, { fill: true, ...rest, children: [_jsxs(Step, { children: [_jsxs(Page, { children: [media, _jsx(CardHead, { level: "h1", heading: heading }), typeof body === 'string' ? _jsx(Text, { level: "body", children: body }) : body, _jsx(CtaPack, { children: list.map((w, i) => (_jsx(Btn, { primary: i === 0, quiet: i > 0, "aria-expanded": on === i, onClick: () => { setAt('full'); set(i); }, children: w.action }, i))) })] }), list.map(({ sheet: sh }, i) => (_jsxs(Sheet, { state: on === i ? at : 'away', onStateChange: (s) => { if (s === 'away')
                             set(null);
                         else

package/dist/templates/Home.d.ts

@@ -7,7 +7,7 @@ export interface HomeSheet {
     /** the sheet head's end when it has no tabs: an Icon, an IconRow */
     icon?: ReactNode;
     /** the paper: 1 light · 2 tinted · 3 dark (default: 2, 3, 1, 2, 3 by place) */
-    tone?: 1 | 2 | 3;
+    tone?: 1 | 2 | 3 | 4 | 5;
     /** the sheet's pages as icon tabs in its head (a count shows as a small circle over the icon) — see `StackSheet` */
     tabs?: StackSheetTab[];
     /** the tab shown first (default: the first) */

package/dist/templates/Home.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useState } from 'react';
+import { useControlled } from '../state.js';
 import { Screen } from '../scaffold/Screen.js';
 import { SheetStack } from '../sheets/SheetStack.js';
 import { StackSheet } from '../sheets/StackSheet.js';
@@ -14,8 +15,7 @@ const LEAVE = 800; // ms: a closing sheet keeps its body until it has slid home
  * sections on one home never cost three pages (`keep` holds a body once opened).
  */
 export function Home({ top, title, sheets, open: openProp, defaultOpen = null, onOpenChange, base, keep, backLabel = 'Back', children, ...rest }) {
-    const [own, setOwn] = useState(defaultOpen);
-    const open = openProp !== undefined ? openProp : own;
+    const [open, setOwn] = useControlled(openProp, defaultOpen);
     const [leaving, setLeaving] = useState(null);
     const [seen, setSeen] = useState(() => new Set(open != null ? [open] : []));
     const [was, setWas] = useState(open);
@@ -32,8 +32,7 @@ export function Home({ top, title, sheets, open: openProp, defaultOpen = null, o
         const t = setTimeout(() => setLeaving(null), LEAVE);
         return () => clearTimeout(t);
     }, [leaving]);
-    const change = (next) => { if (openProp === undefined)
-        setOwn(next); onOpenChange?.(next); };
+    const change = (next) => { setOwn(next); onOpenChange?.(next); };
     const [tabs, setTabs] = useState(() => Object.fromEntries(sheets.map((x, i) => [i, x.defaultTab ?? x.tabs?.[0]?.id])));
     const shows = (i) => i === open || i === leaving || (keep && seen.has(i));
     return (_jsxs(Screen, { fill: true, top: top, ...rest, children: [_jsx(Text, { level: "h1", as: "h1", sr: true, children: title }), _jsx(SheetStack, { closed: true, open: open, onOpenChange: change, base: base, children: sheets.map((s, i) => (_jsx(StackSheet, { tone: s.tone ?? TONES[i], title: s.title, icon: s.icon, tabs: s.tabs, tab: tabs[i], onTabChange: (t) => setTabs((v) => ({ ...v, [i]: t })), backLabel: backLabel, foot: typeof s.foot === 'function' ? s.foot(tabs[i]) : s.foot, children: shows(i) ? (typeof s.body === 'function' ? s.body(tabs[i]) : s.body) : null }, i))) }), children] }));

package/dist/templates/Splash.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useRef, useState } from 'react';
+import { reducedMotion } from '../state.js';
 import { Screen } from '../scaffold/Screen.js';
 import { cx } from '../cx.js';
 /**
@@ -23,7 +24,7 @@ export function Splash({ mark, text, done, min = 0, onLeft, className, ...rest }
     useEffect(() => {
         if (!leaving)
             return;
-        const still = typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
+        const still = reducedMotion();
         const ms = still ? 0 : parseFloat(getComputedStyle(document.documentElement).getPropertyValue('--motion-sheet')) * 1000 || 350;
         const t = setTimeout(() => left.current?.(), ms);
         return () => clearTimeout(t);

package/dist/templates/Walkthrough.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
-import { useLayoutEffect, useRef, useState } from 'react';
+import { useLayoutEffect, useRef } from 'react';
+import { useControlled } from '../state.js';
 import { Screen } from '../scaffold/Screen.js';
 import { Step } from '../sheets/Step.js';
 import { Page } from '../scaffold/Page.js';
@@ -16,8 +17,7 @@ import { IconBtn } from '../actions/IconBtn.js';
  * first and fixed while the words scroll, one CTA row. Yours: the pages, the row, the state.
  */
 export function Walkthrough({ pages, at: atProp, defaultAt = 0, onAtChange, cta, controls = [], ctaLink, children, backLabel = 'Back', nextLabel = 'Next', ...rest }) {
-    const [own, setOwn] = useState(defaultAt);
-    const at = atProp ?? own;
+    const [at, setOwn] = useControlled(atProp, defaultAt);
     const step = useRef(null);
     // a new page starts where a page starts — at its lead, not where the last one was scrolled to (Lh 2026-09-23). A LAYOUT effect:
     // it runs inside the page turn's commit, before the view transition takes its picture — only the sideways slide shows, no scroll
@@ -27,8 +27,7 @@ export function Walkthrough({ pages, at: atProp, defaultAt = 0, onAtChange, cta,
     const go = (to) => {
         if (to < 0 || to >= count || to === at)
             return;
-        slideTo(to > at ? 'next' : 'back', () => { if (atProp === undefined)
-            setOwn(to); onAtChange?.(to); }, step.current ?? document);
+        slideTo(to > at ? 'next' : 'back', () => { setOwn(to); onAtChange?.(to); }, step.current ?? document);
     };
     /* a sideways SWIPE turns the page (Lh 2026-09-23): left = next, right = back. The walk still scrolls up and down itself
        (touch-action: pan-y); a swipe must be mostly sideways and long enough, so a scroll never turns a page */