@usableapp/cardds 0.7.15 → 0.7.17

package/dist/scaffold/Screen.js

@@ -1,6 +1,6 @@
 import { createElement, useEffect, useRef } from 'react';
+import { warnOnce, watchSize } 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. */
@@ -25,9 +24,7 @@ export function Screen({ fill, palette, as = 'div', top, bottom, className, chil
             el?.style.removeProperty('--bottom-h');
             return;
         }
-        const ro = new ResizeObserver(() => el.style.setProperty('--bottom-h', `${bar.offsetHeight}px`));
-        ro.observe(bar);
-        return () => ro.disconnect();
+        return watchSize([bar], () => el.style.setProperty('--bottom-h', `${bar.offsetHeight}px`));
     }, [bottom]);
     const setRef = (node) => {
         own.current = node;

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/Drawer.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Children, Fragment, useEffect, useRef } from 'react';
+import { useLatest } from '../state.js';
 import { cx } from '../cx.js';
 /**
  * Modal — the ask: ONE card at the centre of a `SheetStage dim`, two parts — a `Lift` (the thing being asked about, light, scrolls
@@ -11,8 +12,7 @@ import { cx } from '../cx.js';
  */
 export function Modal({ open = true, onClosed, onDismiss, className, ...rest }) {
     const ref = useRef(null);
-    const closed = useRef(onClosed);
-    closed.current = onClosed;
+    const closed = useLatest(onClosed);
     const shown = useRef(true); // the animations stand played forwards
     useEffect(() => {
         const el = ref.current;
@@ -28,8 +28,7 @@ export function Modal({ open = true, onClosed, onDismiss, className, ...rest })
             closed.current?.(); });
         return () => { live = false; };
     }, [open]);
-    const dismiss = useRef(onDismiss);
-    dismiss.current = onDismiss;
+    const dismiss = useLatest(onDismiss);
     const has = onDismiss !== undefined;
     useEffect(() => {
         const el = ref.current, stage = el?.parentElement;

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, watchSize } 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, request] = useControlled(state, defaultState, onStateChange);
     const ref = useRef(null);
     const handleRef = useRef(null);
     const home = useRef(current !== 'peek' && current !== 'away' ? current : 'half'); // where a tap from peek returns to
@@ -29,13 +28,6 @@ export function Sheet({ state, defaultState = 'half', onStateChange, states, han
         const list = (typeof states === 'string' ? states.split(/\s+/) : [...(states ?? [])]).filter((s) => ORDER.includes(s));
         return list.length ? ORDER.filter((s) => list.includes(s)) : [...ORDER];
     }, [states]);
