@usableapp/cardds 0.7.87 → 0.7.89

package/dist/lists/Row.d.ts

@@ -23,6 +23,8 @@ export interface RowProps extends Omit<ComponentProps<'div'>, 'title'> {
     done?: boolean;
     /** div (default), a link, a label wrapping a Check/Toggle, li */
     as?: 'div' | 'a' | 'label' | 'li';
+    /** with `as="label"`: the `id` of the control the row presses (its `Check`). Needed when the `end` holds a button BEFORE the check (a picked row's own move, "open the map"): a label presses the first control inside it, so without this a touch on the row's words would press that button */
+    htmlFor?: string;
     /** makes the row a link (an `a`); not with `more`, whose row is a summary */
     href?: string;
     /** what the row EXPANDS to show under itself (who liked, the rest of a list): the row becomes a `<details>`' summary */

package/dist/scaffold/EmptyState.d.ts

@@ -10,5 +10,6 @@ export interface EmptyStateProps extends Omit<ComponentProps<'div'>, 'title'> {
     level?: 'h2' | 'h3';
 }
 /** EmptyState — centred: a large icon, a heading, a line of body text, an optional CTA. A component in the content: alone in a `Step` it stands at the content's human centre, 40% down (Lh 2026-09-23 — no longer a `Centre` over the screen)
- *  or inside a card's section ("nothing here yet" under a heading) — the ink follows the card it sits in; full ink throughout, never muted (Lh 2026-09-16). */
+ *  or inside a card's section ("nothing here yet" under a heading) — the ink follows the card it sits in; full ink throughout, never muted (Lh 2026-09-16).
+ *  Knob `--empty-state-at`, a number 0–1: the share of the holder's free room that stands above it. In a `Step` the default is 0.4 (two parts above, three below); alone in a `SheetBody` it is 0 (at the top). A theme's `:root { --empty-state-at: 0.2 }` lifts it everywhere, or set it on a `Screen`, `Step` or `Sheet` for the ones inside. */
 export declare function EmptyState({ icon, title, action, level, className, children, ...rest }: EmptyStateProps): import("react").JSX.Element;

package/dist/scaffold/EmptyState.js

@@ -1,7 +1,8 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cx } from '../cx.js';
 /** EmptyState — centred: a large icon, a heading, a line of body text, an optional CTA. A component in the content: alone in a `Step` it stands at the content's human centre, 40% down (Lh 2026-09-23 — no longer a `Centre` over the screen)
- *  or inside a card's section ("nothing here yet" under a heading) — the ink follows the card it sits in; full ink throughout, never muted (Lh 2026-09-16). */
+ *  or inside a card's section ("nothing here yet" under a heading) — the ink follows the card it sits in; full ink throughout, never muted (Lh 2026-09-16).
+ *  Knob `--empty-state-at`, a number 0–1: the share of the holder's free room that stands above it. In a `Step` the default is 0.4 (two parts above, three below); alone in a `SheetBody` it is 0 (at the top). A theme's `:root { --empty-state-at: 0.2 }` lifts it everywhere, or set it on a `Screen`, `Step` or `Sheet` for the ones inside. */
 export function EmptyState({ icon, title, action, level = 'h2', className, children, ...rest }) {
     const H = level;
     return (_jsxs("div", { className: cx('empty-state', className), ...rest, children: [icon, title != null && _jsx(H, { className: "t-h2", children: title }), typeof children === 'string' ? _jsx("p", { className: "t-body", children: children }) : children, action != null && _jsx("div", { className: "empty-state__action", children: action })] }));

package/dist/stamp/Stamp.d.ts

@@ -15,14 +15,21 @@ export interface StampProps extends Omit<ComponentProps<'span'>, 'onClick'> {
     tilt?: 'left' | 'right';
     /** the whole stamp is a button: it renders a `<button>` */
     onClick?: () => void;
+    /** the member presses send and the stamp that already stands in the card's head is STRUCK onto its place by itself (shown large and faint, pressed down to its size) — as it comes on, or as this turns true. Use it when a stamp stands where the layout put it (`Card end`, a centre, the album) and sending should strike it; the stamp does not move and it keeps its `tilt`. A stamp laid ON a surface at a place the member chose is `StampOn arrive`. A stamp without `arrive` is not struck. With `onArrived` */
+    arrive?: boolean;
+    /** an arriving stamp has LANDED (its strike ended; at once where motion is off, and once per arrival) — the app does what follows: sends, closes, sets the card's `leave` */
+    onArrived?: () => void;
 }
 /**
  * Stamp — a perforated paper stamp, 4:5: the pictures fill the inner frame on a tone, the words sit on the picture's foot.
  * Every stamp is ONE size wherever it stands (`--stamp-size`, two taps wide: 96 × 120) — what holds it only places it; a holder narrower than that shows it whole, smaller.
  * The one small stamp is a stamp stuck on something (`StampOn`). Every inner length follows the stamp's width.
  * The outer box holds the size and the shadow; the paper inside is the one whose edge is punched (a mask would cut the shadow too).
+ * With `arrive` the stamp that stands in its place (the head of a card, `end={<Stamp arrive …/>}`) is struck onto it when the member sends, and `onArrived` tells
+ * the app it has landed, so it sends. The strike scales it down from twice its size, so it never moves the layout (it may cover its neighbours for a moment);
+ * a `tilt` is kept, the stamp ends at its turn. Afterwards the same stamp stands in the same place with no strike: drop `arrive` or keep it, nothing is struck twice.
  */
-export declare function Stamp({ pictures, tone, name, words, bare, tilt, onClick, className, ...rest }: StampProps): import("react").JSX.Element;
+export declare function Stamp({ pictures, tone, name, words, bare, tilt, onClick, arrive, onArrived, className, onAnimationEnd, ...rest }: StampProps): import("react").JSX.Element;
 export interface StampPlaceProps extends Omit<ComponentProps<'span'>, 'onClick'> {
     /** a gap nobody is asked to fill: a paler edge (an album's free places) */
     faint?: boolean;

package/dist/stamp/Stamp.js

@@ -1,16 +1,21 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cx } from '../cx.js';
 import { pressable } from '../pressable.js';
+import { useStrike } from './useStrike.js';
 /**
  * Stamp — a perforated paper stamp, 4:5: the pictures fill the inner frame on a tone, the words sit on the picture's foot.
  * Every stamp is ONE size wherever it stands (`--stamp-size`, two taps wide: 96 × 120) — what holds it only places it; a holder narrower than that shows it whole, smaller.
  * The one small stamp is a stamp stuck on something (`StampOn`). Every inner length follows the stamp's width.
  * The outer box holds the size and the shadow; the paper inside is the one whose edge is punched (a mask would cut the shadow too).
+ * With `arrive` the stamp that stands in its place (the head of a card, `end={<Stamp arrive …/>}`) is struck onto it when the member sends, and `onArrived` tells
+ * the app it has landed, so it sends. The strike scales it down from twice its size, so it never moves the layout (it may cover its neighbours for a moment);
+ * a `tilt` is kept, the stamp ends at its turn. Afterwards the same stamp stands in the same place with no strike: drop `arrive` or keep it, nothing is struck twice.
  */
-export function Stamp({ pictures, tone = 'custard', name, words, bare, tilt, onClick, className, ...rest }) {
+export function Stamp({ pictures, tone = 'custard', name, words, bare, tilt, onClick, arrive, onArrived, className, onAnimationEnd, ...rest }) {
     const shown = pictures.slice(0, 4);
+    const { struck } = useStrike(arrive, onArrived, onAnimationEnd);
     const { tap, Box, boxProps } = pressable(onClick, 'span', rest);
-    return (_jsx(Box, { className: cx('stamp', `stamp--${shown.length}`, bare && 'stamp--bare', tilt && `stamp--tilt-${tilt}`, tap && 'stamp--tap', className), ...boxProps, children: _jsx("span", { className: "stamp__paper", children: _jsxs("span", { className: cx('stamp__pic', `sticky--${tone}`), children: [shown.map((picture, i) => _jsx("span", { className: "stamp__art", "aria-hidden": "true", children: picture }, i)), (name != null || words != null) && (_jsxs("span", { className: "stamp__cap", children: [words != null && _jsx("span", { className: "stamp__words", children: words }), name != null && _jsx("span", { className: "stamp__name", children: name })] }))] }) }) }));
+    return (_jsx(Box, { className: cx('stamp', `stamp--${shown.length}`, bare && 'stamp--bare', tilt && `stamp--tilt-${tilt}`, tap && 'stamp--tap', arrive && 'stamp--arrive', className), onAnimationEnd: struck, ...boxProps, children: _jsx("span", { className: "stamp__paper", children: _jsxs("span", { className: cx('stamp__pic', `sticky--${tone}`), children: [shown.map((picture, i) => _jsx("span", { className: "stamp__art", "aria-hidden": "true", children: picture }, i)), (name != null || words != null) && (_jsxs("span", { className: "stamp__cap", children: [words != null && _jsx("span", { className: "stamp__words", children: words }), name != null && _jsx("span", { className: "stamp__name", children: name })] }))] }) }) }));
 }
 /**
  * StampPlace — an empty place for a stamp: a 4:5 frame of round dots the size a Stamp is (`--stamp-size`), a word or an Icon inside.

package/dist/stamp/StampOn.d.ts

@@ -24,7 +24,7 @@ export interface StampOnProps extends ComponentProps<'div'> {
     /** the stamp at the stamp's MAIN size, 96 × 120 (`--stamp-size`), to cover what it lies on; the default is the small size, 48 × 60 (`--stamp-sm-size`), which leaves a note's words readable */
     main?: boolean;
     /** the stamp sticks ITSELF: as it comes onto the screen it is struck onto its place (shown large, pressed down to its size). Nobody
-     *  picked it or pressed to stick it — the app shows it when its own move (send) begins. With `onArrived` */
+     *  picked it or pressed to stick it — the app shows it when its own move (send) begins. With `onArrived`. A stamp that already stands in a card's head or a centre, where the layout put it, is `Stamp arrive` instead */
     arrive?: boolean;
     /** an arriving stamp has LANDED (its strike ended; at once where motion is off) — the app does what follows: sends, closes */
     onArrived?: () => void;

package/dist/stamp/StampOn.js

@@ -1,10 +1,11 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useContext, useEffect, useRef, useState } from 'react';
 import { cx } from '../cx.js';
-import { reducedMotion, useControlled } from '../state.js';
+import { useControlled } from '../state.js';
 import { Icon } from '../type/Icon.js';
 import { word } from '../words.js';
 import { UnderNotes } from './underNotes.js';
+import { useStrike } from './useStrike.js';
 const MIDDLE = { x: 0.5, y: 0.5 };
 const STEP = 0.02; // an arrow key's move: a share of the surface
 const MOVES = { ArrowLeft: [-STEP, 0], ArrowRight: [STEP, 0], ArrowUp: [0, -STEP], ArrowDown: [0, STEP] };
@@ -18,7 +19,6 @@ function within(el, x, y) {
     const mx = el.offsetWidth / 2 / box.clientWidth, my = el.offsetHeight / 2 / box.clientHeight;
     return { x: round(clamp(x, mx, 1 - mx)), y: round(clamp(y, my, 1 - my)) };
 }
-const STRIKE = 'strike'; // css/tokens.css — the strike every mark struck onto paper reads
 const write = (el, at) => { el.style.setProperty('--stamp-on-x', String(at.x)); el.style.setProperty('--stamp-on-y', String(at.y)); };
 /**
  * StampOn — a Stamp (the child) stuck on a surface at the place the member chose. The surface is the nearest positioned box:
@@ -46,7 +46,7 @@ export function StampOn({ at, defaultAt = MIDDLE, turn = 0, onAtChange, label, o
     const grip = useRef(null);
     const timer = useRef(undefined);
     const moves = onAtChange != null && !under;
-    const [arrived, setArrived] = useState(false);
+    const { arrived, struck } = useStrike(arrive, onArrived, onAnimationEnd);
     const removes = onRemove != null && !under && !(arrive && !arrived);
     const ask = (next) => { if (next.x !== shown.x || next.y !== shown.y)
         request(next); };
@@ -115,20 +115,6 @@ export function StampOn({ at, defaultAt = MIDDLE, turn = 0, onAtChange, label, o
         if (!moves)
             show();
     };
-    const landed = useRef(onArrived);
-    landed.current = onArrived;
-    const land = () => { setArrived(true); landed.current?.(); };
-    useEffect(() => { if (!arrive)
-        setArrived(false);
-    else if (reducedMotion()) {
-        setArrived(true);
-        landed.current?.();
-    } }, [arrive]); // no strike to wait for
-    const struck = (e) => {
-        onAnimationEnd?.(e);
-        if (arrive && e.target === e.currentTarget && e.animationName === STRIKE)
-            land();
-    };
     const place = { '--stamp-on-x': shown.x, '--stamp-on-y': shown.y, '--stamp-on-turn': turn, ...style };
     const own = moves || removes ? { tabIndex: 0, role: 'group', 'aria-label': label, onKeyDown: key } : null;
     const drag = moves ? { onPointerDown: down, onPointerMove: move, onPointerUp: up, onPointerCancel: up } : null;

package/dist/stamp/useStrike.d.ts

@@ -0,0 +1,7 @@
+import { type AnimationEvent } from 'react';
+/** a holder that `arrive`s: has its strike ended? Returns `arrived` (false again once `arrive` turns off) and `struck`, the holder's `onAnimationEnd`
+ *  (it calls `onAnimationEnd` first). `onArrived` comes once per arrival: when the strike ends, at once where motion is off */
+export declare function useStrike<E extends Element>(arrive: boolean | undefined, onArrived: (() => void) | undefined, onAnimationEnd?: (e: AnimationEvent<E>) => void): {
+    arrived: boolean;
+    struck: (e: AnimationEvent<E>) => void;
+};

package/dist/stamp/useStrike.js

@@ -0,0 +1,20 @@
+import { useEffect, useState } from 'react';
+import { reducedMotion, useLatest } from '../state.js';
+const STRIKE = 'strike'; // css/tokens.css — the strike every mark struck onto paper reads
+/** a holder that `arrive`s: has its strike ended? Returns `arrived` (false again once `arrive` turns off) and `struck`, the holder's `onAnimationEnd`
+ *  (it calls `onAnimationEnd` first). `onArrived` comes once per arrival: when the strike ends, at once where motion is off */
+export function useStrike(arrive, onArrived, onAnimationEnd) {
+    const told = useLatest(onArrived);
+    const [arrived, setArrived] = useState(false);
+    const land = () => { setArrived(true); told.current?.(); };
+    useEffect(() => { if (!arrive)
+        setArrived(false);
+    else if (reducedMotion())
+        land(); }, [arrive]); // no strike to wait for
+    const struck = (e) => {
+        onAnimationEnd?.(e);
+        if (arrive && e.target === e.currentTarget && e.animationName === STRIKE)
+            land();
+    };
+    return { arrived, struck };
+}

package/lint/rules.mjs

@@ -209,5 +209,12 @@ export function checkSource(source, file, { classes = carddsClasses() } = {}) {
     }
   }
 
+  // 8 · a label presses the FIRST control inside it: a button before the row's Check takes the press meant for the row
+  for (const m of text.matchAll(/<Row\b/g)) {
+    const tag = tagAt(text, m.index);
+    if (/\sas\s*=\s*\{?\s*["']label["']/.test(tag) && /<(?:IconBtn|Btn|Link)\b/.test(tag) && !/\shtmlFor\s*=/.test(tag))
+      add('row-label-button', 'warn', m.index, '<Row as="label"> holding a button and no htmlFor: a label presses the first control inside it, so a touch on the row\'s words presses that button, not its Check. Give the Check an id and the row htmlFor={id}.');
+  }
+
   return findings.sort((a, b) => a.line - b.line);
 }

package/package.json

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