@usableapp/cardds 0.7.30 → 0.7.31

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 > 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.31 — 2026-09-29
+
+### Changed
+- **One rule, one mechanic: a part that becomes active has its field waiting with the cursor** (Lh 2026-09-29). Every component that becomes active now uses the same helper inside cardds (`focusWhenActive`): once the part has settled, the cursor goes to the field marked `data-autofocus`, else its first field, else its heading; a field that already has the cursor keeps it.
+  - `Sheet` (as 0.7.30) and `SheetSteps` (as before) — now on the one mechanic.
+  - `SheetStack` (so `Home`): a sheet opened → the first field in its body has the cursor after the slide. New. A section with no field: nothing moves.
+  - `Modal`: arrived → the cursor is in it (its field, else the `Drawer`'s question — no ring), not left on the button behind the scrim. New.
+  Nothing to change in a screen: remove any focus code of your own for these parts.
+
 ## 0.7.30 — 2026-09-29
 
 ### Changed

package/README.md

@@ -302,6 +302,10 @@ whose markup has rules, because the sheet's box is the step itself:
   A sheet always ARRIVES and LEAVES by sliding: mounted already up, it starts `away` for one frame and slides in. To
   take it off the screen set `state="away"` and unmount it in `onSettled` (`s === 'away'`) — unmounting it while it is up
   only makes it vanish (dev warning). Story: `Sheet · MountedOnDemand`.
+- **A part that becomes active has its field waiting with the cursor** (Lh 2026-09-29) — a `Sheet` come up, a `SheetStep`
+  opened, a `SheetStack` sheet opened, a `Modal` arrived. Once it has settled: the field marked `data-autofocus`, else its
+  first field, else its heading (a step's title, a modal's question) or, for a sheet come onto the screen, its handle. A field
+  that already has the cursor keeps it. One mechanic for all of them (`focusWhenActive`, src/state.ts); an app writes no focus code.
 
 ## Centred card markup
 

package/css/layover.css

@@ -82,6 +82,7 @@
 /* the CONFIRM: a Modal with no Lift — the drawer IS the card, as tall as its words (no fixed band, no second beat) */
 .modal:not(:has(> .modal__lift)) > .modal__drawer { height: auto; padding-block: var(--modal-confirm-pad-y, var(--sp-6)); animation: none; }
 .modal__drawer .t-caption { opacity: var(--dim); }
+.modal__drawer > h2:focus { outline: none; } /* the question takes the cursor when the modal arrives (for a screen reader, the keyboard's way in) — it is not a control: no ring */
 .modal__drawer .icon-btn { background: transparent; color: inherit; border-color: var(--ink-rail); }
 .modal__drawer .icon-btn--invert { background: var(--accent); color: var(--on-accent); border-color: transparent; width: var(--tap-lg); height: var(--tap-lg); }
 @media (prefers-reduced-motion: no-preference) {

package/dist/actions/Btn.d.ts

@@ -19,11 +19,13 @@ export interface BtnProps extends Omit<ComponentProps<'button'>, 'form'> {
  * In a CardFoot up to four share the line; in an ActionBar it takes the width. An Icon xs may lead or trail the label.
  */
 export declare function Btn({ primary, quiet, block, form, xl, href, className, type, ...rest }: BtnProps): import("react").DetailedReactHTMLElement<{
+    translate?: "yes" | "no" | undefined | undefined;
     onChange?: import("react").ChangeEventHandler<HTMLButtonElement, Element> | undefined;
-    name?: string | undefined | undefined;
     slot?: string | undefined | undefined;
     style?: import("react").CSSProperties | undefined;
     title?: string | undefined | undefined;
+    dir?: string | undefined | undefined;
+    name?: string | undefined | undefined;
     children?: import("react").ReactNode;
     suppressHydrationWarning?: boolean | undefined | undefined;
     color?: string | undefined | undefined;
@@ -266,12 +268,10 @@ export declare function Btn({ primary, quiet, block, form, xl, href, className,
     autoFocus?: boolean | undefined | undefined;
     contentEditable?: (boolean | "true" | "false") | "inherit" | "plaintext-only" | undefined;
     contextMenu?: string | undefined | undefined;
-    dir?: string | undefined | undefined;
     draggable?: (boolean | "true" | "false") | undefined;
     enterKeyHint?: "enter" | "done" | "go" | "next" | "previous" | "search" | "send" | undefined | undefined;
     hidden?: boolean | undefined | undefined;
     spellCheck?: (boolean | "true" | "false") | undefined;
-    translate?: "yes" | "no" | undefined | undefined;
     radioGroup?: string | undefined | undefined;
     about?: string | undefined | undefined;
     content?: string | undefined | undefined;
@@ -309,6 +309,6 @@ export declare function Btn({ primary, quiet, block, form, xl, href, className,
     formTarget?: string | undefined | undefined;
     value?: string | number | readonly string[] | undefined;
     href: string | undefined;
-    type: "button" | "submit" | "reset" | undefined;
+    type: "reset" | "submit" | "button" | undefined;
     className: string;
 }, HTMLButtonElement>;

package/dist/actions/IconBtn.d.ts

@@ -306,6 +306,6 @@ export declare function IconBtn({ label, icon, sm, invert, href, className, type
     onTransitionStart?: import("react").TransitionEventHandler<HTMLButtonElement> | undefined;
     onTransitionStartCapture?: import("react").TransitionEventHandler<HTMLButtonElement> | undefined;
     href: string | undefined;
-    type: "button" | "submit" | "reset" | undefined;
+    type: "reset" | "submit" | "button" | undefined;
     className: string;
 }, HTMLButtonElement>;

package/dist/cardds.css

@@ -3652,6 +3652,7 @@ button:enabled { cursor: pointer; } /* a disabled one keeps the arrow */
 /* the CONFIRM: a Modal with no Lift — the drawer IS the card, as tall as its words (no fixed band, no second beat) */
 .modal:not(:has(> .modal__lift)) > .modal__drawer { height: auto; padding-block: var(--modal-confirm-pad-y, var(--sp-6)); animation: none; }
 .modal__drawer .t-caption { opacity: var(--dim); }
+.modal__drawer > h2:focus { outline: none; } /* the question takes the cursor when the modal arrives (for a screen reader, the keyboard's way in) — it is not a control: no ring */
 .modal__drawer .icon-btn { background: transparent; color: inherit; border-color: var(--ink-rail); }
 .modal__drawer .icon-btn--invert { background: var(--accent); color: var(--on-accent); border-color: transparent; width: var(--tap-lg); height: var(--tap-lg); }
 @media (prefers-reduced-motion: no-preference) {

package/dist/media/Tile.d.ts

@@ -38,9 +38,11 @@ export interface TileProps extends Omit<ComponentProps<'div'>, 'onChange'> {
 }
 /** Tile — a big square: icon top, label bottom; `pick` toggles, `stat` shows a value, `upload` is the dashed slot. */
 export declare function Tile({ icon, label, value, sub, pick, type, name, checked, defaultChecked, onChange, on, stat, upload, wide, tone, as, className, children, ...rest }: TileProps): import("react").DetailedReactHTMLElement<{
+    translate?: "yes" | "no" | undefined | undefined;
     slot?: string | undefined | undefined;
     style?: import("react").CSSProperties | undefined;
     title?: string | undefined | undefined;
+    dir?: string | undefined | undefined;
     suppressHydrationWarning?: boolean | undefined | undefined;
     color?: string | undefined | undefined;
     id?: string | undefined | undefined;
@@ -281,12 +283,10 @@ export declare function Tile({ icon, label, value, sub, pick, type, name, checke
     autoFocus?: boolean | undefined | undefined;
     contentEditable?: (boolean | "true" | "false") | "inherit" | "plaintext-only" | undefined;
     contextMenu?: string | undefined | undefined;
-    dir?: string | undefined | undefined;
     draggable?: (boolean | "true" | "false") | undefined;
     enterKeyHint?: "enter" | "done" | "go" | "next" | "previous" | "search" | "send" | undefined | undefined;
     hidden?: boolean | undefined | undefined;
     spellCheck?: (boolean | "true" | "false") | undefined;
-    translate?: "yes" | "no" | undefined | undefined;
     radioGroup?: string | undefined | undefined;
     about?: string | undefined | undefined;
     content?: string | undefined | undefined;

package/dist/sheets/Drawer.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Children, Fragment, useEffect, useRef } from 'react';
-import { useLatest } from '../state.js';
+import { focusWhenActive, useLatest } from '../state.js';
 import { cx } from '../cx.js';
 /**
  * Modal — the ask: ONE card at the centre of a `SheetStage dim`, two parts — a `Lift` (the thing being asked about, light, scrolls
@@ -28,6 +28,16 @@ export function Modal({ open = true, onClosed, onDismiss, className, ...rest })
             closed.current?.(); });
         return () => { live = false; };
     }, [open]);
+    /* it has arrived → the cursor is in it, not left behind the scrim: its field if it holds one, else its question (the one rule of every
+       part that becomes active: focusWhenActive) — once the beats have played */
+    useEffect(() => {
+        const el = ref.current;
+        if (!el || !open)
+            return;
+        const beats = Math.max(0, ...el.getAnimations({ subtree: true }).map((a) => Number(a.effect?.getComputedTiming().endTime) || 0));
+        const cancel = focusWhenActive(el, { wait: beats, fallback: () => el.querySelector('.modal__drawer > h2') });
+        return () => { cancel(); };
+    }, [open]);
     const dismiss = useLatest(onDismiss);
     const has = onDismiss !== undefined;
     useEffect(() => {
@@ -52,7 +62,7 @@ export function Lift({ className, ...rest }) {
  *  with the app's `onClick`; the Drawer does nothing with them. A `Modal` holding ONLY a Drawer (no `Lift`) is the CONFIRM: a question with nothing
  *  to show above it — the Drawer is the whole card and comes in with it in one beat. */
 export function Drawer({ title, caption, light, className, children, ...rest }) {
-    return (_jsxs("div", { className: cx('modal__drawer', light && 'modal__drawer--light', className), ...rest, children: [_jsx("h2", { className: "t-h2", children: title }), caption != null && _jsx("p", { className: "t-caption", children: caption }), children] }));
+    return (_jsxs("div", { className: cx('modal__drawer', light && 'modal__drawer--light', className), ...rest, children: [_jsx("h2", { className: "t-h2", tabIndex: -1, children: title }), caption != null && _jsx("p", { className: "t-caption", children: caption }), children] }));
 }
 /** BtnTrio — three round buttons with dotted connectors between them (× · ? · ✓); the middle one inverted. */
 export function BtnTrio({ className, children, ...rest }) {

package/dist/sheets/Sheet.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
-import { useControlled, useLatest, warnOnce, watchSize } from '../state.js';
+import { focusWhenActive, useControlled, useLatest, warnOnce, watchSize } from '../state.js';
 import { cx } from '../cx.js';
 const ORDER = ['peek', 'half', '3q', 'full']; // low → high; `away` is below them all and outside them
 const RANK = { away: 0, peek: 1, half: 2, '3q': 3, full: 4 };
@@ -91,25 +91,8 @@ export function Sheet({ state, defaultState = 'half', onStateChange, onSettled,
         was.current = current;
         if (!rose)
             return;
-        const el = ref.current;
-        let done = false;
-        const land = () => {
-            if (done || !el)
-                return;
-            done = true;
-            el.removeEventListener('transitionend', onEnd);
-            const at = document.activeElement;
-            if (at && el.contains(at) && at !== handleRef.current && at.matches('input, textarea, select, [contenteditable]'))
-                return;
-            const field = el.querySelector('[data-autofocus]:not([inert] *)')
-                ?? el.querySelector(':scope > .sheet__body :is(input:not([type=checkbox], [type=radio], [type=hidden], [disabled]), textarea, select):not([inert] *)');
-            (field ?? (from === 'away' ? handleRef.current : null))?.focus({ preventScroll: true });
-        };
-        const onEnd = (e) => { if (e.target === el && e.propertyName === 'translate')
-            land(); };
-        el?.addEventListener('transitionend', onEnd);
-        const t = setTimeout(land, 600); // no transition (reduced motion): land anyway
-        return () => { clearTimeout(t); el?.removeEventListener('transitionend', onEnd); if (!done)
+        const cancel = focusWhenActive(ref.current, { scope: ':scope > .sheet__body', fallback: () => (from === 'away' ? handleRef.current : null) });
+        return () => { if (!cancel())
             was.current = from; }; // cut short (StrictMode's trial run, or a new state mid-slide): the rise still counts from where it began
     }, [current]);
     /* geometry, read once per gesture — never stored: how far it has slid, and where each state rests, in px from its top at full */

package/dist/sheets/SheetStack.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useLayoutEffect, useRef } from 'react';
-import { useControlled } from '../state.js';
+import { useEffect, useLayoutEffect, useRef } from 'react';
+import { focusWhenActive, useControlled } from '../state.js';
 import { cx } from '../cx.js';
 const PHASE = 380; // ms before the before-pack un-tucks on close, so the after-pack is clear first
 /* the stack's sheets, in slot order: its direct children — or, where a host wraps each child in one box of its own, the first .card in
@@ -67,6 +67,13 @@ export function SheetStack({ mode = 'tap', open, defaultOpen = null, onOpenChang
         if (!untuck.current)
             sheets.forEach((c) => c.classList.remove('is-open', 'is-before', 'is-after'));
     });
+    /* a sheet opened → its field has the cursor once it has slid up (the one rule of every part that becomes active: focusWhenActive) */
+    useEffect(() => {
+        if (current == null || mode !== 'tap' || !ref.current)
+            return;
+        const cancel = focusWhenActive(sheetsOf(ref.current)[current], { scope: ':scope > .sheet__body' });
+        return () => { cancel(); };
+    }, [current, mode]);
     const click = (e) => {
         onClick?.(e);
         const stack = ref.current;

package/dist/sheets/SheetSteps.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Children, cloneElement, createContext, isValidElement, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
-import { useControlled, reducedMotion } from '../state.js';
+import { focusWhenActive, useControlled, reducedMotion } from '../state.js';
 import { cx } from '../cx.js';
 import { Icon } from '../type/Icon.js';
 import { Link } from '../actions/Link.js';
@@ -102,15 +102,12 @@ export function SheetSteps({ at, reached, defaultAt = 0, onAtChange, reversible
             else
                 at.blur();
         }
-        const t = setTimeout(() => {
-            const now = ref.current?.querySelector('.sheet-step--now');
-            // the cursor stands by: the step's first field takes the focus (the keyboard comes with it); a step with no field — its
-            // title, so a screen reader hears where it is
-            (now?.querySelector('.sheet-step__inner :is(input:not([type=checkbox], [type=radio], [type=hidden]), textarea)') ?? now?.querySelector('.sheet-step__title'))?.focus({ preventScroll: true });
-            glide.current = performance.now() + 900;
-            settle();
-        }, MOVE_MS);
-        return () => clearTimeout(t);
+        // the cursor stands by: the step's first field takes the focus (the keyboard comes with it); a step with no field — its
+        // title, so a screen reader hears where it is (the one rule of every part that becomes active: focusWhenActive)
+        const cancel = focusWhenActive(ref.current, { wait: MOVE_MS, scope: '.sheet-step--now .sheet-step__inner',
+            fallback: () => ref.current?.querySelector('.sheet-step--now .sheet-step__title'),
+            then: () => { glide.current = performance.now() + 900; settle(); } });
+        return () => { cancel(); };
     }, [current]);
     /* the keyboard comes and goes: the body's scroll JUMPS (the Sheet's reveal, the browser's own, ours below, the box growing back).
        For a short while after a field in the steps gains or loses the focus, every such jump is played as a quick slide (FLIP: the steps

package/dist/state.d.ts

@@ -21,4 +21,14 @@ export declare function watchSize(targets: Array<Element | null | undefined>, fn
 export declare const warnOnce: (key: string, text: string) => void;
 /** the member asked for less motion (false where there is no window, e.g. a server render) */
 export declare const reducedMotion: () => boolean;
+/** give `box` the cursor once it has settled: after its own `translate` transition (600ms at most), or after `wait` ms. It lands on the field
+ *  marked `data-autofocus`, else the first field inside `scope` (a selector under `box`; default: all of it), else `fallback`. A field in
+ *  `box` that already has the cursor keeps it. Nothing moves the page (`preventScroll`). Returns the cancel — `true` when it had already
+ *  landed (so a component can tell a move cut short from a finished one). */
+export declare function focusWhenActive(box: HTMLElement | null | undefined, { scope, fallback, wait, then }?: {
+    scope?: string;
+    fallback?: () => HTMLElement | null | undefined;
+    wait?: 'translate' | number;
+    then?: () => void;
+}): () => boolean;
 export {};

package/dist/state.js

@@ -55,3 +55,36 @@ export const warnOnce = (key, text) => { if (!warned.has(key)) {
 } };
 /** the member asked for less motion (false where there is no window, e.g. a server render) */
 export const reducedMotion = () => typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
+/* THE RULE (Lh 2026-09-29): a part of the screen that has just become ACTIVE — a sheet come up, a step opened, a stack sheet opened, a
+   modal asking — has its field waiting with the cursor. ONE mechanic for every such part; the component only says WHEN it became active. */
+const FIELD = 'input:not([type=checkbox], [type=radio], [type=hidden], [disabled], [tabindex="-1"]), textarea:not([disabled]), select:not([disabled]), [contenteditable="true"]';
+/** give `box` the cursor once it has settled: after its own `translate` transition (600ms at most), or after `wait` ms. It lands on the field
+ *  marked `data-autofocus`, else the first field inside `scope` (a selector under `box`; default: all of it), else `fallback`. A field in
+ *  `box` that already has the cursor keeps it. Nothing moves the page (`preventScroll`). Returns the cancel — `true` when it had already
+ *  landed (so a component can tell a move cut short from a finished one). */
+export function focusWhenActive(box, { scope, fallback, wait = 'translate', then } = {}) {
+    if (!box)
+        return () => false;
+    let done = false;
+    const land = () => {
+        if (done)
+            return;
+        done = true;
+        stop();
+        const at = document.activeElement;
+        if (!(at instanceof HTMLElement && box.contains(at) && at.matches(FIELD))) {
+            const root = scope ? box.querySelector(scope) : box;
+            const target = box.querySelector('[data-autofocus]:not([inert] *)')
+                ?? root?.querySelector(`:is(${FIELD}):not([inert] *)`) ?? fallback?.();
+            target?.focus({ preventScroll: true });
+        }
+        then?.();
+    };
+    const onEnd = (e) => { if (e.target === box && e.propertyName === 'translate')
+        land(); };
+    const t = setTimeout(land, wait === 'translate' ? 600 : wait); // no transition (reduced motion) or none came: land anyway
+    if (wait === 'translate')
+        box.addEventListener('transitionend', onEnd);
+    function stop() { clearTimeout(t); box.removeEventListener('transitionend', onEnd); }
+    return () => { const was = done; done = true; stop(); return was; };
+}

package/package.json

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