@usableapp/cardds 0.7.86 → 0.7.88

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/lists/Row.js

@@ -2,7 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cloneElement, createElement, isValidElement, useId, useLayoutEffect, useRef } from 'react';
 import { cx } from '../cx.js';
 import { Icon } from '../type/Icon.js';
-import { reducedMotion, useDisclosure } from '../state.js';
+import { reducedMotion, setRefs, 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`.
@@ -56,12 +56,5 @@ export function Rows({ heading, className, children, ref, ...rest }) {
         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] }));
+    return (_jsxs("div", { ref: setRefs(own, ref), 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/pressable.d.ts

@@ -0,0 +1,8 @@
+import type { ComponentProps } from 'react';
+/** a box that is a `<button>` when it can be pressed (`onClick` given), else `still` — the tag to render and what to spread on it:
+ *  `type="button"`, the onClick and `extra` (attributes a button alone takes, `aria-pressed`) before `rest`. `tap` says which it is */
+export declare function pressable<E extends 'span' | 'div'>(onClick: (() => void) | undefined, still: E, rest: ComponentProps<E>, extra?: ComponentProps<'button'>): {
+    tap: boolean;
+    Box: E;
+    boxProps: ComponentProps<E>;
+};

package/dist/pressable.js

@@ -0,0 +1,6 @@
+/** a box that is a `<button>` when it can be pressed (`onClick` given), else `still` — the tag to render and what to spread on it:
+ *  `type="button"`, the onClick and `extra` (attributes a button alone takes, `aria-pressed`) before `rest`. `tap` says which it is */
+export function pressable(onClick, still, rest, extra) {
+    const tap = onClick != null;
+    return { tap, Box: (tap ? 'button' : still), boxProps: (tap ? { type: 'button', onClick, ...extra, ...rest } : rest) };
+}

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/scaffold/Screen.js

@@ -1,5 +1,5 @@
 import { createElement, useEffect, useRef } from 'react';
-import { warnOnce, watchSize } from '../state.js';
+import { setRefs, warnOnce, watchSize } from '../state.js';
 import { cx } from '../cx.js';
 /**
  * Screen — the mobile screen in THREE parts: **top** and **content** (the children) in one flex column, the content down to the
@@ -39,12 +39,5 @@ export function Screen({ fill, palette, as = 'div', top, bottom, ready = true, c
         }
         return watchSize([lead], () => el.style.setProperty('--top-h', `${lead.offsetHeight}px`));
     }, [top, ready]);
-    const setRef = (node) => {
-        own.current = node;
-        if (typeof ref === 'function')
-            ref(node);
-        else if (ref)
-            ref.current = node;
-    };
-    return createElement(as, { className: cx('screen', fill && 'screen--fill', top === 'lead' && 'screen--lead', className), 'data-palette': palette, 'data-pending': ready ? undefined : '', 'aria-busy': ready ? undefined : true, ref: setRef, ...rest }, ready && top !== 'lead' ? top : null, ready ? children : null, ready ? bottom : null);
+    return createElement(as, { className: cx('screen', fill && 'screen--fill', top === 'lead' && 'screen--lead', className), 'data-palette': palette, 'data-pending': ready ? undefined : '', 'aria-busy': ready ? undefined : true, ref: setRefs(own, ref), ...rest }, ready && top !== 'lead' ? top : null, ready ? children : null, ready ? bottom : null);
 }

package/dist/sheets/StackSheet.js

@@ -12,6 +12,7 @@ import { Text } from '../type/Text.js';
 import { Icon } from '../type/Icon.js';
 import { Badge } from '../numbers/Badge.js';
 import { word } from '../words.js';
+import { runOver } from './sheetMeasure.js';
 /**
  * StackSheet — ONE sheet of a `SheetStack`, in the one sheet shape: SHEET HEAD (back · title · tabs or an icon) pinned at the top ·
  * SHEET BODY (the children; scrolls) · SHEET FOOT (`foot`, the CTA) at the bottom. Its tabs are icon buttons. The chosen one is filled
@@ -22,19 +23,14 @@ import { word } from '../words.js';
 export function StackSheet({ title, tone, paper, icon, tabs, tab: tabProp, defaultTab, onTabChange, foot, backLabel = word('back'), backAt = 'none', stack, className, children, ...rest }) {
     const [tab, pick] = useControlled(tabProp, defaultTab ?? tabs?.[0]?.id, onTabChange);
     // a title longer than its room does not wrap: it runs sideways, like a song title in a short slot — the room it overflows by
-    // is measured here (the tabs may grow with the text size) and handed to the CSS as --_over
+    // is measured here (the tabs may grow with the text size) and handed to the CSS as --_over / --_run, the Sheet's measurer
     const titleRef = useRef(null);
     const [long, setLong] = useState(false);
     useEffect(() => {
         const h = titleRef.current, run = h?.firstElementChild;
         if (!h || !run)
             return;
-        const measure = () => {
-            const over = Math.max(0, Math.ceil(run.scrollWidth - h.clientWidth));
-            h.style.setProperty('--_over', `${over}px`);
-            h.style.setProperty('--_run', `${(over / 30 + 3).toFixed(1)}s`);
-            setLong(over > 0);
-        };
+        const measure = () => setLong(runOver(h, run));
         measure();
         return watchSize([h, run], measure);
     }, [title]);

package/dist/sheets/sheetMeasure.d.ts

@@ -5,6 +5,7 @@ type SheetRef = RefObject<HTMLElement | null>;
 export declare const slid: (el: HTMLElement) => number;
 export declare const stopsOf: (el: HTMLElement) => Record<Resting, number>;
 export declare function usePeekStrip(ref: SheetRef): void;
+export declare function runOver(line: HTMLElement, words?: Node): boolean;
 export declare function useTitleRun(ref: SheetRef, onLong: (long: boolean) => void): void;
 export declare function useFootRoom(ref: SheetRef): void;
 export {};

package/dist/sheets/sheetMeasure.js

@@ -38,9 +38,19 @@ export function usePeekStrip(ref) {
         return () => { stop(); box.style.removeProperty('--sheet-peek'); };
     }, []);
 }
-/* the TITLE is one line; too long for it, it runs sideways like a song title (Lh 2026-10-03): the sheet measures how far its
-   words overflow the line and hands the widths to the CSS (--_over, --_run). The heading renders `.is-long` from what this
-   reports. Measured on the words themselves (a range), so the running indent never feeds back into the number. */
+/* a TITLE is one line; too long for it, it runs sideways like a song title (Lh 2026-09-24 for the StackSheet, 2026-10-03 for the Sheet):
+   how far its `words` overflow the `line` they stand on, published on the line for the CSS — `--_over` (px) and `--_run` (30px a
+   second plus the pauses). Measured on the words themselves (a range), so the running indent or translate never feeds back into
+   the number. Returns whether it is long; the heading renders `.is-long` from that. */
+export function runOver(line, words = line) {
+    const range = document.createRange();
+    range.selectNodeContents(words);
+    const over = Math.max(0, Math.ceil(range.getBoundingClientRect().width - line.clientWidth));
+    line.style.setProperty('--_over', `${over}px`);
+    line.style.setProperty('--_run', `${(over / 30 + 3).toFixed(1)}s`);
+    return over > 0;
+}
+/* the Sheet's title: the app's own heading, measured whole (sheet.css runs it with text-indent) */
 export function useTitleRun(ref, onLong) {
     useEffect(() => {
         const el = ref.current, title = el?.querySelector(':scope > .card__head > :is(h1, h2, h3):first-child, :scope > .sheet__head .sheet__title');
@@ -48,12 +58,7 @@ export function useTitleRun(ref, onLong) {
             return;
         let was = false;
         const measure = () => {
-            const words = document.createRange();
-            words.selectNodeContents(title);
-            const over = Math.max(0, Math.ceil(words.getBoundingClientRect().width - title.clientWidth));
-            title.style.setProperty('--_over', `${over}px`);
-            title.style.setProperty('--_run', `${(over / 30 + 3).toFixed(1)}s`);
-            const long = over > 0;
+            const long = runOver(title);
             if (long !== was) {
                 was = long;
                 onLong(long);

package/dist/sheets/stackCard.js

@@ -46,6 +46,31 @@ const pullsHead = (target, head) => {
         return false;
     return target === head || !!target.closest('.sheet-stack__back') || !!target.closest('.card__head > :is(h1, h2, h3)');
 };
+/* once a finger is down the DOCUMENT hears it, not the head or the body it started on: the finger leaves them while it drags.
+   One set of move / up / cancel at a time; `stop` takes the set off, and is safe to call with none on */
+const docPointer = () => {
+    let stop = () => { };
+    return {
+        listen: (move, up, cancel) => {
+            stop();
+            document.addEventListener('pointermove', move, { passive: false });
+            document.addEventListener('pointerup', up);
+            document.addEventListener('pointercancel', cancel);
+            stop = () => {
+                document.removeEventListener('pointermove', move);
+                document.removeEventListener('pointerup', up);
+                document.removeEventListener('pointercancel', cancel);
+                stop = () => { };
+            };
+        },
+        stop: () => stop(),
+    };
+};
+/* a pull that moved ends in a click the browser still fires: the card swallows it for one frame */
+const armSwallow = (swallow) => {
+    swallow.current = true;
+    requestAnimationFrame(() => { swallow.current = false; });
+};
 /**
  * The card's own pull, refresh and focus. Listeners sit on this card's head and body.
  * `--_pull` / `--_lift` are written while a finger is down, the same way a single Sheet writes `--_drag`.
@@ -86,24 +111,8 @@ export function useStackCard(ref, place, swallow) {
         const stack = card.closest('.sheet-stack');
         const head = card.querySelector(':scope > .card__head');
         const scroller = card.querySelector(':scope > .sheet__body') ?? card;
-        let stopDoc = () => { };
-        const listen = (move, up, cancel) => {
-            stopDoc();
-            document.addEventListener('pointermove', move, { passive: false });
-            document.addEventListener('pointerup', up);
-            document.addEventListener('pointercancel', cancel);
-            stopDoc = () => {
-                document.removeEventListener('pointermove', move);
-                document.removeEventListener('pointerup', up);
-                document.removeEventListener('pointercancel', cancel);
-                stopDoc = () => { };
-            };
-        };
+        const doc = docPointer();
         const primary = (e) => e.isPrimary && e.button === 0;
-        const armSwallow = () => {
-            swallow.current = true;
-            requestAnimationFrame(() => { swallow.current = false; });
-        };
         const release = (prop) => {
             live.current = null;
             card.classList.remove('is-dragging');
@@ -144,7 +153,7 @@ export function useStackCard(ref, place, swallow) {
                 const dy = Math.max(pull.last, along('down', pull.startY, ev.clientY));
                 const moved = pull.moved || dy >= pull.slop;
                 headPull.current = null;
-                stopDoc();
+                doc.stop();
                 if (moved && dy >= pull.commit) {
                     card.classList.remove('is-dragging');
                     readFrame(card);
@@ -156,16 +165,16 @@ export function useStackCard(ref, place, swallow) {
                 else
                     release('--_pull');
                 if (moved)
-                    armSwallow();
+                    armSwallow(swallow);
             };
             const onCancel = (ev) => {
                 if (ev.pointerId !== pull.pointerId || headPull.current !== pull)
                     return;
                 headPull.current = null;
-                stopDoc();
+                doc.stop();
                 release('--_pull');
             };
-            listen(onMove, onUp, onCancel);
+            doc.listen(onMove, onUp, onCancel);
         };
         const onBodyDown = (e) => {
             const ask = placeRef.current;
@@ -220,22 +229,22 @@ export function useStackCard(ref, place, swallow) {
                 const dy = Math.max(pull.lastDy, Math.max(0, ev.clientY - pull.startY));
                 const go = pull.moved && !pull.drop && scroller.scrollTop <= 0 && dy >= pull.commit;
                 bodyPull.current = null;
-                stopDoc();
+                doc.stop();
                 readFrame(scroller);
                 finish();
                 if (go)
                     placeRef.current?.onRefresh?.();
                 if (pull.moved)
-                    armSwallow();
+                    armSwallow(swallow);
             };
             const onCancel = (ev) => {
                 if (ev.pointerId !== pull.pointerId || bodyPull.current !== pull)
                     return;
                 bodyPull.current = null;
-                stopDoc();
+                doc.stop();
                 finish();
             };
-            listen(onMove, onUp, onCancel);
+            doc.listen(onMove, onUp, onCancel);
         };
         /* a finger: the browser takes a touch for its own scroll at the first move unless that move is refused here */
         let touch = null;
@@ -264,7 +273,7 @@ export function useStackCard(ref, place, swallow) {
         return () => {
             scroller.removeEventListener('touchstart', onTouchStart);
             scroller.removeEventListener('touchmove', onTouchMove);
-            stopDoc();
+            doc.stop();
             headPull.current = null;
             bodyPull.current = null;
             scroller.style.removeProperty('--_refresh');
@@ -285,23 +294,7 @@ export function useStackCard(ref, place, swallow) {
         const head = card.querySelector(':scope > .card__head');
         if (!head || !stack)
             return;
-        let stopDoc = () => { };
-        const listen = (move, up, cancel) => {
-            stopDoc();
-            document.addEventListener('pointermove', move, { passive: false });
-            document.addEventListener('pointerup', up);
-            document.addEventListener('pointercancel', cancel);
-            stopDoc = () => {
-                document.removeEventListener('pointermove', move);
-                document.removeEventListener('pointerup', up);
-                document.removeEventListener('pointercancel', cancel);
-                stopDoc = () => { };
-            };
-        };
-        const armSwallow = () => {
-            swallow.current = true;
-            requestAnimationFrame(() => { swallow.current = false; });
-        };
+        const doc = docPointer();
         const release = () => {
             live.current = null;
             card.classList.remove('is-dragging');
@@ -365,7 +358,7 @@ export function useStackCard(ref, place, swallow) {
                 const upPx = Math.max(pull.last, along('up', pull.startY, ev.clientY));
                 const moved = pull.moved || upPx >= pull.slop;
                 headPull.current = null;
-                stopDoc();
+                doc.stop();
                 if (moved && upPx >= pull.commit) {
                     card.classList.remove('is-dragging');
                     readFrame(card);
@@ -377,20 +370,20 @@ export function useStackCard(ref, place, swallow) {
                 else
                     release();
                 if (moved)
-                    armSwallow();
+                    armSwallow(swallow);
             };
             const onCancel = (ev) => {
                 if (ev.pointerId !== pull.pointerId || headPull.current !== pull)
                     return;
                 headPull.current = null;
-                stopDoc();
+                doc.stop();
                 release();
             };
-            listen(onMove, onUp, onCancel);
+            doc.listen(onMove, onUp, onCancel);
         };
         head.addEventListener('pointerdown', onDown);
         return () => {
-            stopDoc();
+            doc.stop();
             headPull.current = null;
             if (live.current?.prop === '--_lift')
                 release();

package/dist/stamp/Stamp.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cx } from '../cx.js';
+import { pressable } from '../pressable.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.
@@ -8,9 +9,7 @@ import { cx } from '../cx.js';
  */
 export function Stamp({ pictures, tone = 'custard', name, words, bare, tilt, onClick, className, ...rest }) {
     const shown = pictures.slice(0, 4);
-    const tap = onClick != null;
-    const Box = (tap ? 'button' : 'span');
-    const boxProps = (tap ? { type: 'button', onClick, ...rest } : rest);
+    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 })] }))] }) }) }));
 }
 /**
@@ -19,8 +18,6 @@ export function Stamp({ pictures, tone = 'custard', name, words, bare, tilt, onC
  * and a `--stamp-place-dash` above 0 stretches each dot into a dash.
  */
 export function StampPlace({ faint, onClick, className, children, ...rest }) {
-    const tap = onClick != null;
-    const Box = (tap ? 'button' : 'span');
-    const boxProps = (tap ? { type: 'button', onClick, ...rest } : rest);
+    const { Box, boxProps } = pressable(onClick, 'span', rest);
     return (_jsxs(Box, { className: cx('stamp-place', faint && 'stamp-place--faint', className), ...boxProps, children: [_jsx("svg", { className: "stamp-place__edge", "aria-hidden": "true", focusable: "false", children: _jsx("rect", {}) }), children] }));
 }

package/dist/stamp/StampBook.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Children } from 'react';
 import { cx } from '../cx.js';
+import { pressable } from '../pressable.js';
 import { Icon } from '../type/Icon.js';
 import { StampPlace } from './Stamp.js';
 /** StampBook — the album page: StampCells three across on an album ground, the free places drawn empty up to `places`. The book places its stamps and never sizes them: each is the one size of a stamp, in the middle of its third. */
@@ -10,8 +11,6 @@ export function StampBook({ places = 0, strip, bare, className, children, ...res
 }
 /** StampCell — one place of a StampBook: a Stamp (the child) and a short label under it. */
 export function StampCell({ label, onClick, on, className, children, ...rest }) {
-    const tap = onClick != null;
-    const Box = (tap ? 'button' : 'span');
-    const boxProps = (tap ? { type: 'button', onClick, 'aria-pressed': on, ...rest } : rest);
+    const { Box, boxProps } = pressable(onClick, 'span', rest, { 'aria-pressed': on });
     return (_jsxs(Box, { className: cx('stamp-cell', className), ...boxProps, children: [children, label != null && _jsx("span", { className: "stamp-cell__label", children: label }), on && _jsx("span", { className: "stamp-cell__on", "aria-hidden": "true", children: _jsx(Icon, { name: "check" }) })] }));
 }

package/dist/stamp/StampOn.js

@@ -18,7 +18,7 @@ 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 = 'stamp-on-strike'; // css/stamp.css
+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:

package/dist/state.d.ts

@@ -1,4 +1,4 @@
-import { type SyntheticEvent } from 'react';
+import { type Ref, type SyntheticEvent } from 'react';
 /** controlled like an input: `value` given = the app owns it; undefined = the component keeps its own, starting at `initial`.
  *  Returns the value shown and `request(next, …extra)`: nothing when `next` is what shows; else it moves the component's own copy
  *  (uncontrolled only) and ASKS the app — `onChange(next, …extra)`. `request` keeps one identity for the component's life. */
@@ -12,6 +12,10 @@ export declare function useDisclosure(open: boolean | undefined, defaultOpen?: b
     open: boolean;
     onToggle: (e: SyntheticEvent<HTMLDetailsElement>) => void;
 };
+/** the node to the component's own ref AND the caller's `ref` (a function or an object: React 19 passes it as a prop). Give the result to the element's `ref` */
+export declare const setRefs: <T extends Element>(own: {
+    current: Element | null;
+}, ref: Ref<T> | undefined) => (node: T | null) => void;
 /** the latest value in a ref — for a handler that a timer, an observer or a listener set up once calls later */
 export declare function useLatest<T>(value: T): import("react").RefObject<T>;
 /** watch boxes for a size change (the keyboard, a font arriving, a wrap): `fn` on each — once at the start too, as the browser

package/dist/state.js

@@ -30,6 +30,14 @@ export function useDisclosure(open, defaultOpen = false, onOpenChange) {
         },
     };
 }
+/** the node to the component's own ref AND the caller's `ref` (a function or an object: React 19 passes it as a prop). Give the result to the element's `ref` */
+export const setRefs = (own, ref) => (node) => {
+    own.current = node;
+    if (typeof ref === 'function')
+        ref(node);
+    else if (ref)
+        ref.current = node;
+};
 /** the latest value in a ref — for a handler that a timer, an observer or a listener set up once calls later */
 export function useLatest(value) {
     const ref = useRef(value);

package/dist/sticky/Sticky.js

@@ -1,5 +1,6 @@
 import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
 import { cx } from '../cx.js';
+import { pressable } from '../pressable.js';
 import { word } from '../words.js';
 /**
  * Sticky — a paper note: a flat pastel SQUARE of one size (168, the knob `--sticky-size`), square corners, a soft shadow under it.
@@ -9,9 +10,7 @@ import { word } from '../words.js';
  */
 export function Sticky({ tone = 'custard', flat, unreadLabel, head, date, tilt, foot, corner, stuck, onClick, className, children, ...rest }) {
     const notched = corner != null;
-    const tap = onClick != null && !notched;
-    const Box = (tap ? 'button' : 'div');
+    const { tap, Box, boxProps } = pressable(notched ? undefined : onClick, 'div', rest);
     const Part = tap ? 'span' : 'div';
-    const boxProps = (tap ? { type: 'button', onClick, ...rest } : rest);
     return (_jsxs(Box, { className: cx('sticky', `sticky--${tone}`, flat && 'sticky--flat', notched && 'sticky--corner', tilt && `sticky--tilt-${tilt}`, tap && 'sticky--tap', className), ...boxProps, children: [_jsxs(Part, { className: "sticky__paper", children: [(head != null || date != null) && _jsxs(Part, { className: "sticky__head", children: [head, date] }), _jsx(Part, { className: "sticky__body", children: children }), foot != null && _jsx(Part, { className: "sticky__foot", children: foot }), !flat && !notched && _jsx("span", { className: "sticky__fold", "aria-hidden": "true" }), !flat && !notched && _jsx("span", { className: "sticky__state t-sr", children: unreadLabel ?? word('unread') })] }), stuck != null && _jsx(Part, { className: "sticky__stuck", children: stuck }), notched && _jsx("div", { className: "sticky__corner", children: corner })] }));
 }

package/lib/catalog.mjs

@@ -29,8 +29,10 @@ const representsOf = ({ represents }) => represents.filter((v) => v !== '—');
 
 /** the names only — the first call of nearly every session, so it stays small. `group` is the src folder; `represents`, `shape` and `interact` say what it is for */
 export const list = (cat) => cat.components.map(({ name, group, role }) => ({ name, group, represents: representsOf(role), shape: shapeOf(role), interact: interactOf(role) }));
+/** the finishes of the paper (`data-finish`, css/finish.css): a style apart from colour, not a component — each with what it is and its knobs */
+export const finishes = (cat) => cat.finishes ?? [];
 
-const sentence = (text) => {
+export const sentence = (text) => {
   const flat = text.replace(/\s+/g, ' ').trim();
   const one = flat.match(/^.*?[.!?](?=\s|$)/)?.[0] ?? flat;
   return one.length > 160 ? `${one.slice(0, 157)}…` : one;
@@ -56,7 +58,7 @@ const closest = (names, wanted) => {
   return [...names].sort((a, b) => rank(a) - rank(b)).slice(0, 5);
 };
 
-/** one component: its props (a ReactNode prop is a slot) and its variations — the stories of its own file first, then a few that use it */
+/** one component: its props (a ReactNode prop is a slot), what it composes and what composes it, its knobs, and its variations — the stories of its own file first, then a few that use it */
 export function get(cat, name, { html = false, all = false } = {}) {
   const c = cat.components.find((x) => x.name.toLowerCase() === String(name).toLowerCase());
   if (!c) return { error: `no component "${name}"`, closest: closest(cat.components.map((x) => x.name), String(name)) };
@@ -72,6 +74,9 @@ export function get(cat, name, { html = false, all = false } = {}) {
     element: c.element,
     props: c.props.map((p) => ({ ...p, ...(isSlot(p.type) && { slot: true }) })),
     ...(c.params && { params: c.params }),
+    composes: c.composes,
+    composedBy: c.composedBy,
+    knobs: c.knobs,
     variations: [...own, ...elsewhere.filter((s) => shown.includes(s))].map(show),
     ...(elsewhere.length > shown.length && { alsoUsedIn: elsewhere.filter((s) => !shown.includes(s)).map((s) => s.id) }),
   };
@@ -82,6 +87,7 @@ const STOP = new Set(['the', 'and', 'for', 'with', 'from', 'that', 'this', 'into
 const tokens = (query) => [...new Set(words(String(query)).filter((t) => t.length > 1 && !STOP.has(t)))];
 const stem = (t) => (t.length > 3 && t.endsWith('s') ? t.slice(0, -1) : t);
 const hits = (text, token) => words(text).some((w) => w.startsWith(token) || w.startsWith(stem(token)));
+const isName = (name, token) => name.toLowerCase() === token || name.toLowerCase() === stem(token);
 
 const TOP = 8; // answers per kind; the components that match every axis are never cut
 
@@ -119,7 +125,7 @@ const matchesUnion = (roles, want) => roles.length > 0
 /** short ranked answer to "what is there for this?". `axes` ({ represents?, shape?, interact? } — what it represents, how many, what the member can do with it) are
  *  asked first: whatever matches every one of them (a component, or a screen where one component does, then a screen whose parts do between them) ranks above whatever matches only words;
  *  with axes and no words they are the whole answer. Among screens that tie on words, the one whose description says the axes comes first, then the one where a single component matches them all.
- *  Then the words: screens already drawn, then components, then what they are used with.
+ *  Then the words: screens already drawn, then components, then what they are used with — a screen that answers fewer of the words than the best component comes after the components.
  *  A query that matches nothing (another language, say) returns `fallback: true`, a hint and how many screens are drawn — not their ids:
  *  they did not help to choose; ask again in English or by the axes, or `scaffold` with no id lists them. */
 export function find(cat, query, axes = {}) {
@@ -129,11 +135,11 @@ export function find(cat, query, axes = {}) {
   const roles = new Map(cat.components.map((c) => [c.name, roleOf(c)]));
   const toks = tokens(query);
   const axisWords = [...(asked.want.represents ?? []), ...(asked.want.interact || [])]; // the axis values as words: a screen's own description may say them
-  const rank = (items, fields, level, said = () => 0) => {
+  const rank = (items, fields, level, said = () => 0) => { // a field is [text, weight, match = hits]
     const scored = items.map((item) => {
       let matched = 0, score = 0;
       for (const t of toks) {
-        const w = fields(item).filter(([text]) => hits(text, t)).reduce((sum, [, weight]) => sum + weight, 0);
+        const w = fields(item).filter(([text, , match = hits]) => match(text, t)).reduce((sum, [, weight]) => sum + weight, 0);
         if (w) { matched++; score += w; }
       }
       return { item, matched, score, level: active ? level(item) : 0, said: active ? said(item) : 0 };
@@ -152,9 +158,20 @@ export function find(cat, query, axes = {}) {
   };
   const said = (s) => axisWords.filter((v) => hits(s.description, v)).length;
   const [screenAxis, screenRest] = tier(rank(screens, (s) => [[s.id, 5], [s.description, 3], [s.uses.join(' '), 1]], level, said), TOP);
-  const components = rank(cat.components, (c) => [[c.name, 6], [c.description, 2], [c.props.map((p) => p.name).join(' '), 1]], (c) => Number(matches(roles.get(c.name), asked.want)));
+  // a component is found by its name (the name that IS the word counts as much again as one that contains it: "card" is Card before FeedCard, whatever
+  // their other words say), its description, its role's note (what it is FOR, in the words of a request: "a setting turned on or off") and what it stands in for, then its prop names
+  const components = rank(cat.components, (c) => [[c.name, 6, isName], [c.name, 6], [c.description, 2], [c.role?.note ?? '', 2], [(c.role?.standsInFor ?? []).map((s) => `${s.name} ${s.condition}`).join(' '), 1], [c.props.map((p) => p.name).join(' '), 1]], (c) => Number(matches(roles.get(c.name), asked.want)));
   const [componentAxis, componentRest] = tier(components, Math.max(TOP, components.axis.length));
-  const ranked = [...screenAxis.map(screenOf), ...componentAxis.map(componentOf), ...screenRest.map(screenOf), ...componentRest.map(componentOf)];
+  // a screen drawn comes before the components when it answers the words as well as the best component does; one that answers FEWER of them
+  // comes after (a question by intention, "a setting turned on or off", is answered by Toggle, not by eight screens that say "off" or "or")
+  const best = componentRest[0]?.matched ?? 0;
+  // a finish asked for by its name ("printed", "sticker") or by the word finish is the thing itself, so it comes before the screens that only show it;
+  // one that answers a word of its description ("card") is an aside, after the components
+  const finishOf = ({ item: f }) => ({ kind: 'finish', name: f.name, summary: sentence(f.is), knobs: f.knobs.map((k) => k.name) });
+  const named = (text, t) => t.startsWith(text) || text.startsWith(t);
+  const finishRest = rank(finishes(cat), (f) => [[f.name, 6, named], ['finish', 6], [f.is, 2], [f.knobs.map((k) => k.name).join(' '), 1]], () => 0).rest;
+  const ranked = [...screenAxis.map(screenOf), ...componentAxis.map(componentOf), ...finishRest.filter((r) => r.score >= 6).map(finishOf), ...screenRest.filter((r) => r.matched >= best).map(screenOf),
+    ...componentRest.map(componentOf), ...finishRest.filter((r) => r.score < 6).map(finishOf), ...screenRest.filter((r) => r.matched < best).map(screenOf)];
   if (!ranked.length && active && !toks.length) return { query, results: [], hint: 'no component or screen has that role: drop an axis, or add English words' };
   if (!ranked.length) return { query, fallback: true, hint: 'the names and descriptions are English: ask again in English words, or by the axes (represents · shape · interact); `scaffold` with no id lists the screens', screens: screens.length };
 

package/lib/mcp.mjs

@@ -36,19 +36,19 @@ const bool = (description) => ({ type: 'boolean', description });
 const TOOLS = [
   {
     name: 'list_components',
-    description: 'The names of every cardds component and what each is FOR, nothing else. represents is what it stands for (person, group, time…) or, for a control that stands for no one thing, the KIND of data it carries (words, number, picture, signal); the word in parentheses after a name in the text is its represents. Every component shows information; shape says how much: "one" (one thing), "group-brief" (a group read at a glance or in a line), "group-detail" (a group read in detail), "—" (a helper function or structure, not something drawn). interact says whether the member can do something with it: false (it only shows or holds), or the kinds, any of pick, act, write, navigate — alone when shape is one (a Btn acts), as a group when shape is a group (a BtnGroup picks among several). Two kinds mean it does both. group is the src folder, not what it is for. Call this once, first, in a session that will build a UI with cardds, to learn what exists; then get_component for the ones you use.',
+    description: 'The names of every cardds component and what each is FOR, nothing else. represents is what it stands for (person, group, time…) or, for a control that stands for no one thing, the KIND of data it carries (words, number, picture, signal); the word in parentheses after a name in the text is its represents. Every component shows information; shape says how much: "one" (one thing), "group-brief" (a group read at a glance or in a line), "group-detail" (a group read in detail), "—" (a helper function or structure, not something drawn). interact says whether the member can do something with it: false (it only shows or holds), or the kinds, any of pick, act, write, navigate — alone when shape is one (a Btn acts), as a group when shape is a group (a BtnGroup picks among several). Two kinds mean it does both. group is the src folder, not what it is for. Call this once, first, in a session that will build a UI with cardds, to learn what exists; then get_component for the ones you use. The finishes of the paper (data-finish on <html>: lit, print, sticker, ink — a style apart from colour, not a component) are answered by find_components ("printed paper", "finish").',
     inputSchema: { type: 'object', properties: {} },
     run: (cat) => catalog.list(cat),
   },
   {
     name: 'get_component',
-    description: 'One component in full: what it is, its props (a prop marked slot takes children: ReactNode), and its variations, each a working story with its code. Call it before you use a component you have not used yet, and copy a variation rather than guessing a prop. A component used everywhere (Btn, Text) comes with a few of its stories and the ids of the rest (pass all for their code). Names are case-insensitive; a miss returns the closest names.',
+    description: 'One component in full: what it is, its props (a prop marked slot takes children: ReactNode), what it composes and what composes it (composes · composedBy: the catalog names its source renders or calls, and the inverse), its knobs (the CSS custom properties a theme sets to retune it, each with its default, what it sets and the selector that reads it — joined by the classes the component emits, so a knob named for an old name is listed under the component that has it now), and its variations, each a working story with its code. Call it before you use a component you have not used yet, and copy a variation rather than guessing a prop. A component used everywhere (Btn, Text) comes with a few of its stories and the ids of the rest (pass all for their code). Names are case-insensitive; a miss returns the closest names.',
     inputSchema: { type: 'object', properties: { name: str('component name, e.g. Menu'), html: bool('also return each variation\'s rendered HTML — only to see the markup it makes'), all: bool('include the code of every story that uses the component') }, required: ['name'] },
     run: (cat, a) => catalog.get(cat, a.name, { html: a.html, all: a.all }),
   },
   {
     name: 'find_components',
-    description: (cat) => `Find what to build with when you do not know the component name. Ask BOTH ways and read both answers: by the AXES (translated from the request) AND by the English noun of the task ("stamp", "otp", "postcard") — the screen already drawn is often found by the noun. The axes are a closed vocabulary, so ask by them in any language: represents (what it stands for, or for a control the KIND of data it carries${cat ? `: ${catalog.vocabulary(cat).represents.join(' · ')}` : ' — the word in parentheses after a name in list_components'}), shape (one · group-brief · group-detail · group = either group shape), interact (the kinds the member can do with it: ${catalog.KINDS.join(' · ')}, or "none" = it only shows). "Show all the members" is represents [person] + shape group; adding interact [pick] narrows it to the ones the member chooses from. Whatever matches every axis you give comes first, each with its role so you see why; with axes and no words they are the whole answer. Words ("stamp", "otp pin", "bottom sheet") rank what matches only by words, in ENGLISH — the names and descriptions are English, translate first. Answers short: the screens cardds has already drawn (a screen is a composition: it counts when its parts answer the axes between them, one component per axis, and one that answers them all ranks higher), then components, then the components most often used together with them. Call it at the start of a task, before composing a screen from parts: if a screen like it exists, scaffold_screen gives its code. A query that matches nothing returns fallback: true, a hint and the number of screens drawn, not their ids: ask again in English words or by the axes, or call scaffold_screen with no id to list them.`,
+    description: (cat) => `Find what to build with when you do not know the component name. Ask BOTH ways and read both answers: by the AXES (translated from the request) AND by the English noun of the task ("stamp", "otp", "postcard") — the screen already drawn is often found by the noun. The axes are a closed vocabulary, so ask by them in any language: represents (what it stands for, or for a control the KIND of data it carries${cat ? `: ${catalog.vocabulary(cat).represents.join(' · ')}` : ' — the word in parentheses after a name in list_components'}), shape (one · group-brief · group-detail · group = either group shape), interact (the kinds the member can do with it: ${catalog.KINDS.join(' · ')}, or "none" = it only shows). "Show all the members" is represents [person] + shape group; adding interact [pick] narrows it to the ones the member chooses from. Whatever matches every axis you give comes first, each with its role so you see why; with axes and no words they are the whole answer. Words ("stamp", "otp pin", "bottom sheet") rank what matches only by words, in ENGLISH — the names and descriptions are English, translate first; a component's words include its role's note and what it stands in for, so a question by intention ("a setting turned on or off", "a code digit by digit") finds the piece. Answers short: the screens cardds has already drawn (a screen is a composition: it counts when its parts answer the axes between them, one component per axis, and one that answers them all ranks higher), then components, then the components most often used together with them; a screen that answers fewer of the words than the best component comes after the components, so a question by intention ("a setting turned on or off") names the piece first. A FINISH of the paper (data-finish on <html>, beside any palette: lit, print, sticker, ink) is answered too, kind "finish", with its knobs: ask "printed paper", "sticker", or "finish" for all four. Call it at the start of a task, before composing a screen from parts: if a screen like it exists, scaffold_screen gives its code. A query that matches nothing returns fallback: true, a hint and the number of screens drawn, not their ids: ask again in English words or by the axes, or call scaffold_screen with no id to list them.`,
     inputSchema: {
       type: 'object',
       properties: {

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.86",
+  "version": "0.7.88",
   "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.",