@usableapp/cardds 0.7.49 → 0.7.51

package/dist/sheets/sheetDrag.js

@@ -0,0 +1,49 @@
+/* the Sheet's handle held and moved — its own behaviour, not exported from the package: the sheet follows the finger (`--_drag`),
+   and on release asks for the nearest of its states. A move shorter than a tap is left to the click. */
+import { useRef } from 'react';
+import { slid, stopsOf } from './sheetMeasure.js';
+const TAP_REM = 0.5; // = --sp-2: a move shorter than this is a tap, not a drag
+/** the handle's pointer handlers, and `afterDrag()` — true once for the click that follows a drag (it is not a tap) */
+export function useSheetDrag(ref, allowed, snap) {
+    const skipClick = useRef(false);
+    const drag = useRef(null);
+    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
+        snap(d.allowed.reduce((a, b) => (Math.abs(d.stops[b] - d.y) < Math.abs(d.stops[a] - d.y) ? b : a)));
+        skipClick.current = true;
+        requestAnimationFrame(() => { skipClick.current = false; });
+    };
+    const afterDrag = () => { const skip = skipClick.current; skipClick.current = false; return skip; };
+    return { down, move, up, afterDrag };
+}

package/dist/sheets/sheetMeasure.d.ts

@@ -0,0 +1,10 @@
+import { type RefObject } from 'react';
+export declare const ORDER: readonly ["peek", "half", "3q", "full"];
+export type Resting = (typeof ORDER)[number];
+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 useFootRoom(ref: SheetRef): void;
+export {};

package/dist/sheets/sheetMeasure.js

@@ -0,0 +1,84 @@
+/* what a Sheet MEASURES — its own behaviour, not exported from the package: where it is and where each state rests (read once per
+   gesture, never stored), and the three numbers it publishes for its CSS: the peek strip, the title's run, the foot's room. */
+import { useEffect } from 'react';
+import { watchSize } from '../state.js';
+export const ORDER = ['peek', 'half', '3q', 'full']; // low → high; `away` is below them all and outside them
+/* geometry, read once per gesture — never stored: how far it has slid, and where each state rests, in px from its top at full */
+export const slid = (el) => {
+    const box = (el.offsetParent ?? el.parentElement);
+    return el.getBoundingClientRect().top - (box.getBoundingClientRect().top + box.clientTop + el.offsetTop);
+};
+export 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
+    };
+};
+/* the peek strip holds the handle and the WHOLE title row. CSS gives the box the strip for a one-line head (--sheet-peek in
+   sheet.css); when the head is taller than that floor — a title wrapped on a narrow phone at a large text size — the sheet
+   measures its head and publishes the real strip on its box, so nothing of the title is under the cut (2026-09-22, with the
+   22-base type scale). Removed when the head fits the floor again, so the CSS number is the one in force. */
+export function usePeekStrip(ref) {
+    useEffect(() => {
+        const el = ref.current, box = el?.parentElement, head = el?.querySelector(':scope > .card__head, :scope > .sheet__head');
+        if (!el || !box || !head)
+            return;
+        const publish = () => {
+            box.style.removeProperty('--sheet-peek'); // read the CSS strip, not our own
+            const cs = getComputedStyle(el);
+            const strip = parseFloat(cs.getPropertyValue('--sheet-peek')) || 0, floor = parseFloat(cs.getPropertyValue('--sheet-head-h')) || 0;
+            const over = head.getBoundingClientRect().height - floor;
+            if (over > 0.5)
+                box.style.setProperty('--sheet-peek', `${strip + over}px`);
+        };
+        const stop = watchSize([head], publish);
+        return () => { stop(); box.style.removeProperty('--sheet-peek'); };
+    }, []);
+}
+/* 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) {
+    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;
+        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 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'); };
+    });
+}
+/* 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
+   line may stand over it (an error) — the CSS strip was a fixed sum (--btn-h), so the body's words ran under the button. The
+   sheet measures its foot's rows and publishes --sheet-foot-h; the strip, its ground and the body's stop all read it. */
+export function useFootRoom(ref) {
+    useEffect(() => {
+        const el = ref.current, foot = el?.querySelector(':scope > .card__foot');
+        if (!el || !foot) {
+            el?.style.removeProperty('--sheet-foot-h');
+            return;
+        }
+        const publish = () => {
+            const rows = [...foot.children].map((c) => c.getBoundingClientRect()).filter((r) => r.height > 0);
+            if (!rows.length)
+                return el.style.removeProperty('--sheet-foot-h');
+            el.style.setProperty('--sheet-foot-h', `${Math.max(...rows.map((r) => r.bottom)) - Math.min(...rows.map((r) => r.top))}px`);
+        };
+        const stop = watchSize([...foot.children], publish);
+        const mo = new MutationObserver(publish);
+        mo.observe(foot, { childList: true });
+        return () => { stop(); mo.disconnect(); };
+    }); // every render: the foot's rows are the app's, they come and go
+}

