@usableapp/cardds 0.7.53 → 0.7.54

package/dist/sheets/SheetStack.js

@@ -1,37 +1,27 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useLayoutEffect, useRef } from 'react';
-import { flushSync } from 'react-dom';
-import { focusWhenActive, useControlled, useLatest } from '../state.js';
+import { Children, cloneElement, isValidElement, useEffect, useRef, useState } from 'react';
+import { useControlled, warnOnce } from '../state.js';
 import { cx } from '../cx.js';
+import { Card } from '../cards/Card.js';
+import { StackSheet } from './StackSheet.js';
 const PHASE = 380; // ms before the before-pack un-tucks on close, so the after-pack is clear first
-/* the stack's sheets, in slot order: its direct children — or, where a host wraps each child in one box of its own, the first .card in
-   each. Never deeper: a card inside a sheet's content is content. The base is what shows behind the sheets, never a sheet. */
-const sheetsOf = (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 SLOP_REM = 0.5;
-const COMMIT_REM = 4.5;
-const pxFromRem = (rem) => parseFloat(getComputedStyle(document.documentElement).fontSize) * rem;
-const restPullPx = (card, stack) => {
-    if (!stack.classList.contains('sheet-stack--closed'))
-        return card.offsetTop;
-    const sheets = sheetsOf(stack);
-    const step = sheets[1]?.offsetTop ?? 0;
-    return Math.max(0, stack.clientHeight - sheets.length * step) + card.offsetTop;
-};
-const readFrame = (card) => { card.getBoundingClientRect(); };
-const along = (dir, startY, y) => (dir === 'down' ? Math.max(0, y - startY) : Math.max(0, startY - y));
-const releaseProp = (card, prop) => {
-    card.classList.remove('is-dragging');
-    readFrame(card);
-    card.style.removeProperty(prop);
-};
-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)');
-};
+const SHEET = new Set([Card, StackSheet]);
+/* one wrapper around a sheet is fine (a host's own box). The props land on the Card or StackSheet inside it, so the card renders them. */
+function stamp(child, place) {
+    if (SHEET.has(child.type))
+        return cloneElement(child, { stack: place });
+    const inner = Children.toArray(child.props.children);
+    let found = false;
+    const next = inner.map((c) => {
+        if (found || !isValidElement(c) || !SHEET.has(c.type))
+            return c;
+        found = true;
+        return cloneElement(c, { stack: place });
+    });
+    if (!found)
+        warnOnce('stack-child', 'cardds SheetStack: a sheet is a Card or a StackSheet — one wrapper around it is fine. open and refreshing are that card\'s props; a plain element cannot hold them.');
+    return found ? cloneElement(child, {}, ...next) : child;
+}
 /**
  * SheetStack — the MENU: sheets stacked like paper at the middle of the home screen, every one a main section.
  * Children are Cards, direct children only, at most five: first = the back of the stack, last = the front (open) sheet.
@@ -42,420 +32,48 @@ const pullsHead = (target, head) => {
  * 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`.
  *
  * A COMPONENT, not a wiring: WHICH sheet is open is the app's (`open` + `onOpenChange`, or `defaultOpen`) — so a button anywhere, a route or
- * the phone's back button can open and close a section. Its own behaviour stays inside and only asks: a tap on a peeked head, or a pull up on
- * that head (the title, the back button, or the head itself — not a tab), opens it. The open sheet's StackBack or its title, tapped or pulled
- * down, folds it. A pull down in the content, already at the top, asks `onRefresh` and does not fold; `refreshing` fades that sheet's four grip dots up and down while the app reloads. 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.
+ * the phone's back button can open and close a section. WHAT the sheet does with that, and with `refreshing`, lives on the card (`stack`):
+ * the place classes, the grip, the pull. The stack only says which index. Sheets are rigid — the open 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); never a size.
  */
