@usableapp/cardds 0.7.15 → 0.7.17

package/dist/cards/Card.d.ts

@@ -1,14 +1,17 @@
-import { type ComponentProps } from 'react';
+import { type ComponentProps, type ReactNode } from 'react';
+import { type CardHeadProps } from './CardHead.js';
+/** a card's paper: 1 (default, light) · 2 (tinted) · 3 (dark / accent — controls invert) · 4 · 5 (more colours, from the palette) */
+export type Tone = 1 | 2 | 3 | 4 | 5;
 export interface CardProps extends ComponentProps<'article'> {
-    /** the tone slot: 1 (default, light) · 2 (tinted) · 3 (dark / accent — controls invert automatically) · 4 · 5 (more colours, from the palette) */
-    tone?: 1 | 2 | 3 | 4 | 5;
+    /** the tone slot — see `Tone` */
+    tone?: Tone;
     /** compact: a small card inside a card or a sheet body (a note, a promo) */
     sm?: boolean;
     /** a list row that is its own card: thumb · body · end, in a CardList */
     row?: boolean;
     /** the image IS the card: a Placeholder or img first, text over a scrim */
     cover?: boolean;
-    /** a sticky-note corner, no border (swipe decks, quotes) */
+    /** a sticky-note corner, no border (quotes) */
     fold?: boolean;
     /** one card at the human centre of a `Screen fill` (the introduction screens) */
     centre?: boolean;
@@ -17,14 +20,28 @@ export interface CardProps extends ComponentProps<'article'> {
     /** the element: article (default), a when it links, label when it wraps an input, div/section */
     as?: 'article' | 'div' | 'a' | 'label' | 'section' | 'li';
     href?: string;
+    /** THE HEAD, filled in place: the heading (wraps freely) — the card writes its CardHead first. For a head of your own shape
+     *  (a chip before the words, a tile badge) write `<CardHead>` as the first child instead, and leave these out */
+    heading?: ReactNode;
+    /** the muted line under the heading */
+    caption?: ReactNode;
+    /** the head's far-right thing: a Chip, an IconBtn, a Badge, a small Ring */
+    end?: ReactNode;
+    /** the heading's level (h2 default; h1 for the one-feature page) */
+    level?: CardHeadProps['level'];
+    /** THE FOOT, filled in place: its Btns (≤4, one line) — the card writes its CardFoot last */
+    foot?: ReactNode;
+    /** the small Link under the foot's buttons (CardFoot `link`) */
+    footLink?: ReactNode;
 }
 /**
  * Card — ONE boundary: head · content · foot. Cards are content the system offers (the words, the thing to read).
- * Children: a CardHead first (heading left, contextual info far right), the content (frameless rows, kv, a ring,
- * a paragraph — never a second card boundary), an optional CardFoot (≤4 buttons on one line).
+ * The head and the foot are SLOTS: `heading` · `caption` · `end` (the card writes its CardHead first) and `foot` · `footLink`
+ * (its CardFoot last); the children are the content between them (frameless rows, kv, a ring, a paragraph — never a second card
+ * boundary). The order is the card's, never the writer's. A head of its own shape: write `<CardHead>` as the first child instead.
  * A page with one feature and one CTA may be a single card. Keep everything big.
  */
-export declare function Card({ tone, sm, row, cover, fold, centre, band, as, className, ...rest }: CardProps): import("react").DetailedReactHTMLElement<{
+export declare function Card({ tone, sm, row, cover, fold, centre, band, as, heading, caption, end, level, foot, footLink, className, children, ...rest }: CardProps): import("react").DetailedReactHTMLElement<{
     href?: string;
     ref?: import("react").Ref<HTMLElement> | undefined;
     key?: import("react").Key | null | undefined;
@@ -135,7 +152,6 @@ export declare function Card({ tone, sm, row, cover, fold, centre, band, as, cla
     "aria-valuemin"?: number | undefined;
     "aria-valuenow"?: number | undefined;
     "aria-valuetext"?: string | undefined;
-    children?: import("react").ReactNode | undefined;
     dangerouslySetInnerHTML?: {
         __html: string | TrustedHTML;
     } | undefined;

package/dist/cards/Card.js

@@ -1,14 +1,29 @@
-import { createElement } from 'react';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Children, createElement, isValidElement } from 'react';
 import { cx } from '../cx.js';
+import { warnOnce } from '../state.js';
+import { CardHead } from './CardHead.js';
+import { CardFoot } from './CardFoot.js';
 /**
  * Card — ONE boundary: head · content · foot. Cards are content the system offers (the words, the thing to read).
- * Children: a CardHead first (heading left, contextual info far right), the content (frameless rows, kv, a ring,
- * a paragraph — never a second card boundary), an optional CardFoot (≤4 buttons on one line).
+ * The head and the foot are SLOTS: `heading` · `caption` · `end` (the card writes its CardHead first) and `foot` · `footLink`
+ * (its CardFoot last); the children are the content between them (frameless rows, kv, a ring, a paragraph — never a second card
+ * boundary). The order is the card's, never the writer's. A head of its own shape: write `<CardHead>` as the first child instead.
  * A page with one feature and one CTA may be a single card. Keep everything big.
  */
-export function Card({ tone, sm, row, cover, fold, centre, band, as = 'article', className, ...rest }) {
-    return createElement(as, {
-        className: cx('card', tone && tone !== 1 && `card--${tone}`, sm && 'card--sm', row && 'card--row', cover && 'card--cover', fold && 'card--fold', centre && 'card--centre', band && 'card--band', className),
-        ...rest,
-    });
+export function Card({ tone, sm, row, cover, fold, centre, band, as = 'article', heading, caption, end, level, foot, footLink, className, children, ...rest }) {
+    const head = heading != null || caption != null || end != null;
+    const tail = foot != null || footLink != null;
+    if (head || tail) {
+        const parts = Children.toArray(children).filter(isValidElement); // dev hint only
+        if (head && parts.some((c) => c.type === CardHead))
+            warnOnce('card-head-twice', 'cardds Card: `heading`/`caption`/`end` AND a <CardHead> child — one head per card; use one way');
+        if (tail && parts.some((c) => c.type === CardFoot))
+            warnOnce('card-foot-twice', 'cardds Card: `foot`/`footLink` AND a <CardFoot> child — one foot per card; use one way');
+    }
+    const props = { className: cx('card', tone && tone !== 1 && `card--${tone}`, sm && 'card--sm', row && 'card--row', cover && 'card--cover', fold && 'card--fold', centre && 'card--centre', band && 'card--band', className), ...rest };
+    if (!head && !tail)
+        return createElement(as, props, children);
+    return createElement(as, props, head && _jsx(CardHead, { heading: heading, caption: caption, end: end, level: level }, "head"), ...Children.toArray(children), // keyed: the slots sit around them
+    tail && _jsx(CardFoot, { link: footLink, children: foot }, "foot"));
 }

package/dist/cards/CardHead.d.ts

@@ -2,7 +2,6 @@ import type { ComponentProps, ReactNode } from 'react';
 export interface CardHeadProps extends ComponentProps<'div'> {
     /** the heading (a string becomes an h2 at level `t-h2`) — wraps freely, as many lines as the words need */
     heading?: ReactNode;
-    /** small caps above the heading ("Step 1 of 4", "Time bank") */
     /** the muted line under the heading (a date, a subtitle) */
     caption?: ReactNode;
     /** the contextual thing at the far right: a chip, an IconBtn (more), a Link, a small Ring, an Avatar, a Badge (a count in a stack head) */

package/dist/cards/CardHead.js

@@ -7,5 +7,5 @@ import { cx } from '../cx.js';
  */
 export function CardHead({ heading, caption, end, top, level = 'h2', className, children, ...rest }) {
     const H = level === 'h1' ? 'h1' : 'h2';
-    return (_jsxs("div", { className: cx('card__head', top && 'card__head--top', className), ...rest, children: [heading != null && _jsx(H, { className: level === 'display' ? 't-display' : `t-${level}`, children: heading }), caption != null && _jsx("span", { className: "t-caption t-muted", children: caption }), children, end] }));
+    return (_jsxs("div", { className: cx('card__head', top && 'card__head--top', className), ...rest, children: [heading != null && _jsx(H, { className: `t-${level}`, children: heading }), caption != null && _jsx("span", { className: "t-caption t-muted", children: caption }), children, end] }));
 }

package/dist/choice/Calendar.js

@@ -1,13 +1,10 @@
 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';
 /** Calendar — a month grid of 44px round cells: one accent day, optional marks; prev/next in the head. It shows ONE month and knows no dates:
  *  the app owns which month (`title`, `days`, `start` + `onPrev` / `onNext`) and which day (`selected` + `onSelect`, or `defaultSelected`). */
 export function Calendar({ title, days = 30, start = 1, selected, defaultSelected, onSelect, onPrev, onNext, prevLabel = 'Previous', nextLabel = 'Next', marks = [], marks2 = [], disabled = [], weekdays = ['Su', 'Mo', 'Tu', 'We', 'Th', 'Fr', 'Sa'], nav, className, ...rest }) {
-    const [inner, setInner] = useState(defaultSelected);
-    const day = selected !== undefined ? selected : inner;
-    const pick = (d) => { if (selected === undefined)
-        setInner(d); onSelect?.(d); };
+    const [day, pick] = useControlled(selected, defaultSelected, onSelect);
     return (_jsxs("div", { className: cx('calendar', className), ...rest, children: [_jsxs("div", { className: "calendar__head", children: [_jsx("span", { className: "t-title", children: title }), nav ?? (_jsxs("span", { className: "icon-row", children: [_jsx(IconBtn, { sm: true, icon: "chevron-left", label: prevLabel, onClick: onPrev }), _jsx(IconBtn, { sm: true, icon: "chevron-right", label: nextLabel, onClick: onNext })] }))] }), _jsxs("div", { className: "calendar__grid", children: [weekdays.map((d) => _jsx("span", { className: "calendar__wd", children: d }, d)), Array.from({ length: days }, (_, i) => i + 1).map((d) => (_jsx("button", { type: "button", className: cx('calendar__day', marks.includes(d) && 'calendar__day--mark', marks2.includes(d) && 'calendar__day--mark2'), "aria-selected": d === day ? 'true' : undefined, onClick: () => pick(d), disabled: disabled.includes(d), style: d === 1 ? { '--start': start } : undefined, children: d }, d)))] })] }));
 }

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, pick] = useControlled(value, defaultValue, onChange);
+    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: () => pick(n) }), _jsx("span", { className: "mood__dot" })] }, n))) }));
 }