package/dist/sheets/sheetSlide.d.ts

@@ -0,0 +1,9 @@
+import { type RefObject } from 'react';
+import type { SheetState } from './Sheet.js';
+/** `shown` = the state its class says · `live` = where it is as far as its own habits go (a held sheet has not come up yet) ·
+ *  `held` = it waits for the sheet going away before it to be settled */
+export declare function useSheetSlide(ref: RefObject<HTMLElement | null>, current: SheetState, onSettled?: (state: SheetState) => void): {
+    shown: SheetState;
+    live: SheetState;
+    held: boolean;
+};

package/dist/sheets/sheetSlide.js

@@ -0,0 +1,96 @@
+/* how a Sheet comes and goes — its own behaviour, not exported from the package: the first frame `away` (so it slides in), the rest
+   after it went away, the wait of a sheet asked up meanwhile, `onSettled`, and the warning when it is unmounted while up. */
+import { useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { reducedMotion, useLatest, warnOnce } from '../state.js';
+/* A SHEET THAT GOES AWAY IS NOT DONE WHEN IT LANDS (Lh 2026-10-03): it holds its box for a beat more (--motion-sheet-rest) — the base
+   is seen — and only then is it settled. `out` = the sheets still on their way out, per box; a sheet asked up in that box waits for it to empty. */
+const out = new WeakMap();
+const waiting = new WeakMap();
+const leave = (box, key) => { if (!out.has(box))
+    out.set(box, new Set()); out.get(box).add(key); };
+const gone = (box, key) => { const set = out.get(box); if (set?.delete(key) && !set.size)
+    [...(waiting.get(box) ?? [])].forEach((go) => go()); };
+const ms = (t) => Math.max(0, ...t.split(',').map((v) => parseFloat(v) * (v.trim().endsWith('ms') ? 1 : 1000) || 0)); // a computed `0.35s, 0s` list → its longest, in ms
+/** `shown` = the state its class says · `live` = where it is as far as its own habits go (a held sheet has not come up yet) ·
+ *  `held` = it waits for the sheet going away before it to be settled */
+export function useSheetSlide(ref, current, onSettled) {
+    const [entered, setEntered] = useState(false); // false for the first frame: the class says `away`, so a sheet mounted up has somewhere to slide from
+    const me = useRef({}).current; // this sheet, in its box's list of sheets on their way out
+    const [held, setHeld] = useState(false); // true while it waits for the sheet going away before it to be settled
+    const [prev, setPrev] = useState('away'); // asked up from `away` (or mounted up): it holds first, and rises once its box is free
+    if (prev !== current) {
+        setPrev(current);
+        setHeld(prev === 'away' && current !== 'away');
+    }
+    const shown = entered && !held ? current : 'away';
+    const live = held ? 'away' : current; // where it is as far as its own habits go: a held sheet has not come up yet
+    const latest = useLatest({ current, onSettled });
+    const last = useRef('away'); // where it was last SHOWN (the settle effect keeps it)
+    useLayoutEffect(() => {
+        void ref.current?.offsetHeight; // the browser styles the `away` frame first, or there is no transition to run
+        setEntered(true);
+    }, []);
+    /* it starts on its way out: said in the commit itself, before any sheet of the box decides to rise */
+    useLayoutEffect(() => {
+        const box = ref.current?.parentElement;
+        if (box && current === 'away' && last.current !== 'away' && !reducedMotion())
+            leave(box, me);
+    }, [current, me]);
+    /* held: it rises when no sheet of its box is on its way out — at once if none is */
+    useEffect(() => {
+        const box = ref.current?.parentElement;
+        if (!held)
+            return;
+        if (!box || !out.get(box)?.size) {
+            setHeld(false);
+            return;
+        }
+        const go = () => setHeld(false);
+        if (!waiting.has(box))
+            waiting.set(box, new Set());
+        waiting.get(box).add(go);
+        return () => { waiting.get(box)?.delete(go); };
+    }, [held]);
+    /* it has finished moving: the transition ended (or at once where there is none) — say so once per move; a move cut short by another says nothing */
+    useEffect(() => {
+        const el = ref.current, box = el?.parentElement;
+        if (!el || last.current === shown)
+            return;
+        last.current = shown;
+        const cs = getComputedStyle(el);
+        let done = false, rest = 0;
+        const settled = () => { if (box)
+            gone(box, me); latest.current.onSettled?.(latest.current.current); };
+        const end = () => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(t);
+            el.removeEventListener('transitionend', onEnd);
+            if (shown !== 'away' || reducedMotion())
+                return settled();
+            rest = window.setTimeout(settled, ms(cs.getPropertyValue('--motion-sheet-rest') || '0s')); // landed: the base is seen for the rest, THEN it is settled
+        };
+        const onEnd = (e) => { if (e.target === el && e.propertyName === 'translate')
+            end(); };
+        el.addEventListener('transitionend', onEnd);
+        const t = setTimeout(end, ms(cs.transitionDuration) + ms(cs.transitionDelay) + 100); // no transition (motion off) or none came: settled anyway
+        return () => { done = true; clearTimeout(t); clearTimeout(rest); el.removeEventListener('transitionend', onEnd); if (box && shown === 'away')
+            gone(box, me); }; // cut short on its way out (raised again, unmounted): the box is free
+    }, [shown, latest, me]);
+    /* taken out of the tree while it is still up — the box stays, the sheet goes: nothing to slide, so it vanishes. Said once in dev.
+       (A whole screen leaving takes the box too; StrictMode's trial unmount is over by the time the timer looks.) */
+    const alive = useRef(false);
+    useEffect(() => {
+        alive.current = true;
+        const box = ref.current?.parentElement;
+        return () => {
+            alive.current = false;
+            setTimeout(() => {
+                if (!alive.current && box?.isConnected && latest.current.current !== 'away')
+                    warnOnce('sheet-unmount', 'cardds Sheet: unmounted while on the screen, so it vanished instead of sliding out. Set state="away" and unmount it in onSettled (state === "away").');
+            });
+        };
+    }, [latest]);
+    return { shown, live, held };
+}