-    const request = useCallback((next, reason) => {
-        if (next === current)
-            return;
-        if (!controlled)
-            setInner(next);
-        onStateChange?.(next, reason);
-    }, [current, controlled, onStateChange]);
     useEffect(() => {
         if (current !== 'peek' && current !== 'away')
             home.current = current;
@@ -105,10 +97,10 @@ export function Sheet({ state, defaultState = 'half', onStateChange, states, han
        in this sheet has the focus, make sure it still shows */
     useEffect(() => {
         const el = ref.current;
-        if (!el || typeof ResizeObserver === 'undefined')
+        if (!el)
             return;
-        let first = true;
-        const ro = new ResizeObserver(() => {
+        let first = true; // the browser's report at the start is not a resize
+        return watchSize([el, el.parentElement], () => {
             if (first) {
                 first = false;
                 return;
@@ -117,10 +109,6 @@ export function Sheet({ state, defaultState = 'half', onStateChange, states, han
             if (at && el.contains(at))
                 reveal(at, 'keyboard');
         });
-        ro.observe(el);
-        if (el.parentElement)
-            ro.observe(el.parentElement);
-        return () => ro.disconnect();
     }, [reveal]);
     /* the peek strip holds the handle and the WHOLE title row. CSS gives the box the strip for a one-line head (--sheet-peek in
        sheet.css); when the head is taller than that floor — a title wrapped on a narrow phone at a large text size — the sheet
@@ -128,7 +116,7 @@ export function Sheet({ state, defaultState = 'half', onStateChange, states, han
        22-base type scale). Removed when the head fits the floor again, so the CSS number is the one in force. */
     useEffect(() => {
         const el = ref.current, box = el?.parentElement, head = el?.querySelector(':scope > .card__head, :scope > .sheet__head');
-        if (!el || !box || !head || typeof ResizeObserver === 'undefined')
+        if (!el || !box || !head)
             return;
         const publish = () => {
             box.style.removeProperty('--sheet-peek'); // read the CSS strip, not our own
@@ -138,9 +126,8 @@ export function Sheet({ state, defaultState = 'half', onStateChange, states, han
             if (over > 0.5)
                 box.style.setProperty('--sheet-peek', `${strip + over}px`);
         };
-        const ro = new ResizeObserver(publish);
-        ro.observe(head);
-        return () => { ro.disconnect(); box.style.removeProperty('--sheet-peek'); };
+        const stop = watchSize([head], publish);
+        return () => { stop(); box.style.removeProperty('--sheet-peek'); };
     }, []);
     const focus = (e) => {
         onFocus?.(e);

package/dist/sheets/SheetStack.d.ts

@@ -21,7 +21,7 @@ export interface SheetStackProps extends ComponentProps<'div'> {
  * Children are Cards, direct children only, at most five: first = the back of the stack, last = the front (open) sheet.
  * Every sheet is the stack's full height; a peek is the strip the next sheet doesn't cover. A stack head is a CardHead
  * with CHILDREN, in this order: `<StackBack />` (tap mode), `<Text level="h2" caps>Shopping</Text>`, an `<IconRow>` of Icons —
- * never the `heading` prop (it wraps the h2 in a div; the stack's one-line peek needs the bare h2). Put it last in a `Screen fill`, it bleeds
+ * never the `heading` prop (a stack head is back · h2 · tabs on ONE line — StackSheet builds it). Put it last in a `Screen fill`, it bleeds
  * off the bottom. `closed`: nothing open on arrival — every head peeks at the bottom and the base above shows `base` (a home screen
  * with a picture over the menu); the `base` slot is rendered after the sheets, so it never takes a sheet's slot. This is the sheet STACK; a single bottom sheet is `Sheet`.
  *
@@ -30,4 +30,4 @@ export interface SheetStackProps extends ComponentProps<'div'> {
  * sheet's StackBack or its title (folds it). How the sheets MOVE is its own too: sheets are rigid — the tapped one slides up, the ones after it leave below, the ones
  * before tuck under nearest-first; closing reverses in two beats. Only `translate` (stack.css); it sets classes, never a size.
  */
-export declare function SheetStack({ mode, open, defaultOpen, onOpenChange, fanned, closed, base, className, children, onClick, ...rest }: SheetStackProps): import("react").JSX.Element;
+export declare function SheetStack({ mode, open, defaultOpen, onOpenChange, fanned, closed, base, className, children, onClick, onKeyDown, ...rest }: SheetStackProps): import("react").JSX.Element;

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
@@ -13,7 +14,7 @@ const sheetsOf = (stack) => [...stack.children]
  * Children are Cards, direct children only, at most five: first = the back of the stack, last = the front (open) sheet.
  * Every sheet is the stack's full height; a peek is the strip the next sheet doesn't cover. A stack head is a CardHead
  * with CHILDREN, in this order: `<StackBack />` (tap mode), `<Text level="h2" caps>Shopping</Text>`, an `<IconRow>` of Icons —
- * never the `heading` prop (it wraps the h2 in a div; the stack's one-line peek needs the bare h2). Put it last in a `Screen fill`, it bleeds
+ * never the `heading` prop (a stack head is back · h2 · tabs on ONE line — StackSheet builds it). Put it last in a `Screen fill`, it bleeds
  * off the bottom. `closed`: nothing open on arrival — every head peeks at the bottom and the base above shows `base` (a home screen
  * with a picture over the menu); the `base` slot is rendered after the sheets, so it never takes a sheet's slot. This is the sheet STACK; a single bottom sheet is `Sheet`.
  *
@@ -22,25 +23,24 @@ const sheetsOf = (stack) => [...stack.children]
  * sheet's StackBack or its title (folds it). How the sheets MOVE is its own too: sheets are rigid — the tapped one slides up, the ones after it leave below, the ones
  * 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;
+export function SheetStack({ mode = 'tap', open, defaultOpen = null, onOpenChange, fanned, closed, base, className, children, onClick, onKeyDown, ...rest }) {
+    const [current, request] = useControlled(open, defaultOpen, onOpenChange);
     const ref = useRef(null);
     const was = useRef(null);
     const untuck = useRef(null);
-    const request = (next) => {
-        if (next === current)
-            return;
-        if (open === undefined)
-            setInner(next);
-        onOpenChange?.(next);
-    };
     /* paint the state onto the sheets — after every render, so a re-rendered Card never loses its place */
     useLayoutEffect(() => {
         const stack = ref.current;
         if (!stack || mode !== 'tap')
             return;
         const sheets = sheetsOf(stack);
+        // the keyboard's way in: a head's title takes the focus where a tap on it would do something — every title while none is
+        // open (Enter opens that sheet), only the open one's while one is (Enter folds it)
+        sheets.forEach((c, i) => {
+            const title = c.querySelector(':scope > .card__head > :is(h1, h2, h3)');
+            if (title)
+                title.tabIndex = current == null || i === current ? 0 : -1;
+        });
         const prev = was.current;
         was.current = current;
         if (current != null) {
@@ -87,5 +87,12 @@ export function SheetStack({ mode = 'tap', open, defaultOpen = null, onOpenChang
         if (at >= 0 && current == null)
             request(at);
     };
-    return (_jsxs("div", { ref: ref, onClick: click, className: cx('sheet-stack', mode !== 'static' && `sheet-stack--${mode}`, fanned && 'sheet-stack--fanned', closed && 'sheet-stack--closed', className), ...rest, children: [children, base != null && _jsx("div", { className: "sheet-stack__base", children: base })] }));
+    const key = (e) => {
+        onKeyDown?.(e);
+        if ((e.key === 'Enter' || e.key === ' ') && e.target.matches('.card__head > :is(h1, h2, h3)')) {
+            e.preventDefault();
+            e.target.click();
+        }
+    };
+    return (_jsxs("div", { ref: ref, onClick: click, onKeyDown: key, className: cx('sheet-stack', mode !== 'static' && `sheet-stack--${mode}`, fanned && 'sheet-stack--fanned', closed && 'sheet-stack--closed', className), ...rest, children: [children, base != null && _jsx("div", { className: "sheet-stack__base", children: base })] }));
 }

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, request] = useControlled(at, defaultAt, onAtChange);
     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 */
@@ -39,11 +39,8 @@ export function SheetSteps({ at, reached, defaultAt = 0, onAtChange, reversible
     } // from the very render that changes it: the old field's blur and the keyboard's jump come in that same commit
     const press = useRef(null);
     const go = (i, reason) => {
-        if (i === current || i < 0 || i > count)
-            return;
-        if (at === undefined)
-            setInner(i);
-        onAtChange?.(i, reason);
+        if (i >= 0 && i <= count)
+            request(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
        above the open step, and half of the one before — older ones go up out of sight, one row at a time, so what was done never seems to vanish (Lh
@@ -72,7 +69,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 +124,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';
@@ -221,7 +218,7 @@ export function SheetStep({ title, summary, skippable, skipLabel = 'Skip', error
             e.preventDefault();
     };
     const press = (e) => {
-        const btn = e.target.closest('.btn');
+        const btn = e.target.closest('button.btn'); // a FileBtn is a label.btn: picking a file is not the step's press
         if (!btn || btn.disabled)
             return;
         let bad = null;
@@ -243,7 +240,7 @@ export function SheetStep({ title, summary, skippable, skipLabel = 'Skip', error
     const enter = (e) => {
         if (e.key !== 'Enter' || e.nativeEvent.isComposing || !(e.target instanceof HTMLInputElement))
             return;
-        const btn = e.currentTarget.querySelector('.btn:not(:disabled)');
+        const btn = e.currentTarget.querySelector('button.btn:not(:disabled)');
         if (btn) {
             e.preventDefault();
             btn.click();

package/dist/sheets/StackBack.js

@@ -1,8 +1,9 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { cx } from '../cx.js';
 import { Icon } from '../type/Icon.js';
+import { IconBtn } from '../actions/IconBtn.js';
 /** StackBack — the back button a tapped stack sheet reveals in its head; first child of that sheet's CardHead. Hidden until the sheet is open.
  * A SMALL disc (Lh 2026-09-23): 32px with a chevron — the head keeps its room for the title and the tabs; the 44px tap target stays. */
 export function StackBack({ label = 'Back', className, ...rest }) {
-    return (_jsx("button", { type: "button", className: cx('icon-btn icon-btn--sm sheet-stack__back', className), "aria-label": label, ...rest, children: _jsx(Icon, { name: "chevron-left" }) }));
+    return _jsx(IconBtn, { sm: true, label: label, className: cx('sheet-stack__back', className), ...rest, children: _jsx(Icon, { name: "chevron-left" }) });
 }

package/dist/sheets/StackSheet.d.ts

@@ -1,4 +1,5 @@
 import { type ComponentProps, type ReactNode } from 'react';
+import { type Tone } from '../cards/Card.js';
 import { type IconName } from '../type/Icon.js';
 export interface StackSheetTab {
     id: string;
@@ -11,8 +12,8 @@ export interface StackSheetTab {
 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 | 4 | 5;
+    /** the paper — see `Tone` */
+    tone?: Tone;
     /** 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,7 +1,9 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useRef, useState } from 'react';
+import { useEffect, useRef } from 'react';
+import { useControlled, watchSize } from '../state.js';
 import { cx } from '../cx.js';
 import { Card } from '../cards/Card.js';
+import { IconBtn } from '../actions/IconBtn.js';
 import { CardHead } from '../cards/CardHead.js';
 import { CardFoot } from '../cards/CardFoot.js';
 import { SheetBody } from './SheetBody.js';
@@ -16,16 +18,13 @@ 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, pick] = useControlled(tabProp, defaultTab ?? tabs?.[0]?.id, onTabChange);
     // 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);
     useEffect(() => {
         const h = titleRef.current, run = h?.firstElementChild;
-        if (!h || !run || typeof ResizeObserver === 'undefined')
+        if (!h || !run)
             return;
         const measure = () => {
             const over = Math.max(0, Math.ceil(run.scrollWidth - h.clientWidth));
@@ -33,11 +32,8 @@ export function StackSheet({ title, tone, icon, tabs, tab: tabProp, defaultTab,
             h.style.setProperty('--_run', `${(over / 30 + 3).toFixed(1)}s`);
             h.classList.toggle('is-long', over > 0);
         };
-        const ro = new ResizeObserver(measure);
-        ro.observe(h);
-        ro.observe(run);
         measure();
-        return () => ro.disconnect();
+        return watchSize([h, run], measure);
     }, [title]);
-    return (_jsxs(Card, { tone: tone, className: cx('stack-sheet', className), ...rest, children: [_jsxs(CardHead, { children: [_jsx(StackBack, { label: backLabel }), _jsx(Text, { level: "h2", ref: titleRef, className: "stack-sheet__title", children: _jsx("span", { className: "stack-sheet__run", children: title }) }), tabs?.length ? (_jsx("span", { className: "stack-sheet__tabs", role: "tablist", children: tabs.map((t) => (_jsxs("button", { type: "button", role: "tab", "aria-selected": t.id === tab, "aria-label": t.label, className: cx('icon-btn icon-btn--sm stack-sheet__tab', t.id === tab && 'icon-btn--invert'), onClick: () => pick(t.id), children: [_jsx(Icon, { name: t.icon }), t.count ? _jsx(Badge, { className: "stack-sheet__count", children: t.count > 99 ? '99+' : t.count }) : null] }, t.id))) })) : icon] }), _jsx(SheetBody, { role: tabs?.length ? 'tabpanel' : undefined, children: children }), foot != null && _jsx(CardFoot, { children: foot })] }));
+    return (_jsxs(Card, { tone: tone, className: cx('stack-sheet', className), ...rest, children: [_jsxs(CardHead, { children: [_jsx(StackBack, { label: backLabel }), _jsx(Text, { level: "h2", ref: titleRef, className: "stack-sheet__title", children: _jsx("span", { className: "stack-sheet__run", children: title }) }), tabs?.length ? (_jsx("span", { className: "stack-sheet__tabs", role: "tablist", children: tabs.map((t) => (_jsxs(IconBtn, { sm: true, invert: t.id === tab, role: "tab", "aria-selected": t.id === tab, label: t.label, className: "stack-sheet__tab", onClick: () => pick(t.id), children: [_jsx(Icon, { name: t.icon }), t.count ? _jsx(Badge, { className: "stack-sheet__count", children: t.count > 99 ? '99+' : t.count }) : null] }, t.id))) })) : icon] }), _jsx(SheetBody, { role: tabs?.length ? 'tabpanel' : undefined, children: children }), foot != null && _jsx(CardFoot, { children: foot })] }));
 }

package/dist/state.d.ts

@@ -0,0 +1,24 @@
+import { type SyntheticEvent } 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 `request(next, …extra)`: nothing when `next` is what shows; else it moves the component's own copy
+ *  (uncontrolled only) and ASKS the app — `onChange(next, …extra)`. `request` keeps one identity for the component's life. */
+type Asks<T, A extends unknown[]> = {
+    ask(next: T, ...extra: A): void;
+}['ask'];
+export declare function useControlled<T, A extends unknown[] = []>(value: T | undefined, initial: T, onChange?: Asks<T, A>): readonly [T, (next: T, ...extra: A) => void];
+/** a native `<details>` controlled like an input: `open` + `onOpenChange`, or `defaultOpen`. Spread the result on the details.
+ *  The browser opens it on a tap by itself — a controlled one is put back until the app says so. */
+export declare function useDisclosure(open: boolean | undefined, defaultOpen?: boolean, onOpenChange?: (open: boolean) => void): {
+    open: boolean;
+    onToggle: (e: SyntheticEvent<HTMLDetailsElement>) => void;
+};
+/** the latest value in a ref — for a handler that a timer, an observer or a listener set up once calls later */
+export declare function useLatest<T>(value: T): import("react").RefObject<T>;
+/** watch boxes for a size change (the keyboard, a font arriving, a wrap): `fn` on each — once at the start too, as the browser
+ *  reports. Returns the stop, for an effect's cleanup; nothing is watched where the browser has no ResizeObserver. */
+export declare function watchSize(targets: Array<Element | null | undefined>, fn: () => void): () => 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;
+export {};

package/dist/state.js

@@ -0,0 +1,57 @@
+import { useCallback, useRef, useState } from 'react';
+export function useControlled(value, initial, onChange) {
+    const [own, setOwn] = useState(initial);
+    const shown = value !== undefined ? value : own;
+    const live = useRef({ controlled: value !== undefined, shown, onChange });
+    live.current = { controlled: value !== undefined, shown, onChange };
+    const request = useCallback((next, ...extra) => {
+        const { controlled, shown, onChange } = live.current;
+        if (Object.is(next, shown))
+            return;
+        if (!controlled)
+            setOwn(next);
+        onChange?.(next, ...extra);
+    }, []);
+    return [shown, request];
+}
+/** a native `<details>` controlled like an input: `open` + `onOpenChange`, or `defaultOpen`. Spread the result on the details.
+ *  The browser opens it on a tap by itself — a controlled one is put back until the app says so. */
+export function useDisclosure(open, defaultOpen = false, onOpenChange) {
+    const [shown, request] = useControlled(open, defaultOpen, onOpenChange);
+    return {
+        open: shown,
+        onToggle: (e) => {
+            const el = e.currentTarget;
+            if (el.open === shown)
+                return;
+            request(el.open);
+            if (open !== undefined)
+                el.open = open;
+        },
+    };
+}
+/** the latest value in a ref — for a handler that a timer, an observer or a listener set up once calls later */
+export function useLatest(value) {
+    const ref = useRef(value);
+    ref.current = value;
+    return ref;
+}
+/** watch boxes for a size change (the keyboard, a font arriving, a wrap): `fn` on each — once at the start too, as the browser
+ *  reports. Returns the stop, for an effect's cleanup; nothing is watched where the browser has no ResizeObserver. */
+export function watchSize(targets, fn) {
+    if (typeof ResizeObserver === 'undefined')
+        return () => { };
+    const ro = new ResizeObserver(fn);
+    for (const t of targets)
+        if (t)
+            ro.observe(t);
+    return () => ro.disconnect();
+}
+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,8 @@ 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, set] = useControlled(openProp === undefined ? undefined : index(openProp), index(defaultOpen), onOpenChange && ((next) => onOpenChange(next !== null, next)));
     const [at, setAt] = useState('full');
-    const set = (next) => { if (openProp === undefined)
-        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

@@ -1,4 +1,5 @@
 import { type ComponentProps, type ReactNode } from 'react';
+import type { Tone } from '../cards/Card.js';
 import { Screen } from '../scaffold/Screen.js';
 import { type StackSheetTab } from '../sheets/StackSheet.js';
 export interface HomeSheet {
@@ -6,8 +7,8 @@ export interface HomeSheet {
     title: ReactNode;
     /** 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 | 4 | 5;
+    /** the paper — see `Tone` (default: 2, 3, 1, 2, 3 by place) */
+    tone?: Tone;
     /** 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, change] = useControlled(openProp, defaultOpen, onOpenChange);
     const [leaving, setLeaving] = useState(null);
     const [seen, setSeen] = useState(() => new Set(open != null ? [open] : []));
     const [was, setWas] = useState(open);
@@ -32,8 +32,6 @@ 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 [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, useLatest } from '../state.js';
 import { Screen } from '../scaffold/Screen.js';
 import { cx } from '../cx.js';
 /**
@@ -12,8 +13,7 @@ import { cx } from '../cx.js';
 export function Splash({ mark, text, done, min = 0, onLeft, className, ...rest }) {
     const born = useRef(Date.now());
     const [leaving, setLeaving] = useState(false);
-    const left = useRef(onLeft);
-    left.current = onLeft;
+    const left = useLatest(onLeft);
     useEffect(() => {
         if (!done)
             return;
@@ -23,7 +23,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, turn] = useControlled(atProp, defaultAt, onAtChange);
     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', () => turn(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 */

package/dist/type/Icon.js

@@ -1,4 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
+import { warnOnce } from '../state.js';
 import { cx } from '../cx.js';
 import { ICONS } from './icons.js';
 /* the stroke style every stock symbol shares (Lucide): a project's drawing takes it unless it brings its own attrs */
@@ -14,7 +15,6 @@ export function registerIcons(icons) {
     for (const [name, d] of Object.entries(icons))
         OWN.set(name, typeof d === 'string' ? { attrs: STROKE, body: d } : { attrs: { ...STROKE, ...d.attrs }, body: d.body });
 }
-const warned = new Set();
 /**
  * Icon — a stroke icon, inlined (no sprite file at runtime): one of the stock Lucide symbols, one of the project's OWN (`registerIcons`), or a
  * one-off drawn with `children`. The set is open — a project never comes to cardds for an icon.
@@ -23,10 +23,8 @@ const warned = new Set();
  */
 export function Icon({ name, children, size = 'md', label, className, ...rest }) {
     const icon = name === undefined ? undefined : OWN.get(name) ?? ICONS[name];
-    if (name !== undefined && !icon && !warned.has(name)) {
-        warned.add(name);
-        console.warn(`cardds Icon: no icon named "${name}" — a stock name is misspelt, or the project has not registered it (registerIcons)`);
-    }
+    if (name !== undefined && !icon)
+        warnOnce(`icon:${name}`, `cardds Icon: no icon named "${name}" — a stock name is misspelt, or the project has not registered it (registerIcons)`);
     const shared = { className: cx('icon', size !== 'md' && `icon--${size}`, className), role: label ? 'img' : undefined, 'aria-label': label, 'aria-hidden': label ? undefined : true };
     // an unknown name draws nothing but keeps its box — a missing icon never takes a screen down
     if (!icon)