@usableapp/cardds 0.7.52 → 0.7.54

package/dist/cards/Card.js

@@ -1,9 +1,10 @@
-import { jsx as _jsx } from "react/jsx-runtime";
-import { Children, createElement, isValidElement } from 'react';
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Children, createElement, isValidElement, useRef } from 'react';
 import { cx } from '../cx.js';
 import { warnOnce } from '../state.js';
 import { CardHead } from './CardHead.js';
 import { CardFoot } from './CardFoot.js';
+import { StackHeadCtx, stackPaint, useStackCard } from '../sheets/stackCard.js';
 /**
  * Card — ONE boundary: head · content · foot. Cards are content the system offers (the words, the thing to read).
  * The head and the foot are SLOTS: `heading` · `caption` · `end` (the card writes its CardHead first) and `foot` · `footLink`
@@ -11,7 +12,7 @@ import { CardFoot } from './CardFoot.js';
  * boundary). The order is the card's, never the writer's. A head of its own shape: write `<CardHead>` as the first child instead.
  * A page with one feature and one CTA may be a single card. Keep everything big.
  */
-export function Card({ tone, sm, row, cover, fold, centre, band, as = 'article', heading, caption, end, level, foot, footLink, className, children, ...rest }) {
+export function Card({ tone, sm, row, cover, fold, centre, band, as = 'article', heading, caption, end, level, foot, footLink, stack, className, style, children, onClick, ref, ...rest }) {
     const head = heading != null || caption != null || end != null;
     const tail = foot != null || footLink != null;
     if (head || tail) {
@@ -21,9 +22,44 @@ export function Card({ tone, sm, row, cover, fold, centre, band, as = 'article',
         if (tail && parts.some((c) => c.type === CardFoot))
             warnOnce('card-foot-twice', 'cardds Card: `foot`/`footLink` AND a <CardFoot> child — one foot per card; use one way');
     }
-    const props = { className: cx('card', tone && tone !== 1 && `card--${tone}`, sm && 'card--sm', row && 'card--row', cover && 'card--cover', fold && 'card--fold', centre && 'card--centre', band && 'card--band', className), ...rest };
+    const own = useRef(null);
+    const swallow = useRef(false);
+    useStackCard(own, stack, swallow);
+    const painted = stackPaint(stack);
+    const setRef = (node) => {
+        own.current = node;
+        const passed = ref;
+        if (typeof passed === 'function')
+            passed(node);
+        else if (passed)
+            passed.current = node;
+    };
+    const click = (e) => {
+        onClick?.(e);
+        if (!stack || e.defaultPrevented || swallow.current)
+            return;
+        const target = e.target;
+        if (target.closest('.sheet-stack__back')) {
+            stack.onClose();
+            return;
+        }
+        if (stack.open && target.closest('.card__head > :is(h1, h2, h3)')) {
+            stack.onClose();
+            return;
+        } // the title folds it; the back stays the keyboard's way
+        if (!stack.open && !stack.before && !stack.after)
+            stack.onOpen();
+    };
+    const inner = (body) => (_jsx(StackHeadCtx.Provider, { value: stack ? (stack.before || stack.after ? -1 : 0) : null, children: body }));
+    const props = {
+        ...rest,
+        ref: setRef,
+        className: cx('card', tone && tone !== 1 && `card--${tone}`, sm && 'card--sm', row && 'card--row', cover && 'card--cover', fold && 'card--fold', centre && 'card--centre', band && 'card--band', painted.className, className),
+        style: painted.style || style ? { ...painted.style, ...style } : undefined,
+        ...(stack ? { 'aria-busy': painted.busy } : {}),
+        onClick: stack ? click : onClick,
+    };
     if (!head && !tail)
-        return createElement(as, props, children);
-    return createElement(as, props, head && _jsx(CardHead, { heading: heading, caption: caption, end: end, level: level }, "head"), ...Children.toArray(children), // keyed: the slots sit around them
-    tail && _jsx(CardFoot, { link: footLink, children: foot }, "foot"));
+        return createElement(as, props, inner(children));
+    return createElement(as, props, inner(_jsxs(_Fragment, { children: [head && _jsx(CardHead, { heading: heading, caption: caption, end: end, level: level }, "head"), Children.toArray(children), tail && _jsx(CardFoot, { link: footLink, children: foot }, "foot")] })));
 }

package/dist/cards/CardHead.d.ts

@@ -1,4 +1,4 @@
-import type { ComponentProps, ReactNode } from 'react';
+import { type ComponentProps, type ReactNode } from 'react';
 export interface CardHeadProps extends ComponentProps<'div'> {
     /** the heading (a string becomes an h2 at level `t-h2`) — wraps freely, as many lines as the words need */
     heading?: ReactNode;
@@ -11,9 +11,4 @@ export interface CardHeadProps extends ComponentProps<'div'> {
     /** the heading level to render the string heading with (h2 default; h1 for the one-feature page) */
     level?: 'h1' | 'h2' | 'display';
 }
-/**
- * CardHead — the card's head: the heading on the left takes the room, the contextual info hugs the far right.
- * Use `heading` (+ `caption`) and `end` for the standard head, or pass children for a custom one
- * (the FIRST child takes the room). Flat markup: no wrapper element, no <p> — the caption is a span on a row of its own (card.css). Never put buttons here — they go in the CardFoot.
- */
 export declare function CardHead({ heading, caption, end, top, level, className, children, ...rest }: CardHeadProps): import("react").JSX.Element;

package/dist/cards/CardHead.js

@@ -1,11 +1,36 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Children, cloneElement, isValidElement, useContext } from 'react';
 import { cx } from '../cx.js';
+import { Text } from '../type/Text.js';
+import { StackHeadCtx } from '../sheets/stackCard.js';
 /**
  * CardHead — the card's head: the heading on the left takes the room, the contextual info hugs the far right.
  * Use `heading` (+ `caption`) and `end` for the standard head, or pass children for a custom one
  * (the FIRST child takes the room). Flat markup: no wrapper element, no <p> — the caption is a span on a row of its own (card.css). Never put buttons here — they go in the CardFoot.
  */
+const onTitleKey = (e) => {
+    if (e.key !== 'Enter' && e.key !== ' ')
+        return;
+    e.preventDefault();
+    e.currentTarget.click();
+};
+/** the stack's title is the keyboard's way in. The heading renders the tab stop; nothing sets it on the node afterwards */
+function markTitle(node, tab) {
+    if (!isValidElement(node))
+        return node;
+    const el = node;
+    const level = el.type === Text ? el.props.level : null;
+    const intrinsic = typeof el.type === 'string' && /^h[1-3]$/.test(el.type);
+    if (level !== 'h1' && level !== 'h2' && level !== 'display' && !intrinsic)
+        return node;
+    return cloneElement(el, {
+        tabIndex: tab,
+        onKeyDown: (e) => { el.props.onKeyDown?.(e); if (!e.defaultPrevented)
+            onTitleKey(e); },
+    });
+}
 export function CardHead({ heading, caption, end, top, level = 'h2', className, children, ...rest }) {
+    const tab = useContext(StackHeadCtx);
     const H = level === 'h1' ? 'h1' : 'h2';
-    return (_jsxs("div", { className: cx('card__head', top && 'card__head--top', className), ...rest, children: [heading != null && _jsx(H, { className: `t-${level}`, children: heading }), caption != null && _jsx("span", { className: "t-caption t-muted", children: caption }), children, end] }));
+    return (_jsxs("div", { className: cx('card__head', top && 'card__head--top', className), ...rest, children: [heading != null && _jsx(H, { className: `t-${level}`, tabIndex: tab ?? undefined, onKeyDown: tab != null ? onTitleKey : undefined, children: heading }), caption != null && _jsx("span", { className: "t-caption t-muted", children: caption }), tab == null ? children : Children.map(children, (c) => markTitle(c, tab)), end] }));
 }

package/dist/choice/Slider.js

@@ -1,18 +1,14 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useRef } from 'react';
+import { useState } from 'react';
 import { cx } from '../cx.js';
+import { useStepCursor } from '../sheets/stepCursor.js';
+const share = (value, min, max) => (max > min ? Math.min(1, Math.max(0, (value - min) / (max - min))) : 0);
 /** Slider — one value along a hairline rail with a 48px knob; the whole range is thumb-tall. */
 export function Slider({ label, glyph, className, style, onInput, ...input }) {
-    const range = useRef(null);
-    const box = useRef(null);
-    // the knob's place along the rail, 0..1, published on the slider as --slider-at so the glyph can ride the knob (choice.css)
-    const place = () => {
-        const r = range.current;
-        if (!r || !box.current)
-            return;
-        const min = Number(r.min) || 0, max = Number(r.max) || 100;
-        box.current.style.setProperty('--slider-at', String(max > min ? Math.min(1, Math.max(0, (Number(r.value) - min) / (max - min))) : 0));
-    };
-    useEffect(place); // after every render: a controlled value, a new min / max
-    return (_jsxs("label", { ref: box, className: cx('slider', className), style: style, children: [label != null && _jsx("span", { className: "slider__label", children: label }), glyph != null && _jsx("span", { className: "slider__glyph", "aria-hidden": "true", children: glyph }), _jsx("input", { ref: range, className: "slider__range", type: "range", onInput: (e) => { place(); onInput?.(e); }, ...input })] }));
+    const cursor = useStepCursor();
+    const min = Number(input.min) || 0, max = Number(input.max) || 100;
+    const [live, setLive] = useState(Number(input.defaultValue ?? input.value ?? min));
+    const value = input.value != null && input.value !== '' ? Number(input.value) : live;
+    return (_jsxs("label", { className: cx('slider', className), style: { ...style, '--slider-at': String(share(value, min, max)) }, children: [label != null && _jsx("span", { className: "slider__label", children: label }), glyph != null && _jsx("span", { className: "slider__glyph", "aria-hidden": "true", children: glyph }), _jsx("input", { className: "slider__range", type: "range", onInput: (e) => { if (input.value == null)
+                    setLive(Number(e.currentTarget.value)); onInput?.(e); }, ...input, ...cursor })] }));
 }

package/dist/forms/Composer.js

@@ -1,6 +1,8 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cx } from '../cx.js';
+import { useStepCursor } from '../sheets/stepCursor.js';
 /** Composer — a big write-in area (display type) with a bottom bar: icon · hint · send. The write-in step's sheet content. */
 export function Composer({ hint, lead, send, className, style, ...textarea }) {
-    return (_jsxs("div", { className: cx('composer', className), style: style, children: [_jsx("textarea", { className: "composer__input", ...textarea }), _jsxs("div", { className: "composer__bar", children: [lead, hint != null && _jsx("span", { className: "composer__hint", children: hint }), send] })] }));
+    const cursor = useStepCursor();
+    return (_jsxs("div", { className: cx('composer', className), style: style, children: [_jsx("textarea", { className: "composer__input", ...textarea, ...cursor }), _jsxs("div", { className: "composer__bar", children: [lead, hint != null && _jsx("span", { className: "composer__hint", children: hint }), send] })] }));
 }

package/dist/forms/Field.js

@@ -4,6 +4,7 @@ import { watchSize } from '../state.js';
 import { formatOk, useCheck } from './check.js';
 import { cx } from '../cx.js';
 import { Icon } from '../type/Icon.js';
+import { useStepCursor } from '../sheets/stepCursor.js';
 /** the digits of `v`, written into `mask`; a mark is written only when a digit comes after it */
 export function applyMask(v, mask) {
     const d = v.replace(/\D/g, '');
@@ -36,6 +37,7 @@ export function Field({ icon, action, label, error, format, digits, formatError,
     };
     const { say } = useCheck((strict) => { const w = verdict(strict); if (w != null)
         setBad(true); return w; }, () => { ref.current?.focus(); ref.current?.select(); });
+    const cursor = useStepCursor();
     /* a placeholder longer than the box SHRINKS to show whole (Lh 2026-09-25): its width is measured in the input's own font,
        and `--_ph-fit` (the share that fits, ≤ 1) scales the placeholder's size — again whenever the box or the font changes */
     useLayoutEffect(() => {
@@ -70,7 +72,7 @@ export function Field({ icon, action, label, error, format, digits, formatError,
         }
         // eslint-disable-next-line react-hooks/exhaustive-deps -- when the app's error comes or changes
     }, [error]);
-    return (_jsxs("label", { className: cx('field', action != null && 'field--action', wrong && 'field--error', className), style: style, children: [icon && _jsx(Icon, { name: icon, size: "sm" }), _jsx("input", { ref: ref, "aria-label": label, "aria-invalid": wrong || undefined, ...input, onBlur: (e) => { onBlur?.(e); if (!checked)
+    return (_jsxs("label", { className: cx('field', action != null && 'field--action', wrong && 'field--error', className), style: style, children: [icon && _jsx(Icon, { name: icon, size: "sm" }), _jsx("input", { ref: ref, "aria-label": label, "aria-invalid": wrong || undefined, ...input, ...cursor, onBlur: (e) => { onBlur?.(e); if (!checked)
                     return; const w = verdict(false); setBad(w != null); say(w); }, onChange: (e) => {
                     if (mask) {
                         const el = e.currentTarget, before = el.value.slice(0, el.selectionStart ?? el.value.length).replace(/\D/g, '').length;

package/dist/forms/FileBtn.js

@@ -1,10 +1,12 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cx } from '../cx.js';
+import { useStepCursor } from '../sheets/stepCursor.js';
 /**
  * FileBtn — a Btn that opens the device's file picker: the button IS the label of a hidden file input, so the
  * whole button is the tap target and nothing is forwarded by script. `accept="image/*" capture="environment"`
  * opens the camera; without `capture` the gallery. The picked file arrives in `onChange` like any input.
  */
 export function FileBtn({ primary, quiet, block, className, children, ...input }) {
-    return (_jsxs("label", { className: cx('btn', primary && 'btn--primary', quiet && 'btn--quiet', block && 'btn--block', className), children: [_jsx("input", { type: "file", className: "t-sr", ...input }), children] }));
+    const cursor = useStepCursor();
+    return (_jsxs("label", { className: cx('btn', primary && 'btn--primary', quiet && 'btn--quiet', block && 'btn--block', className), children: [_jsx("input", { type: "file", className: "t-sr", ...input, ...cursor }), children] }));
 }

package/dist/forms/Pin.js

@@ -4,6 +4,7 @@ import { useControlled, useLatest } from '../state.js';
 import { cx } from '../cx.js';
 import { useCheck } from './check.js';
 import { word } from '../words.js';
+import { useStepCursor } from '../sheets/stepCursor.js';
 const RESET_MS = 900; // a code that does not match: red + shake this long, then the cells empty for a new try
 /**
  * Pin — big code entry, one digit per pill; a filled cell turns accent. Lives in a Sheet.
@@ -13,6 +14,7 @@ const RESET_MS = 900; // a code that does not match: red + shake this long, then
  */
 export function Pin({ length = 6, value, defaultValue = '', label = word('digit'), onChange, autoFocus, error, match, formatError, secret, className, onAnimationEnd, ...rest }) {
     const ref = useRef(null);
+    const cursor = useStepCursor();
     const [typed, request] = useControlled(value, defaultValue, onChange);
     const code = typed.replace(/\D/g, '').slice(0, length);
     const cell = (i) => ref.current?.querySelectorAll('.pin__cell')[i];
@@ -171,7 +173,7 @@ export function Pin({ length = 6, value, defaultValue = '', label = word('digit'
             setFresh(null); onAnimationEnd?.(e); }, children: Array.from({ length }, (_, i) => (
         // no maxLength: the browser would cut a pasted code before this ever saw it. A cell holds one digit — typing into a full one
         // replaces it, so its digit is selected whenever the cell takes the focus
-        _jsx("input", { className: cx('pin__cell', secret && fresh === i && 'is-fresh'), inputMode: "numeric", pattern: "[0-9]*", placeholder: " ", value: code[i] ?? '', "aria-label": `${label} ${i + 1}`, "aria-invalid": wrong || undefined, autoComplete: i === 0 && !secret ? 'one-time-code' : 'off', onChange: input(i), onPaste: paste, onKeyDown: key(i), onFocus: (e) => {
+        _jsx("input", { className: cx('pin__cell', secret && fresh === i && 'is-fresh'), inputMode: "numeric", pattern: "[0-9]*", placeholder: " ", value: code[i] ?? '', "aria-label": `${label} ${i + 1}`, "aria-invalid": wrong || undefined, ...(i === 0 ? cursor : undefined), autoComplete: i === 0 && !secret ? 'one-time-code' : 'off', onChange: input(i), onPaste: paste, onKeyDown: key(i), onFocus: (e) => {
                 if (!restart.current)
                     e.currentTarget.select();
                 if (performance.now() - tapped.current > 700 && window.matchMedia('(pointer: coarse)').matches && !keyboardUp())

package/dist/sheets/Sheet.d.ts

@@ -21,6 +21,12 @@ export interface SheetProps extends Omit<ComponentProps<'article'>, 'onChange'>
     states?: string | readonly Resting[];
     /** the grab handle; `false` for a sheet with no handle, a string sets its accessible name */
     handle?: boolean | string;
+    /** the grab mark. `line` (default) or `dots`: both sit in the card's top padding, the same distance from the edge, so the title does not move */
+    mark?: 'line' | 'dots';
+    /** the card tone slot, as `Card tone` — 2 and up add `card--N`. The head shows it; with `paper` the content does not */
+    tone?: 1 | 2 | 3 | 4 | 5;
+    /** the content is white paper and the head keeps the sheet's colour. Omit it and the content is the same colour as the head */
+    paper?: boolean;
 }
 /**
  * Sheet — the SINGLE sheet: one card as a bottom sheet holding what the member ACTS on. Always the full height of its
@@ -43,4 +49,4 @@ export interface SheetProps extends Omit<ComponentProps<'article'>, 'onChange'>
  * crossing and never one continuous move, whatever the app's wiring (both states set in one render, or the next raised from the
  * first's `onSettled`) — the app adds no timer.
  */
-export declare function Sheet({ state, defaultState, onStateChange, onSettled, states, handle, className, children, onFocus, ...rest }: SheetProps): import("react").JSX.Element;
+export declare function Sheet({ state, defaultState, onStateChange, onSettled, states, handle, mark, tone, paper, className, children, onFocus, ...rest }: SheetProps): import("react").JSX.Element;

package/dist/sheets/Sheet.js

@@ -28,7 +28,7 @@ const RANK = { away: 0, peek: 1, half: 2, '3q': 3, full: 4 };
  * crossing and never one continuous move, whatever the app's wiring (both states set in one render, or the next raised from the
  * first's `onSettled`) — the app adds no timer.
  */
-export function Sheet({ state, defaultState = 'half', onStateChange, onSettled, states, handle = true, className, children, onFocus, ...rest }) {
+export function Sheet({ state, defaultState = 'half', onStateChange, onSettled, states, handle = true, mark = 'line', tone, paper, className, children, onFocus, ...rest }) {
     const [current, request] = useControlled(state, defaultState, onStateChange);
     const ref = useRef(null);
     const handleRef = useRef(null);
@@ -120,5 +120,5 @@ export function Sheet({ state, defaultState = 'half', onStateChange, onSettled,
             return; // the click that follows a drag is not a tap
         request(current === 'peek' ? (allowed().includes(home.current) ? home.current : allowed().find((s) => s !== 'peek') ?? 'half') : 'peek', 'tap');
     };
-    return (_jsxs("article", { ref: ref, className: cx('card sheet', `sheet--${shown}`, className), inert: current === 'away' || held || undefined, onFocus: focus, ...rest, children: [handle !== false && (_jsx("button", { ref: handleRef, className: "sheet__handle", type: "button", "aria-label": typeof handle === 'string' ? handle : word('resize'), onClick: tap, onPointerDown: down, onPointerMove: move, onPointerUp: up, onPointerCancel: up })), children] }));
+    return (_jsxs("article", { ref: ref, className: cx('card sheet', tone && tone !== 1 && `card--${tone}`, paper && 'sheet--paper', `sheet--${shown}`, className), inert: current === 'away' || held || undefined, onFocus: focus, ...rest, children: [handle !== false && (_jsx("button", { ref: handleRef, className: cx('sheet__handle', mark === 'dots' && 'sheet__handle--dots'), type: "button", "aria-label": typeof handle === 'string' ? handle : word('resize'), onClick: tap, onPointerDown: down, onPointerMove: move, onPointerUp: up, onPointerCancel: up })), children] }));
 }

package/dist/sheets/SheetStack.d.ts

@@ -11,6 +11,8 @@ export interface SheetStackProps extends ComponentProps<'div'> {
     onOpenChange?: (open: number | null) => void;
     /** the open sheet's scroller was already at the top and the finger pulled down past the commit. The stack asks with that index. It does not fetch. Omit it and a pull in the body only scrolls */
     onRefresh?: (index: number) => void;
+    /** the sheet the app is reloading (its index), or `null`: while it is the open one its four grip dots fade up and down, at rest again when the app clears it, and a pull there does not ask again. The app sets it in `onRefresh` and clears it when its data is in */
+    refreshing?: number | null;
     /** wider peeks so more of each title shows (display stacks) */
     fanned?: boolean;
     /** nothing open on arrival (tap mode): every sheet, the front one too, peeks at the stack's bottom; the room above is the base's (`base`). A tap opens any sheet over it */
@@ -28,9 +30,8 @@ export interface SheetStackProps extends ComponentProps<'div'> {
  * with a picture over the menu); the `base` slot is rendered after the sheets, so it never takes a sheet's slot. This is the sheet STACK; a single bottom sheet is `Sheet`.
  *
  * A COMPONENT, not a wiring: WHICH sheet is open is the app's (`open` + `onOpenChange`, or `defaultOpen`) — so a button anywhere, a route or
- * the phone's back button can open and close a section. Its own behaviour stays inside and only asks: a tap on a peeked head, or a pull up on
- * that head (the title, the back button, or the head itself — not a tab), opens it. The open sheet's StackBack or its title, tapped or pulled
- * down, folds it. A pull down in the content, already at the top, asks `onRefresh` and does not fold. How the sheets MOVE is its own too: sheets are rigid — the tapped one slides up, the ones after it leave below, the ones
- * before tuck under nearest-first; closing reverses in two beats. Only `translate` (stack.css); it sets classes, never a size.
+ * the phone's back button can open and close a section. WHAT the sheet does with that, and with `refreshing`, lives on the card (`stack`):
+ * the place classes, the grip, the pull. The stack only says which index. Sheets are rigid — the open one slides up, the ones after it leave
+ * below, the ones before tuck under nearest-first; closing reverses in two beats. Only `translate` (stack.css); never a size.
  */
-export declare function SheetStack({ mode, open, defaultOpen, onOpenChange, onRefresh, fanned, closed, base, className, children, onClick, onKeyDown, ...rest }: SheetStackProps): import("react").JSX.Element;
+export declare function SheetStack({ mode, open, defaultOpen, onOpenChange, onRefresh, refreshing, fanned, closed, base, className, children, ...rest }: SheetStackProps): import("react").JSX.Element;