@usableapp/cardds 0.7.36 → 0.7.38

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 > 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.38 — 2026-10-01
+
+### Fixed
+- **`Banner`: its words ran past the band when a line held a word with no break in it** (a link; found in mailpool, Lh 2026-10-01) — the body's column grew as wide as that word. The column is now held to the band and such a word breaks where it must. Nothing to change in a screen.
+
+- **`Sheet`: the body's words ran under the foot's button at a large text size** (found in timebank, Lh 2026-10-01). The room a sheet kept for its foot was a fixed sum (the button's token height), but a button grows with the member's text size, and a line may stand over it. The Sheet now measures its foot's rows and keeps that much room (`--sheet-foot-h`, its own data — not a knob); the strip's ground covers all of it. Nothing to change in a screen; a `Text` put in a `CardFoot` over the button is counted too.
+
+### Added
+- **`Spinner` — "working on it"** (Lh 2026-10-01, asked by mailpool): a ring that turns, for a wait of unknown length (a known share is a `Progress`). `<Spinner label="…" />` alone (the label is read out), or `<Spinner>words</Spinner>` with a caption-sized line beside it; `size` = an Icon's (`xs` · `md` · `lg`); `role="status"`. In a row's `end`, a card, a sheet's body, an `EmptyState`'s `icon`. Still when motion is reduced. Knob `--spinner-ink`. Before, the only turning ring was inside `FormNote busy`, not exported. A whole screen that is not known yet still shows nothing (`Screen ready`), not a spinner.
+
+## 0.7.37 — 2026-10-01
+
+### Fixed
+- **`slideScreen` held nothing for a `ready={false}` screen under a router that renders a tick after `navigate()`** (react-router 7; found by timebank, 2026-10-01): any mutation in the page — a popover closing — ended the wait while the old screen was still the one there, so the new screen came after the transition, blank, then drawn, with no slide. Now the wait ends only when the SCREEN changed (another element, or the same one with new children), then a pending screen is held as 0.7.36 said. `ready` on a data screen works as described from this version.
+
+### Added
+- **`IconBtnGroup vertical`** (Lh 2026-10-01, asked by mailpool): the buttons one over the other, the panel one button wide (`--tap`), each button at least a tap tall, the rule between them across. For a `Row`'s `end` — a panel across took almost half the row and the title wrapped. `select` and `aria-pressed` as before.
+- **`Rows` slides its rows when the app reorders them** (Lh 2026-10-01): the same keyed rows rendered in another order move to their new places (`--motion-sheet`), the one going up passing over the others; before, they jumped. Nothing to set; reduced motion = no slide. Story `IconBtnGroup · VerticalInARow` (up / down commands at a row's end).
+- **The back stack: `useLayer` · `useLayers` · `LayerHistory`** (Lh 2026-10-01; the formula proven in timebank first). Back takes ONE thing off: a screen, or a LAYER — a whole bottom sheet, a modal. Before, each project wired this by hand (an open sheet in the query made the whole screen slide on back; in `useState`, back left the page). Now: wrap the screens once in `<LayerHistory state push replace back>` (your router's entry state and three moves — README has the react-router lines), then `const way = useLayer('way')`: `value` (null = not up) · `open(value)` (one entry; already up = the same entry, new value) · `close()` (the part's own close) · `arrive(value)` (a link straight to an open sheet). `useLayers()`: `up` · `closeAll(then)`. Nothing inside a layer takes an entry. The state key is `layers` (`{ [name]: { value, pushed } }`), other keys of the entry are kept. Rule added with it: a finished process is not gone back into — move on by `replace`, and a page that cannot be returned to checks on arrival (`Screen ready={false}`) and replaces itself.
+
 ## 0.7.36 — 2026-10-01
 
 ### Added

package/README.md

@@ -360,6 +360,21 @@ between at 40% down the screen (see *Anatomy*, "Where the centre is"):
     is drawn; arrived at through `slideScreen` / the back button, the screen before stays until it is ready (at most 3 s), then
     the right one slides in. Never one outcome first and another after (story `Step · ArrivesReady`). On a first load there is
     no screen before: hold the `Splash` (`done`) until the first screen is known.
+    THE BACK STACK (Lh 2026-10-01): back takes ONE thing off — a screen (a route), or a LAYER: what lies over a screen, a whole
+    bottom sheet or a modal. A layer is one history entry, kept in the entry's STATE (the address stays the page's own, so the
+    screen behind does not slide): `const way = useLayer('way')` → `way.value` (null = not up) · `way.open(value)` (one entry;
+    already up = the same entry shows the new value) · `way.close()` (the part's own close: the handle, the scrim, a button —
+    back one entry, or, when it came with the page, the entry without it) · `way.arrive(value)` (a link straight to an open
+    sheet: read `?way=` once, no entry added, the query dropped). `useLayers().closeAll(then)` takes every layer off, then moves
+    (signing out). NOTHING INSIDE A LAYER TAKES AN ENTRY — a step, typed text, a sheet's rest, a tab: back at any step takes the
+    whole sheet down, and opened again it starts anew (a new `key` per opening). The project hands its router over once:
+    `<LayerHistory state push replace back>` around its screens — react-router: `state = useLocation().state`,
+    `push = (s) => navigate({ pathname }, { state: s })`, `replace = (s) => navigate({ pathname }, { replace: true, state: s })`,
+    `back = (n) => navigate(-n)`. cardds never calls the History API itself. Story `LayerHistory · Back`.
+    A FINISHED PROCESS IS NOT GONE BACK INTO: history cannot be deleted, so (a) inside a process every move on is a `replace`,
+    never a push — when it ends, back skips all of it; (b) a page that can no longer be returned to guards itself: it checks on
+    arrival (`Screen ready={false}` meanwhile) and, when its work is already done, replaces itself with the right screen — that
+    covers forward, an old link, and entries left ahead after `closeAll`.
   - *Sheets the app calls:* the base offers WAYS IN — sign in · new phone · join — as buttons (`.cta-pack`); each
     way has a sheet that holds its WHOLE form and its own submit on its foot, starting `.sheet--away` (not on the
     screen: slid out, hidden once gone, `inert`). **The wiring is the app's, not cardds's**: a `useState` of which

package/css/actions.css

@@ -108,6 +108,10 @@
 .icon-btn-group > .icon-btn { flex: 1 1 0; min-width: 0; width: auto; height: auto; border: 0; border-radius: 0; background: transparent; color: inherit; box-shadow: none; }
 .icon-btn-group > .icon-btn + .icon-btn { border-inline-start: var(--border-w) solid var(--icon-btn-group-rule, var(--icon-btn-group-border, var(--outline))); }
 .card__foot > .icon-btn-group { flex: 1 1 0; }
+/* --vertical: the buttons one over the other, ONE button wide — at a row's end, where a panel across would take the words' room */
+.icon-btn-group--vertical { flex-direction: column; flex: none; width: var(--tap); }
+.icon-btn-group--vertical > .icon-btn { flex: 1 0 auto; min-height: var(--tap); }
+.icon-btn-group--vertical > .icon-btn + .icon-btn { border-inline-start: 0; border-block-start: var(--border-w) solid var(--icon-btn-group-rule, var(--icon-btn-group-border, var(--outline))); }
 .icon-btn-group > .icon-btn[aria-pressed="true"] { background: var(--icon-btn-group-on-bg, var(--accent)); color: var(--icon-btn-group-on-ink, var(--on-accent)); } /* `select`: a pressed button STAYS filled (Lh 2026-09-29) */
 .icon-btn-group > .icon-btn:active:not(:disabled) { scale: 1; opacity: var(--press-dim); } /* a part of one frame DIMS, it never shrinks inside it */
 

package/css/layover.css

@@ -176,7 +176,7 @@
      <div class="banner__body">…</div></details>
    A light tint (not a card tone) with a slightly darker rule above and below, edge to edge of its card or screen (Lh 2026-09-24). */
 .banner {
-  display: grid;
+  display: grid; grid-template-columns: minmax(0, 1fr);
   background: var(--banner-bg, var(--ink-tint));
   color: var(--banner-ink, inherit);
   border-block: var(--border-w) solid var(--banner-border, var(--hairline));
@@ -192,7 +192,9 @@
 .banner__summary::-webkit-details-marker { display: none; }
 .banner__summary .icon { transition: rotate var(--motion-quick) ease; }
 .banner[open] .banner__summary .icon { rotate: 180deg; }
-.banner__body { display: grid; gap: var(--banner-body-gap, var(--sp-1)); padding-bottom: var(--sp-4); }
+/* the band's words never run past it: one column that cannot be wider than the band (a grid track is as wide as its longest
+   word otherwise), and a word with no break in it — a link — breaks where it must (mailpool, Lh 2026-10-01) */
+.banner__body { display: grid; grid-template-columns: minmax(0, 1fr); overflow-wrap: anywhere; gap: var(--banner-body-gap, var(--sp-1)); padding-bottom: var(--sp-4); }
 .banner::details-content { width: 100%; }
 @supports (interpolate-size: allow-keywords) {
   @media (prefers-reduced-motion: no-preference) {

package/css/numbers.css

@@ -242,6 +242,14 @@
 .bar--on::after { background: var(--accent); }
 .bar--on > span { background: var(--accent); color: var(--on-accent); padding: var(--sp-0) var(--sp-2); border-radius: var(--r-chip); }
 
+/* ---- spinner: "working on it", a wait of unknown length (Lh 2026-10-01) ----
+   <span class="spinner" role="status"><svg class="icon">…loader-circle…</svg>Loading…</span>
+   The ring turns; words beside it are optional and take the caption's look. Still when motion is reduced. */
+.spinner { display: inline-flex; align-items: center; justify-content: center; gap: var(--sp-2); vertical-align: middle; font: var(--type-caption); color: var(--spinner-ink, currentColor); }
+.spinner > .icon { flex: none; }
+@media (prefers-reduced-motion: no-preference) { .spinner > .icon { animation: spinner-turn 0.9s linear infinite; } }
+@keyframes spinner-turn { to { rotate: 1turn; } }
+
 /* ---- progress: one straight line, the done share solid, the rest faint (Lh 2026-09-22) — a voice note's
    timeline, a download, a step count as a line. <div class="progress" role="progressbar" style="--progress-at: 0.4"></div>
    --progress-at is DATA the component writes (0–1), not a knob (scripts/knobs.mjs lists it). The done part is a

package/css/sheet.css

@@ -81,7 +81,7 @@
   border-radius: var(--r-card) var(--r-card) 0 0;
   border-bottom: 0;
   box-shadow: var(--sheet-shadow, var(--shadow-sheet));
-  --_foot: calc(var(--card-gap) + var(--btn-h) + var(--card-pad) + var(--_safe-b-open)); /* the foot strip's height (below) — merged here, one bare .sheet rule */
+  --_foot: calc(var(--card-gap) + var(--sheet-foot-h, var(--btn-h)) + var(--card-pad) + var(--_safe-b-open)); /* the foot strip's height (below) — merged here, one bare .sheet rule */
 }
 .sheet--full { --_y: 0%; --_cover: 0rem; }
 .sheet--half { --_y: calc(var(--sheet-half) * 100%); --_cover: calc(var(--sheet-half) * var(--_box)); }
@@ -148,7 +148,7 @@
    stops that far above the sheet's edge. At peek there is only the handle and the title: the foot is gone.
    One row, ≤ 2 buttons. <div class="card__foot"><button class="btn btn--primary btn--block">…</button></div> */
 /* …and the link row under the button, when there is one (its line + the gap over it) */
-.sheet:has(> .card__foot--link) { --_foot: calc(var(--card-gap) + var(--btn-h) + var(--sp-1) + var(--link-sm-min-h, calc(var(--tap-base) * 7 / 12)) + var(--card-pad) + var(--_safe-b-open)); }
+.sheet:has(> .card__foot--link) { --_foot: calc(var(--card-gap) + var(--sheet-foot-h, calc(var(--btn-h) + var(--sp-1) + var(--link-sm-min-h, calc(var(--tap-base) * 7 / 12)))) + var(--card-pad) + var(--_safe-b-open)); } /* --sheet-foot-h: the foot's rows as the Sheet measured them (a button grows with the text size) */
 .sheet > .card__foot {
   position: absolute; inset: calc(-1 * var(--border-w)) 0 0; z-index: 1; /* the sheet's border box: the same height the sheet's own % reads */
   align-items: end;

package/dist/actions/Btn.d.ts

@@ -302,12 +302,12 @@ export declare function Btn({ primary, quiet, block, form, xl, href, className,
     is?: string | undefined | undefined;
     exportparts?: string | undefined | undefined;
     disabled?: boolean | undefined | undefined;
+    value?: string | number | readonly string[] | undefined;
     formAction?: string | ((formData: FormData) => void | Promise<void>) | undefined;
     formEncType?: string | undefined | undefined;
     formMethod?: string | undefined | undefined;
     formNoValidate?: boolean | undefined | undefined;
     formTarget?: string | undefined | undefined;
-    value?: string | number | readonly string[] | undefined;
     href: string | undefined;
     type: "reset" | "submit" | "button" | undefined;
     className: string;

package/dist/actions/IconBtnGroup.d.ts

@@ -11,9 +11,12 @@ export interface IconBtnGroupProps extends Omit<ComponentProps<'div'>, 'onChange
     defaultValue?: Picked;
     /** asks the app: `one` → the pressed value · `many` → the new list */
     onChange?: (value: Picked) => void;
+    /** the buttons one OVER the other, the panel one button wide — at a `Row`'s `end`, where a panel across would take the words' room */
+    vertical?: boolean;
 }
 /** IconBtnGroup — a panel of up to FOUR icon-only buttons in ONE frame, sharing its width, a rule between them in the frame's
  *  colour (Lh 2026-09-29). Each is an `IconBtn` (its `label` is its spoken name). Plain: each does its own thing on its onClick.
- *  With `select`, a pressed button stays filled (aria-pressed): `one` or `many`. At home in a card's or a sheet's foot. */
-export declare function IconBtnGroup({ label, select, value, defaultValue, onChange, className, children, ...rest }: IconBtnGroupProps): import("react").JSX.Element;
+ *  With `select`, a pressed button stays filled (aria-pressed): `one` or `many`. At home in a card's or a sheet's foot;
+ *  `vertical` at a row's end. */
+export declare function IconBtnGroup({ label, select, value, defaultValue, onChange, vertical, className, children, ...rest }: IconBtnGroupProps): import("react").JSX.Element;
 export {};

package/dist/actions/IconBtnGroup.js

@@ -4,8 +4,9 @@ import { cx } from '../cx.js';
 import { useControlled, warnOnce } from '../state.js';
 /** IconBtnGroup — a panel of up to FOUR icon-only buttons in ONE frame, sharing its width, a rule between them in the frame's
  *  colour (Lh 2026-09-29). Each is an `IconBtn` (its `label` is its spoken name). Plain: each does its own thing on its onClick.
- *  With `select`, a pressed button stays filled (aria-pressed): `one` or `many`. At home in a card's or a sheet's foot. */
-export function IconBtnGroup({ label, select, value, defaultValue, onChange, className, children, ...rest }) {
+ *  With `select`, a pressed button stays filled (aria-pressed): `one` or `many`. At home in a card's or a sheet's foot;
+ *  `vertical` at a row's end. */
+export function IconBtnGroup({ label, select, value, defaultValue, onChange, vertical, className, children, ...rest }) {
     if (Children.count(children) > 4)
         warnOnce('icon-btn-group', 'cardds IconBtnGroup: more than 4 buttons — keep 4, put the rest in a Menu behind one of them');
     const [shown, request] = useControlled(value, defaultValue ?? (select === 'many' ? [] : null), onChange);
@@ -30,5 +31,5 @@ export function IconBtnGroup({ label, select, value, defaultValue, onChange, cla
             },
         });
     });
-    return _jsx("div", { role: "group", "aria-label": label, className: cx('icon-btn-group', className), ...rest, children: items });
+    return _jsx("div", { role: "group", "aria-label": label, className: cx('icon-btn-group', vertical && 'icon-btn-group--vertical', className), ...rest, children: items });
 }

package/dist/cardds.css

@@ -1374,7 +1374,7 @@ button:enabled { cursor: pointer; } /* a disabled one keeps the arrow */
   border-radius: var(--r-card) var(--r-card) 0 0;
   border-bottom: 0;
   box-shadow: var(--sheet-shadow, var(--shadow-sheet));
-  --_foot: calc(var(--card-gap) + var(--btn-h) + var(--card-pad) + var(--_safe-b-open)); /* the foot strip's height (below) — merged here, one bare .sheet rule */
+  --_foot: calc(var(--card-gap) + var(--sheet-foot-h, var(--btn-h)) + var(--card-pad) + var(--_safe-b-open)); /* the foot strip's height (below) — merged here, one bare .sheet rule */
 }
 .sheet--full { --_y: 0%; --_cover: 0rem; }
 .sheet--half { --_y: calc(var(--sheet-half) * 100%); --_cover: calc(var(--sheet-half) * var(--_box)); }
@@ -1441,7 +1441,7 @@ button:enabled { cursor: pointer; } /* a disabled one keeps the arrow */
    stops that far above the sheet's edge. At peek there is only the handle and the title: the foot is gone.
    One row, ≤ 2 buttons. <div class="card__foot"><button class="btn btn--primary btn--block">…</button></div> */
 /* …and the link row under the button, when there is one (its line + the gap over it) */
-.sheet:has(> .card__foot--link) { --_foot: calc(var(--card-gap) + var(--btn-h) + var(--sp-1) + var(--link-sm-min-h, calc(var(--tap-base) * 7 / 12)) + var(--card-pad) + var(--_safe-b-open)); }
+.sheet:has(> .card__foot--link) { --_foot: calc(var(--card-gap) + var(--sheet-foot-h, calc(var(--btn-h) + var(--sp-1) + var(--link-sm-min-h, calc(var(--tap-base) * 7 / 12)))) + var(--card-pad) + var(--_safe-b-open)); } /* --sheet-foot-h: the foot's rows as the Sheet measured them (a button grows with the text size) */
 .sheet > .card__foot {
   position: absolute; inset: calc(-1 * var(--border-w)) 0 0; z-index: 1; /* the sheet's border box: the same height the sheet's own % reads */
   align-items: end;
@@ -2140,6 +2140,10 @@ button:enabled { cursor: pointer; } /* a disabled one keeps the arrow */
 .icon-btn-group > .icon-btn { flex: 1 1 0; min-width: 0; width: auto; height: auto; border: 0; border-radius: 0; background: transparent; color: inherit; box-shadow: none; }
 .icon-btn-group > .icon-btn + .icon-btn { border-inline-start: var(--border-w) solid var(--icon-btn-group-rule, var(--icon-btn-group-border, var(--outline))); }
 .card__foot > .icon-btn-group { flex: 1 1 0; }
+/* --vertical: the buttons one over the other, ONE button wide — at a row's end, where a panel across would take the words' room */
+.icon-btn-group--vertical { flex-direction: column; flex: none; width: var(--tap); }
+.icon-btn-group--vertical > .icon-btn { flex: 1 0 auto; min-height: var(--tap); }
+.icon-btn-group--vertical > .icon-btn + .icon-btn { border-inline-start: 0; border-block-start: var(--border-w) solid var(--icon-btn-group-rule, var(--icon-btn-group-border, var(--outline))); }
 .icon-btn-group > .icon-btn[aria-pressed="true"] { background: var(--icon-btn-group-on-bg, var(--accent)); color: var(--icon-btn-group-on-ink, var(--on-accent)); } /* `select`: a pressed button STAYS filled (Lh 2026-09-29) */
 .icon-btn-group > .icon-btn:active:not(:disabled) { scale: 1; opacity: var(--press-dim); } /* a part of one frame DIMS, it never shrinks inside it */
 
@@ -2674,6 +2678,14 @@ button:enabled { cursor: pointer; } /* a disabled one keeps the arrow */
 .bar--on::after { background: var(--accent); }
 .bar--on > span { background: var(--accent); color: var(--on-accent); padding: var(--sp-0) var(--sp-2); border-radius: var(--r-chip); }
 
+/* ---- spinner: "working on it", a wait of unknown length (Lh 2026-10-01) ----
+   <span class="spinner" role="status"><svg class="icon">…loader-circle…</svg>Loading…</span>
+   The ring turns; words beside it are optional and take the caption's look. Still when motion is reduced. */
+.spinner { display: inline-flex; align-items: center; justify-content: center; gap: var(--sp-2); vertical-align: middle; font: var(--type-caption); color: var(--spinner-ink, currentColor); }
+.spinner > .icon { flex: none; }
+@media (prefers-reduced-motion: no-preference) { .spinner > .icon { animation: spinner-turn 0.9s linear infinite; } }
+@keyframes spinner-turn { to { rotate: 1turn; } }
+
 /* ---- progress: one straight line, the done share solid, the rest faint (Lh 2026-09-22) — a voice note's
    timeline, a download, a step count as a line. <div class="progress" role="progressbar" style="--progress-at: 0.4"></div>
    --progress-at is DATA the component writes (0–1), not a knob (scripts/knobs.mjs lists it). The done part is a
@@ -3766,7 +3778,7 @@ button:enabled { cursor: pointer; } /* a disabled one keeps the arrow */
      <div class="banner__body">…</div></details>
    A light tint (not a card tone) with a slightly darker rule above and below, edge to edge of its card or screen (Lh 2026-09-24). */
 .banner {
-  display: grid;
+  display: grid; grid-template-columns: minmax(0, 1fr);
   background: var(--banner-bg, var(--ink-tint));
   color: var(--banner-ink, inherit);
   border-block: var(--border-w) solid var(--banner-border, var(--hairline));
@@ -3782,7 +3794,9 @@ button:enabled { cursor: pointer; } /* a disabled one keeps the arrow */
 .banner__summary::-webkit-details-marker { display: none; }
 .banner__summary .icon { transition: rotate var(--motion-quick) ease; }
 .banner[open] .banner__summary .icon { rotate: 180deg; }
-.banner__body { display: grid; gap: var(--banner-body-gap, var(--sp-1)); padding-bottom: var(--sp-4); }
+/* the band's words never run past it: one column that cannot be wider than the band (a grid track is as wide as its longest
+   word otherwise), and a word with no break in it — a link — breaks where it must (mailpool, Lh 2026-10-01) */
+.banner__body { display: grid; grid-template-columns: minmax(0, 1fr); overflow-wrap: anywhere; gap: var(--banner-body-gap, var(--sp-1)); padding-bottom: var(--sp-4); }
 .banner::details-content { width: 100%; }
 @supports (interpolate-size: allow-keywords) {
   @media (prefers-reduced-motion: no-preference) {

package/dist/index.d.ts

@@ -17,6 +17,7 @@ export * from './scaffold/Page.js';
 export * from './scaffold/EmptyState.js';
 export * from './scaffold/Centre.js';
 export * from './scaffold/slideScreen.js';
+export * from './scaffold/LayerHistory.js';
 export * from './cards/Card.js';
 export * from './cards/CardHead.js';
 export * from './cards/CardFoot.js';
@@ -55,6 +56,7 @@ export * from './choice/Mood.js';
 export * from './choice/Slider.js';
 export * from './numbers/Ring.js';
 export * from './numbers/Progress.js';
+export * from './numbers/Spinner.js';
 export * from './numbers/Track.js';
 export * from './numbers/Band.js';
 export * from './numbers/DotGrid.js';

package/dist/index.js

@@ -21,6 +21,7 @@ export * from './scaffold/Page.js';
 export * from './scaffold/EmptyState.js';
 export * from './scaffold/Centre.js';
 export * from './scaffold/slideScreen.js';
+export * from './scaffold/LayerHistory.js';
 export * from './cards/Card.js';
 export * from './cards/CardHead.js';
 export * from './cards/CardFoot.js';
@@ -59,6 +60,7 @@ export * from './choice/Mood.js';
 export * from './choice/Slider.js';
 export * from './numbers/Ring.js';
 export * from './numbers/Progress.js';
+export * from './numbers/Spinner.js';
 export * from './numbers/Track.js';
 export * from './numbers/Band.js';
 export * from './numbers/DotGrid.js';

package/dist/lists/Row.d.ts

@@ -45,5 +45,7 @@ export interface RowsProps extends ComponentProps<'div'> {
      *  Words = the small label; an ELEMENT (`<Text level="title" as="h3">`) is used as the heading itself — the group is labelled by it. */
     heading?: ReactNode;
 }
-/** Rows — a list of Rows separated by hairlines; `heading` names the group (a `role="group"` labelled by it). */
-export declare function Rows({ heading, className, children, ...rest }: RowsProps): import("react").JSX.Element;
+/** Rows — a list of Rows separated by hairlines; `heading` names the group (a `role="group"` labelled by it).
+ *  REORDERED (the app renders the same keyed rows in another order): each row SLIDES to its new place — the one going up passes
+ *  over the others — instead of jumping (Lh 2026-10-01). The order is the app's; the move is the list's. */
+export declare function Rows({ heading, className, children, ref, ...rest }: RowsProps): import("react").JSX.Element;

package/dist/lists/Row.js

@@ -1,8 +1,8 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { cloneElement, createElement, isValidElement, useId } from 'react';
+import { cloneElement, createElement, isValidElement, useId, useLayoutEffect, useRef } from 'react';
 import { cx } from '../cx.js';
 import { Icon } from '../type/Icon.js';
-import { useDisclosure } from '../state.js';
+import { reducedMotion, useDisclosure } from '../state.js';
 /**
  * Row — a frameless row inside a card: lead · title + meta · end. 48px+ tall, a tap target.
  * Several go in Rows (hairlines between). A row that IS a card is `Card row`.
@@ -18,9 +18,50 @@ export function Row({ lead, leadIcon, title, meta, body, end, endValue, endCapti
         return row;
     return (_jsxs("details", { className: "row-expand", ...rest, ...disclosure, children: [row, _jsx("div", { className: "row-expand__more", children: more })] }));
 }
-/** Rows — a list of Rows separated by hairlines; `heading` names the group (a `role="group"` labelled by it). */
-export function Rows({ heading, className, children, ...rest }) {
+/** Rows — a list of Rows separated by hairlines; `heading` names the group (a `role="group"` labelled by it).
+ *  REORDERED (the app renders the same keyed rows in another order): each row SLIDES to its new place — the one going up passes
+ *  over the others — instead of jumping (Lh 2026-10-01). The order is the app's; the move is the list's. */
+export function Rows({ heading, className, children, ref, ...rest }) {
     const id = useId();
     const named = heading != null;
-    return (_jsxs("div", { className: cx('rows', className), role: named ? 'group' : undefined, "aria-labelledby": named ? id : undefined, ...rest, children: [named && (isValidElement(heading) ? cloneElement(heading, { id }) : _jsx("span", { className: "rows__head", id: id, children: heading })), children] }));
+    const own = useRef(null);
+    const was = useRef(new Map());
+    const order = useRef([]);
+    useLayoutEffect(() => {
+        const box = own.current;
+        if (!box)
+            return;
+        const rows = [...box.children].filter((el) => el.id !== id);
+        rows.forEach((el) => el.getAnimations().forEach((a) => { if (a.id === 'rows-move')
+            a.cancel(); })); // read the resting places
+        const at = new Map(rows.map((el) => [el, el.offsetTop]));
+        const before = order.current, moved = before.length === rows.length && rows.some((el, i) => el !== before[i]) && rows.every((el) => was.current.has(el));
+        if (moved && !reducedMotion()) {
+            const ms = (parseFloat(getComputedStyle(box).getPropertyValue('--motion-sheet')) || 0.35) * 1000;
+            for (const el of rows) {
+                const dy = (was.current.get(el) ?? 0) - (at.get(el) ?? 0);
+                if (!dy)
+                    continue;
+                const up = dy > 0; // it goes UP: over the others, on the card's ground so they pass under it
+                const a = el.animate([{ translate: `0 ${dy}px` }, { translate: '0 0' }], { duration: ms, easing: 'cubic-bezier(0.2, 0.8, 0.2, 1)' });
+                a.id = 'rows-move';
+                if (up) {
+                    el.style.position = 'relative';
+                    el.style.zIndex = '1';
+                    const clear = () => { el.style.position = ''; el.style.zIndex = ''; };
+                    a.finished.then(clear, clear);
+                }
+            }
+        }
+        was.current = at;
+        order.current = rows;
+    });
+    const setRef = (node) => {
+        own.current = node;
+        if (typeof ref === 'function')
+            ref(node);
+        else if (ref)
+            ref.current = node;
+    };
+    return (_jsxs("div", { ref: setRef, className: cx('rows', className), role: named ? 'group' : undefined, "aria-labelledby": named ? id : undefined, ...rest, children: [named && (isValidElement(heading) ? cloneElement(heading, { id }) : _jsx("span", { className: "rows__head", id: id, children: heading })), children] }));
 }

package/dist/numbers/Spinner.d.ts

@@ -0,0 +1,13 @@
+import type { ComponentProps, ReactNode } from 'react';
+export interface SpinnerProps extends Omit<ComponentProps<'span'>, 'children'> {
+    /** the ring's size, an Icon's: xs = in a caption or a row's meta · md (default) · lg = an EmptyState's `icon` */
+    size?: 'xs' | 'sm' | 'md' | 'lg';
+    /** what is being waited for, READ OUT (not shown) — give it when there are no words beside the ring */
+    label?: string;
+    /** words shown beside the ring ("กำลังโหลด…"): the line says it, the ring only turns */
+    children?: ReactNode;
+}
+/** Spinner — "working on it": a ring that turns, alone or with a line of words beside it. For a wait of unknown length — a known
+ *  share is a `Progress`. `role="status"`: the words (or `label`) are read out when it appears. In a row's `end`, a card, a
+ *  sheet's body, an `EmptyState`'s `icon`; a whole SCREEN that is not known yet shows nothing instead (`Screen ready`). */
+export declare function Spinner({ size, label, className, children, ...rest }: SpinnerProps): import("react").JSX.Element;

package/dist/numbers/Spinner.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cx } from '../cx.js';
+import { Icon } from '../type/Icon.js';
+/** Spinner — "working on it": a ring that turns, alone or with a line of words beside it. For a wait of unknown length — a known
+ *  share is a `Progress`. `role="status"`: the words (or `label`) are read out when it appears. In a row's `end`, a card, a
+ *  sheet's body, an `EmptyState`'s `icon`; a whole SCREEN that is not known yet shows nothing instead (`Screen ready`). */
+export function Spinner({ size = 'md', label, className, children, ...rest }) {
+    return (_jsxs("span", { className: cx('spinner', className), role: "status", "aria-label": children == null ? label : undefined, ...rest, children: [_jsx(Icon, { name: "loader-circle", size: size }), children] }));
+}

package/dist/scaffold/LayerHistory.d.ts

@@ -0,0 +1,53 @@
+import { type ReactNode } from 'react';
+export type LayerValue = string | number;
+type EntryState = Record<string, unknown>;
+export interface LayerHistoryProps {
+    /** the CURRENT history entry's state, as a value of this render — the hook re-reads it on every back / forward / push
+     *  (react-router: `useLocation().state`) */
+    state: unknown;
+    /** a NEW entry for the same page with this state: the path kept, the query dropped (react-router:
+     *  `navigate({ pathname }, { state })`) */
+    push: (state: EntryState) => void;
+    /** the SAME entry, its state replaced: the path kept, the query dropped (`navigate({ pathname }, { replace: true, state })`) */
+    replace: (state: EntryState) => void;
+    /** back by this many entries (`navigate(-entries)`) */
+    back: (entries: number) => void;
+    children?: ReactNode;
+}
+/**
+ * LayerHistory — the project's router, handed to cardds ONCE, around the app's screens (inside the router): the entry's `state`
+ * and the three moves `push` · `replace` · `back`. `useLayer` / `useLayers` stand on it. cardds never touches the History API
+ * itself — a router would not see it.
+ */
+export declare function LayerHistory({ state, push, replace, back, children }: LayerHistoryProps): import("react").JSX.Element;
+export interface LayerApi {
+    /** what the layer shows while it is up (which way's sheet, which question); `null` = not up */
+    value: LayerValue | null;
+    /** UP: one entry of its own. Already up → the new value on the entry it has, never a second entry (one layer, one back) —
+     *  so `open` called from INSIDE the layer (a step that turns this sheet into another way's) is a replace, not a push. */
+    open: (value: LayerValue) => void;
+    /** the PART asked to close (a handle to away, `onDismiss`, a button): back one entry when the app put one there — else (it
+     *  came with the page) the entry it is on, without it. Nothing when it is not up: the back button already took it. */
+    close: () => void;
+    /** it CAME WITH THE PAGE (a link straight to an open sheet, `?way=`): read the address once, call this — no entry is added,
+     *  and the query is dropped. Closing it then stays on the page. */
+    arrive: (value: LayerValue) => void;
+}
+/**
+ * useLayer — ONE layer of this screen, by its name: a whole bottom sheet, a modal. Back takes it off; the screen stays.
+ * `const way = useLayer('way')` → `<CallSheet open={way.value} onOpenChange={(up, i) => (up ? way.open(i!) : way.close())}>`.
+ * A Modal: `open={ask.value !== null}` + the app's own `mounted` flag cleared in `onClosed`. Opened again a layer starts anew —
+ * give what is inside a new `key` per opening.
+ */
+export declare function useLayer(name: string): LayerApi;
+/**
+ * useLayers — every layer over this screen: `up` (how many), and `closeAll(then)` — take them ALL off, then run `then`: before a
+ * move that must leave nothing of this page's layers under it (signed out → replace with the sign-in page). The entries are
+ * counted when the move is MADE, not when it was asked (the member may press back while a call runs), and `then` runs once the
+ * history shows them gone.
+ */
+export declare function useLayers(): {
+    up: number;
+    closeAll: (then: () => void) => void;
+};
+export {};

package/dist/scaffold/LayerHistory.js

@@ -0,0 +1,94 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useEffect, useMemo, useRef } from 'react';
+import { warnOnce } from '../state.js';
+const Ctx = createContext(null);
+/**
+ * LayerHistory — the project's router, handed to cardds ONCE, around the app's screens (inside the router): the entry's `state`
+ * and the three moves `push` · `replace` · `back`. `useLayer` / `useLayers` stand on it. cardds never touches the History API
+ * itself — a router would not see it.
+ */
+export function LayerHistory({ state, push, replace, back, children }) {
+    const value = useMemo(() => ({ state, push, replace, back }), [state, push, replace, back]);
+    return _jsx(Ctx.Provider, { value: value, children: children });
+}
+/* the state is untyped — an old entry, another library's keys: read only what has the shape, keep the rest as it is */
+const read = (state) => {
+    if (typeof state !== 'object' || state === null || Array.isArray(state))
+        return { rest: {}, layers: {} };
+    const { layers: raw, ...rest } = state;
+    const layers = {};
+    if (typeof raw === 'object' && raw !== null) {
+        for (const [name, l] of Object.entries(raw)) {
+            const v = l?.value;
+            if (typeof v === 'string' || typeof v === 'number')
+                layers[name] = { value: v, pushed: l.pushed === true };
+        }
+    }
+    return { rest, layers };
+};
+const NONE = { state: null, push: () => undefined, replace: () => undefined, back: () => undefined };
+const useHistory = () => {
+    const h = useContext(Ctx);
+    if (!h)
+        warnOnce('layer-history', 'cardds useLayer: no <LayerHistory> above — hand the router over once, around the screens; until then a layer never comes up.');
+    return h ?? NONE;
+};
+/**
+ * useLayer — ONE layer of this screen, by its name: a whole bottom sheet, a modal. Back takes it off; the screen stays.
+ * `const way = useLayer('way')` → `<CallSheet open={way.value} onOpenChange={(up, i) => (up ? way.open(i!) : way.close())}>`.
+ * A Modal: `open={ask.value !== null}` + the app's own `mounted` flag cleared in `onClosed`. Opened again a layer starts anew —
+ * give what is inside a new `key` per opening.
+ */
+export function useLayer(name) {
+    const { state, push, replace, back } = useHistory();
+    return useMemo(() => {
+        const { rest, layers } = read(state);
+        const layer = layers[name] ?? null;
+        const others = () => Object.fromEntries(Object.entries(layers).filter(([key]) => key !== name));
+        return {
+            value: layer?.value ?? null,
+            open: (to) => (layer ? replace({ ...rest, layers: { ...layers, [name]: { value: to, pushed: layer.pushed } } }) : push({ ...rest, layers: { ...layers, [name]: { value: to, pushed: true } } })),
+            // already up on an entry the app pushed (the link opened where the layer was): it stays a pushed one, or the close would leave that entry behind
+            arrive: (as) => replace({ ...rest, layers: { ...layers, [name]: { value: as, pushed: layer?.pushed ?? false } } }),
+            close: () => {
+                if (!layer)
+                    return;
+                if (layer.pushed)
+                    back(1);
+                else
+                    replace({ ...rest, layers: others() });
+            },
+        };
+    }, [state, push, replace, back, name]);
+}
+/**
+ * useLayers — every layer over this screen: `up` (how many), and `closeAll(then)` — take them ALL off, then run `then`: before a
+ * move that must leave nothing of this page's layers under it (signed out → replace with the sign-in page). The entries are
+ * counted when the move is MADE, not when it was asked (the member may press back while a call runs), and `then` runs once the
+ * history shows them gone.
+ */
+export function useLayers() {
+    const { state, back } = useHistory();
+    const { layers } = read(state);
+    const up = Object.keys(layers).length;
+    const pushed = Object.values(layers).filter((l) => l.pushed).length;
+    const now = useRef(pushed);
+    const after = useRef(null);
+    const goBack = useRef(back);
+    goBack.current = back;
+    useEffect(() => {
+        now.current = pushed;
+        if (pushed > 0 || !after.current)
+            return;
+        const then = after.current;
+        after.current = null;
+        then();
+    }, [pushed, up]);
+    const closeAll = useRef((then) => {
+        if (now.current === 0)
+            return then();
+        after.current = then;
+        goBack.current(now.current);
+    }).current;
+    return { up, closeAll };
+}

package/dist/scaffold/slideScreen.js

@@ -2,20 +2,23 @@
    old one out to the left, the new one in from the right; `back`: the reverse; `--motion-slide`, card.css). It is a view
    transition named for the move only: the leaving `.screen` is `screen-out`, the arriving one `screen-in`. */
 const screenIn = (scope) => scope.querySelector('.screen:not(.screen .screen)');
-/** wait until the screen in `scope` CHANGED — another element, or new content in the same one (React may keep the element when
-    both routes render a Screen in the same place) — a route rendered, sync or not; at most `ms`. A new Screen that is not
-    `ready` yet (`data-pending`) is waited for too, at most `hold`: the old screen stays until the new one knows what it is. */
+/** wait until the screen in `scope` CHANGED — another element, or the same one with new children (React may keep the element
+    when both routes render a Screen in the same place) — a route rendered, sync or not; at most `ms`. Any OTHER mutation is not
+    the route (a router renders a tick later: a popover closing meanwhile must not end the wait — timebank, 2026-10-01). A new
+    Screen that is not `ready` yet (`data-pending`) is waited for too, at most `hold`: the old screen stays until the new one
+    knows what it is. */
 function newScreen(scope, old, ms = 800, hold = 3000) {
     return new Promise((done) => {
-        const pending = (el) => !!el?.hasAttribute('data-pending');
-        const now = screenIn(scope);
-        if (now !== old && !pending(now))
-            return done(now);
         const root = scope instanceof Document ? scope.documentElement : scope;
+        let changed = false, held = false;
         const end = () => { mo.disconnect(); clearTimeout(t); done(screenIn(scope)); };
-        let held = false;
-        const look = () => {
-            if (!pending(screenIn(scope)))
+        const look = (records = []) => {
+            const now = screenIn(scope);
+            if (now !== old || records.some((r) => r.target === old))
+                changed = true; // its own children / its own data-pending
+            if (!changed)
+                return;
+            if (!now?.hasAttribute('data-pending'))
                 return end();
             if (!held) {
                 held = true;
@@ -26,8 +29,7 @@ function newScreen(scope, old, ms = 800, hold = 3000) {
         const mo = new MutationObserver(look);
         mo.observe(root, { childList: true, subtree: true, attributes: true, attributeFilter: ['data-pending'] });
         let t = setTimeout(end, ms);
-        if (pending(now))
-            look();
+        look();
     });
 }
 let running = false;

package/dist/sheets/Sheet.js

@@ -173,6 +173,26 @@ export function Sheet({ state, defaultState = 'half', onStateChange, onSettled,
         const stop = watchSize([head], publish);
         return () => { stop(); box.style.removeProperty('--sheet-peek'); };
     }, []);
+    /* 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. */
+    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
     const focus = (e) => {
         onFocus?.(e);
         if (current !== 'peek' || e.target.closest('.sheet__handle'))

package/package.json

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