@usableapp/cardds 0.7.53 → 0.7.55

package/dist/sheets/StackSheet.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useRef } from 'react';
+import { useEffect, useRef, useState } from 'react';
 import { useControlled, watchSize } from '../state.js';
 import { cx } from '../cx.js';
 import { Card } from '../cards/Card.js';
@@ -19,11 +19,12 @@ import { word } from '../words.js';
  * A count shows as a small circle over its icon. The body is the app's: render the page of the chosen tab (and nothing while the sheet
  * is closed — see `Home`). A direct child of `SheetStack`.
  */
-export function StackSheet({ title, tone, icon, tabs, tab: tabProp, defaultTab, onTabChange, foot, backLabel = word('back'), backAt = 'none', className, children, ...rest }) {
+export function StackSheet({ title, tone, icon, tabs, tab: tabProp, defaultTab, onTabChange, foot, backLabel = word('back'), backAt = 'none', stack, className, children, ...rest }) {
     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);
+    const [long, setLong] = useState(false);
     useEffect(() => {
         const h = titleRef.current, run = h?.firstElementChild;
         if (!h || !run)
@@ -32,10 +33,10 @@ export function StackSheet({ title, tone, icon, tabs, tab: tabProp, defaultTab,
             const over = Math.max(0, Math.ceil(run.scrollWidth - h.clientWidth));
             h.style.setProperty('--_over', `${over}px`);
             h.style.setProperty('--_run', `${(over / 30 + 3).toFixed(1)}s`);
-            h.classList.toggle('is-long', over > 0);
+            setLong(over > 0);
         };
         measure();
         return watchSize([h, run], measure);
     }, [title]);
-    return (_jsxs(Card, { tone: tone, className: cx('stack-sheet', className), ...rest, children: [_jsxs(CardHead, { children: [backAt === 'start' && _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, backAt === 'end' && _jsx(StackBack, { end: true, label: backLabel })] }), _jsx(SheetBody, { role: tabs?.length ? 'tabpanel' : undefined, children: children }), foot != null && _jsx(CardFoot, { children: foot })] }));
+    return (_jsxs(Card, { stack: stack, tone: tone, className: cx('stack-sheet', className), ...rest, children: [_jsxs(CardHead, { children: [backAt === 'start' && _jsx(StackBack, { label: backLabel }), _jsx(Text, { level: "h2", ref: titleRef, className: cx('stack-sheet__title', long && 'is-long'), 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, backAt === 'end' && _jsx(StackBack, { end: true, label: backLabel })] }), _jsx(SheetBody, { role: tabs?.length ? 'tabpanel' : undefined, children: children }), foot != null && _jsx(CardFoot, { children: foot })] }));
 }

package/dist/sheets/sheetMeasure.d.ts

@@ -5,6 +5,6 @@ type SheetRef = RefObject<HTMLElement | null>;
 export declare const slid: (el: HTMLElement) => number;
 export declare const stopsOf: (el: HTMLElement) => Record<Resting, number>;
 export declare function usePeekStrip(ref: SheetRef): void;
-export declare function useTitleRun(ref: SheetRef): void;
+export declare function useTitleRun(ref: SheetRef, onLong: (long: boolean) => void): void;
 export declare function useFootRoom(ref: SheetRef): void;
 export {};

package/dist/sheets/sheetMeasure.js

@@ -39,25 +39,30 @@ export function usePeekStrip(ref) {
     }, []);
 }
 /* the TITLE is one line; too long for it, it runs sideways like a song title (Lh 2026-10-03): the sheet measures how far its
-   words overflow the line and hands it to the CSS (--_over, --_run, .is-long — sheet.css). Measured on the words themselves
-   (a range), so the running indent never feeds back into the number. */
-export function useTitleRun(ref) {
+   words overflow the line and hands the widths to the CSS (--_over, --_run). The heading renders `.is-long` from what this
+   reports. Measured on the words themselves (a range), so the running indent never feeds back into the number. */
+export function useTitleRun(ref, onLong) {
     useEffect(() => {
         const el = ref.current, title = el?.querySelector(':scope > .card__head > :is(h1, h2, h3):first-child, :scope > .sheet__head .sheet__title');
         if (!el || !title)
             return;
+        let was = false;
         const measure = () => {
             const words = document.createRange();
             words.selectNodeContents(title);
             const over = Math.max(0, Math.ceil(words.getBoundingClientRect().width - title.clientWidth));
             title.style.setProperty('--_over', `${over}px`);
             title.style.setProperty('--_run', `${(over / 30 + 3).toFixed(1)}s`);
-            title.classList.toggle('is-long', over > 0);
+            const long = over > 0;
+            if (long !== was) {
+                was = long;
+                onLong(long);
+            }
         };
         const stop = watchSize([title], measure);
         const mo = new MutationObserver(measure);
         mo.observe(title, { childList: true, characterData: true, subtree: true }); // the app changed the words
-        return () => { stop(); mo.disconnect(); title.classList.remove('is-long'); title.style.removeProperty('--_over'); title.style.removeProperty('--_run'); };
+        return () => { stop(); mo.disconnect(); title.style.removeProperty('--_over'); title.style.removeProperty('--_run'); };
     });
 }
 /* the FOOT's room follows what the foot really holds (timebank, Lh 2026-10-01): a button grows with the member's text size, a

package/dist/sheets/stackCard.d.ts

@@ -0,0 +1,33 @@
+import { type CSSProperties, type RefObject } from 'react';
+/** where one sheet sits, derived by the stack from the app's indexes and handed to the card as a prop */
+export interface StackPlace {
+    /** this sheet is the one the app has open */
+    open: boolean;
+    /** the app is reloading this sheet */
+    refreshing: boolean;
+    /** tucked under the open sheet. Stays through the first beat of a close */
+    before: boolean;
+    /** in front of the open sheet, leaving below */
+    after: boolean;
+    /** nearest-first delay, while tucked and while those sheets return */
+    stagger: number;
+    onOpen: () => void;
+    onClose: () => void;
+    onRefresh?: () => void;
+}
+/** the head's title is a tab stop while this sheet is the one Enter acts on: every title when none is open, only the open one otherwise */
+export declare const StackHeadCtx: import("react").Context<0 | -1 | null>;
+/** a finger is pulling this card's content. The body renders `is-refreshing` from it */
+export declare const StackPullCtx: import("react").Context<boolean>;
+export declare function stackPaint(place: StackPlace | undefined, pulling?: boolean): {
+    className?: string;
+    style?: CSSProperties;
+    busy?: true;
+};
+/**
+ * The card's own pull, refresh and focus. Listeners sit on this card's head and body.
+ * `--_pull` / `--_lift` are written while a finger is down, the same way a single Sheet writes `--_drag`.
+ */
+export declare function useStackCard(ref: RefObject<HTMLElement | null>, place: StackPlace | undefined, swallow: {
+    current: boolean;
+}): boolean;

package/dist/sheets/stackCard.js

@@ -0,0 +1,396 @@
+/* one sheet of a tap stack — its own behaviour, not exported from the package.
+   The app says which sheet is open and whether its data is in (`SheetStack`'s `open` and `refreshing`).
+   This card renders what those two mean: the place classes, the grip, the pull. Nothing stamps them on afterwards. */
+import { createContext, useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { flushSync } from 'react-dom';
+import { focusWhenActive } from '../state.js';
+const SLOP_REM = 0.5;
+const COMMIT_REM = 4.5;
+/** the head's title is a tab stop while this sheet is the one Enter acts on: every title when none is open, only the open one otherwise */
+export const StackHeadCtx = createContext(null);
+/** a finger is pulling this card's content. The body renders `is-refreshing` from it */
+export const StackPullCtx = createContext(false);
+export function stackPaint(place, pulling = false) {
+    if (!place)
+        return {};
+    const loading = place.open && place.refreshing;
+    const className = ['stack-card', place.open && 'is-open', place.before && 'is-before', place.after && 'is-after', loading && 'is-loading', pulling && 'is-refreshing'].filter(Boolean).join(' ');
+    return {
+        className,
+        style: place.stagger > 0 ? { '--stagger': String(place.stagger) } : undefined,
+        busy: loading || undefined,
+    };
+}
+const pxFromRem = (rem) => parseFloat(getComputedStyle(document.documentElement).fontSize) * rem;
+/* the pull's reach is the room the sheet still has to travel — measured, not a class */
+const sheetsIn = (stack) => [...stack.children]
+    .filter((c) => !c.classList.contains('sheet-stack__base'))
+    .map((c) => (c.classList.contains('card') ? c : c.querySelector(':scope > .card')))
+    .filter((c) => c instanceof HTMLElement);
+const restPullPx = (card, stack) => {
+    if (!stack.classList.contains('sheet-stack--closed'))
+        return card.offsetTop;
+    const sheets = sheetsIn(stack);
+    const step = sheets[1]?.offsetTop ?? 0;
+    return Math.max(0, stack.clientHeight - sheets.length * step) + card.offsetTop;
+};
+const readFrame = (el) => { el.getBoundingClientRect(); };
+const along = (dir, startY, y) => (dir === 'down' ? Math.max(0, y - startY) : Math.max(0, startY - y));
+const pullsHead = (target, head) => {
+    if (!(target instanceof Element))
+        return false;
+    return target === head || !!target.closest('.sheet-stack__back') || !!target.closest('.card__head > :is(h1, h2, h3)');
+};
+/**
+ * The card's own pull, refresh and focus. Listeners sit on this card's head and body.
+ * `--_pull` / `--_lift` are written while a finger is down, the same way a single Sheet writes `--_drag`.
+ */
+export function useStackCard(ref, place, swallow) {
+    const placeRef = useRef(place);
+    placeRef.current = place;
+    const live = useRef(null);
+    const headPull = useRef(null);
+    const bodyPull = useRef(null);
+    const [pulling, setPulling] = useState(false);
+    useLayoutEffect(() => {
+        const el = ref.current;
+        if (!el || !place)
+            return;
+        const g = live.current;
+        if (g) {
+            el.classList.add('is-dragging');
+            el.style.setProperty(g.prop, g.px);
+            return;
+        }
+        /* a finger let go: the prop leaves in this commit, so the sheet eases from the frame just read */
+        el.style.removeProperty('--_pull');
+        el.style.removeProperty('--_lift');
+    });
+    useEffect(() => {
+        if (!place?.open || !ref.current)
+            return;
+        const cancel = focusWhenActive(ref.current, { scope: ':scope > .sheet__body' });
+        return () => { cancel(); };
+    }, [place?.open, ref]);
+    /* open: a pull down on the head folds it; a pull down in the content, already at the top, asks for a reload */
+    useEffect(() => {
+        const card = ref.current;
+        const here = placeRef.current;
+        if (!card || !here?.open)
+            return;
+        const stack = card.closest('.sheet-stack');
+        const head = card.querySelector(':scope > .card__head');
+        const scroller = card.querySelector(':scope > .sheet__body') ?? card;
+        let stopDoc = () => { };
+        const listen = (move, up, cancel) => {
+            stopDoc();
+            document.addEventListener('pointermove', move, { passive: false });
+            document.addEventListener('pointerup', up);
+            document.addEventListener('pointercancel', cancel);
+            stopDoc = () => {
+                document.removeEventListener('pointermove', move);
+                document.removeEventListener('pointerup', up);
+                document.removeEventListener('pointercancel', cancel);
+                stopDoc = () => { };
+            };
+        };
+        const primary = (e) => e.isPrimary && e.button === 0;
+        const armSwallow = () => {
+            swallow.current = true;
+            requestAnimationFrame(() => { swallow.current = false; });
+        };
+        const release = (prop) => {
+            live.current = null;
+            card.classList.remove('is-dragging');
+            readFrame(card);
+            card.style.removeProperty(prop);
+        };
+        const onHeadDown = (e) => {
+            e.stopPropagation();
+            if (!head || !stack || !primary(e) || headPull.current || bodyPull.current)
+                return;
+            if (!pullsHead(e.target, head))
+                return;
+            const slop = pxFromRem(SLOP_REM);
+            const commit = pxFromRem(COMMIT_REM);
+            const pull = { pointerId: e.pointerId, startY: e.clientY, last: 0, cap: Math.max(restPullPx(card, stack), commit), commit, slop, moved: false };
+            headPull.current = pull;
+            const onMove = (ev) => {
+                if (ev.pointerId !== pull.pointerId || headPull.current !== pull)
+                    return;
+                const dy = along('down', pull.startY, ev.clientY);
+                pull.last = dy;
+                if (dy < pull.slop)
+                    return;
+                pull.moved = true;
+                ev.preventDefault();
+                try {
+                    if (head && !head.hasPointerCapture(ev.pointerId))
+                        head.setPointerCapture(ev.pointerId);
+                }
+                catch { /* the pointer is already gone */ }
+                live.current = { prop: '--_pull', px: `${Math.min(dy, pull.cap)}px` };
+                card.classList.add('is-dragging');
+                card.style.setProperty('--_pull', live.current.px);
+            };
+            const onUp = (ev) => {
+                if (ev.pointerId !== pull.pointerId || headPull.current !== pull)
+                    return;
+                const dy = Math.max(pull.last, along('down', pull.startY, ev.clientY));
+                const moved = pull.moved || dy >= pull.slop;
+                headPull.current = null;
+                stopDoc();
+                if (moved && dy >= pull.commit) {
+                    card.classList.remove('is-dragging');
+                    readFrame(card);
+                    live.current = null;
+                    flushSync(() => placeRef.current?.onClose());
+                    if (card.isConnected && card.classList.contains('is-open') && card.style.getPropertyValue('--_pull'))
+                        release('--_pull');
+                }
+                else
+                    release('--_pull');
+                if (moved)
+                    armSwallow();
+            };
+            const onCancel = (ev) => {
+                if (ev.pointerId !== pull.pointerId || headPull.current !== pull)
+                    return;
+                headPull.current = null;
+                stopDoc();
+                release('--_pull');
+            };
+            listen(onMove, onUp, onCancel);
+        };
+        const onBodyDown = (e) => {
+            const ask = placeRef.current;
+            if (!primary(e) || headPull.current || bodyPull.current || !ask?.onRefresh || (ask.open && ask.refreshing))
+                return;
+            if (scroller.scrollTop > 0)
+                return;
+            if (e.target instanceof Element && e.target.closest('.card__head'))
+                return;
+            const slop = pxFromRem(SLOP_REM);
+            const commit = pxFromRem(COMMIT_REM);
+            const pull = { pointerId: e.pointerId, startX: e.clientX, startY: e.clientY, lastDy: 0, commit, slop, moved: false, drop: false };
+            bodyPull.current = pull;
+            const onMove = (ev) => {
+                if (ev.pointerId !== pull.pointerId || bodyPull.current !== pull)
+                    return;
+                if (scroller.scrollTop > 0) {
+                    pull.drop = true;
+                    return;
+                }
+                if (pull.drop)
+                    return;
+                const dx = ev.clientX - pull.startX;
+                const dy = ev.clientY - pull.startY;
+                pull.lastDy = Math.max(0, dy);
+                if (!pull.moved && !pull.drop) {
+                    if (Math.max(Math.abs(dx), Math.abs(dy)) < pull.slop)
+                        return;
+                    if (Math.abs(dx) > dy || dy <= 0) {
+                        pull.drop = true;
+                        return;
+                    }
+                }
+                if (!pull.moved)
+                    flushSync(() => setPulling(true));
+                pull.moved = true;
+                ev.preventDefault();
+                try {
+                    if (!scroller.hasPointerCapture(ev.pointerId))
+                        scroller.setPointerCapture(ev.pointerId);
+                }
+                catch { /* the pointer is already gone */ }
+                scroller.style.setProperty('--_refresh', `${Math.min(dy, pull.commit)}px`);
+            };
+            const finish = () => {
+                scroller.style.removeProperty('--_refresh');
+                setPulling(false);
+            };
+            const onUp = (ev) => {
+                if (ev.pointerId !== pull.pointerId || bodyPull.current !== pull)
+                    return;
+                const dy = Math.max(pull.lastDy, Math.max(0, ev.clientY - pull.startY));
+                const go = pull.moved && !pull.drop && scroller.scrollTop <= 0 && dy >= pull.commit;
+                bodyPull.current = null;
+                stopDoc();
+                readFrame(scroller);
+                finish();
+                if (go)
+                    placeRef.current?.onRefresh?.();
+                if (pull.moved)
+                    armSwallow();
+            };
+            const onCancel = (ev) => {
+                if (ev.pointerId !== pull.pointerId || bodyPull.current !== pull)
+                    return;
+                bodyPull.current = null;
+                stopDoc();
+                finish();
+            };
+            listen(onMove, onUp, onCancel);
+        };
+        /* a finger: the browser takes a touch for its own scroll at the first move unless that move is refused here */
+        let touch = null;
+        const onTouchStart = (e) => {
+            const t = e.touches[0];
+            const ask = placeRef.current;
+            const inHead = e.target instanceof Element && !!e.target.closest('.card__head');
+            touch = e.touches.length === 1 && t && ask?.onRefresh && !(ask.open && ask.refreshing) && scroller.scrollTop <= 0 && !inHead
+                ? { x: t.clientX, y: t.clientY, ours: null } : null;
+        };
+        const onTouchMove = (e) => {
+            const t = e.touches[0];
+            if (!touch || !t)
+                return;
+            const dx = t.clientX - touch.x;
+            const dy = t.clientY - touch.y;
+            if (touch.ours == null)
+                touch.ours = dy > 0 && dy >= Math.abs(dx) && scroller.scrollTop <= 0;
+            if (touch.ours && e.cancelable)
+                e.preventDefault();
+        };
+        head?.addEventListener('pointerdown', onHeadDown);
+        scroller.addEventListener('pointerdown', onBodyDown);
+        scroller.addEventListener('touchstart', onTouchStart, { passive: true });
+        scroller.addEventListener('touchmove', onTouchMove, { passive: false });
+        return () => {
+            scroller.removeEventListener('touchstart', onTouchStart);
+            scroller.removeEventListener('touchmove', onTouchMove);
+            stopDoc();
+            headPull.current = null;
+            bodyPull.current = null;
+            scroller.style.removeProperty('--_refresh');
+            setPulling(false);
+            if (live.current?.prop === '--_pull')
+                release('--_pull');
+            head?.removeEventListener('pointerdown', onHeadDown);
+            scroller.removeEventListener('pointerdown', onBodyDown);
+        };
+    }, [place?.open, !!place?.onRefresh, ref, swallow]);
+    /* none open: a pull up on a peeked head follows the finger and, past the commit, opens this sheet */
+    useEffect(() => {
+        const card = ref.current;
+        const here = placeRef.current;
+        if (!card || !here || here.open || here.before || here.after)
+            return;
+        const stack = card.closest('.sheet-stack');
+        const head = card.querySelector(':scope > .card__head');
+        if (!head || !stack)
+            return;
+        let stopDoc = () => { };
+        const listen = (move, up, cancel) => {
+            stopDoc();
+            document.addEventListener('pointermove', move, { passive: false });
+            document.addEventListener('pointerup', up);
+            document.addEventListener('pointercancel', cancel);
+            stopDoc = () => {
+                document.removeEventListener('pointermove', move);
+                document.removeEventListener('pointerup', up);
+                document.removeEventListener('pointercancel', cancel);
+                stopDoc = () => { };
+            };
+        };
+        const armSwallow = () => {
+            swallow.current = true;
+            requestAnimationFrame(() => { swallow.current = false; });
+        };
+        const release = () => {
+            live.current = null;
+            card.classList.remove('is-dragging');
+            readFrame(card);
+            card.style.removeProperty('--_lift');
+        };
+        const onDown = (e) => {
+            if (!e.isPrimary || e.button !== 0 || headPull.current)
+                return;
+            if (!pullsHead(e.target, head)) {
+                if (!(e.target instanceof Element) || !e.target.closest('button, a'))
+                    return;
+                const startY = e.clientY;
+                const id = e.pointerId;
+                const slop = pxFromRem(SLOP_REM);
+                const move = (ev) => {
+                    if (ev.pointerId !== id)
+                        return;
+                    if (Math.abs(ev.clientY - startY) >= slop)
+                        swallow.current = true;
+                };
+                const up = (ev) => {
+                    if (ev.pointerId !== id)
+                        return;
+                    document.removeEventListener('pointermove', move);
+                    document.removeEventListener('pointerup', up);
+                    if (swallow.current)
+                        requestAnimationFrame(() => { swallow.current = false; });
+                };
+                document.addEventListener('pointermove', move);
+                document.addEventListener('pointerup', up);
+                return;
+            }
+            e.stopPropagation();
+            const slop = pxFromRem(SLOP_REM);
+            const commit = pxFromRem(COMMIT_REM);
+            const travel = card.getBoundingClientRect().top - stack.getBoundingClientRect().top;
+            const pull = { pointerId: e.pointerId, startY: e.clientY, last: 0, cap: Math.max(travel, commit), commit, slop, moved: false };
+            headPull.current = pull;
+            const onMove = (ev) => {
+                if (ev.pointerId !== pull.pointerId || headPull.current !== pull)
+                    return;
+                const upPx = along('up', pull.startY, ev.clientY);
+                pull.last = upPx;
+                if (upPx < pull.slop)
+                    return;
+                pull.moved = true;
+                ev.preventDefault();
+                try {
+                    if (!head.hasPointerCapture(ev.pointerId))
+                        head.setPointerCapture(ev.pointerId);
+                }
+                catch { /* the pointer is already gone */ }
+                live.current = { prop: '--_lift', px: `${Math.min(upPx, pull.cap)}px` };
+                card.classList.add('is-dragging');
+                card.style.setProperty('--_lift', live.current.px);
+            };
+            const onUp = (ev) => {
+                if (ev.pointerId !== pull.pointerId || headPull.current !== pull)
+                    return;
+                const upPx = Math.max(pull.last, along('up', pull.startY, ev.clientY));
+                const moved = pull.moved || upPx >= pull.slop;
+                headPull.current = null;
+                stopDoc();
+                if (moved && upPx >= pull.commit) {
+                    card.classList.remove('is-dragging');
+                    readFrame(card);
+                    live.current = null;
+                    flushSync(() => placeRef.current?.onOpen());
+                    if (card.isConnected && !card.classList.contains('is-open') && card.style.getPropertyValue('--_lift'))
+                        release();
+                }
+                else
+                    release();
+                if (moved)
+                    armSwallow();
+            };
+            const onCancel = (ev) => {
+                if (ev.pointerId !== pull.pointerId || headPull.current !== pull)
+                    return;
+                headPull.current = null;
+                stopDoc();
+                release();
+            };
+            listen(onMove, onUp, onCancel);
+        };
+        head.addEventListener('pointerdown', onDown);
+        return () => {
+            stopDoc();
+            headPull.current = null;
+            if (live.current?.prop === '--_lift')
+                release();
+            head.removeEventListener('pointerdown', onDown);
+        };
+    }, [place?.open, place?.before, place?.after, ref, swallow]);
+    return pulling;
+}

package/dist/sheets/stepCursor.d.ts

@@ -0,0 +1,12 @@
+export interface StepCursorValue {
+    parked: boolean;
+    /** cleared by the open step at the start of its render; the first field this render writes its id, and keeps the mark if it renders again on its own */
+    slot: {
+        id: string | null;
+    };
+}
+export declare const StepCursor: import("react").Context<StepCursorValue | null>;
+export declare function useStepCursor(): {
+    'data-autofocus'?: '';
+    'data-cursor'?: '';
+};

package/dist/sheets/stepCursor.js

@@ -0,0 +1,15 @@
+/* the open step's first field renders its own cursor marks. Sheet reads `data-autofocus` when it rises;
+   `data-cursor` is the caret a phone shows while the keyboard waits on the steps' holder. */
+import { createContext, useContext, useId } from 'react';
+export const StepCursor = createContext(null);
+export function useStepCursor() {
+    const ctx = useContext(StepCursor);
+    const id = useId();
+    if (!ctx)
+        return {};
+    if (ctx.slot.id == null)
+        ctx.slot.id = id;
+    if (ctx.slot.id !== id)
+        return {};
+    return ctx.parked ? { 'data-autofocus': '', 'data-cursor': '' } : { 'data-autofocus': '' };
+}

package/dist/templates/Home.d.ts

@@ -49,7 +49,7 @@ export interface HomeProps extends Omit<ComponentProps<typeof Screen>, 'children
  * Home — TEMPLATE, a `Screen` with its parts filled — top: the AppBar · content: the `base` (title, welcome…) over a closed `SheetStack` · no bottom
  * (the stack is content, never the bottom: open, a sheet fills everything under the top).
  * Every section is a `StackSheet` of three parts: SHEET HEAD (title + icon tabs, a count over a tab; the back button once open) · SHEET BODY (scrolls) · SHEET FOOT (the CTA,
- * at the bottom). A tap on a head brings that sheet up to fill everything under the top. Only the open sheet's body is rendered — three
+ * at the bottom). A tap on a head brings that sheet up to fill everything under the top. With a LayerHistory above and no `open` prop, that open sheet is one history entry named `home`. Only the open sheet's body is rendered — three
  * sections on one home never cost three pages (`keep` holds a body once opened).
  */
 export declare function Home({ top, title, sheets, open: openProp, defaultOpen, onOpenChange, onRefresh, refreshing, base, keep, backLabel, backAt, children, ...rest }: HomeProps): import("react").JSX.Element;

package/dist/templates/Home.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useState } from 'react';
 import { useControlled } from '../state.js';
+import { useOptionalLayer } from '../scaffold/LayerHistory.js';
 import { Screen } from '../scaffold/Screen.js';
 import { SheetStack } from '../sheets/SheetStack.js';
 import { StackSheet } from '../sheets/StackSheet.js';
@@ -12,20 +13,34 @@ const LEAVE = 800; // ms: a closing sheet keeps its body until it has slid home
  * Home — TEMPLATE, a `Screen` with its parts filled — top: the AppBar · content: the `base` (title, welcome…) over a closed `SheetStack` · no bottom
  * (the stack is content, never the bottom: open, a sheet fills everything under the top).
  * Every section is a `StackSheet` of three parts: SHEET HEAD (title + icon tabs, a count over a tab; the back button once open) · SHEET BODY (scrolls) · SHEET FOOT (the CTA,
- * at the bottom). A tap on a head brings that sheet up to fill everything under the top. Only the open sheet's body is rendered — three
+ * at the bottom). A tap on a head brings that sheet up to fill everything under the top. With a LayerHistory above and no `open` prop, that open sheet is one history entry named `home`. Only the open sheet's body is rendered — three
  * 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, onRefresh, refreshing, base, keep, backLabel = word('back'), backAt, children, ...rest }) {
-    const [open, change] = useControlled(openProp, defaultOpen, onOpenChange);
+    const layer = useOptionalLayer('home');
+    const [local, change] = useControlled(openProp, defaultOpen, onOpenChange);
+    // A passed `open` is the parent's. With no LayerHistory the index stays local, so a story without a router still opens sheets.
+    const shown = openProp !== undefined ? local : layer == null ? local : typeof layer.value === 'number' ? layer.value : null;
+    const request = (next) => {
+        if (openProp !== undefined || layer == null) {
+            change(next);
+            return;
+        }
+        onOpenChange?.(next);
+        if (next == null)
+            layer.close();
+        else
+            layer.open(next);
+    };
     const [leaving, setLeaving] = useState(null);
-    const [seen, setSeen] = useState(() => new Set(open != null ? [open] : []));
-    const [was, setWas] = useState(open);
-    if (was !== open) { // derived during render: which body must stay while its sheet slides home
-        if (was != null && open == null)
+    const [seen, setSeen] = useState(() => new Set(shown != null ? [shown] : []));
+    const [was, setWas] = useState(shown);
+    if (was !== shown) { // derived during render: which body must stay while its sheet slides home
+        if (was != null && shown == null)
             setLeaving(was);
-        if (open != null && !seen.has(open))
-            setSeen(new Set(seen).add(open));
-        setWas(open);
+        if (shown != null && !seen.has(shown))
+            setSeen(new Set(seen).add(shown));
+        setWas(shown);
     }
     useEffect(() => {
         if (leaving == null)
@@ -34,6 +49,6 @@ export function Home({ top, title, sheets, open: openProp, defaultOpen = null, o
         return () => clearTimeout(t);
     }, [leaving]);
     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, onRefresh: onRefresh, refreshing: refreshing, 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, backAt: backAt, 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] }));
+    const shows = (i) => i === shown || 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: shown, onOpenChange: request, onRefresh: onRefresh, refreshing: refreshing, 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, backAt: backAt, 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usableapp/cardds",
-  "version": "0.7.53",
+  "version": "0.7.55",
   "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.",