@usableapp/cardds 0.7.46 → 0.7.48

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 > For: a project that consumes `@usableapp/cardds` and its AI — what changed between versions, written as before → after, so a screen can be brought up to date without reading the source. Newest first. A consumer never edits cardds; if something here leaves you without a way to do what you did before, report the gap.
 
+## 0.7.48 — 2026-10-03
+
+### Changed
+- **A sheet going away has a rest of its own** (Lh 2026-10-03): when a `Sheet` slides to `away`, it is settled `--motion-sheet-rest` (0.2s) AFTER it landed — every time, whether or not another sheet follows. So `onSettled('away')` now fires 0.2s later than in 0.7.47 (slide 0.35s + rest 0.2s); an app that unmounts the sheet or moves on from `onSettled('away')` does so a beat later. A sheet asked up in the same box meanwhile waits until the one leaving is settled. What a member sees when one sheet follows another is as in 0.7.47 (down · the base · up); what changed is whose timeout it is — the sheet that slid out, not the one coming up. Only going away rests: peek ↔ full is as before. Nothing to change in a screen; add no timer of your own.
+
+### Added
+- **A `Track` as the top of a map screen**: `<Screen fill top={<Track>…</Track>}>` over a `SheetStage` — the track is a layer on the stage (the map shows around it, to the screen's top), and the sheet at full stops 16px under it. Story `MapArea · TrackOnTop`.
+
+## 0.7.47 — 2026-10-03
+
+### Changed
+- **One sheet follows another: the first goes all the way down, the base is seen, then the next comes up** (Lh 2026-10-03). It is the `Sheet`'s own habit now: a sheet asked up while another sheet of the same box (`Step`, `SheetStage`) is leaving waits at `away` until that one has landed, the base shows for `--motion-sheet-rest` (0.2s), then it rises — 0.35s down · 0.2s base · 0.35s up, never two sheets in the box. Before, two sheets set in one render crossed (`CallSheet ways` going from one way to another, `Step · Calls`), and a sheet raised from the first one's `onSettled('away')` started in the very frame the first landed — one continuous move. Nothing to change in a screen: both wirings now play the same, and an app adds no timer of its own (remove one if you had it). `onSettled` of the sheet coming up fires later by the wait. With reduced motion there is no wait. New root token `--motion-sheet-rest`.
+
+### Fixed
+- **`TrackStep num`: the number sits in the middle of its round at every text size** — the round is cut from its own number (`1.877em`, 32px at the default text as before) and the digit is lifted onto the middle, as the SheetSteps' number. Knobs `--track-dot-size` · `--track-dot-lift`. At a large text a NUMBERED track's pill grows with its rounds and is taller than the top bar (160% text: 88px beside a 78px bar); an icon track keeps the bar's height.
+
 ## 0.7.46 — 2026-10-03
 
 ### Changed

package/css/numbers.css

@@ -89,7 +89,13 @@
   background: var(--ink-rail);
   color: var(--_ink);
 }
-.track__step > .track__dot { display: grid; place-items: center; padding: 0; font: var(--track-dot-font, var(--type-caption)); font-variant-numeric: tabular-nums; } /* a number in the round (TrackStep num) */
+.track__step > .track__dot { /* a number in the round (TrackStep num) */
+  display: grid; place-items: center; box-sizing: border-box;
+  font: var(--track-dot-font, var(--type-caption)); line-height: 1; font-variant-numeric: tabular-nums;
+  width: var(--track-dot-size, 1.877em); height: var(--track-dot-size, 1.877em); /* em, not rem (Lh 2026-10-03, as the SheetSteps' number and the StackSheet's count): the round is cut from ITS OWN
+     number's size — 1.877em of a 17px caption = the 32px of an icon's round; at a larger text it grows with its number, and the pill with it */
+  padding: 0 0 var(--track-dot-lift, 0.1em); /* the room UNDER the number lifts it onto the round's middle: a digit has no descender */
+}
 .track__step.is-done > .icon,
 .track__step.is-done > .track__dot { background: var(--accent); color: var(--on-accent); }
 

package/css/step.css

@@ -150,6 +150,17 @@
   margin-top: var(--track-top-lead, var(--sp-4));
   margin-bottom: calc(var(--track-top-gap, var(--sp-4)) - var(--screen-gap));
 }
