@usableapp/cardds 0.7.53 → 0.7.54

package/dist/sheets/stackCard.d.ts

@@ -0,0 +1,31 @@
+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 tuck, only while `before` */
+    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>;
+export declare function stackPaint(place: StackPlace | undefined): {
+    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;
+}): void;

package/dist/sheets/stackCard.js

@@ -0,0 +1,389 @@
+/* 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 } 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);
+export function stackPaint(place) {
+    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'].filter(Boolean).join(' ');
+    return {
+        className,
+        style: place.before ? { '--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);
+    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;
+                    }
+                }
+                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 finish = () => {
+                scroller.classList.remove('is-refreshing');
+                scroller.style.removeProperty('--_refresh');
+            };
+            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;
+            if (live.current?.prop === '--_pull')
+                release('--_pull');
+            head?.removeEventListener('pointerdown', onHeadDown);
+            scroller.removeEventListener('pointerdown', onBodyDown);
+        };
+    }, [place?.open, place?.refreshing, !!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]);
+}

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/package.json

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