@usableapp/cardds 0.7.87 → 0.7.88

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 > 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.88 — 2026-10-13
+
+Nothing here breaks an existing screen: a prop pair (`Card leave` + `onLeft`) and three knobs are added and none removed, no class or markup of an existing screen changed (a `Card` without `leave` is as before), and an `EmptyState` with its knob unset stands where it did in 0.7.87.
+
+### Added
+- **`Card leave` + `onLeft`: the card floats away, and the app is told when it has gone** (asked after a send: one `Card` standing in a `Page`, with a `StampOn main arrive` that has just landed on it, leaves, and the app then changes the page). Before → after: the only thing that left was the `PostDesk`'s own card (`state="sent"`), and a `Card` could be hidden only by the app taking it out of the tree, with no motion and no word of when → `leave` (a boolean, the app's, controlled like an input) sends the card up and out with a small turn, all it holds with it, and `onLeft` is called once when the motion has ended (at once with reduced motion, or when the card has no motion). Set back to `false` the card stands again where it was, and a leave set back before it ended says nothing. A card that has left takes no taps and is `inert` (out of the accessibility tree); it moves by `translate` and `rotate` only, so the room round it does not change. If a send fails the app never sets `leave` and the card stays. A card in a box that clips (a scrolling `StackSheet` body clips at its edge) is cut there as it goes. A card that is a `SheetStack` sheet (`stack`) ignores `leave`. A card given `leave` (true or false) wears `card--leaver`, and `card--away` while it is asked to go: two new classes, on no other card. Knobs `--leave-rise` (160%, how far it goes up, a share of its own height) and `--leave-turn` (-5deg); the time is `--motion-sheet`. Under `data-finish="sticker"` a leaving lone card turns to `--leave-turn` from its lean and back. Stories `Card · Leaves`, `Controlled` and `AfterTheSend` (the `StampOn arrive` → `leave` → `onLeft` sequence); the `Card` JSDoc, and so `cardds get Card` and `cardds find "card flies away"`, name it.
+- **`Row htmlFor`: a row that is a label can name the control it presses.** Before → after: `Row as="label"` typed a div's attributes, so `htmlFor` was a type error (it worked when run) → `htmlFor` is a prop. It is needed when the row's `end` holds a button before its `Check` (a picked row's own move, "open the map"): a label presses the first control inside it, so without `htmlFor` a touch on the row's words pressed that button. Story `Row · PickShowsItsMove`: pick one row, the picked row shows its button, a second touch keeps the pick.
+- **`cardds check` warns on a label row that holds a button and names no control** (`row-label-button`): `<Row as="label">` with an `IconBtn`, `Btn` or `Link` inside and no `htmlFor`. Before, the check was silent and the row's words pressed the button.
+- **`--empty-state-at`: where an `EmptyState` stands in the free room of what holds it.** A number from 0 to 1, the share of the free room that stands above it. Before → after: alone in a `Step` it stood two parts from the top and three from the bottom (40%) and a theme could not move it → that is the knob's default, 0.4, and `:root { --empty-state-at: 0.2 }` in a project's theme puts it a fifth down on every screen (or set it on a `Screen` / `Step` for the ones inside). Alone in a `SheetBody` (a `Sheet`, or a `StackSheet` of a `SheetStack`) it stood at the top of the body with no way to lower it → still at the top by default (0), and the knob lowers it by that share of the body's free room, 0.4 putting it where a `Step` puts it. The body is a flex column only while an `EmptyState` is its only child; the geometry of every other body is as before. Stories `EmptyState · HigherUp` and `EmptyState · InASheet`; the `EmptyState` JSDoc, and so `cardds get EmptyState`, names the knob.
+
+### Changed
+- **The `PostDesk`'s leave and the `Card`'s are one mechanic.** Before → after: `post.css` wrote the sent card's `--_y: -160%`, `rotate: -5deg` and its `translate` / `rotate` transition for itself → one rule in card.css (LEAVE) holds the transition and reads `--leave-rise` and `--leave-turn` for both holders, and post.css keeps only what is its own (the half's `--_x`). Nothing changes for a screen: a `PostDesk` sent draws, moves and times as in 0.7.87 (computed style of all 449 stories identical before and after), and a theme that set neither knob sees no difference.
+
 ## 0.7.87 — 2026-10-12
 
 Nothing here breaks an existing screen: no class and no markup changed, six knobs are added and none removed; three mechanics that two files each wrote twice are now one rule each, and every screen without `data-finish` draws as in 0.7.86.

package/css/card.css

@@ -25,6 +25,15 @@
    screens. Children shrink to the track; they never size the card. */
 .card > * { min-width: 0; }
 