+/* …and over a STAGE (a map behind a sheet, Lh 2026-10-03): the stage is the whole screen, so the track is a LAYER on it — the map
+   shows around the pill — and the stage keeps the track's line free itself: a sheet at full stops --track-top-gap under the
+   track, as in a step. --top-h is the track's own height, measured by Screen (a numbered track grows with the text). */
+.screen--fill > .track:first-child:has(+ .sheet-stage) {
+  position: absolute; z-index: 1;
+  inset: calc(var(--safe-top) + var(--track-top-lead, var(--sp-4))) var(--screen-pad) auto;
+  margin: 0;
+}
+.screen--fill > .track:first-child + .sheet-stage {
+  --_top: calc(var(--track-top-lead, var(--sp-4)) + var(--top-h, var(--header-h)) + var(--track-top-gap, var(--sp-4)));
+}
 /* a walk page that OPENS on a picture (Lh 2026-09-23): the picture takes the lead's room — as wide as the content (edge to edge), from the top edge, as tall as
    the lead + the picture's own height (--page-media-h), square — so the words start where they always did */
 .step > .pages > .page:has(> :is(img, .ph):first-child) { margin-top: 0; }

package/css/tokens.css

@@ -95,6 +95,7 @@
 
   /* ---- motion ---- */
   --motion-sheet: 0.35s;
+  --motion-sheet-rest: 0.2s; /* one sheet follows another: how long the base is seen between the one that left and the one that comes (Sheet.tsx reads it) */
   --motion-quick: 0.2s;  /* a small state flip that isn't a press: a chevron turning, a popover/banner opening */
   --motion-slide: 0.22s; /* a centred card sliding out and the next in (card.css) — quick, a page turn (Lh, 2026-09-12) */
   --motion-flip: 0.45s;  /* a postcard turning over (media.css) — slow enough to read as a card in the hand */

package/dist/cardds.css

@@ -136,6 +136,7 @@
 
   /* ---- motion ---- */
   --motion-sheet: 0.35s;
+  --motion-sheet-rest: 0.2s; /* one sheet follows another: how long the base is seen between the one that left and the one that comes (Sheet.tsx reads it) */
   --motion-quick: 0.2s;  /* a small state flip that isn't a press: a chevron turning, a popover/banner opening */
   --motion-slide: 0.22s; /* a centred card sliding out and the next in (card.css) — quick, a page turn (Lh, 2026-09-12) */
   --motion-flip: 0.45s;  /* a postcard turning over (media.css) — slow enough to read as a card in the hand */
@@ -1910,6 +1911,17 @@ button:enabled { cursor: pointer; } /* a disabled one keeps the arrow */
   margin-top: var(--track-top-lead, var(--sp-4));
   margin-bottom: calc(var(--track-top-gap, var(--sp-4)) - var(--screen-gap));
 }
+/* …and over a STAGE (a map behind a sheet, Lh 2026-10-03): the stage is the whole screen, so the track is a LAYER on it — the map
+   shows around the pill — and the stage keeps the track's line free itself: a sheet at full stops --track-top-gap under the
+   track, as in a step. --top-h is the track's own height, measured by Screen (a numbered track grows with the text). */
+.screen--fill > .track:first-child:has(+ .sheet-stage) {
+  position: absolute; z-index: 1;
+  inset: calc(var(--safe-top) + var(--track-top-lead, var(--sp-4))) var(--screen-pad) auto;
+  margin: 0;
+}
+.screen--fill > .track:first-child + .sheet-stage {
+  --_top: calc(var(--track-top-lead, var(--sp-4)) + var(--top-h, var(--header-h)) + var(--track-top-gap, var(--sp-4)));
+}
 /* a walk page that OPENS on a picture (Lh 2026-09-23): the picture takes the lead's room — as wide as the content (edge to edge), from the top edge, as tall as
    the lead + the picture's own height (--page-media-h), square — so the words start where they always did */
 .step > .pages > .page:has(> :is(img, .ph):first-child) { margin-top: 0; }
@@ -2577,7 +2589,13 @@ button:enabled { cursor: pointer; } /* a disabled one keeps the arrow */
   background: var(--ink-rail);
   color: var(--_ink);
 }