package/dist/sheets/sheetStepsPile.d.ts

@@ -0,0 +1,8 @@
+import { type RefObject } from 'react';
+export declare const GLIDE_MS = 220;
+/** `settle()` scrolls the pile to its place · `glideNow()` = the next jumps are played as slides. `moving` = until when a step
+ *  change is playing its beats (the SheetSteps keeps it). */
+export declare function usePile(ref: RefObject<HTMLElement | null>, moving: RefObject<number>): {
+    settle: () => void;
+    glideNow: () => void;
+};

package/dist/sheets/sheetStepsPile.js

@@ -0,0 +1,70 @@
+/* the PILE of a SheetSteps — its own behaviour, not exported from the package: where the body is scrolled when a step opens or a
+   field takes the keyboard, and the quick slide that replays every jump of that scroll so the eye can follow it. */
+import { useEffect, useRef } from 'react';
+import { reducedMotion } from '../state.js';
+export const GLIDE_MS = 220; // the pile's slide out of the keyboard's way and back: quick, but the eye follows it
+const GLIDE_FOR = 900; // how long after a focus move (or a step change) a jump of the scroll is replayed as a slide
+/** `settle()` scrolls the pile to its place · `glideNow()` = the next jumps are played as slides. `moving` = until when a step
+ *  change is playing its beats (the SheetSteps keeps it). */
+export function usePile(ref, moving) {
+    const glide = useRef(0), last = useRef(0), own = useRef(0); // own: our smooth scroll is playing — not a jump to replay
+    const glideNow = () => { glide.current = performance.now() + GLIDE_FOR; };
+    /* how far the body is scrolled when a step opens or a field in it takes the keyboard: the TWO latest done rows always show
+       above the open step, and half of the one before — older ones go up out of sight, one row at a time, so what was done never seems to vanish (Lh
+       2026-09-24: moving the pile further startled; with two rows or fewer nothing moves) */
+    const settle = () => {
+        const list = ref.current, body = list?.closest('.sheet__body'), now = list?.querySelector('.sheet-step--now');
+        if (!list || !body || !now)
+            return;
+        const above = [];
+        for (let el = now.previousElementSibling; el; el = el.previousElementSibling)
+            above.unshift(el);
+        const bTop = body.getBoundingClientRect().top, at = (el) => body.scrollTop + el.getBoundingClientRect().top - bTop;
+        const third = above.length > 2 ? above[above.length - 3] : null; // 2½ rows show (Lh 2026-09-24): the two latest whole, the one before cut in half — a sign there is more above
+        let to = third ? at(third) + third.getBoundingClientRect().height / 2 : 0;
+        /* …unless the field with the focus would still be under the cut (a short phone, a big text size): then up as far as it needs —
+           but never past the LATEST done row, which always stays in sight */
+        const focused = document.activeElement instanceof HTMLElement && now.contains(document.activeElement) ? document.activeElement : null;
+        if (focused) {
+            const vv = window.visualViewport;
+            const cut = Math.min(body.getBoundingClientRect().bottom - (parseFloat(getComputedStyle(body).scrollPaddingBottom) || 0), vv ? vv.offsetTop + vv.height : Infinity);
+            const under = (focused.closest('.field, .pin') ?? focused).getBoundingClientRect().bottom + (body.scrollTop - to) - cut; // where its bottom will be once scrolled to `to`
+            const most = above.length ? at(above[above.length - 1]) : 0;
+            if (under > 0)
+                to = Math.min(to + under, Math.max(most, to));
+        }
+        if (Math.abs(to - body.scrollTop) <= 1)
+            return;
+        // the pile SCROLLS there, animated (Lh 2026-09-24) — the browser's own smooth scroll; its frames are not replayed as jumps
+        const smooth = !reducedMotion();
+        own.current = performance.now() + (smooth ? 700 : 0);
+        body.scrollTo({ top: to, behavior: smooth ? 'smooth' : 'auto' });
+    };
+    /* the keyboard comes and goes: the body's scroll JUMPS (the Sheet's reveal, the browser's own, ours below, the box growing back).
+       For a short while after a field in the steps gains or loses the focus, every such jump is played as a quick slide (FLIP: the steps
+       are set back by the jump, then eased to rest) so the eye can follow the pile moving out of the way and back. */
+    useEffect(() => {
+        const el = ref.current, body = el?.closest('.sheet__body');
+        if (!el || !body)
+            return;
+        last.current = body.scrollTop;
+        const onScroll = () => {
+            const d = body.scrollTop - last.current;
+            last.current = body.scrollTop;
+            if (!d || performance.now() > glide.current || performance.now() < own.current || reducedMotion())
+                return;
+            const from = parseFloat(el.style.translate.split(' ')[1] || '0') || 0;
+            el.style.transition = 'none';
+            el.style.translate = `0 ${from + d}px`;
+            void el.offsetHeight; // the set-back lands before the ease
+            const hold = Math.max(0, moving.current - 100 - performance.now()); // during a step change: held until the fold is done (beat 2)
+            el.style.transition = `translate ${GLIDE_MS}ms ease-out ${hold}ms`;
+            el.style.translate = '0 0';
+        };
+        const clean = () => { el.style.removeProperty('transition'); el.style.removeProperty('translate'); };
+        body.addEventListener('scroll', onScroll);
+        el.addEventListener('transitionend', clean);
+        return () => { body.removeEventListener('scroll', onScroll); el.removeEventListener('transitionend', clean); };
+    }, []);
+    return { settle, glideNow };
+}

