@usableapp/cardds 0.7.16 → 0.7.17

package/dist/sheets/SheetSteps.js

@@ -18,7 +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 [current, setOwn] = useControlled(at, defaultAt);
+    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,10 +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;
-        setOwn(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
@@ -220,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;
@@ -242,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,8 +1,9 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useRef } from 'react';
-import { useControlled } from '../state.js';
+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';
@@ -17,14 +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 [tab, setOwn] = useControlled(tabProp, defaultTab ?? tabs?.[0]?.id);
-    const pick = (id) => { 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));
@@ -32,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

@@ -1,7 +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 a setter that only moves the component's own copy — the caller still ASKS the app (onXChange). */
-export declare function useControlled<T>(value: T | undefined, initial: T): [T, (next: T) => void];
+ *  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

@@ -1,11 +1,51 @@
-import { useState } from 'react';
-/** controlled like an input: `value` given = the app owns it; undefined = the component keeps its own, starting at `initial`.
- *  Returns the value shown and a setter that only moves the component's own copy — the caller still ASKS the app (onXChange). */
-export function useControlled(value, initial) {
+import { useCallback, useRef, useState } from 'react';
+export function useControlled(value, initial, onChange) {
     const [own, setOwn] = useState(initial);
-    const controlled = value !== undefined;
-    return [controlled ? value : own, (next) => { if (!controlled)
-            setOwn(next); }];
+    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 */

package/dist/templates/CallSheet.js

@@ -19,9 +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 [on, setOwn] = useControlled(openProp === undefined ? undefined : index(openProp), index(defaultOpen));
+    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) => { 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

@@ -15,7 +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 [open, setOwn] = useControlled(openProp, defaultOpen);
+    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,7 +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) => { 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,6 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useRef, useState } from 'react';
-import { reducedMotion } from '../state.js';
+import { reducedMotion, useLatest } from '../state.js';
 import { Screen } from '../scaffold/Screen.js';
 import { cx } from '../cx.js';
 /**
@@ -13,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;

package/dist/templates/Walkthrough.js

@@ -17,7 +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 [at, setOwn] = useControlled(atProp, defaultAt);
+    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,7 +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', () => { 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/Text.d.ts

@@ -14,12 +14,12 @@ export interface TextProps extends React.HTMLAttributes<HTMLElement> {
     grow?: boolean;
     /** uppercase */
     caps?: boolean;
-    /** the element; defaults per level (h2 for display/h1/h2, p for title/body/stat, span for the rest) */
     /** READ, NOT SHOWN: the words stay in the page for a screen reader (a page's h1 that the design does not show), and take no room */
     sr?: boolean;
     /** the member may select and copy these words (a code, an address, a reference number) — everything else in a Screen is not
      *  selectable, like a native app (Lh 2026-09-25) */
     selectable?: boolean;
+    /** the element; defaults per level (h2 for display/h1/h2, p for title/body/stat, span for the rest) */
     as?: 'h1' | 'h2' | 'h3' | 'p' | 'span' | 'strong' | 'div';
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usableapp/cardds",
-  "version": "0.7.16",
+  "version": "0.7.17",
   "license": "UNLICENSED",
   "type": "module",
   "description": "card-first mobile design system, React-first: the components in src/ are thin wrappers over the CSS contract (css/*.css stays the only truth); gallery/ shows every story live (npm run dev), tests/ measures the geometry.",
@@ -14,7 +14,10 @@
     "test": "playwright test",
     "validate:inbox": "node scripts/validate-inbox.mjs",
     "prepack": "npm run build",
-    "knobs": "node scripts/knobs.mjs"
+    "knobs": "node scripts/knobs.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p gallery/tsconfig.json --noEmit",
+    "snapshot:write": "CARDDS_SNAPSHOT=write playwright test tests/style-snapshot.spec.js",
+    "snapshot:check": "CARDDS_SNAPSHOT=check playwright test tests/style-snapshot.spec.js"
   },
   "devDependencies": {
     "@playwright/test": "1.58.2",
@@ -52,8 +55,8 @@
     "CHANGELOG.md"
   ],
   "peerDependencies": {
-    "react": ">=18",
-    "react-dom": ">=18"
+    "react": ">=19",
+    "react-dom": ">=19"
   },
   "publishConfig": {
     "access": "public"