package/dist/forms/Field.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { watchSize } from '../state.js';
 import { formatOk, useCheck } from './check.js';
 import { cx } from '../cx.js';
 import { Icon } from '../type/Icon.js';
@@ -59,10 +60,8 @@ export function Field({ icon, action, label, error, format, digits, formatError,
                 el.style.removeProperty('--_ph-fit');
         };
         fit();
-        const ro = new ResizeObserver(fit);
-        ro.observe(el);
         document.fonts?.ready.then(fit);
-        return () => ro.disconnect();
+        return watchSize([el], fit);
     }, [input.placeholder]);
     useEffect(() => {
         if (wrong) {

package/dist/forms/FileBtn.js

@@ -6,5 +6,5 @@ import { cx } from '../cx.js';
  * opens the camera; without `capture` the gallery. The picked file arrives in `onChange` like any input.
  */
 export function FileBtn({ primary, quiet, block, className, children, ...input }) {
-    return (_jsxs("label", { className: cx('btn', primary && 'btn--primary', quiet && 'btn--quiet', block && 'btn--block', className), children: [_jsx("input", { type: "file", hidden: true, ...input }), children] }));
+    return (_jsxs("label", { className: cx('btn', primary && 'btn--primary', quiet && 'btn--quiet', block && 'btn--block', className), children: [_jsx("input", { type: "file", className: "t-sr", ...input }), children] }));
 }

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, useLatest } 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,23 +12,20 @@ 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, request] = useControlled(value, defaultValue, onChange);
+    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 = useLatest(error);
     const miss = () => {
         restart.current = true;
         setShake(true);
         clearTimeout(reset.current);
         reset.current = setTimeout(() => {
             setBad(false);
-            setCleared(latest.current.error);
+            setCleared(latest.current);
             restart.current = false;
-            if (latest.current.value === undefined)
-                setInner('');
-            latest.current.onChange?.('', false);
+            request('', false);
             cell(0)?.focus();
         }, RESET_MS);
     };
@@ -46,10 +44,7 @@ export function Pin({ length = 6, value, defaultValue = '', label = 'Digit', onC
             said.current = true;
             miss();
         }
-        if (value === undefined)
-            setInner(next);
-        if (next !== code)
-            onChange?.(next, next.length === length);
+        request(next, next.length === length);
     };
     useEffect(() => {
         if (autoFocus)

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

@@ -1,6 +1,6 @@
 // cardds — the React adapter over the CSS. Thin: every component emits the
-// markup contract the CSS documents, nothing more. cardds.js rides along for
-// the behaviours (sheet handle, stack open/close, dropdown value sync).
+// markup contract the CSS documents; a component's own behaviour is its own React code.
+// cardds.js rides along for the environment only: the keyboard's height (--kb) and .bleed's scrollbar.
 import '../cardds.js';
 // Popover for Safari/iOS 16.4–16.x (native from 17): applies itself only where the platform lacks it.
 import '@oddbird/popover-polyfill';
@@ -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/layover/Banner.d.ts

@@ -1,8 +1,15 @@
 import type { ComponentProps, ReactNode } from 'react';
-export interface BannerProps extends Omit<ComponentProps<'details'>, 'summary'> {
+export interface BannerProps extends Omit<ComponentProps<'details'>, 'summary' | 'open' | 'onToggle'> {
     /** the line that opens it — words (and an inline Icon); the chevron is the Banner's own */
     summary: ReactNode;
+    /** CONTROLLED: open — with `onOpenChange`; or `defaultOpen` */
+    open?: boolean;
+    /** UNCONTROLLED: start open */
+    defaultOpen?: boolean;
+    /** the summary was tapped: the state it asks for */
+    onOpenChange?: (open: boolean) => void;
 }
 /** Banner — ONE band: the line that opens it and what it opens share the same ground, so they read as one piece (Lh 2026-09-24).
- *  A light tint with a darker rule above and below, edge to edge of its card or screen — a band, never a card in a card. A native details, no JS. */
-export declare function Banner({ summary, className, children, ...rest }: BannerProps): import("react").JSX.Element;
+ *  A light tint with a darker rule above and below, edge to edge of its card or screen — a band, never a card in a card.
+ *  A native details, controlled like an input: `open` + `onOpenChange`, or `defaultOpen`. */
+export declare function Banner({ summary, open, defaultOpen, onOpenChange, className, children, ...rest }: BannerProps): import("react").JSX.Element;

package/dist/layover/Banner.js

@@ -1,8 +1,11 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cx } from '../cx.js';
 import { Icon } from '../type/Icon.js';
+import { useDisclosure } from '../state.js';
 /** Banner — ONE band: the line that opens it and what it opens share the same ground, so they read as one piece (Lh 2026-09-24).
- *  A light tint with a darker rule above and below, edge to edge of its card or screen — a band, never a card in a card. A native details, no JS. */
-export function Banner({ summary, className, children, ...rest }) {
-    return (_jsxs("details", { className: cx('banner', className), ...rest, children: [_jsxs("summary", { className: "banner__summary", children: [summary, _jsx(Icon, { name: "chevron-down", size: "xs" })] }), _jsx("div", { className: "banner__body", children: children })] }));
+ *  A light tint with a darker rule above and below, edge to edge of its card or screen — a band, never a card in a card.
+ *  A native details, controlled like an input: `open` + `onOpenChange`, or `defaultOpen`. */
+export function Banner({ summary, open, defaultOpen, onOpenChange, className, children, ...rest }) {
+    const disclosure = useDisclosure(open, defaultOpen, onOpenChange);
+    return (_jsxs("details", { className: cx('banner', className), ...rest, ...disclosure, children: [_jsxs("summary", { className: "banner__summary", children: [summary, _jsx(Icon, { name: "chevron-down", size: "xs" })] }), _jsx("div", { className: "banner__body", children: children })] }));
 }

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,7 +1,8 @@
 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';
+import { useDisclosure } from '../state.js';
 /**
  * Row — a frameless row inside a card: lead · title + meta · end. 48px+ tall, a tap target.
  * Several go in Rows (hairlines between). A row that IS a card is `Card row`.
@@ -10,17 +11,16 @@ import { Icon } from '../type/Icon.js';
  * An `end` chevron turns when it is open — the app fetches whatever `more` lists; the row only shows it.
  */
 export function Row({ lead, leadIcon, title, meta, body, end, endValue, endCaption, lg, done, as, href, more, open, defaultOpen, onOpenChange, className, children, ...rest }) {
+    const disclosure = useDisclosure(open, defaultOpen, onOpenChange);
     const el = more !== undefined ? 'summary' : as ?? (href ? 'a' : 'div');
     const row = createElement(el, { href, className: cx('row', lg && 'row--lg', done && 'row--done', className), 'aria-disabled': done || undefined, ...(more === undefined ? rest : {}) }, leadIcon ? _jsx("span", { className: "row__lead", children: _jsx(Icon, { name: leadIcon }) }) : lead, (title != null || meta != null || body != null) && (_jsxs("div", { className: "row__body", children: [title != null && _jsx("span", { className: "row__title", children: title }), meta != null && _jsx("span", { className: "row__meta", children: meta }), body] })), children, (endValue != null || endCaption != null) && (_jsxs("span", { className: "row__end", children: [endValue != null && _jsx("span", { className: "t-title", children: endValue }), endCaption != null && _jsx("span", { className: "t-caption t-muted", children: endCaption })] })), end, done && _jsx("span", { className: "row__done", children: _jsx(Icon, { name: "check", size: "sm" }) }));
     if (more === undefined)
         return row;
-    return (_jsxs("details", { className: "row-expand", open: open ?? defaultOpen, ...rest, onToggle: (e) => { const is = e.currentTarget.open; if (open !== undefined && is !== open)
-            e.currentTarget.open = open; if (is !== (open ?? !is))
-            onOpenChange?.(is); }, children: [row, _jsx("div", { className: "row-expand__more", children: more })] }));
+    return (_jsxs("details", { className: "row-expand", ...rest, ...disclosure, children: [row, _jsx("div", { className: "row-expand__more", children: more })] }));
 }
 /** Rows — a list of Rows separated by hairlines; `heading` names the group (a `role="group"` labelled by it). */
 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, flip] = useControlled(flipped, defaultFlipped, onFlip);
+    const turn = () => flip(!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/numbers/Band.d.ts

@@ -1,4 +1,5 @@
 import type { ComponentProps, ReactNode } from 'react';
+import type { Tone } from '../cards/Card.js';
 export interface BandProps extends ComponentProps<'article'> {
     /** the two-line label (use a `<br />` to break it) */
     label: ReactNode;
@@ -6,7 +7,8 @@ export interface BandProps extends ComponentProps<'article'> {
     num: ReactNode;
     /** the footnote under the label */
     foot?: ReactNode;
-    tone?: 1 | 2 | 3 | 4 | 5;
+    /** the paper — see `Tone` */
+    tone?: Tone;
 }
 /** 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,18 +10,10 @@ 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, pick] = useControlled(value, defaultValue, onChange);
     const rail = useRef(null);
     const mounted = useRef(false);
     const settle = useRef(null);
-    const pick = (next) => {
-        if (next === current)
-            return;
-        if (value === undefined)
-            setInner(next);
-        onChange?.(next);
-    };
     const items = () => [...(rail.current?.querySelectorAll(':scope > .picker__item') ?? [])];
     const column = () => (rail.current ? rail.current.clientWidth / 3 : 0); // the rail is three columns wide; item i stands in the centre at i × one column
     /* the chosen value stands in the centre — at once on arrival, sliding after */

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/ActionBar.d.ts

@@ -1,6 +1,6 @@
 import type { ComponentProps } from 'react';
 export interface ActionBarProps extends ComponentProps<'div'> {
-    /** `pager`: previous / next as two equal buttons at the edges (a Link may sit between them; the PagerAt dots never do — they go under the card) · `tiers`: rows stacked — a control tier above the buttons */
+    /** `pager`: previous / next as two equal buttons at the edges (a Link may sit between them) · `tiers`: rows stacked — a control tier above the buttons */
     variant?: 'pager' | 'tiers';
     /** a bare bar for a preview: no position, full width, no side padding (a real bar is a Screen's `bottom`) */
     inline?: boolean;
@@ -8,8 +8,8 @@ export interface ActionBarProps extends ComponentProps<'div'> {
 /**
  * ActionBar — the screen's ONE move: the Screen's `bottom` (`<Screen fill bottom={<ActionBar…>}>`), the last part of its flex
  * column, as tall as its rows. Never after `</Screen>`, never positioned by hand.
- * Plain: one wide primary Btn (the step that commits). `pager`: Back + Next as peers — buttons only; where you are is the
- * PagerAt under the card in a Centre group, never in the bar (Lh, 2026-09-12).
+ * Plain: one wide primary Btn (the step that commits).
+ * `pager`: Back + Next as peers — buttons only. The PagerAt dots may be the bar's first row (a Walkthrough).
  * `tiers`: an ActionBarTier with a control (a Slider) above the button tier.
  * In a `Screen fill` it is a layer over the content's foot; on a scrolling Screen a sticky last row.
  */

package/dist/scaffold/ActionBar.js

@@ -3,8 +3,8 @@ import { cx } from '../cx.js';
 /**
  * ActionBar — the screen's ONE move: the Screen's `bottom` (`<Screen fill bottom={<ActionBar…>}>`), the last part of its flex
  * column, as tall as its rows. Never after `</Screen>`, never positioned by hand.
- * Plain: one wide primary Btn (the step that commits). `pager`: Back + Next as peers — buttons only; where you are is the
- * PagerAt under the card in a Centre group, never in the bar (Lh, 2026-09-12).
+ * Plain: one wide primary Btn (the step that commits).
+ * `pager`: Back + Next as peers — buttons only. The PagerAt dots may be the bar's first row (a Walkthrough).
  * `tiers`: an ActionBarTier with a control (a Slider) above the button tier.
  * In a `Screen fill` it is a layer over the content's foot; on a scrolling Screen a sticky last row.
  */

package/dist/scaffold/Centre.d.ts

@@ -3,12 +3,12 @@ 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
  * and scrolling inside, for a screen that must never scroll. Its children stack at the screen's rhythm.
- * Put it after the TopBar; the ActionBar, if any, stays outside the Screen.
+ * Put it after the TopBar; the ActionBar, if any, is the Screen's `bottom`.
  */
 export declare function Centre({ className, ...rest }: CentreProps): import("react").JSX.Element;
 export interface PagesProps extends ComponentProps<'div'> {

package/dist/scaffold/Centre.js

@@ -3,12 +3,12 @@ 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
  * and scrolling inside, for a screen that must never scroll. Its children stack at the screen's rhythm.
- * Put it after the TopBar; the ActionBar, if any, stays outside the Screen.
+ * Put it after the TopBar; the ActionBar, if any, is the Screen's `bottom`.
  */
 export function Centre({ className, ...rest }) {
     return _jsx("div", { className: cx('screen__centre', className), ...rest });

package/dist/scaffold/PagerAt.d.ts

@@ -7,5 +7,5 @@ export interface PagerAtProps extends Omit<ComponentProps<'span'>, 'children'> {
     /** accessible name; defaults to "Page {at} of {of}" */
     label?: string;
 }
-/** PagerAt — the "where am I" dots: one accent dot at the current page. Under the card that changes (a child of Centre), or a Step's child after its Pages — pinned to the base's foot. One per walk, never inside an ActionBar, never inside a page. */
+/** PagerAt — the "where am I" dots: one accent dot at the current page. Under the card that changes (a child of Centre), or a Step's child after its Pages — pinned to the base's foot. One per walk, never inside a page; in a Walkthrough it is the bottom layer's first row (an ActionBar child, centred). */
 export declare function PagerAt({ at, of, label, className, ...rest }: PagerAtProps): import("react").JSX.Element;

package/dist/scaffold/PagerAt.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { cx } from '../cx.js';
-/** PagerAt — the "where am I" dots: one accent dot at the current page. Under the card that changes (a child of Centre), or a Step's child after its Pages — pinned to the base's foot. One per walk, never inside an ActionBar, never inside a page. */
+/** PagerAt — the "where am I" dots: one accent dot at the current page. Under the card that changes (a child of Centre), or a Step's child after its Pages — pinned to the base's foot. One per walk, never inside a page; in a Walkthrough it is the bottom layer's first row (an ActionBar child, centred). */
 export function PagerAt({ at, of, label, className, ...rest }) {
     return (_jsx("span", { className: cx('pager__at', className), role: "img", "aria-label": label ?? `Page ${at} of ${of}`, ...rest, children: Array.from({ length: of }, (_, i) => _jsx("i", { className: i + 1 === at ? 'is-at' : undefined }, i)) }));
 }