@usableapp/cardds 0.2.1 → 0.3.0

package/dist/sheets/Drawer.js

@@ -1,15 +1,39 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Children, Fragment } from 'react';
+import { Children, Fragment, useEffect, useRef } from 'react';
 import { cx } from '../cx.js';
-/** Modal — the ask: ONE card at the centre of a `SheetStage ask`, two parts — a `Lift` (the thing being asked about, light, scrolls when tall) and a `Drawer` (the dark end that asks). No border. Two beats on appearing: drops in from above to the centre · the drawer comes out below while the lift moves up. A click on any button in the Drawer plays them backwards and fires `cardds:modal` on the stage (`detail.answer` = the button's `data-answer`) for the app to remove it. */
-export function Modal({ className, ...rest }) {
-    return _jsx("article", { className: cx('card modal', className), ...rest });
+/**
+ * Modal — the ask: ONE card at the centre of a `SheetStage ask`, two parts — a `Lift` (the thing being asked about, light, scrolls
+ * when tall) and a `Drawer` (the dark end that asks). No border. Two beats on appearing: drops in from above, then the drawer comes
+ * out below while the lift moves up.
+ * A COMPONENT, not a wiring: it does not know its buttons. They are plain `IconBtn`s / `Btn`s with the app's `onClick` — the app
+ * records the answer and sets `open={false}`; the modal's one behaviour is how it leaves.
+ */
+export function Modal({ open = true, onClosed, className, ...rest }) {
+    const ref = useRef(null);
+    const closed = useRef(onClosed);
+    closed.current = onClosed;
+    const shown = useRef(true); // the animations stand played forwards
+    useEffect(() => {
+        const el = ref.current;
+        if (!el || open === shown.current)
+            return;
+        shown.current = open;
+        const anims = el.getAnimations({ subtree: true });
+        anims.forEach((a) => a.reverse()); // the same keyframes, backwards to leave, forwards again to return — no closing keyframes to keep in step
+        if (open)
+            return;
+        let live = true;
+        void Promise.all(anims.map((a) => a.finished.catch(() => undefined))).then(() => { if (live)
+            closed.current?.(); });
+        return () => { live = false; };
+    }, [open]);
+    return _jsx("article", { ref: ref, className: cx('card modal', className), ...rest });
 }
 /** Lift — the light part of a `Modal`: the case, request or item the question is about (a CardHead, rows, a timeline); scrolls inside when tall. */
 export function Lift({ className, ...rest }) {
     return _jsx("div", { className: cx('modal__lift', className), ...rest });
 }
-/** Drawer — the dark end of a `Modal`: the question, its fine print, and a `BtnTrio` (or two buttons); give each button a `data-answer` — any of them closes the modal. */
+/** Drawer — the dark end of a `Modal`: the question, its fine print, and a `BtnTrio` (or two buttons) — plain buttons with the app's `onClick`; the Drawer does nothing with them. */
 export function Drawer({ title, caption, className, children, ...rest }) {
     return (_jsxs("div", { className: cx('modal__drawer', className), ...rest, children: [_jsx("h2", { className: "t-h2", children: title }), caption != null && _jsx("p", { className: "t-caption", children: caption }), children] }));
 }

package/dist/sheets/Sheet.d.ts

@@ -1,24 +1,37 @@
 import type { ComponentPropsWithoutRef } from 'react';
+/** how far the sheet slid. `away` = not on the screen (slid out, inert) — a state the app sets, never one a drag or a tap lands on */
 export type SheetState = 'peek' | 'half' | '3q' | 'full' | 'away';
-export interface SheetProps extends ComponentPropsWithoutRef<'article'> {
-    /** how far the sheet slid: `peek` (handle + title row) · `half` (default) · `3q` (three quarters showing) · `full` (its top edge at the top bar) — a class, never a height. `away` = a CALLED sheet not on the screen yet (slid out, inert): a `Btn aria-controls={its id}` in the Step's BaseContent calls it up to full and sends any other away. A tap on the handle toggles between this state and peek; a drag snaps to any of `states` */
+/** what asked for the change: the handle's `tap`, a `drag` released, `focus` in a peeked sheet, the `keyboard` (or anything else) moving the cut */
+export type SheetChangeReason = 'tap' | 'drag' | 'focus' | 'keyboard';
+declare const ORDER: readonly ["peek", "half", "3q", "full"];
+type Resting = (typeof ORDER)[number];
+export interface SheetProps extends Omit<ComponentPropsWithoutRef<'article'>, 'onChange'> {
+    /** CONTROLLED: where the sheet is. The app owns it — pair it with `onStateChange`, or the sheet cannot move (like `value` without `onChange`).
+     *  `peek` (handle + title row) · `half` · `3q` · `full` (its top edge at the top bar) · `away` (not on the screen). A class, never a height. */
     state?: SheetState;
+    /** UNCONTROLLED: where it starts (default `half`); the sheet then keeps its own state. Ignored when `state` is given. */
+    defaultState?: SheetState;
+    /** the sheet ASKS to move — the handle was tapped or dragged, a field in a peeked sheet took focus, the keyboard moved the cut.
+     *  Controlled: set your state to it (or don't — the sheet stays). This is where an app ties a sheet to its router / back button. */
+    onStateChange?: (state: SheetState, reason: SheetChangeReason) => void;
+    /** the states a drag snaps to and a reveal may climb through — "peek half full", or an array (default all four) */
+    states?: string | readonly Resting[];
     /** floats above a footnote strip on a dim stage (bottom corners and border back) */
     raised?: boolean;
-    /** the grab handle (tap / drag / keyboard via cardds.js); `false` for a sheet with no handle, a string sets its accessible name */
+    /** the grab handle; `false` for a sheet with no handle, a string sets its accessible name */
     handle?: boolean | string;
-    /** which states a drag snaps to, e.g. "peek half full" (default all four: peek half 3q full) */
-    states?: string;
 }
 /**
- * Sheet — the SINGLE sheet: one card as a bottom sheet holding what the member ACTS on (controls, or small `Card sm`
- * content cards). Always the full height of its box — a Step or a SheetStage — a state is only how far it slid.
- * Shape: handle · head (a CardHead, a SheetHead — or ONE label Row carrying a Check/Toggle, when the sheet's
- * whole ask is that switch and peek must show it) · SheetBody (the only part that scrolls). Written top-down.
- * It FINISHES on itself: a `CardFoot` as its last child holds the one button that completes it — standing at the bottom at
- * half / 3q / full, gone at peek. Never an ActionBar in front of a sheet (a bar is the base's). Nothing in the body commits
- * on its own. Older note — its own buttons only on a
- * screen with no bar (the map sheet). Called sheets: several `Sheet state="away" states="peek full"` in one Step, each with an `id` a
- * button names — one on the screen at a time; never beside a pager. This is the single sheet; the menu of stacked sheets is `SheetStack`.
+ * Sheet — the SINGLE sheet: one card as a bottom sheet holding what the member ACTS on. Always the full height of its
+ * box — a Step or a SheetStage — a state is only how far it slid (translate; the material never changes size).
+ * ONE SHAPE, written top-down: handle · head (a CardHead / SheetHead — pinned, never scrolls) · SheetBody (scrolls, as far as
+ * it needs) · CardFoot (the button that finishes the sheet — at the bottom, above the keyboard; gone at peek).
+ *
+ * It is a COMPONENT, not a wiring: it knows nothing of what opens it. The app owns `state` and sets it from whatever it
+ * likes — a button, a route, a timer: `<Btn onClick={() => setSheet('full')}>` … `<Sheet state={sheet} onStateChange={setSheet}>`.
+ * Its own behaviour stays inside it and only ever ASKS (`onStateChange`): a tap on the handle toggles its own state ↔ peek,
+ * a drag snaps to the nearest of `states`, focus in a peeked sheet raises it, and when the cut moves (the keyboard) it
+ * climbs until the focused control has room above the foot.
  */
-export declare function Sheet({ state, raised, handle, states, className, children, ...rest }: SheetProps): import("react").JSX.Element;
+export declare function Sheet({ state, defaultState, onStateChange, states, raised, handle, className, children, onFocus, ...rest }: SheetProps): import("react").JSX.Element;
+export {};

package/dist/sheets/Sheet.js

@@ -1,16 +1,162 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useRef, useState } from 'react';
 import { cx } from '../cx.js';
+const ORDER = ['peek', 'half', '3q', 'full']; // low → high; `away` is below them all and outside them
+const TAP_REM = 0.5; // = --sp-2: a move shorter than this is a tap, not a drag
 /**
- * Sheet — the SINGLE sheet: one card as a bottom sheet holding what the member ACTS on (controls, or small `Card sm`
- * content cards). Always the full height of its box — a Step or a SheetStage — a state is only how far it slid.
- * Shape: handle · head (a CardHead, a SheetHead — or ONE label Row carrying a Check/Toggle, when the sheet's
- * whole ask is that switch and peek must show it) · SheetBody (the only part that scrolls). Written top-down.
- * It FINISHES on itself: a `CardFoot` as its last child holds the one button that completes it — standing at the bottom at
- * half / 3q / full, gone at peek. Never an ActionBar in front of a sheet (a bar is the base's). Nothing in the body commits
- * on its own. Older note — its own buttons only on a
- * screen with no bar (the map sheet). Called sheets: several `Sheet state="away" states="peek full"` in one Step, each with an `id` a
- * button names — one on the screen at a time; never beside a pager. This is the single sheet; the menu of stacked sheets is `SheetStack`.
+ * Sheet — the SINGLE sheet: one card as a bottom sheet holding what the member ACTS on. Always the full height of its
+ * box — a Step or a SheetStage — a state is only how far it slid (translate; the material never changes size).
+ * ONE SHAPE, written top-down: handle · head (a CardHead / SheetHead — pinned, never scrolls) · SheetBody (scrolls, as far as
+ * it needs) · CardFoot (the button that finishes the sheet — at the bottom, above the keyboard; gone at peek).
+ *
+ * It is a COMPONENT, not a wiring: it knows nothing of what opens it. The app owns `state` and sets it from whatever it
+ * likes — a button, a route, a timer: `<Btn onClick={() => setSheet('full')}>` … `<Sheet state={sheet} onStateChange={setSheet}>`.
+ * Its own behaviour stays inside it and only ever ASKS (`onStateChange`): a tap on the handle toggles its own state ↔ peek,
+ * a drag snaps to the nearest of `states`, focus in a peeked sheet raises it, and when the cut moves (the keyboard) it
+ * climbs until the focused control has room above the foot.
  */
-export function Sheet({ state = 'half', raised, handle = true, states, className, children, ...rest }) {
-    return (_jsxs("article", { className: cx('card sheet', `sheet--${state}`, raised && 'sheet--raised', className), "data-sheet-states": states, inert: state === 'away' || undefined, ...rest, children: [handle !== false && _jsx("button", { className: "sheet__handle", type: "button", "aria-label": typeof handle === 'string' ? handle : 'Resize' }), children] }));
+export function Sheet({ state, defaultState = 'half', onStateChange, states, raised, handle = true, className, children, onFocus, ...rest }) {
+    const [inner, setInner] = useState(defaultState);
+    const current = state ?? inner;
+    const controlled = state !== undefined;
+    const ref = useRef(null);
+    const handleRef = useRef(null);
+    const home = useRef(current !== 'peek' && current !== 'away' ? current : 'half'); // where a tap from peek returns to
+    const was = useRef(current);
+    const skipClick = useRef(false);
+    const drag = useRef(null);
+    const allowed = useCallback(() => {
+        const list = (typeof states === 'string' ? states.split(/\s+/) : [...(states ?? [])]).filter((s) => ORDER.includes(s));
+        return list.length ? ORDER.filter((s) => list.includes(s)) : [...ORDER];
+    }, [states]);
+    const request = useCallback((next, reason) => {
+        if (next === current)
+            return;
+        if (!controlled)
+            setInner(next);
+        onStateChange?.(next, reason);
+    }, [current, controlled, onStateChange]);
+    useEffect(() => {
+        if (current !== 'peek' && current !== 'away')
+            home.current = current;
+        if (was.current === 'away' && current !== 'away')
+            handleRef.current?.focus({ preventScroll: true }); // it just came onto the screen: the keyboard user is on it
+        was.current = current;
+    }, [current]);
+    /* geometry, read once per gesture — never stored: how far it has slid, and where each state rests, in px from its top at full */
+    const slid = (el) => {
+        const box = (el.offsetParent ?? el.parentElement);
+        return el.getBoundingClientRect().top - (box.getBoundingClientRect().top + box.clientTop + el.offsetTop);
+    };
+    const stopsOf = (el) => {
+        const cs = getComputedStyle(el), height = el.getBoundingClientRect().height;
+        return {
+            full: 0,
+            half: height * (parseFloat(cs.getPropertyValue('--sheet-half')) || 0),
+            '3q': height * (parseFloat(cs.getPropertyValue('--sheet-3q')) || 0),
+            peek: height - (parseFloat(cs.getPropertyValue('--sheet-peek')) || 0), // registered in tokens.css: reads back resolved
+        };
+    };
+    /* bring a control into the part of the body that shows — between the pinned head and the foot's strip on the cut. The sheet asks
+       for the lowest of its states, from the current one (or `atLeast`) upward, that has room; if none has, its highest. */
+    const reveal = useCallback((target, reason, atLeast) => {
+        const el = ref.current;
+        if (!el || !target || !el.contains(target) || target.closest('.sheet__handle') || current === 'away')
+            return;
+        const control = target.closest('.field') ?? target; // the control's box, not the bare input inside it
+        const list = allowed(), stops = stopsOf(el);
+        const from = Math.max(list.indexOf(current), atLeast ? list.indexOf(atLeast) : -1, 0);
+        const rect = el.getBoundingClientRect();
+        const restTop = rect.top - slid(el);
+        const bodyTop = (el.querySelector(':scope > .sheet__body') ?? el).getBoundingClientRect().top - rect.top;
+        const box = el.parentElement.getBoundingClientRect(); // what clips it: the Step or the SheetStage
+        const vv = window.visualViewport;
+        const edge = Math.min(box.bottom, restTop + rect.height); // the sheet's own bottom edge at rest — above the box's on a stage that gave the keyboard its room
+        const cut = Math.min(edge, vv ? vv.offsetTop + vv.height : Infinity);
+        const button = el.querySelector(':scope > .card__foot')?.firstElementChild; // the foot's button stands on that edge at every state: the control has to clear its strip too
+        const need = control.getBoundingClientRect().height + (button ? edge - button.getBoundingClientRect().top : 0);
+        let to = list[list.length - 1];
+        for (let i = from; i < list.length; i++)
+            if (cut - (restTop + stops[list[i]] + bodyTop) >= need) {
+                to = list[i];
+                break;
+            }
+        request(to, reason);
+        requestAnimationFrame(() => control.scrollIntoView({ block: 'nearest' })); // after the state (and its scroll-padding) landed
+    }, [allowed, current, request]);
+    /* the cut moved — the keyboard came up (the Step shrank by --kb, or the layout viewport did), the phone turned: if a control
+       in this sheet has the focus, make sure it still shows */
+    useEffect(() => {
+        const el = ref.current;
+        if (!el || typeof ResizeObserver === 'undefined')
+            return;
+        let first = true;
+        const ro = new ResizeObserver(() => {
+            if (first) {
+                first = false;
+                return;
+            }
+            const at = document.activeElement;
+            if (at && el.contains(at))
+                reveal(at, 'keyboard');
+        });
+        ro.observe(el);
+        if (el.parentElement)
+            ro.observe(el.parentElement);
+        return () => ro.disconnect();
+    }, [reveal]);
+    const focus = (e) => {
+        onFocus?.(e);
+        if (current !== 'peek' || e.target.closest('.sheet__handle'))
+            return;
+        const body = ref.current?.querySelector(':scope > .sheet__body');
+        if (body)
+            body.scrollTop = 0; // the browser's own reveal scrolled it against the peek strip: start over
+        reveal(e.target, 'focus', home.current);
+    };
+    const tap = () => {
+        if (skipClick.current) {
+            skipClick.current = false;
+            return;
+        } // the click that follows a drag is not a tap
+        request(current === 'peek' ? (allowed().includes(home.current) ? home.current : allowed().find((s) => s !== 'peek') ?? 'half') : 'peek', 'tap');
+    };
+    const down = (e) => {
+        const el = ref.current;
+        if (!el || !e.isPrimary || e.button !== 0)
+            return;
+        const list = allowed(), stops = stopsOf(el), y = slid(el); // where it is now — mid-slide too, so a grab never jumps
+        drag.current = { startY: e.clientY, y0: y, y, stops, allowed: list, moved: false,
+            min: Math.min(...list.map((s) => stops[s])), max: Math.max(...list.map((s) => stops[s])),
+            tap: TAP_REM * parseFloat(getComputedStyle(document.documentElement).fontSize) };
+        e.currentTarget.setPointerCapture(e.pointerId);
+    };
+    const move = (e) => {
+        const d = drag.current, el = ref.current;
+        if (!d || !el || !e.isPrimary)
+            return;
+        const dy = e.clientY - d.startY;
+        if (!d.moved) {
+            if (Math.abs(dy) < d.tap)
+                return;
+            d.moved = true;
+            el.classList.add('is-dragging');
+        }
+        d.y = Math.min(Math.max(d.y0 + dy, d.min), d.max); // never above full, never below its lowest state
+        el.style.setProperty('--_drag', `${d.y - d.y0}px`); // the one thing written while held — the CSS adds it to the state's translate
+    };
+    const up = () => {
+        const d = drag.current, el = ref.current;
+        drag.current = null;
+        if (!d || !el)
+            return;
+        el.classList.remove('is-dragging');
+        if (!d.moved)
+            return; // a tap: the click that follows toggles
+        el.style.removeProperty('--_drag'); // same state, or the app says no: it eases back on its own
+        request(d.allowed.reduce((a, b) => (Math.abs(d.stops[b] - d.y) < Math.abs(d.stops[a] - d.y) ? b : a)), 'drag');
+        skipClick.current = true;
+        requestAnimationFrame(() => { skipClick.current = false; });
+    };
+    return (_jsxs("article", { ref: ref, className: cx('card sheet', `sheet--${current}`, raised && 'sheet--raised', className), inert: current === 'away' || undefined, onFocus: focus, ...rest, children: [handle !== false && (_jsx("button", { ref: handleRef, className: "sheet__handle", type: "button", "aria-label": typeof handle === 'string' ? handle : 'Resize', onClick: tap, onPointerDown: down, onPointerMove: move, onPointerUp: up, onPointerCancel: up })), children] }));
 }

package/dist/sheets/SheetStack.d.ts

@@ -2,6 +2,13 @@ import type { ComponentPropsWithoutRef, ReactNode } from 'react';
 export interface SheetStackProps extends ComponentPropsWithoutRef<'div'> {
     /** `tap` (default): a tapped head brings its sheet to the front, its back button returns it · `display`: the giant title is the peek (recents, a library) · `static`: peeks only, the last sheet open */
     mode?: 'tap' | 'display' | 'static';
+    /** CONTROLLED (tap mode): which sheet is open — its index among the children, first = 0 — or `null` for none. The app owns it (a route, a
+     *  button anywhere, the back button): pair it with `onOpenChange`, or the stack cannot move. */
+    open?: number | null;
+    /** UNCONTROLLED: the sheet open on arrival (default none); the stack then keeps its own */
+    defaultOpen?: number | null;
+    /** the stack ASKS: a peeked head was tapped (its index), or the open sheet's `CardBack` (`null`) */
+    onOpenChange?: (open: number | null) => void;
     /** wider peeks so more of each title shows (display stacks) */
     fanned?: boolean;
     /** nothing open on arrival (tap mode): every sheet, the front one too, peeks at the stack's bottom; the room above is the base's (`base`). A tap opens any sheet over it */
@@ -17,5 +24,10 @@ export interface SheetStackProps extends ComponentPropsWithoutRef<'div'> {
  * never the `heading` prop (it wraps the h2 in a div; the stack's one-line peek needs the bare h2). Put it last in a `Screen fill`, it bleeds
  * off the bottom. `closed`: nothing open on arrival — every head peeks at the bottom and the base above shows `base` (a home screen
  * with a picture over the menu); the `base` slot is rendered after the sheets, so it never takes a sheet's slot. This is the sheet STACK; a single bottom sheet is `Sheet`.
+ *
+ * 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, the open
+ * sheet's CardBack. How the sheets MOVE is its own too: sheets are rigid — the tapped one slides up, the ones after it leave below, the ones
+ * before tuck under nearest-first; closing reverses in two beats. Only `translate` (stack.css); it sets classes, never a size.
  */
-export declare function SheetStack({ mode, fanned, closed, base, className, children, ...rest }: SheetStackProps): import("react").JSX.Element;
+export declare function SheetStack({ mode, open, defaultOpen, onOpenChange, fanned, closed, base, className, children, onClick, ...rest }: SheetStackProps): import("react").JSX.Element;

package/dist/sheets/SheetStack.js

@@ -1,5 +1,13 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useLayoutEffect, useRef, useState } from 'react';
 import { cx } from '../cx.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);
 /**
  * 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.
@@ -8,7 +16,71 @@ import { cx } from '../cx.js';
  * never the `heading` prop (it wraps the h2 in a div; the stack's one-line peek needs the bare h2). Put it last in a `Screen fill`, it bleeds
  * off the bottom. `closed`: nothing open on arrival — every head peeks at the bottom and the base above shows `base` (a home screen
  * with a picture over the menu); the `base` slot is rendered after the sheets, so it never takes a sheet's slot. This is the sheet STACK; a single bottom sheet is `Sheet`.
+ *
+ * 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, the open
+ * sheet's CardBack. How the sheets MOVE is its own too: sheets are rigid — the tapped one slides up, the ones after it leave below, the ones
+ * before tuck under nearest-first; closing reverses in two beats. Only `translate` (stack.css); it sets classes, never a size.
  */
-export function SheetStack({ mode = 'tap', fanned, closed, base, className, children, ...rest }) {
-    return (_jsxs("div", { 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 })] }));
+export function SheetStack({ mode = 'tap', open, defaultOpen = null, onOpenChange, fanned, closed, base, className, children, onClick, ...rest }) {
+    const [inner, setInner] = useState(defaultOpen);
+    const current = open !== undefined ? open : inner;
+    const ref = useRef(null);
+    const was = useRef(null);
+    const untuck = useRef(null);
+    const request = (next) => {
+        if (next === current)
+            return;
+        if (open === undefined)
+            setInner(next);
+        onOpenChange?.(next);
+    };
+    /* paint the state onto the sheets — after every render, so a re-rendered Card never loses its place */
+    useLayoutEffect(() => {
+        const stack = ref.current;
+        if (!stack || mode !== 'tap')
+            return;
+        const sheets = sheetsOf(stack);
+        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'));
+    });
+    const click = (e) => {
+        onClick?.(e);
+        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('.card__back')) {
+            request(null);
+            return;
+        }
+        if (at >= 0 && current == null)
+            request(at);
+    };
+    return (_jsxs("div", { ref: ref, onClick: click, className: cx('sheet-stack', mode !== 'static' && `sheet-stack--${mode}`, fanned && 'sheet-stack--fanned', closed && 'sheet-stack--closed', className), ...rest, children: [children, base != null && _jsx("div", { className: "sheet-stack__base", children: base })] }));
 }

package/package.json

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