@usableapp/cardds 0.7.16 → 0.7.17

package/dist/cards/Card.d.ts

@@ -1,7 +1,10 @@
-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 */
@@ -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

@@ -5,7 +5,6 @@ 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 [day, setOwn] = useControlled(selected, defaultSelected);
-    const pick = (d) => { setOwn(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.js

@@ -3,6 +3,6 @@ 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, 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))) }));
+    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,6 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useEffect, useRef, useState } from 'react';
-import { useControlled } from '../state.js';
+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
@@ -12,22 +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 [typed, setOwn] = useControlled(value, defaultValue);
+    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({ setOwn, onChange, error });
-    latest.current = { setOwn, 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;
-            latest.current.setOwn('');
-            latest.current.onChange?.('', false);
+            request('', false);
             cell(0)?.focus();
         }, RESET_MS);
     };
@@ -46,9 +44,7 @@ export function Pin({ length = 6, value, defaultValue = '', label = 'Digit', onC
             said.current = true;
             miss();
         }
-        setOwn(next);
-        if (next !== code)
-            onChange?.(next, next.length === length);
+        request(next, next.length === length);
     };
     useEffect(() => {
         if (autoFocus)

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';

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

@@ -2,6 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 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,13 +11,12 @@ 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 }) {

package/dist/media/Postcard.js

@@ -9,8 +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 [back, setOwn] = useControlled(flipped, defaultFlipped);
-    const turn = () => { setOwn(!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

@@ -10,16 +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 [current, setOwn] = useControlled(value, defaultValue);
+    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;
-        setOwn(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/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

@@ -8,7 +8,7 @@ export interface CentreProps extends ComponentProps<'div'> {
  * 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

@@ -8,7 +8,7 @@ import { cx } from '../cx.js';
  * 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)) }));
 }

package/dist/scaffold/Screen.js

@@ -1,5 +1,5 @@
 import { createElement, useEffect, useRef } from 'react';
-import { warnOnce } from '../state.js';
+import { warnOnce, watchSize } from '../state.js';
 import { cx } from '../cx.js';
 /**
  * Screen — the mobile screen in THREE parts: **top** and **content** (the children) in one flex column, the content down to the
@@ -24,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/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,6 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useRef } from 'react';
-import { useControlled } from '../state.js';
+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
@@ -17,7 +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 [current, setOwn] = useControlled(state, defaultState);
+    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
@@ -28,12 +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;
-        setOwn(next);
-        onStateChange?.(next, reason);
-    }, [current, setOwn, onStateChange]);
     useEffect(() => {
         if (current !== 'peek' && current !== 'away')
             home.current = current;
@@ -103,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;
@@ -115,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
@@ -126,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
@@ -136,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

@@ -14,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`.
  *
@@ -23,23 +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 [current, setOwn] = useControlled(open, defaultOpen);
+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;
-        setOwn(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) {
@@ -86,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 })] }));
 }