+/* LEAVE — a card that goes: up and out with a small turn, as one piece (translate and rotate only, so nothing round it moves). The post desk's
+   card once `sent` and a `Card` with `leave` read the same two knobs; the time is --motion-sheet. `.card--leaver` is a card whose app may ask it
+   to go (it holds the transition, so it comes back as it went); `.card--away` is one that has been asked. A knob of the time would read dead:
+   the knob walk switches motion off */
+:is(.card--leaver, .post-desk__card) { transition: translate var(--motion-sheet) ease, rotate var(--motion-sheet) ease; }
+:is(.card--away, .post-desk--sent .post-desk__card) { --_y: calc(var(--leave-rise, 160%) * -1); rotate: var(--leave-turn, -5deg); }
+.card--away { translate: 0 var(--_y); }
+@media (prefers-reduced-motion: reduce) { :is(.card--leaver, .post-desk__card) { transition: none; } }
+
 .card--2 { --card-bg: var(--card-2-bg); --card-ink: var(--card-2-ink); --card-muted: var(--card-2-muted); }
 /* dark/accent slot: accent-toned controls would vanish — the slot re-points
    the accent tokens, so every accent consumer (btn--primary, chip--on,

package/css/finish.css

@@ -145,8 +145,8 @@
     0 calc(var(--sticker-cut, 5px) + 4px) 0 0 color-mix(in srgb, var(--on-surface) 16%, transparent),
     0 calc(var(--sticker-cut, 5px) + 12px) 20px -8px color-mix(in srgb, var(--on-surface) 22%, transparent);
 }
-[data-finish="sticker"] .card:not(.sheet, .modal, .sheet-stack *, .card-list > *, .card-feed > *) { rotate: var(--sticker-tilt, 0.8deg); }
-[data-finish="sticker"] .card:not(.sheet, .modal, .sheet-stack *, .card-list > *, .card-feed > *):nth-of-type(even) { rotate: calc(-1 * var(--sticker-tilt, 0.8deg)); }
+[data-finish="sticker"] .card:not(.sheet, .modal, .card--away, .sheet-stack *, .card-list > *, .card-feed > *) { rotate: var(--sticker-tilt, 0.8deg); }
+[data-finish="sticker"] .card:not(.sheet, .modal, .card--away, .sheet-stack *, .card-list > *, .card-feed > *):nth-of-type(even) { rotate: calc(-1 * var(--sticker-tilt, 0.8deg)); }
 [data-finish="sticker"] .card-list { gap: var(--sp-5); }
 [data-finish="sticker"] .btn {
   box-shadow: 0 3px 0 0 color-mix(in srgb, currentColor 30%, transparent);

package/css/post.css

@@ -199,10 +199,9 @@
   width: calc(var(--_p) * 2);
   aspect-ratio: 3 / 2;
   translate: var(--_x) var(--_y);
-  transition: translate var(--motion-sheet) ease, rotate var(--motion-sheet) ease;
 }
 .post-desk--address .post-desk__card { --_x: calc(100cqi - var(--_p) * 2); }
-.post-desk--sent .post-desk__card { --_y: -160%; rotate: -5deg; }
+/* sent: the card leaves by card.css LEAVE, as a `Card` with `leave` does */
 .post-desk__half { min-width: 0; min-height: 0; padding: var(--post-desk-pad, var(--sp-5)); display: flex; flex-direction: column; }
 .post-desk__half--address { border-inline-start: var(--rule-w) solid var(--_rule); gap: var(--sp-4); }
 .post-desk__write {
@@ -271,7 +270,6 @@
 .post-desk__note { margin: 0; font: var(--type-caption); color: var(--post-desk-note-ink, var(--on-surface-muted)); min-height: 1.35em; }
 /* what stands where the card was, once it has left */
 .post-desk__gone { position: absolute; inset: 0; display: grid; grid-template-columns: minmax(0, 1fr); align-content: center; gap: var(--sp-2); }
-@media (prefers-reduced-motion: reduce) { .post-desk__card { transition: none; } }
 
 /* ============================================================
    post-box — KEEPING many. The cards whole and landscape, standing one behind another; each shows its top edge: who, where,

package/css/step.css

@@ -185,7 +185,12 @@
   object-fit: cover;
 }
 /* an EMPTY STATE is a component in the content box too (Lh 2026-09-23 — it no longer floats in a Centre over the screen): alone in a
-   Step it stands at the human centre of the content, 40% down (two parts of room above it, three below) */
-.step:has(> .empty-state)::before { content: ""; flex: 2 1 0; }
-.step:has(> .empty-state)::after { content: ""; flex: 3 1 0; }
+   Step it stands at the human centre of the content, 40% down (two parts of room above it, three below). --empty-state-at is the share of the
+   free room that stands above it (a theme's 0.2 puts it a fifth down); a sheet's body holds an only EmptyState by the same share, but defaults to 0: at the top, as it always stood */
+.step:has(> .empty-state)::before { content: ""; flex: calc(var(--empty-state-at, 0.4) * 5) 1 0; }
+.step:has(> .empty-state)::after { content: ""; flex: calc(5 - var(--empty-state-at, 0.4) * 5) 1 0; }
 .step > .empty-state { flex: none; }
+.sheet__body:has(> .empty-state:only-child) { display: flex; flex-direction: column; gap: 0; }
+.sheet__body:has(> .empty-state:only-child)::before { content: ""; flex: calc(var(--empty-state-at, 0) * 5) 1 0; }
+.sheet__body:has(> .empty-state:only-child)::after { content: ""; flex: calc(5 - var(--empty-state-at, 0) * 5) 1 0; }
+.sheet__body > .empty-state:only-child { flex: none; }

package/dist/cardds.css

@@ -717,6 +717,15 @@ button:enabled { cursor: pointer; } /* a disabled one keeps the arrow */
    screens. Children shrink to the track; they never size the card. */
 .card > * { min-width: 0; }
 
+/* LEAVE — a card that goes: up and out with a small turn, as one piece (translate and rotate only, so nothing round it moves). The post desk's
+   card once `sent` and a `Card` with `leave` read the same two knobs; the time is --motion-sheet. `.card--leaver` is a card whose app may ask it
+   to go (it holds the transition, so it comes back as it went); `.card--away` is one that has been asked. A knob of the time would read dead:
+   the knob walk switches motion off */
+:is(.card--leaver, .post-desk__card) { transition: translate var(--motion-sheet) ease, rotate var(--motion-sheet) ease; }
+:is(.card--away, .post-desk--sent .post-desk__card) { --_y: calc(var(--leave-rise, 160%) * -1); rotate: var(--leave-turn, -5deg); }
+.card--away { translate: 0 var(--_y); }
+@media (prefers-reduced-motion: reduce) { :is(.card--leaver, .post-desk__card) { transition: none; } }
+
 .card--2 { --card-bg: var(--card-2-bg); --card-ink: var(--card-2-ink); --card-muted: var(--card-2-muted); }
 /* dark/accent slot: accent-toned controls would vanish — the slot re-points
    the accent tokens, so every accent consumer (btn--primary, chip--on,
@@ -2287,10 +2296,15 @@ button:enabled { cursor: pointer; } /* a disabled one keeps the arrow */
   object-fit: cover;
 }
 /* an EMPTY STATE is a component in the content box too (Lh 2026-09-23 — it no longer floats in a Centre over the screen): alone in a
-   Step it stands at the human centre of the content, 40% down (two parts of room above it, three below) */
-.step:has(> .empty-state)::before { content: ""; flex: 2 1 0; }
-.step:has(> .empty-state)::after { content: ""; flex: 3 1 0; }
+   Step it stands at the human centre of the content, 40% down (two parts of room above it, three below). --empty-state-at is the share of the
+   free room that stands above it (a theme's 0.2 puts it a fifth down); a sheet's body holds an only EmptyState by the same share, but defaults to 0: at the top, as it always stood */
+.step:has(> .empty-state)::before { content: ""; flex: calc(var(--empty-state-at, 0.4) * 5) 1 0; }
+.step:has(> .empty-state)::after { content: ""; flex: calc(5 - var(--empty-state-at, 0.4) * 5) 1 0; }
 .step > .empty-state { flex: none; }
+.sheet__body:has(> .empty-state:only-child) { display: flex; flex-direction: column; gap: 0; }
+.sheet__body:has(> .empty-state:only-child)::before { content: ""; flex: calc(var(--empty-state-at, 0) * 5) 1 0; }
+.sheet__body:has(> .empty-state:only-child)::after { content: ""; flex: calc(5 - var(--empty-state-at, 0) * 5) 1 0; }
+.sheet__body > .empty-state:only-child { flex: none; }
 
 /* ---- css/forms.css — outlined fields, add-row ---- */
 /* ============================================================
@@ -4627,10 +4641,9 @@ button:enabled { cursor: pointer; } /* a disabled one keeps the arrow */
   width: calc(var(--_p) * 2);
   aspect-ratio: 3 / 2;
   translate: var(--_x) var(--_y);
-  transition: translate var(--motion-sheet) ease, rotate var(--motion-sheet) ease;
 }
 .post-desk--address .post-desk__card { --_x: calc(100cqi - var(--_p) * 2); }
-.post-desk--sent .post-desk__card { --_y: -160%; rotate: -5deg; }
+/* sent: the card leaves by card.css LEAVE, as a `Card` with `leave` does */
 .post-desk__half { min-width: 0; min-height: 0; padding: var(--post-desk-pad, var(--sp-5)); display: flex; flex-direction: column; }
 .post-desk__half--address { border-inline-start: var(--rule-w) solid var(--_rule); gap: var(--sp-4); }
 .post-desk__write {
@@ -4699,7 +4712,6 @@ button:enabled { cursor: pointer; } /* a disabled one keeps the arrow */
 .post-desk__note { margin: 0; font: var(--type-caption); color: var(--post-desk-note-ink, var(--on-surface-muted)); min-height: 1.35em; }
 /* what stands where the card was, once it has left */
 .post-desk__gone { position: absolute; inset: 0; display: grid; grid-template-columns: minmax(0, 1fr); align-content: center; gap: var(--sp-2); }
-@media (prefers-reduced-motion: reduce) { .post-desk__card { transition: none; } }
 
 /* ============================================================
    post-box — KEEPING many. The cards whole and landscape, standing one behind another; each shows its top edge: who, where,
@@ -5554,8 +5566,8 @@ button:enabled { cursor: pointer; } /* a disabled one keeps the arrow */
     0 calc(var(--sticker-cut, 5px) + 4px) 0 0 color-mix(in srgb, var(--on-surface) 16%, transparent),
     0 calc(var(--sticker-cut, 5px) + 12px) 20px -8px color-mix(in srgb, var(--on-surface) 22%, transparent);
 }
-[data-finish="sticker"] .card:not(.sheet, .modal, .sheet-stack *, .card-list > *, .card-feed > *) { rotate: var(--sticker-tilt, 0.8deg); }
-[data-finish="sticker"] .card:not(.sheet, .modal, .sheet-stack *, .card-list > *, .card-feed > *):nth-of-type(even) { rotate: calc(-1 * var(--sticker-tilt, 0.8deg)); }
+[data-finish="sticker"] .card:not(.sheet, .modal, .card--away, .sheet-stack *, .card-list > *, .card-feed > *) { rotate: var(--sticker-tilt, 0.8deg); }
+[data-finish="sticker"] .card:not(.sheet, .modal, .card--away, .sheet-stack *, .card-list > *, .card-feed > *):nth-of-type(even) { rotate: calc(-1 * var(--sticker-tilt, 0.8deg)); }
 [data-finish="sticker"] .card-list { gap: var(--sp-5); }
 [data-finish="sticker"] .btn {
   box-shadow: 0 3px 0 0 color-mix(in srgb, currentColor 30%, transparent);

package/dist/cards/Card.d.ts

@@ -40,6 +40,14 @@ export interface CardProps extends ComponentProps<'article'> {
     footLink?: ReactNode;
     /** set by `SheetStack` from the app's `open` and `refreshing`. The card renders its place, its grip and its pull. Leave it unset on any other card */
     stack?: StackPlace;
+    /** THE CARD LEAVES — the card floats away: up and out with a small turn, as one piece with all it holds (a stamp that has just landed on it goes with it).
+     *  The app sets it when its own move begins (the send went out) and does what follows in `onLeft`; if the send fails the app never sets it and the card
+     *  stays. Set back to false the card stands again where it was. Controlled like an input: the app owns it, the card only moves. A card that has left
+     *  takes no taps and is hidden from assistive tech (`inert`); the room round it does not change, so nothing jumps. A card in a box that clips (a
+     *  scrolling `StackSheet` body clips at its edge) is cut there as it goes. A card that is a `SheetStack` sheet (`stack`) ignores it. Knobs `--leave-rise` · `--leave-turn` */
+    leave?: boolean;
+    /** a card that was asked to `leave` HAS left (its motion ended; at once where motion is off, or when it has no motion) — the app does what follows: changes the page, closes. Once per leave */
+    onLeft?: () => void;
 }
 /**
  * Card — ONE boundary: head · content · foot. Cards are content the system offers (the words, the thing to read).
@@ -50,8 +58,9 @@ export interface CardProps extends ComponentProps<'article'> {
  * PRESSED WHOLE: a card whose ONLY control is its foot's button, or a row card's end button, is pressed anywhere — a touch off the
  * button runs that button's own action once, and the card dims under the finger. The app writes nothing; any other card is only read.
  */
-export declare function Card({ tone, paper, sm, row, cover, fold, centre, band, as, heading, caption, end, level, foot, footLink, stack, className, style, children, onClick, ref, ...rest }: CardProps): import("react").DetailedReactHTMLElement<{
+export declare function Card({ tone, paper, sm, row, cover, fold, centre, band, as, heading, caption, end, level, foot, footLink, stack, leave, onLeft, className, style, children, onClick, ref, ...rest }: CardProps): import("react").DetailedReactHTMLElement<{
     onClick: (e: MouseEvent<HTMLElement>) => void;
+    inert?: boolean | undefined;
     "aria-busy"?: (boolean | "true" | "false") | undefined;
     ref: (node: HTMLElement | null) => void;
     className: string;
@@ -965,7 +974,6 @@ export declare function Card({ tone, paper, sm, row, cover, fold, centre, band,
     popover?: "" | "auto" | "manual" | "hint" | undefined;
     popoverTargetAction?: "toggle" | "show" | "hide" | undefined;
     popoverTarget?: string | undefined;
-    inert?: boolean | undefined;
     inputMode?: "none" | "text" | "tel" | "url" | "email" | "numeric" | "decimal" | "search" | undefined;
     is?: string | undefined;
     exportparts?: string | undefined;

package/dist/cards/Card.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
-import { Children, createElement, isValidElement, useLayoutEffect, useRef, useState } from 'react';
+import { Children, createElement, isValidElement, useEffect, useLayoutEffect, useRef, useState } from 'react';
 import { cx } from '../cx.js';
-import { warnOnce } from '../state.js';
+import { useLatest, warnOnce } from '../state.js';
 import { CardHead } from './CardHead.js';
 import { CardFoot } from './CardFoot.js';
 import { goControl } from './cardGo.js';
@@ -15,7 +15,7 @@ import { StackHeadCtx, StackPullCtx, ownHead, stackPaint, useStackCard } from '.
  * PRESSED WHOLE: a card whose ONLY control is its foot's button, or a row card's end button, is pressed anywhere — a touch off the
  * button runs that button's own action once, and the card dims under the finger. The app writes nothing; any other card is only read.
  */
-export function Card({ tone, paper, sm, row, cover, fold, centre, band, as = 'article', heading, caption, end, level, foot, footLink, stack, className, style, children, onClick, ref, ...rest }) {
+export function Card({ tone, paper, sm, row, cover, fold, centre, band, as = 'article', heading, caption, end, level, foot, footLink, stack, leave, onLeft, className, style, children, onClick, ref, ...rest }) {
     const head = heading != null || caption != null || end != null;
     const tail = foot != null || footLink != null;
     if (head || tail) {
@@ -37,6 +37,19 @@ export function Card({ tone, paper, sm, row, cover, fold, centre, band, as = 'ar
         else if (passed)
             passed.current = node;
     };
+    const leaver = leave != null && !stack;
+    const away = leaver && leave;
+    const left = useLatest(onLeft);
+    useEffect(() => {
+        const card = own.current;
+        if (!away || !card)
+            return;
+        let live = true;
+        const moving = card.getAnimations().filter((a) => a instanceof CSSTransition && (a.transitionProperty === 'translate' || a.transitionProperty === 'rotate')); // the leave's own; none where motion is off
+        Promise.all(moving.map((a) => a.finished)).then(() => { if (live)
+            left.current?.(); }, () => { }); // a transition cancelled by `leave` set back rejects
+        return () => { live = false; };
+    }, [away]);
     const [go, setGo] = useState(false);
     useLayoutEffect(() => { setGo(own.current != null && goControl(own.current) != null); }); // every render: what the card holds is its children's
     const pressing = useRef(false);
@@ -77,9 +90,10 @@ export function Card({ tone, paper, sm, row, cover, fold, centre, band, as = 'ar
     const props = {
         ...rest,
         ref: setRef,
-        className: cx('card', tone && tone !== 1 && `card--${tone}`, paper && 'sheet--paper', sm && 'card--sm', row && 'card--row', cover && 'card--cover', fold && 'card--fold', centre && 'card--centre', band && 'card--band', go && 'card--go', painted.className, className),
+        className: cx('card', tone && tone !== 1 && `card--${tone}`, paper && 'sheet--paper', sm && 'card--sm', row && 'card--row', cover && 'card--cover', fold && 'card--fold', centre && 'card--centre', band && 'card--band', go && 'card--go', leaver && 'card--leaver', away && 'card--away', painted.className, className),
         style: painted.style || style ? { ...painted.style, ...style } : undefined,
         ...(stack ? { 'aria-busy': painted.busy } : {}),
+        ...(away ? { inert: true } : {}),
         onClick: click,
     };
     if (!head && !tail)