-export function SheetStack({ mode = 'tap', open, defaultOpen = null, onOpenChange, onRefresh, refreshing = null, fanned, closed, base, className, children, onClick, onKeyDown, ...rest }) {
+export function SheetStack({ mode = 'tap', open, defaultOpen = null, onOpenChange, onRefresh, refreshing = null, fanned, closed, base, className, children, ...rest }) {
     const [current, request] = useControlled(open, defaultOpen, onOpenChange);
-    const ref = useRef(null);
-    const was = useRef(null);
-    const untuck = useRef(null);
-    const headPull = useRef(null);
-    const bodyPull = useRef(null);
-    const swallow = useRef(false);
-    const refreshRef = useLatest(onRefresh);
-    const loadingRef = useLatest(refreshing);
-    /* 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);
-        for (const c of sheets)
-            if (!c.classList.contains('is-dragging')) {
-                c.style.removeProperty('--_pull');
-                c.style.removeProperty('--_lift');
-            }
-        // 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;
-        });
-        sheets.forEach((c, i) => {
-            const loading = refreshing === i && current === i;
-            c.classList.toggle('is-loading', loading);
-            if (loading)
-                c.setAttribute('aria-busy', 'true');
-            else
-                c.removeAttribute('aria-busy');
-        });
-        const prev = was.current;
-        was.current = current;
-        if (current != null) {
-            if (untuck.current) {
-                clearTimeout(untuck.current);
-                untuck.current = null;
-            }
-            sheets.forEach((c, i) => {
-                c.classList.toggle('is-open', i === current);
-                c.classList.toggle('is-before', i < current); // already behind it — tuck under the next strip and get covered…
-                c.classList.toggle('is-after', i > current); // in front of it — these leave below
-                c.style.setProperty('--stagger', String(i < current ? current - 1 - i : 0)); // …nearest one first
-            });
-            return;
-        }
-        if (prev != null && prev !== current) {
-            // beat 1: the after-pack comes back in while the opened sheet drops into its slot, over the still-covered before-pack
-            sheets.forEach((c) => c.classList.remove('is-open', 'is-after'));
-            // beat 2: then the before-pack slides back up from behind it, the same order it tucked away
-            untuck.current = setTimeout(() => { untuck.current = null; if (ref.current)
-                sheetsOf(ref.current).forEach((c) => c.classList.remove('is-before')); }, PHASE);
-            return;
-        }
-        if (!untuck.current)
-            sheets.forEach((c) => c.classList.remove('is-open', 'is-before', 'is-after'));
-    });
-    /* a sheet opened → its field has the cursor once it has slid up (the one rule of every part that becomes active: focusWhenActive) */
-    useEffect(() => {
-        if (current == null || mode !== 'tap' || !ref.current)
-            return;
-        const cancel = focusWhenActive(sheetsOf(ref.current)[current], { scope: ':scope > .sheet__body' });
-        return () => { cancel(); };
-    }, [current, mode]);
-    useEffect(() => {
-        const stack = ref.current;
-        if (!stack || mode !== 'tap' || current == null)
-            return;
-        const card = sheetsOf(stack)[current];
-        if (!card)
-            return;
-        const head = card.querySelector(':scope > .card__head');
-        const scroller = card.querySelector(':scope > .sheet__body') ?? card;
-        const index = current;
-        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 onHeadDown = (e) => {
-            e.stopPropagation();
-            if (!head || !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, card, index, dir: 'down', 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 */ }
-                card.classList.add('is-dragging');
-                card.style.setProperty('--_pull', `${Math.min(dy, pull.cap)}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);
-                    flushSync(() => request(null));
-                    if (card.isConnected && card.classList.contains('is-open') && card.style.getPropertyValue('--_pull'))
-                        releaseProp(card, '--_pull');
-                }
-                else
-                    releaseProp(card, '--_pull');
-                if (moved)
-                    armSwallow();
-            };
-            const onCancel = (ev) => {
-                if (ev.pointerId !== pull.pointerId || headPull.current !== pull)
-                    return;
-                headPull.current = null;
-                stopDoc();
-                releaseProp(card, '--_pull');
-            };
-            listen(onMove, onUp, onCancel);
-        };
-        const onBodyDown = (e) => {
-            if (!primary(e) || headPull.current || bodyPull.current || !refreshRef.current || loadingRef.current === index)
-                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, scroller, index, 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;
-                    }
-                }
-                pull.moved = true;
-                ev.preventDefault();
-                try {
-                    if (!scroller.hasPointerCapture(ev.pointerId))
-                        scroller.setPointerCapture(ev.pointerId);
-                }
-                catch { /* the pointer is already gone */ }
-                scroller.classList.add('is-refreshing');
-                scroller.style.setProperty('--_refresh', `${Math.min(dy, pull.commit)}px`);
-            };
-            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 ask = pull.moved && !pull.drop && scroller.scrollTop <= 0 && dy >= pull.commit;
-                bodyPull.current = null;
-                stopDoc();
-                scroller.classList.remove('is-refreshing');
-                readFrame(scroller);
-                scroller.style.removeProperty('--_refresh');
-                if (ask)
-                    refreshRef.current?.(pull.index);
-                if (pull.moved)
-                    armSwallow();
-            };
-            const onCancel = (ev) => {
-                if (ev.pointerId !== pull.pointerId || bodyPull.current !== pull)
-                    return;
-                bodyPull.current = null;
-                stopDoc();
-                scroller.classList.remove('is-refreshing');
-                scroller.style.removeProperty('--_refresh');
-            };
-            listen(onMove, onUp, onCancel);
-        };
-        /* a FINGER: the browser takes a touch for its own scroll at the first move and cancels the pointer — unless that first move is
-           refused. So the first move decides, once: down and at the top = the pull's (refused, no scroll); anything else = the scroll's */
-        let touch = null;
-        const onTouchStart = (e) => {
-            const t = e.touches[0];
-            const inHead = e.target instanceof Element && !!e.target.closest('.card__head');
-            touch = e.touches.length === 1 && t && refreshRef.current && loadingRef.current !== index && 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();
-            const held = headPull.current;
-            headPull.current = null;
-            bodyPull.current = null;
-            if (held?.card.classList.contains('is-dragging'))
-                releaseProp(held.card, '--_pull');
-            head?.removeEventListener('pointerdown', onHeadDown);
-            scroller.removeEventListener('pointerdown', onBodyDown);
-        };
-    }, [current, mode, request]);
-    /* none open: a pull UP on a peeked head (not a tab) follows the finger and, past the commit, opens that sheet */
+    const prev = useRef(current);
+    const [closingFrom, setClosingFrom] = useState(null);
+    if (prev.current !== current) {
+        const from = prev.current;
+        prev.current = current;
+        if (from != null && current == null)
+            setClosingFrom(from);
+        else if (current != null && closingFrom != null)
+            setClosingFrom(null);
+    }
     useEffect(() => {
-        const stack = ref.current;
-        if (!stack || mode !== 'tap' || current != null)
+        if (closingFrom == null)
             return;
-        const sheets = sheetsOf(stack);
-        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 t = setTimeout(() => setClosingFrom(null), PHASE);
+        return () => clearTimeout(t);
+    }, [closingFrom]);
+    const closing = current == null && closingFrom != null;
+    const anchor = current ?? closingFrom;
+    const items = Children.toArray(children);
+    let sheet = 0;
+    const stamped = mode === 'tap' ? items.map((child) => {
+        if (!isValidElement(child))
+            return child;
+        const i = sheet++;
+        const before = anchor != null && i < anchor;
+        const place = {
+            open: !closing && current === i,
+            refreshing: refreshing === i,
+            before,
+            after: !closing && current != null && i > current,
+            stagger: before && anchor != null ? anchor - 1 - i : 0,
+            onOpen: () => request(i),
+            onClose: () => request(null),
+            onRefresh: onRefresh ? () => onRefresh(i) : undefined,
         };
-        const armSwallow = () => {
-            swallow.current = true;
-            requestAnimationFrame(() => { swallow.current = false; });
-        };
-        const cleanups = [];
-        sheets.forEach((card, index) => {
-            const head = card.querySelector(':scope > .card__head');
-            if (!head)
-                return;
-            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, card, index, dir: 'up', 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 */ }
-                    card.classList.add('is-dragging');
-                    card.style.setProperty('--_lift', `${Math.min(upPx, pull.cap)}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);
-                        flushSync(() => request(pull.index));
-                        if (card.isConnected && !card.classList.contains('is-open'))
-                            releaseProp(card, '--_lift');
-                    }
-                    else
-                        releaseProp(card, '--_lift');
-                    if (moved)
-                        armSwallow();
-                };
-                const onCancel = (ev) => {
-                    if (ev.pointerId !== pull.pointerId || headPull.current !== pull)
-                        return;
-                    headPull.current = null;
-                    stopDoc();
-                    releaseProp(card, '--_lift');
-                };
-                listen(onMove, onUp, onCancel);
-            };
-            head.addEventListener('pointerdown', onDown);
-            cleanups.push(() => head.removeEventListener('pointerdown', onDown));
-        });
-        return () => {
-            stopDoc();
-            const held = headPull.current;
-            headPull.current = null;
-            if (held?.dir === 'up' && held.card.classList.contains('is-dragging'))
-                releaseProp(held.card, '--_lift');
-            cleanups.forEach((fn) => fn());
-        };
-    }, [current, mode, request]);
-    const click = (e) => {
-        onClick?.(e);
-        if (swallow.current)
-            return;
-        const stack = ref.current;
-        if (!stack || mode !== 'tap')
-            return;
-        const target = e.target;
-        const sheets = sheetsOf(stack);
-        const at = sheets.findIndex((c) => c.contains(target)); // the sheet the tap landed in — not the nearest .card: a content card inside an open sheet must not count
-        if (target.closest('.sheet-stack__back')) {
-            request(null);
-            return;
-        }
-        // the open sheet's TITLE folds it too (Lh 2026-09-23) — a bigger target than the back button; the back stays the keyboard's way
-        if (current != null && at === current && target.closest('.card__head > :is(h1, h2, h3)')) {
-            request(null);
-            return;
-        }
-        if (at >= 0 && current == null)
-            request(at);
-    };
-    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 })] }));
+        return stamp(child, place);
+    }) : items;
+    return (_jsxs("div", { className: cx('sheet-stack', mode !== 'static' && `sheet-stack--${mode}`, fanned && 'sheet-stack--fanned', closed && 'sheet-stack--closed', className), ...rest, children: [stamped, base != null && _jsx("div", { className: "sheet-stack__base", children: base })] }));
 }