package/dist/templates/Home.d.ts

@@ -29,6 +29,8 @@ export interface HomeProps extends Omit<ComponentProps<typeof Screen>, 'children
     open?: number | null;
     defaultOpen?: number | null;
     onOpenChange?: (open: number | null) => void;
+    /** the open sheet's scroller was already at the top and the finger pulled down past the commit. The stack asks with that index. It does not fetch. Omit it and a pull in the body only scrolls */
+    onRefresh?: (index: number) => void;
     /** CONTENT above the sheet heads — one `Page`: a welcome, the news, a picture. It reads
      *  from the top; a sheet coming up covers it */
     base?: ReactNode;
@@ -48,4 +50,4 @@ export interface HomeProps extends Omit<ComponentProps<typeof Screen>, 'children
  * 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
  * 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, base, keep, backLabel, backAt, children, ...rest }: HomeProps): import("react").JSX.Element;
+export declare function Home({ top, title, sheets, open: openProp, defaultOpen, onOpenChange, onRefresh, base, keep, backLabel, backAt, children, ...rest }: HomeProps): import("react").JSX.Element;

package/dist/templates/Home.js

@@ -15,7 +15,7 @@ const LEAVE = 800; // ms: a closing sheet keeps its body until it has slid home
  * 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
  * sections on one home never cost three pages (`keep` holds a body once opened).
  */
-export function Home({ top, title, sheets, open: openProp, defaultOpen = null, onOpenChange, base, keep, backLabel = word('back'), backAt, children, ...rest }) {
+export function Home({ top, title, sheets, open: openProp, defaultOpen = null, onOpenChange, onRefresh, base, keep, backLabel = word('back'), backAt, children, ...rest }) {
     const [open, change] = useControlled(openProp, defaultOpen, onOpenChange);
     const [leaving, setLeaving] = useState(null);
     const [seen, setSeen] = useState(() => new Set(open != null ? [open] : []));
@@ -35,5 +35,5 @@ export function Home({ top, title, sheets, open: openProp, defaultOpen = null, o
     }, [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, 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] }));
+    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, 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.49",
+  "version": "0.7.51",
   "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.",