-.track__step > .track__dot { display: grid; place-items: center; padding: 0; font: var(--track-dot-font, var(--type-caption)); font-variant-numeric: tabular-nums; } /* a number in the round (TrackStep num) */
+.track__step > .track__dot { /* a number in the round (TrackStep num) */
+  display: grid; place-items: center; box-sizing: border-box;
+  font: var(--track-dot-font, var(--type-caption)); line-height: 1; font-variant-numeric: tabular-nums;
+  width: var(--track-dot-size, 1.877em); height: var(--track-dot-size, 1.877em); /* em, not rem (Lh 2026-10-03, as the SheetSteps' number and the StackSheet's count): the round is cut from ITS OWN
+     number's size — 1.877em of a 17px caption = the 32px of an icon's round; at a larger text it grows with its number, and the pill with it */
+  padding: 0 0 var(--track-dot-lift, 0.1em); /* the room UNDER the number lifts it onto the round's middle: a digit has no descender */
+}
 .track__step.is-done > .icon,
 .track__step.is-done > .track__dot { background: var(--accent); color: var(--on-accent); }
 

package/dist/scaffold/Screen.js

@@ -28,6 +28,15 @@ export function Screen({ fill, palette, as = 'div', top, bottom, ready = true, c
         }
         return watchSize([bar], () => el.style.setProperty('--bottom-h', `${bar.offsetHeight}px`));
     }, [bottom, ready]);
