@usableapp/cardds 0.2.2 → 0.4.0

package/dist/scaffold/Screen.d.ts

@@ -1,6 +1,6 @@
-import { type ComponentPropsWithoutRef } from 'react';
+import { type ComponentProps } from 'react';
 export type Palette = 'clay' | 'shine' | 'field' | 'roast' | 'hydro';
-export interface ScreenProps extends ComponentPropsWithoutRef<'div'> {
+export interface ScreenProps extends ComponentProps<'div'> {
     /** exactly one phone height (100dvh), clipped: the box a Step or a SheetStack fills — an app screen, not a scrolling page */
     fill?: boolean;
     /** a colour preset from palette.css; omit for the black-and-white wireframe */
@@ -14,74 +14,119 @@ export interface ScreenProps extends ComponentPropsWithoutRef<'div'> {
  * Put an AppBar/TopBar first, the content next, and an ActionBar AFTER the screen (outside it).
  */
 export declare function Screen({ fill, palette, as, className, ...rest }: ScreenProps): import("react").DetailedReactHTMLElement<{
-    slot?: string | undefined | undefined;
+    ref?: import("react").Ref<HTMLDivElement> | undefined;
+    key?: import("react").Key | null | undefined;
+    defaultChecked?: boolean | undefined;
+    defaultValue?: string | number | readonly string[] | undefined;
+    suppressContentEditableWarning?: boolean | undefined;
+    suppressHydrationWarning?: boolean | undefined;
+    accessKey?: string | undefined;
+    autoCapitalize?: "off" | "none" | "on" | "sentences" | "words" | "characters" | undefined | (string & {});
+    autoFocus?: boolean | undefined;
+    contentEditable?: (boolean | "true" | "false") | "inherit" | "plaintext-only" | undefined;
+    contextMenu?: string | undefined;
+    dir?: string | undefined;
+    draggable?: (boolean | "true" | "false") | undefined;
+    enterKeyHint?: "enter" | "done" | "go" | "next" | "previous" | "search" | "send" | undefined;
+    hidden?: boolean | undefined;
+    id?: string | undefined;
+    lang?: string | undefined;
+    nonce?: string | undefined;
+    slot?: string | undefined;
+    spellCheck?: (boolean | "true" | "false") | undefined;
     style?: import("react").CSSProperties | undefined;
-    title?: string | undefined | undefined;
-    suppressHydrationWarning?: boolean | undefined | undefined;
-    color?: string | undefined | undefined;
-    id?: string | undefined | undefined;
-    lang?: string | undefined | undefined;
-    nonce?: string | undefined | undefined;
-    part?: string | undefined | undefined;
+    tabIndex?: number | undefined;
+    title?: string | undefined;
+    translate?: "yes" | "no" | undefined;
+    radioGroup?: string | undefined;
     role?: import("react").AriaRole | undefined;
-    tabIndex?: number | undefined | undefined;
-    "aria-activedescendant"?: string | undefined | undefined;
+    about?: string | undefined;
+    content?: string | undefined;
+    datatype?: string | undefined;
+    inlist?: any;
+    prefix?: string | undefined;
+    property?: string | undefined;
+    rel?: string | undefined;
+    resource?: string | undefined;
+    rev?: string | undefined;
+    typeof?: string | undefined;
+    vocab?: string | undefined;
+    autoCorrect?: string | undefined;
+    autoSave?: string | undefined;
+    color?: string | undefined;
+    itemProp?: string | undefined;
+    itemScope?: boolean | undefined;
+    itemType?: string | undefined;
+    itemID?: string | undefined;
+    itemRef?: string | undefined;
+    results?: number | undefined;
+    security?: string | undefined;
+    unselectable?: "on" | "off" | undefined;
+    popover?: "" | "auto" | "manual" | "hint" | undefined;
+    popoverTargetAction?: "toggle" | "show" | "hide" | undefined;
+    popoverTarget?: string | undefined;
+    inert?: boolean | undefined;
+    inputMode?: "none" | "text" | "tel" | "url" | "email" | "numeric" | "decimal" | "search" | undefined;
+    is?: string | undefined;
+    exportparts?: string | undefined;
+    part?: string | undefined;
+    "aria-activedescendant"?: string | undefined;
     "aria-atomic"?: (boolean | "true" | "false") | undefined;
-    "aria-autocomplete"?: "none" | "inline" | "list" | "both" | undefined | undefined;
-    "aria-braillelabel"?: string | undefined | undefined;
-    "aria-brailleroledescription"?: string | undefined | undefined;
+    "aria-autocomplete"?: "none" | "inline" | "list" | "both" | undefined;
+    "aria-braillelabel"?: string | undefined;
+    "aria-brailleroledescription"?: string | undefined;
     "aria-busy"?: (boolean | "true" | "false") | undefined;
-    "aria-checked"?: boolean | "false" | "mixed" | "true" | undefined | undefined;
-    "aria-colcount"?: number | undefined | undefined;
-    "aria-colindex"?: number | undefined | undefined;
-    "aria-colindextext"?: string | undefined | undefined;
-    "aria-colspan"?: number | undefined | undefined;
-    "aria-controls"?: string | undefined | undefined;
-    "aria-current"?: boolean | "false" | "true" | "page" | "step" | "location" | "date" | "time" | undefined | undefined;
-    "aria-describedby"?: string | undefined | undefined;
-    "aria-description"?: string | undefined | undefined;
-    "aria-details"?: string | undefined | undefined;
+    "aria-checked"?: boolean | "false" | "mixed" | "true" | undefined;
+    "aria-colcount"?: number | undefined;
+    "aria-colindex"?: number | undefined;
+    "aria-colindextext"?: string | undefined;
+    "aria-colspan"?: number | undefined;
+    "aria-controls"?: string | undefined;
+    "aria-current"?: boolean | "false" | "true" | "page" | "step" | "location" | "date" | "time" | undefined;
+    "aria-describedby"?: string | undefined;
+    "aria-description"?: string | undefined;
+    "aria-details"?: string | undefined;
     "aria-disabled"?: (boolean | "true" | "false") | undefined;
-    "aria-dropeffect"?: "none" | "copy" | "execute" | "link" | "move" | "popup" | undefined | undefined;
-    "aria-errormessage"?: string | undefined | undefined;
+    "aria-dropeffect"?: "none" | "copy" | "execute" | "link" | "move" | "popup" | undefined;
+    "aria-errormessage"?: string | undefined;
     "aria-expanded"?: (boolean | "true" | "false") | undefined;
-    "aria-flowto"?: string | undefined | undefined;
+    "aria-flowto"?: string | undefined;
     "aria-grabbed"?: (boolean | "true" | "false") | undefined;
-    "aria-haspopup"?: boolean | "false" | "true" | "menu" | "listbox" | "tree" | "grid" | "dialog" | undefined | undefined;
+    "aria-haspopup"?: boolean | "false" | "true" | "menu" | "listbox" | "tree" | "grid" | "dialog" | undefined;
     "aria-hidden"?: (boolean | "true" | "false") | undefined;
-    "aria-invalid"?: boolean | "false" | "true" | "grammar" | "spelling" | undefined | undefined;
-    "aria-keyshortcuts"?: string | undefined | undefined;
-    "aria-label"?: string | undefined | undefined;
-    "aria-labelledby"?: string | undefined | undefined;
-    "aria-level"?: number | undefined | undefined;
-    "aria-live"?: "off" | "assertive" | "polite" | undefined | undefined;
+    "aria-invalid"?: boolean | "false" | "true" | "grammar" | "spelling" | undefined;
+    "aria-keyshortcuts"?: string | undefined;
+    "aria-label"?: string | undefined;
+    "aria-labelledby"?: string | undefined;
+    "aria-level"?: number | undefined;
+    "aria-live"?: "off" | "assertive" | "polite" | undefined;
     "aria-modal"?: (boolean | "true" | "false") | undefined;
     "aria-multiline"?: (boolean | "true" | "false") | undefined;
     "aria-multiselectable"?: (boolean | "true" | "false") | undefined;
-    "aria-orientation"?: "horizontal" | "vertical" | undefined | undefined;
-    "aria-owns"?: string | undefined | undefined;
-    "aria-placeholder"?: string | undefined | undefined;
-    "aria-posinset"?: number | undefined | undefined;
-    "aria-pressed"?: boolean | "false" | "mixed" | "true" | undefined | undefined;
+    "aria-orientation"?: "horizontal" | "vertical" | undefined;
+    "aria-owns"?: string | undefined;
+    "aria-placeholder"?: string | undefined;
+    "aria-posinset"?: number | undefined;
+    "aria-pressed"?: boolean | "false" | "mixed" | "true" | undefined;
     "aria-readonly"?: (boolean | "true" | "false") | undefined;
-    "aria-relevant"?: "additions" | "additions removals" | "additions text" | "all" | "removals" | "removals additions" | "removals text" | "text" | "text additions" | "text removals" | undefined | undefined;
+    "aria-relevant"?: "additions" | "additions removals" | "additions text" | "all" | "removals" | "removals additions" | "removals text" | "text" | "text additions" | "text removals" | undefined;
     "aria-required"?: (boolean | "true" | "false") | undefined;
-    "aria-roledescription"?: string | undefined | undefined;
-    "aria-rowcount"?: number | undefined | undefined;
-    "aria-rowindex"?: number | undefined | undefined;
-    "aria-rowindextext"?: string | undefined | undefined;
-    "aria-rowspan"?: number | undefined | undefined;
+    "aria-roledescription"?: string | undefined;
+    "aria-rowcount"?: number | undefined;
+    "aria-rowindex"?: number | undefined;
+    "aria-rowindextext"?: string | undefined;
+    "aria-rowspan"?: number | undefined;
     "aria-selected"?: (boolean | "true" | "false") | undefined;
-    "aria-setsize"?: number | undefined | undefined;
-    "aria-sort"?: "none" | "ascending" | "descending" | "other" | undefined | undefined;
-    "aria-valuemax"?: number | undefined | undefined;
-    "aria-valuemin"?: number | undefined | undefined;
-    "aria-valuenow"?: number | undefined | undefined;
-    "aria-valuetext"?: string | undefined | undefined;
-    children?: import("react").ReactNode;
+    "aria-setsize"?: number | undefined;
+    "aria-sort"?: "none" | "ascending" | "descending" | "other" | undefined;
+    "aria-valuemax"?: number | undefined;
+    "aria-valuemin"?: number | undefined;
+    "aria-valuenow"?: number | undefined;
+    "aria-valuetext"?: string | undefined;
+    children?: import("react").ReactNode | undefined;
     dangerouslySetInnerHTML?: {
         __html: string | TrustedHTML;
-    } | undefined | undefined;
+    } | undefined;
     onCopy?: import("react").ClipboardEventHandler<HTMLDivElement> | undefined;
     onCopyCapture?: import("react").ClipboardEventHandler<HTMLDivElement> | undefined;
     onCut?: import("react").ClipboardEventHandler<HTMLDivElement> | undefined;
@@ -250,50 +295,6 @@ export declare function Screen({ fill, palette, as, className, ...rest }: Screen
     onTransitionRunCapture?: import("react").TransitionEventHandler<HTMLDivElement> | undefined;
     onTransitionStart?: import("react").TransitionEventHandler<HTMLDivElement> | undefined;
     onTransitionStartCapture?: import("react").TransitionEventHandler<HTMLDivElement> | undefined;
-    key?: import("react").Key | null | undefined;
-    defaultChecked?: boolean | undefined | undefined;
-    defaultValue?: string | number | readonly string[] | undefined;
-    suppressContentEditableWarning?: boolean | undefined | undefined;
-    accessKey?: string | undefined | undefined;
-    autoCapitalize?: "off" | "none" | "on" | "sentences" | "words" | "characters" | undefined | (string & {}) | undefined;
-    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;
-    datatype?: string | undefined | undefined;
-    inlist?: any;
-    prefix?: string | undefined | undefined;
-    property?: string | undefined | undefined;
-    rel?: string | undefined | undefined;
-    resource?: string | undefined | undefined;
-    rev?: string | undefined | undefined;
-    typeof?: string | undefined | undefined;
-    vocab?: string | undefined | undefined;
-    autoCorrect?: string | undefined | undefined;
-    autoSave?: string | undefined | undefined;
-    itemProp?: string | undefined | undefined;
-    itemScope?: boolean | undefined | undefined;
-    itemType?: string | undefined | undefined;
-    itemID?: string | undefined | undefined;
-    itemRef?: string | undefined | undefined;
-    results?: number | undefined | undefined;
-    security?: string | undefined | undefined;
-    unselectable?: "on" | "off" | undefined | undefined;
-    popover?: "" | "auto" | "manual" | "hint" | undefined | undefined;
-    popoverTargetAction?: "toggle" | "show" | "hide" | undefined | undefined;
-    popoverTarget?: string | undefined | undefined;
-    inert?: boolean | undefined | undefined;
-    inputMode?: "none" | "text" | "tel" | "url" | "email" | "numeric" | "decimal" | "search" | undefined | undefined;
-    is?: string | undefined | undefined;
-    exportparts?: string | undefined | undefined;
     className: string;
     'data-palette': Palette | undefined;
-}, HTMLElement>;
+}, HTMLDivElement>;

package/dist/scaffold/TopBar.d.ts

@@ -1,5 +1,5 @@
-import type { ComponentPropsWithoutRef, ReactNode } from 'react';
-export interface TopBarProps extends Omit<ComponentPropsWithoutRef<'header'>, 'title'> {
+import type { ComponentProps, ReactNode } from 'react';
+export interface TopBarProps extends Omit<ComponentProps<'header'>, 'title'> {
     /** the screen title (uppercase, ellipsised on one line) */
     title: ReactNode;
     /** a leading control — usually `<IconBtn sm icon="arrow-left" label="Back" />` */

package/dist/sheets/CardBack.d.ts

@@ -1,5 +1,5 @@
-import type { ComponentPropsWithoutRef } from 'react';
-export interface CardBackProps extends ComponentPropsWithoutRef<'button'> {
+import type { ComponentProps } from 'react';
+export interface CardBackProps extends ComponentProps<'button'> {
     /** accessible name */
     label?: string;
 }

package/dist/sheets/Drawer.d.ts

@@ -1,21 +1,32 @@
-import { type ComponentPropsWithoutRef, type ReactNode } from 'react';
-export interface ModalProps extends ComponentPropsWithoutRef<'article'> {
+import { type ComponentProps, type ReactNode } from 'react';
+export interface ModalProps extends ComponentProps<'article'> {
+    /** CONTROLLED: on the screen or not (default `true`). The app owns it. Set it `false` and the modal leaves the way it came — its
+     *  opening played backwards — then calls `onClosed`, where the app stops rendering it (and its `SheetStage ask`). */
+    open?: boolean;
+    /** the leaving has finished (at once, when motion is reduced) — unmount here */
+    onClosed?: () => void;
 }
-/** Modal — the ask: ONE card at the centre of a `SheetStage ask`, two parts — a `Lift` (the thing being asked about, light, scrolls when tall) and a `Drawer` (the dark end that asks). No border. Two beats on appearing: drops in from above to the centre · the drawer comes out below while the lift moves up. A click on any button in the Drawer plays them backwards and fires `cardds:modal` on the stage (`detail.answer` = the button's `data-answer`) for the app to remove it. */
-export declare function Modal({ className, ...rest }: ModalProps): import("react").JSX.Element;
-export interface LiftProps extends ComponentPropsWithoutRef<'div'> {
+/**
+ * Modal — the ask: ONE card at the centre of a `SheetStage ask`, two parts — a `Lift` (the thing being asked about, light, scrolls
+ * when tall) and a `Drawer` (the dark end that asks). No border. Two beats on appearing: drops in from above, then the drawer comes
+ * out below while the lift moves up.
+ * A COMPONENT, not a wiring: it does not know its buttons. They are plain `IconBtn`s / `Btn`s with the app's `onClick` — the app
+ * records the answer and sets `open={false}`; the modal's one behaviour is how it leaves.
+ */
+export declare function Modal({ open, onClosed, className, ...rest }: ModalProps): import("react").JSX.Element;
+export interface LiftProps extends ComponentProps<'div'> {
 }
 /** Lift — the light part of a `Modal`: the case, request or item the question is about (a CardHead, rows, a timeline); scrolls inside when tall. */
 export declare function Lift({ className, ...rest }: LiftProps): import("react").JSX.Element;
-export interface DrawerProps extends Omit<ComponentPropsWithoutRef<'div'>, 'title'> {
+export interface DrawerProps extends Omit<ComponentProps<'div'>, 'title'> {
     /** the question */
     title: ReactNode;
     /** the fine print under it */
     caption?: ReactNode;
 }
-/** Drawer — the dark end of a `Modal`: the question, its fine print, and a `BtnTrio` (or two buttons); give each button a `data-answer` — any of them closes the modal. */
+/** Drawer — the dark end of a `Modal`: the question, its fine print, and a `BtnTrio` (or two buttons) — plain buttons with the app's `onClick`; the Drawer does nothing with them. */
 export declare function Drawer({ title, caption, className, children, ...rest }: DrawerProps): import("react").JSX.Element;
-export interface BtnTrioProps extends ComponentPropsWithoutRef<'div'> {
+export interface BtnTrioProps extends ComponentProps<'div'> {
 }
 /** BtnTrio — three round buttons with dotted connectors between them (× · ? · ✓); the middle one inverted. */
 export declare function BtnTrio({ className, children, ...rest }: BtnTrioProps): import("react").JSX.Element;

package/dist/sheets/Drawer.js

@@ -1,15 +1,39 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Children, Fragment } from 'react';
+import { Children, Fragment, useEffect, useRef } from 'react';
 import { cx } from '../cx.js';
-/** Modal — the ask: ONE card at the centre of a `SheetStage ask`, two parts — a `Lift` (the thing being asked about, light, scrolls when tall) and a `Drawer` (the dark end that asks). No border. Two beats on appearing: drops in from above to the centre · the drawer comes out below while the lift moves up. A click on any button in the Drawer plays them backwards and fires `cardds:modal` on the stage (`detail.answer` = the button's `data-answer`) for the app to remove it. */
-export function Modal({ className, ...rest }) {
-    return _jsx("article", { className: cx('card modal', className), ...rest });
+/**
+ * Modal — the ask: ONE card at the centre of a `SheetStage ask`, two parts — a `Lift` (the thing being asked about, light, scrolls
+ * when tall) and a `Drawer` (the dark end that asks). No border. Two beats on appearing: drops in from above, then the drawer comes
+ * out below while the lift moves up.
+ * A COMPONENT, not a wiring: it does not know its buttons. They are plain `IconBtn`s / `Btn`s with the app's `onClick` — the app
+ * records the answer and sets `open={false}`; the modal's one behaviour is how it leaves.
+ */
+export function Modal({ open = true, onClosed, className, ...rest }) {
+    const ref = useRef(null);
+    const closed = useRef(onClosed);
+    closed.current = onClosed;
+    const shown = useRef(true); // the animations stand played forwards
+    useEffect(() => {
+        const el = ref.current;
+        if (!el || open === shown.current)
+            return;
+        shown.current = open;
+        const anims = el.getAnimations({ subtree: true });
+        anims.forEach((a) => a.reverse()); // the same keyframes, backwards to leave, forwards again to return — no closing keyframes to keep in step
+        if (open)
+            return;
+        let live = true;
+        void Promise.all(anims.map((a) => a.finished.catch(() => undefined))).then(() => { if (live)
+            closed.current?.(); });
+        return () => { live = false; };
+    }, [open]);
+    return _jsx("article", { ref: ref, className: cx('card modal', className), ...rest });
 }
 /** Lift — the light part of a `Modal`: the case, request or item the question is about (a CardHead, rows, a timeline); scrolls inside when tall. */
 export function Lift({ className, ...rest }) {
     return _jsx("div", { className: cx('modal__lift', className), ...rest });
 }
-/** Drawer — the dark end of a `Modal`: the question, its fine print, and a `BtnTrio` (or two buttons); give each button a `data-answer` — any of them closes the modal. */
+/** Drawer — the dark end of a `Modal`: the question, its fine print, and a `BtnTrio` (or two buttons) — plain buttons with the app's `onClick`; the Drawer does nothing with them. */
 export function Drawer({ title, caption, className, children, ...rest }) {
     return (_jsxs("div", { className: cx('modal__drawer', className), ...rest, children: [_jsx("h2", { className: "t-h2", children: title }), caption != null && _jsx("p", { className: "t-caption", children: caption }), children] }));
 }

package/dist/sheets/Sheet.d.ts

@@ -1,24 +1,37 @@
-import type { ComponentPropsWithoutRef } from 'react';
+import type { ComponentProps } from 'react';
+/** how far the sheet slid. `away` = not on the screen (slid out, inert) — a state the app sets, never one a drag or a tap lands on */
 export type SheetState = 'peek' | 'half' | '3q' | 'full' | 'away';
-export interface SheetProps extends ComponentPropsWithoutRef<'article'> {
-    /** how far the sheet slid: `peek` (handle + title row) · `half` (default) · `3q` (three quarters showing) · `full` (its top edge at the top bar) — a class, never a height. `away` = a CALLED sheet not on the screen yet (slid out, inert): a `Btn aria-controls={its id}` in the Step's BaseContent calls it up to full and sends any other away. A tap on the handle toggles between this state and peek; a drag snaps to any of `states` */
+/** what asked for the change: the handle's `tap`, a `drag` released, `focus` in a peeked sheet, the `keyboard` (or anything else) moving the cut */
+export type SheetChangeReason = 'tap' | 'drag' | 'focus' | 'keyboard';
+declare const ORDER: readonly ["peek", "half", "3q", "full"];
+type Resting = (typeof ORDER)[number];
+export interface SheetProps extends Omit<ComponentProps<'article'>, 'onChange'> {
+    /** CONTROLLED: where the sheet is. The app owns it — pair it with `onStateChange`, or the sheet cannot move (like `value` without `onChange`).
+     *  `peek` (handle + title row) · `half` · `3q` · `full` (its top edge at the top bar) · `away` (not on the screen). A class, never a height. */
     state?: SheetState;
+    /** UNCONTROLLED: where it starts (default `half`); the sheet then keeps its own state. Ignored when `state` is given. */
+    defaultState?: SheetState;
+    /** the sheet ASKS to move — the handle was tapped or dragged, a field in a peeked sheet took focus, the keyboard moved the cut.
+     *  Controlled: set your state to it (or don't — the sheet stays). This is where an app ties a sheet to its router / back button. */
+    onStateChange?: (state: SheetState, reason: SheetChangeReason) => void;
+    /** the states a drag snaps to and a reveal may climb through — "peek half full", or an array (default all four) */
+    states?: string | readonly Resting[];
     /** floats above a footnote strip on a dim stage (bottom corners and border back) */
     raised?: boolean;
-    /** the grab handle (tap / drag / keyboard via cardds.js); `false` for a sheet with no handle, a string sets its accessible name */
+    /** the grab handle; `false` for a sheet with no handle, a string sets its accessible name */
     handle?: boolean | string;
-    /** which states a drag snaps to, e.g. "peek half full" (default all four: peek half 3q full) */
-    states?: string;
 }
 /**
- * Sheet — the SINGLE sheet: one card as a bottom sheet holding what the member ACTS on (controls, or small `Card sm`
- * content cards). Always the full height of its box — a Step or a SheetStage — a state is only how far it slid.
- * Shape: handle · head (a CardHead, a SheetHead — or ONE label Row carrying a Check/Toggle, when the sheet's
- * whole ask is that switch and peek must show it) · SheetBody (the only part that scrolls). Written top-down.
- * It FINISHES on itself: a `CardFoot` as its last child holds the one button that completes it — standing at the bottom at
- * half / 3q / full, gone at peek. Never an ActionBar in front of a sheet (a bar is the base's). Nothing in the body commits
- * on its own. Older note — its own buttons only on a
- * screen with no bar (the map sheet). Called sheets: several `Sheet state="away" states="peek full"` in one Step, each with an `id` a
- * button names — one on the screen at a time; never beside a pager. This is the single sheet; the menu of stacked sheets is `SheetStack`.
+ * Sheet — the SINGLE sheet: one card as a bottom sheet holding what the member ACTS on. Always the full height of its
+ * box — a Step or a SheetStage — a state is only how far it slid (translate; the material never changes size).
+ * ONE SHAPE, written top-down: handle · head (a CardHead / SheetHead — pinned, never scrolls) · SheetBody (scrolls, as far as
+ * it needs) · CardFoot (the button that finishes the sheet — at the bottom, above the keyboard; gone at peek).
+ *
+ * It is a COMPONENT, not a wiring: it knows nothing of what opens it. The app owns `state` and sets it from whatever it
+ * likes — a button, a route, a timer: `<Btn onClick={() => setSheet('full')}>` … `<Sheet state={sheet} onStateChange={setSheet}>`.
+ * Its own behaviour stays inside it and only ever ASKS (`onStateChange`): a tap on the handle toggles its own state ↔ peek,
+ * a drag snaps to the nearest of `states`, focus in a peeked sheet raises it, and when the cut moves (the keyboard) it
+ * climbs until the focused control has room above the foot.
  */
-export declare function Sheet({ state, raised, handle, states, className, children, ...rest }: SheetProps): import("react").JSX.Element;
+export declare function Sheet({ state, defaultState, onStateChange, states, raised, handle, className, children, onFocus, ...rest }: SheetProps): import("react").JSX.Element;
+export {};

package/dist/sheets/Sheet.js

@@ -1,16 +1,162 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useRef, useState } from 'react';
 import { cx } from '../cx.js';
+const ORDER = ['peek', 'half', '3q', 'full']; // low → high; `away` is below them all and outside them
+const TAP_REM = 0.5; // = --sp-2: a move shorter than this is a tap, not a drag
 /**
- * Sheet — the SINGLE sheet: one card as a bottom sheet holding what the member ACTS on (controls, or small `Card sm`
- * content cards). Always the full height of its box — a Step or a SheetStage — a state is only how far it slid.
- * Shape: handle · head (a CardHead, a SheetHead — or ONE label Row carrying a Check/Toggle, when the sheet's
- * whole ask is that switch and peek must show it) · SheetBody (the only part that scrolls). Written top-down.
- * It FINISHES on itself: a `CardFoot` as its last child holds the one button that completes it — standing at the bottom at
- * half / 3q / full, gone at peek. Never an ActionBar in front of a sheet (a bar is the base's). Nothing in the body commits
- * on its own. Older note — its own buttons only on a
- * screen with no bar (the map sheet). Called sheets: several `Sheet state="away" states="peek full"` in one Step, each with an `id` a
- * button names — one on the screen at a time; never beside a pager. This is the single sheet; the menu of stacked sheets is `SheetStack`.
+ * Sheet — the SINGLE sheet: one card as a bottom sheet holding what the member ACTS on. Always the full height of its
+ * box — a Step or a SheetStage — a state is only how far it slid (translate; the material never changes size).
+ * ONE SHAPE, written top-down: handle · head (a CardHead / SheetHead — pinned, never scrolls) · SheetBody (scrolls, as far as
+ * it needs) · CardFoot (the button that finishes the sheet — at the bottom, above the keyboard; gone at peek).
+ *
+ * It is a COMPONENT, not a wiring: it knows nothing of what opens it. The app owns `state` and sets it from whatever it
+ * likes — a button, a route, a timer: `<Btn onClick={() => setSheet('full')}>` … `<Sheet state={sheet} onStateChange={setSheet}>`.
+ * Its own behaviour stays inside it and only ever ASKS (`onStateChange`): a tap on the handle toggles its own state ↔ peek,
+ * a drag snaps to the nearest of `states`, focus in a peeked sheet raises it, and when the cut moves (the keyboard) it
+ * climbs until the focused control has room above the foot.
  */
-export function Sheet({ state = 'half', raised, handle = true, states, className, children, ...rest }) {
-    return (_jsxs("article", { className: cx('card sheet', `sheet--${state}`, raised && 'sheet--raised', className), "data-sheet-states": states, inert: state === 'away' || undefined, ...rest, children: [handle !== false && _jsx("button", { className: "sheet__handle", type: "button", "aria-label": typeof handle === 'string' ? handle : 'Resize' }), children] }));
+export function Sheet({ state, defaultState = 'half', onStateChange, states, raised, handle = true, className, children, onFocus, ...rest }) {
+    const [inner, setInner] = useState(defaultState);
+    const current = state ?? inner;
+    const controlled = state !== undefined;
+    const ref = useRef(null);
+    const handleRef = useRef(null);
+    const home = useRef(current !== 'peek' && current !== 'away' ? current : 'half'); // where a tap from peek returns to
+    const was = useRef(current);
+    const skipClick = useRef(false);
+    const drag = useRef(null);
+    const allowed = useCallback(() => {
+        const list = (typeof states === 'string' ? states.split(/\s+/) : [...(states ?? [])]).filter((s) => ORDER.includes(s));
+        return list.length ? ORDER.filter((s) => list.includes(s)) : [...ORDER];
+    }, [states]);
+    const request = useCallback((next, reason) => {
+        if (next === current)
+            return;
+        if (!controlled)
+            setInner(next);
+        onStateChange?.(next, reason);
+    }, [current, controlled, onStateChange]);
+    useEffect(() => {
+        if (current !== 'peek' && current !== 'away')
+            home.current = current;
+        if (was.current === 'away' && current !== 'away')
+            handleRef.current?.focus({ preventScroll: true }); // it just came onto the screen: the keyboard user is on it
+        was.current = current;
+    }, [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 */
+    const slid = (el) => {
+        const box = (el.offsetParent ?? el.parentElement);
+        return el.getBoundingClientRect().top - (box.getBoundingClientRect().top + box.clientTop + el.offsetTop);
+    };
+    const stopsOf = (el) => {
+        const cs = getComputedStyle(el), height = el.getBoundingClientRect().height;
+        return {
+            full: 0,
+            half: height * (parseFloat(cs.getPropertyValue('--sheet-half')) || 0),
+            '3q': height * (parseFloat(cs.getPropertyValue('--sheet-3q')) || 0),
+            peek: height - (parseFloat(cs.getPropertyValue('--sheet-peek')) || 0), // registered in tokens.css: reads back resolved
+        };
+    };
+    /* bring a control into the part of the body that shows — between the pinned head and the foot's strip on the cut. The sheet asks
+       for the lowest of its states, from the current one (or `atLeast`) upward, that has room; if none has, its highest. */
+    const reveal = useCallback((target, reason, atLeast) => {
+        const el = ref.current;
+        if (!el || !target || !el.contains(target) || target.closest('.sheet__handle') || current === 'away')
+            return;
+        const control = target.closest('.field') ?? target; // the control's box, not the bare input inside it
+        const list = allowed(), stops = stopsOf(el);
+        const from = Math.max(list.indexOf(current), atLeast ? list.indexOf(atLeast) : -1, 0);
+        const rect = el.getBoundingClientRect();
+        const restTop = rect.top - slid(el);
+        const bodyTop = (el.querySelector(':scope > .sheet__body') ?? el).getBoundingClientRect().top - rect.top;
+        const box = el.parentElement.getBoundingClientRect(); // what clips it: the Step or the SheetStage
+        const vv = window.visualViewport;
+        const edge = Math.min(box.bottom, restTop + rect.height); // the sheet's own bottom edge at rest — above the box's on a stage that gave the keyboard its room
+        const cut = Math.min(edge, vv ? vv.offsetTop + vv.height : Infinity);
+        const button = el.querySelector(':scope > .card__foot')?.firstElementChild; // the foot's button stands on that edge at every state: the control has to clear its strip too
+        const need = control.getBoundingClientRect().height + (button ? edge - button.getBoundingClientRect().top : 0);
+        let to = list[list.length - 1];
+        for (let i = from; i < list.length; i++)
+            if (cut - (restTop + stops[list[i]] + bodyTop) >= need) {
+                to = list[i];
+                break;
+            }
+        request(to, reason);
+        requestAnimationFrame(() => control.scrollIntoView({ block: 'nearest' })); // after the state (and its scroll-padding) landed
+    }, [allowed, current, request]);
+    /* the cut moved — the keyboard came up (the Step shrank by --kb, or the layout viewport did), the phone turned: if a control
+       in this sheet has the focus, make sure it still shows */
+    useEffect(() => {
+        const el = ref.current;
+        if (!el || typeof ResizeObserver === 'undefined')
+            return;
+        let first = true;
+        const ro = new ResizeObserver(() => {
+            if (first) {
+                first = false;
+                return;
+            }
+            const at = document.activeElement;
+            if (at && el.contains(at))
+                reveal(at, 'keyboard');
+        });
+        ro.observe(el);
+        if (el.parentElement)
+            ro.observe(el.parentElement);
+        return () => ro.disconnect();
+    }, [reveal]);
+    const focus = (e) => {
+        onFocus?.(e);
+        if (current !== 'peek' || e.target.closest('.sheet__handle'))
+            return;
+        const body = ref.current?.querySelector(':scope > .sheet__body');
+        if (body)
+            body.scrollTop = 0; // the browser's own reveal scrolled it against the peek strip: start over
+        reveal(e.target, 'focus', home.current);
+    };
+    const tap = () => {
+        if (skipClick.current) {
+            skipClick.current = false;
+            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');
+    };
+    const down = (e) => {
+        const el = ref.current;
+        if (!el || !e.isPrimary || e.button !== 0)
+            return;
+        const list = allowed(), stops = stopsOf(el), y = slid(el); // where it is now — mid-slide too, so a grab never jumps
+        drag.current = { startY: e.clientY, y0: y, y, stops, allowed: list, moved: false,
+            min: Math.min(...list.map((s) => stops[s])), max: Math.max(...list.map((s) => stops[s])),
+            tap: TAP_REM * parseFloat(getComputedStyle(document.documentElement).fontSize) };
+        e.currentTarget.setPointerCapture(e.pointerId);
+    };
+    const move = (e) => {
+        const d = drag.current, el = ref.current;
+        if (!d || !el || !e.isPrimary)
+            return;
+        const dy = e.clientY - d.startY;
+        if (!d.moved) {
+            if (Math.abs(dy) < d.tap)
+                return;
+            d.moved = true;
+            el.classList.add('is-dragging');
+        }
+        d.y = Math.min(Math.max(d.y0 + dy, d.min), d.max); // never above full, never below its lowest state
+        el.style.setProperty('--_drag', `${d.y - d.y0}px`); // the one thing written while held — the CSS adds it to the state's translate
+    };
+    const up = () => {
+        const d = drag.current, el = ref.current;
+        drag.current = null;
+        if (!d || !el)
+            return;
+        el.classList.remove('is-dragging');
+        if (!d.moved)
+            return; // a tap: the click that follows toggles
+        el.style.removeProperty('--_drag'); // same state, or the app says no: it eases back on its own
+        request(d.allowed.reduce((a, b) => (Math.abs(d.stops[b] - d.y) < Math.abs(d.stops[a] - d.y) ? b : a)), 'drag');
+        skipClick.current = true;
+        requestAnimationFrame(() => { skipClick.current = false; });
+    };
+    return (_jsxs("article", { ref: ref, className: cx('card sheet', `sheet--${current}`, raised && 'sheet--raised', className), inert: current === 'away' || undefined, onFocus: focus, ...rest, children: [handle !== false && (_jsx("button", { ref: handleRef, className: "sheet__handle", type: "button", "aria-label": typeof handle === 'string' ? handle : 'Resize', onClick: tap, onPointerDown: down, onPointerMove: move, onPointerUp: up, onPointerCancel: up })), children] }));
 }

package/dist/sheets/SheetBody.d.ts

@@ -1,5 +1,5 @@
-import type { ComponentPropsWithoutRef } from 'react';
-export interface SheetBodyProps extends ComponentPropsWithoutRef<'div'> {
+import type { ComponentProps } from 'react';
+export interface SheetBodyProps extends ComponentProps<'div'> {
 }
 /** SheetBody — everything under a Sheet's head: the one thing that scrolls; its scroll padding keeps a focused control above the cut. Content never goes straight into the Sheet. */
 export declare function SheetBody({ className, ...rest }: SheetBodyProps): import("react").JSX.Element;

package/dist/sheets/SheetHead.d.ts

@@ -1,5 +1,5 @@
-import type { ComponentPropsWithoutRef, ReactNode } from 'react';
-export interface SheetHeadProps extends Omit<ComponentPropsWithoutRef<'div'>, 'title'> {
+import type { ComponentProps, ReactNode } from 'react';
+export interface SheetHeadProps extends Omit<ComponentProps<'div'>, 'title'> {
     /** the round button on the left (an IconBtn sm) */
     lead?: ReactNode;
     /** the centred title */