package/dist/sheets/SheetSteps.js

@@ -8,6 +8,7 @@ import { FormNote } from '../forms/FormNote.js';
 import { CheckContext } from '../forms/check.js';
 import { word } from '../words.js';
 import { usePile } from './sheetStepsPile.js';
+import { StepCursor } from './stepCursor.js';
 const MOVE_MS = 350; // = --motion-sheet: the accordion's beat
 const SWIPE_REM = 3; // an up/down move longer than this (and mostly up/down) is a swipe
 /* the open step's first field — the one that takes the cursor; NOW_INPUT: the one a typed character can be handed to */
@@ -65,16 +66,8 @@ export function SheetSteps({ at, reached, defaultAt = 0, onAtChange, reversible
     };
     /* the step changed, in TWO beats one right after the other: (1) the old step folds while the new one unfolds — nothing else
        moves; (2) then the pile settles (the two latest done rows in sight), gliding. The cursor goes into the new step at once
-       (so a phone's keyboard stays up) but without scrolling. Not on arrival — the body keeps its scroll. */
-    /* the open step's first field is the one to take the cursor when the sheet comes onto the screen (Sheet reads `data-autofocus`) */
-    useLayoutEffect(() => {
-        ref.current?.querySelectorAll('[data-autofocus]').forEach((el) => el.removeAttribute('data-autofocus'));
-        const field = ref.current?.querySelector(NOW_FIELD);
-        field?.setAttribute('data-autofocus', '');
-        ref.current?.querySelectorAll('[data-cursor]').forEach((el) => el.removeAttribute('data-cursor'));
-        if (parked && coarse())
-            field?.setAttribute('data-cursor', ''); // the keyboard is on the holder, for this field: it shows the cursor
-    });
+       (so a phone's keyboard stays up) but without scrolling. Not on arrival — the body keeps its scroll.
+       The open step's first field renders `data-autofocus` itself (Sheet reads it when the sheet comes up). */
     useLayoutEffect(() => {
         if (first.current) {
             first.current = false;
@@ -164,7 +157,7 @@ export function SheetSteps({ at, reached, defaultAt = 0, onAtChange, reversible
         Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value').set.call(field, field.value + typed);
         field.dispatchEvent(new Event('input', { bubbles: true }));
     };
-    return (_jsxs("div", { ref: ref, className: cx('sheet-steps', !reversible && 'sheet-steps--locked', className), style: style, onFocus: focusIn, onBlur: focusOut, onPointerDown: down, onPointerUp: up, onPointerCancel: (e) => { onPointerCancel?.(e); press.current = null; }, ...rest, children: [_jsx("input", { ref: holderRef, className: "sheet-steps__holder", "aria-hidden": true, tabIndex: -1, autoComplete: "off", onFocus: () => setParked(true), onBlur: () => setParked(false), onInput: handOver }), _jsx("ol", { className: "sheet-steps__track", children: steps.map((step, i) => (_jsx(StepCtx.Provider, { value: { numbered, i, at: current, furthest: reach, count, reversible, go, park }, children: step }, step.key ?? i))) }), finish != null && ( // always in sight; it takes taps only once every step is done (or skipped)
+    return (_jsxs("div", { ref: ref, className: cx('sheet-steps', !reversible && 'sheet-steps--locked', className), style: style, onFocus: focusIn, onBlur: focusOut, onPointerDown: down, onPointerUp: up, onPointerCancel: (e) => { onPointerCancel?.(e); press.current = null; }, ...rest, children: [_jsx("input", { ref: holderRef, className: "sheet-steps__holder", "aria-hidden": true, tabIndex: -1, autoComplete: "off", onFocus: () => setParked(true), onBlur: () => setParked(false), onInput: handOver }), _jsx("ol", { className: "sheet-steps__track", children: steps.map((step, i) => (_jsx(StepCtx.Provider, { value: { numbered, i, at: current, furthest: reach, count, reversible, go, park, parked }, children: step }, step.key ?? i))) }), finish != null && ( // always in sight; it takes taps only once every step is done (or skipped)
             _jsx("div", { className: "sheet-steps__finish", children: isValidElement(finish) ? cloneElement(finish, { disabled: reach < count || finish.props.disabled }) : finish }))] }));
 }
 /* the step's format checks, as one group — see SheetStep */
@@ -213,9 +206,12 @@ export function SheetStep({ title, summary, skippable, skipLabel = word('skip'),
     const ctx = useContext(StepCtx);
     if (!ctx)
         throw new Error('SheetStep goes inside a SheetSteps');
-    const { numbered, i, at, furthest, count, reversible, go, park } = ctx;
+    const { numbered, i, at, furthest, count, reversible, go, park, parked } = ctx;
     const phase = i === at ? 'now' : i < furthest ? 'done' : 'next';
     const off = phase !== 'now';
+    const slot = useRef({ id: null });
+    slot.current.id = null;
+    const cursor = phase === 'now' ? { parked: parked && coarse(), slot: slot.current } : null;
     const { note, group, press } = useStepChecks(off, park);
     /* a press on the step's button or link keeps the cursor where it is: the button still clicks, but the field keeps the focus, so a
        phone's keyboard does not drop and come back (the pile jumped up and down with it — Lh 2026-09-24) */
@@ -235,5 +231,5 @@ export function SheetStep({ title, summary, skippable, skipLabel = word('skip'),
             btn.click();
         }
     };
-    return (_jsxs("li", { className: cx('sheet-step', `sheet-step--${phase}`, busy != null && busy !== false && 'sheet-step--busy', className), "aria-current": phase === 'now' ? 'step' : undefined, "aria-busy": busy != null && busy !== false ? true : undefined, "data-skippable": skippable || undefined, ...rest, children: [_jsxs("div", { className: "sheet-step__head", inert: off || undefined, children: [numbered && _jsx("span", { className: "sheet-step__num", "aria-hidden": true, children: i + 1 }), _jsx("h3", { className: "sheet-step__title", tabIndex: -1, children: title }), phase === 'done' && summary != null && _jsx("span", { className: "sheet-step__summary t-caption", children: summary }), phase === 'done' && _jsx(Icon, { name: "check", size: "xs", className: "sheet-step__check" })] }), _jsx("div", { className: "sheet-step__body", children: _jsxs("div", { className: "sheet-step__inner", inert: off || undefined, onClickCapture: press, onPointerDown: keepCursor, onKeyDown: enter, children: [_jsx(CheckContext.Provider, { value: group, children: children }), _jsx(FormNote, { error: error ?? note, busy: busy }), skippable && _jsx(Link, { sm: true, muted: true, className: "sheet-step__skip", onClick: () => go(i + 1, 'skip'), children: skipLabel })] }) }), reversible && off && (_jsx("button", { type: "button", className: "sheet-step__go", "aria-label": typeof title === 'string' ? title : `${i + 1} / ${count}`, onClick: () => go(i, 'tap') }))] }));
+    return (_jsxs("li", { className: cx('sheet-step', `sheet-step--${phase}`, busy != null && busy !== false && 'sheet-step--busy', className), "aria-current": phase === 'now' ? 'step' : undefined, "aria-busy": busy != null && busy !== false ? true : undefined, "data-skippable": skippable || undefined, ...rest, children: [_jsxs("div", { className: "sheet-step__head", inert: off || undefined, children: [numbered && _jsx("span", { className: "sheet-step__num", "aria-hidden": true, children: i + 1 }), _jsx("h3", { className: "sheet-step__title", tabIndex: -1, children: title }), phase === 'done' && summary != null && _jsx("span", { className: "sheet-step__summary t-caption", children: summary }), phase === 'done' && _jsx(Icon, { name: "check", size: "xs", className: "sheet-step__check" })] }), _jsx("div", { className: "sheet-step__body", children: _jsxs("div", { className: "sheet-step__inner", inert: off || undefined, onClickCapture: press, onPointerDown: keepCursor, onKeyDown: enter, children: [_jsx(StepCursor.Provider, { value: cursor, children: _jsx(CheckContext.Provider, { value: group, children: children }) }), _jsx(FormNote, { error: error ?? note, busy: busy }), skippable && _jsx(Link, { sm: true, muted: true, className: "sheet-step__skip", onClick: () => go(i + 1, 'skip'), children: skipLabel })] }) }), reversible && off && (_jsx("button", { type: "button", className: "sheet-step__go", "aria-label": typeof title === 'string' ? title : `${i + 1} / ${count}`, onClick: () => go(i, 'tap') }))] }));
 }

package/dist/sheets/StackSheet.d.ts

@@ -1,6 +1,7 @@
 import { type ComponentProps, type ReactNode } from 'react';
 import { type Tone } from '../cards/Card.js';
 import { type IconName } from '../type/Icon.js';
+import type { StackPlace } from './stackCard.js';
 export interface StackSheetTab {
     id: string;
     icon: IconName;
@@ -29,6 +30,8 @@ export interface StackSheetProps extends Omit<ComponentProps<'article'>, 'title'
     /** where the back button stands: `none` (default — hidden for now, Lh 2026-09-29: not used in real work yet; a tap on the open sheet's title folds it) ·
      *  `end` (after the tabs, chevron DOWN: the sheet folds down) · `start` (before the title, chevron left) */
     backAt?: 'none' | 'start' | 'end';
+    /** set by `SheetStack` from the app's `open` and `refreshing`. This sheet renders what those mean */
+    stack?: StackPlace;
 }
 /**
  * StackSheet — ONE sheet of a `SheetStack`, in the one sheet shape: SHEET HEAD (back · title · tabs or an icon) pinned at the top ·
@@ -37,4 +40,4 @@ export interface StackSheetProps extends Omit<ComponentProps<'article'>, 'title'
  * 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 declare function StackSheet({ title, tone, icon, tabs, tab: tabProp, defaultTab, onTabChange, foot, backLabel, backAt, className, children, ...rest }: StackSheetProps): import("react").JSX.Element;
+export declare function StackSheet({ title, tone, icon, tabs, tab: tabProp, defaultTab, onTabChange, foot, backLabel, backAt, stack, className, children, ...rest }: StackSheetProps): import("react").JSX.Element;

package/dist/sheets/StackSheet.js

@@ -19,7 +19,7 @@ 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
@@ -37,5 +37,5 @@ export function StackSheet({ title, tone, icon, tabs, tab: tabProp, defaultTab,
         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: "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 })] }));
 }