+    /* a TRACK as the top, over a stage: its height published as --top-h — the stage keeps that line free for it (step.css) */
+    useEffect(() => {
+        const el = own.current, track = el?.querySelector(':scope > .track:first-child');
+        if (!el || !track) {
+            el?.style.removeProperty('--top-h');
+            return;
+        }
+        return watchSize([track], () => el.style.setProperty('--top-h', `${track.offsetHeight}px`));
+    }, [top, ready]);
     const setRef = (node) => {
         own.current = node;
         if (typeof ref === 'function')

package/dist/sheets/Sheet.d.ts

@@ -14,7 +14,8 @@ export interface SheetProps extends Omit<ComponentProps<'article'>, 'onChange'>
     /** 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 sheet has FINISHED sliding to `state` (its transition ended; at once where motion is off). To leave the screen: set `away`, and take the
+    /** the sheet has FINISHED its move to `state` (its transition ended; at once where motion is off). Going `away` it is finished a beat
+     *  AFTER it landed (`--motion-sheet-rest`) — its own timeout, every time. To leave the screen: set `away`, and take the
      *  sheet out of the tree here — `onSettled={(s) => s === 'away' && setMounted(false)}` — so it slides out instead of vanishing */
     onSettled?: (state: SheetState) => void;
     /** the states a drag snaps to and a reveal may climb through — "peek half full", or an array (default all four) */
@@ -37,6 +38,11 @@ export interface SheetProps extends Omit<ComponentProps<'article'>, 'onChange'>
  * It ARRIVES and LEAVES by sliding, always: a sheet that mounts already up starts `away` for one frame and slides to its state, so
  * `{open && <Sheet state="full">}` slides in. Leaving is the app's beat: set `away`, and unmount on `onSettled('away')` — unmount it
  * while it is still up and it can only vanish (a dev warning says so).
+ *
+ * GOING AWAY HAS A REST: a sheet that slides out is settled a beat after it landed (`--motion-sheet-rest`, the base is seen) — a
+ * fixed habit of every sheet. A sheet asked up in the same box meanwhile waits for it: "one left, another came", never two sheets
+ * crossing and never one continuous move, whatever the app's wiring (both states set in one render, or the next raised from the
+ * first's `onSettled`) — the app adds no timer.
  */
 export declare function Sheet({ state, defaultState, onStateChange, onSettled, states, handle, className, children, onFocus, ...rest }: SheetProps): import("react").JSX.Element;
 export {};

package/dist/sheets/Sheet.js

@@ -1,11 +1,19 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
-import { focusWhenActive, useControlled, useLatest, warnOnce, watchSize } from '../state.js';
+import { focusWhenActive, reducedMotion, useControlled, useLatest, warnOnce, watchSize } from '../state.js';
 import { cx } from '../cx.js';
 import { word } from '../words.js';
 const ORDER = ['peek', 'half', '3q', 'full']; // low → high; `away` is below them all and outside them
 const RANK = { away: 0, peek: 1, half: 2, '3q': 3, full: 4 };
 const TAP_REM = 0.5; // = --sp-2: a move shorter than this is a tap, not a drag
+/* 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
 /**
  * Sheet — the SINGLE sheet: one card as a bottom sheet holding what the member ACTS on. Always the full height of its
@@ -22,6 +30,11 @@ const ms = (t) => Math.max(0, ...t.split(',').map((v) => parseFloat(v) * (v.trim
  * It ARRIVES and LEAVES by sliding, always: a sheet that mounts already up starts `away` for one frame and slides to its state, so
  * `{open && <Sheet state="full">}` slides in. Leaving is the app's beat: set `away`, and unmount on `onSettled('away')` — unmount it
  * while it is still up and it can only vanish (a dev warning says so).
+ *
+ * GOING AWAY HAS A REST: a sheet that slides out is settled a beat after it landed (`--motion-sheet-rest`, the base is seen) — a
+ * fixed habit of every sheet. A sheet asked up in the same box meanwhile waits for it: "one left, another came", never two sheets
+ * crossing and never one continuous move, whatever the app's wiring (both states set in one render, or the next raised from the
+ * first's `onSettled`) — the app adds no timer.
  */
 export function Sheet({ state, defaultState = 'half', onStateChange, onSettled, states, handle = true, className, children, onFocus, ...rest }) {
     const [current, request] = useControlled(state, defaultState, onStateChange);
@@ -31,8 +44,17 @@ export function Sheet({ state, defaultState = 'half', onStateChange, onSettled,
     const was = useRef('away'); // mounted up = it came onto the screen: it rises from away like any arrival
     const skipClick = useRef(false);
     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 shown = entered ? current : 'away';
+    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)
     const drag = useRef(null);
     const allowed = useCallback(() => {
         const list = (typeof states === 'string' ? states.split(/\s+/) : [...(states ?? [])]).filter((s) => ORDER.includes(s));
@@ -42,29 +64,54 @@ export function Sheet({ state, defaultState = 'half', onStateChange, onSettled,
         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 */
-    const last = useRef(shown);
     useEffect(() => {
-        const el = ref.current;
+        const el = ref.current, box = el?.parentElement;
         if (!el || last.current === shown)
             return;
         last.current = shown;
         const cs = getComputedStyle(el);
-        let done = false;
+        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);
-            latest.current.onSettled?.(latest.current.current);
+            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); el.removeEventListener('transitionend', onEnd); };
-    }, [shown, latest]);
+        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);
@@ -85,17 +132,17 @@ export function Sheet({ state, defaultState = 'half', onStateChange, onSettled,
        field), else the body's first field; with no field, a sheet that came onto the screen gives it to its handle. A field that already
        has the cursor keeps it. */
     useEffect(() => {
-        if (current !== 'peek' && current !== 'away')
-            home.current = current;
-        const rose = current !== 'peek' && current !== 'away' && RANK[current] > RANK[was.current];
+        if (live !== 'peek' && live !== 'away')
+            home.current = live;
+        const rose = live !== 'peek' && live !== 'away' && RANK[live] > RANK[was.current];
         const from = was.current;
-        was.current = current;
+        was.current = live;
         if (!rose)
             return;
         const cancel = focusWhenActive(ref.current, { scope: ':scope > .sheet__body', fallback: () => (from === 'away' ? handleRef.current : null) });
         return () => { if (!cancel())
             was.current = from; }; // cut short (StrictMode's trial run, or a new state mid-slide): the rise still counts from where it began
-    }, [current]);
+    }, [live]);
     /* 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);
@@ -246,5 +293,5 @@ export function Sheet({ state, defaultState = 'half', onStateChange, onSettled,
         skipClick.current = true;
         requestAnimationFrame(() => { skipClick.current = false; });
     };
-    return (_jsxs("article", { ref: ref, className: cx('card sheet', `sheet--${shown}`, 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 : word('resize'), onClick: tap, onPointerDown: down, onPointerMove: move, onPointerUp: up, onPointerCancel: up })), children] }));
+    return (_jsxs("article", { ref: ref, className: cx('card sheet', `sheet--${shown}`, className), inert: current === 'away' || held || undefined, onFocus: focus, ...rest, children: [handle !== false && (_jsx("button", { ref: handleRef, className: "sheet__handle", type: "button", "aria-label": typeof handle === 'string' ? handle : word('resize'), onClick: tap, onPointerDown: down, onPointerMove: move, onPointerUp: up, onPointerCancel: up })), children] }));
 }

package/package.json

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