@usableapp/cardds 0.3.0 → 0.4.1

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/Drawer.d.ts

@@ -1,24 +1,24 @@
-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`). */
+     *  opening played backwards — then calls `onClosed`, where the app stops rendering it (and its `SheetStage dim`). */
     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
+ * Modal — the ask: ONE card at the centre of a `SheetStage dim`, 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 ComponentPropsWithoutRef<'div'> {
+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 */
@@ -26,7 +26,7 @@ export interface DrawerProps extends Omit<ComponentPropsWithoutRef<'div'>, 'titl
 }
 /** 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

@@ -2,7 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 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
+ * Modal — the ask: ONE card at the centre of a `SheetStage dim`, 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

package/dist/sheets/Sheet.d.ts

@@ -1,11 +1,11 @@
-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';
 /** 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<ComponentPropsWithoutRef<'article'>, 'onChange'> {
+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;
@@ -16,8 +16,6 @@ export interface SheetProps extends Omit<ComponentPropsWithoutRef<'article'>, 'o
     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; `false` for a sheet with no handle, a string sets its accessible name */
     handle?: boolean | string;
 }
@@ -33,5 +31,5 @@ export interface SheetProps extends Omit<ComponentPropsWithoutRef<'article'>, 'o
  * 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, defaultState, onStateChange, states, raised, handle, className, children, onFocus, ...rest }: SheetProps): import("react").JSX.Element;
+export declare function Sheet({ state, defaultState, onStateChange, states, handle, className, children, onFocus, ...rest }: SheetProps): import("react").JSX.Element;
 export {};

package/dist/sheets/Sheet.js

@@ -15,7 +15,7 @@ const TAP_REM = 0.5; // = --sp-2: a move shorter than this is a tap, not a drag
  * 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, defaultState = 'half', onStateChange, states, raised, handle = true, className, children, onFocus, ...rest }) {
+export function Sheet({ state, defaultState = 'half', onStateChange, states, handle = true, className, children, onFocus, ...rest }) {
     const [inner, setInner] = useState(defaultState);
     const current = state ?? inner;
     const controlled = state !== undefined;
@@ -158,5 +158,5 @@ export function Sheet({ state, defaultState = 'half', onStateChange, states, rai
         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] }));
+    return (_jsxs("article", { ref: ref, className: cx('card sheet', `sheet--${current}`, 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 */

package/dist/sheets/SheetStack.d.ts

@@ -1,5 +1,5 @@
-import type { ComponentPropsWithoutRef, ReactNode } from 'react';
-export interface SheetStackProps extends ComponentPropsWithoutRef<'div'> {
+import type { ComponentProps, ReactNode } from 'react';
+export interface SheetStackProps extends ComponentProps<'div'> {
     /** `tap` (default): a tapped head brings its sheet to the front, its back button returns it · `display`: the giant title is the peek (recents, a library) · `static`: peeks only, the last sheet open */
     mode?: 'tap' | 'display' | 'static';
     /** CONTROLLED (tap mode): which sheet is open — its index among the children, first = 0 — or `null` for none. The app owns it (a route, a
@@ -7,7 +7,7 @@ export interface SheetStackProps extends ComponentPropsWithoutRef<'div'> {
     open?: number | null;
     /** UNCONTROLLED: the sheet open on arrival (default none); the stack then keeps its own */
     defaultOpen?: number | null;
-    /** the stack ASKS: a peeked head was tapped (its index), or the open sheet's `CardBack` (`null`) */
+    /** the stack ASKS: a peeked head was tapped (its index), or the open sheet's `StackBack` (`null`) */
     onOpenChange?: (open: number | null) => void;
     /** wider peeks so more of each title shows (display stacks) */
     fanned?: boolean;
@@ -20,14 +20,14 @@ export interface SheetStackProps extends ComponentPropsWithoutRef<'div'> {
  * SheetStack — the MENU: sheets stacked like paper at the middle of the home screen, every one a main section.
  * Children are Cards, direct children only, at most five: first = the back of the stack, last = the front (open) sheet.
  * Every sheet is the stack's full height; a peek is the strip the next sheet doesn't cover. A stack head is a CardHead
- * with CHILDREN, in this order: `<CardBack />` (tap mode), `<Text level="h2" caps>Shopping</Text>`, an `<IconRow>` of Icons —
+ * with CHILDREN, in this order: `<StackBack />` (tap mode), `<Text level="h2" caps>Shopping</Text>`, an `<IconRow>` of Icons —
  * never the `heading` prop (it wraps the h2 in a div; the stack's one-line peek needs the bare h2). Put it last in a `Screen fill`, it bleeds
  * off the bottom. `closed`: nothing open on arrival — every head peeks at the bottom and the base above shows `base` (a home screen
  * 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, the open
- * sheet's CardBack. How the sheets MOVE is its own too: sheets are rigid — the tapped one slides up, the ones after it leave below, the ones
+ * sheet's StackBack. 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.
  */
 export declare function SheetStack({ mode, open, defaultOpen, onOpenChange, fanned, closed, base, className, children, onClick, ...rest }: SheetStackProps): import("react").JSX.Element;

package/dist/sheets/SheetStack.js

@@ -12,14 +12,14 @@ const sheetsOf = (stack) => [...stack.children]
  * SheetStack — the MENU: sheets stacked like paper at the middle of the home screen, every one a main section.
  * Children are Cards, direct children only, at most five: first = the back of the stack, last = the front (open) sheet.
  * Every sheet is the stack's full height; a peek is the strip the next sheet doesn't cover. A stack head is a CardHead
- * with CHILDREN, in this order: `<CardBack />` (tap mode), `<Text level="h2" caps>Shopping</Text>`, an `<IconRow>` of Icons —
+ * with CHILDREN, in this order: `<StackBack />` (tap mode), `<Text level="h2" caps>Shopping</Text>`, an `<IconRow>` of Icons —
  * never the `heading` prop (it wraps the h2 in a div; the stack's one-line peek needs the bare h2). Put it last in a `Screen fill`, it bleeds
  * off the bottom. `closed`: nothing open on arrival — every head peeks at the bottom and the base above shows `base` (a home screen
  * 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, the open
- * sheet's CardBack. How the sheets MOVE is its own too: sheets are rigid — the tapped one slides up, the ones after it leave below, the ones
+ * sheet's StackBack. 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.
  */
 export function SheetStack({ mode = 'tap', open, defaultOpen = null, onOpenChange, fanned, closed, base, className, children, onClick, ...rest }) {
@@ -75,7 +75,7 @@ export function SheetStack({ mode = 'tap', open, defaultOpen = null, onOpenChang
         const target = e.target;
         const sheets = sheetsOf(stack);
         const at = sheets.findIndex((c) => c.contains(target)); // the sheet the tap landed in — not the nearest .card: a content card inside an open sheet must not count
-        if (target.closest('.card__back')) {
+        if (target.closest('.sheet-stack__back')) {
             request(null);
             return;
         }

package/dist/sheets/SheetStage.d.ts

@@ -1,20 +1,18 @@
-import type { ComponentPropsWithoutRef, ReactNode } from 'react';
-export interface SheetStageProps extends ComponentPropsWithoutRef<'div'> {
+import type { ComponentProps, ReactNode } from 'react';
+export interface SheetStageProps extends ComponentProps<'div'> {
     /** what sits behind the sheet: a map, previous cards, page copy */
     bg?: ReactNode;
     /** ONE thing shown in the band a half sheet leaves open (a postcard being made), centred there */
     hero?: ReactNode;
     /** blur and darken the background (the dim page sheet) */
     dim?: boolean;
-    /** the ask stage: the page under a scrim, one Modal (Lift + Drawer) at the centre */
-    ask?: boolean;
-    /** a footnote strip on the scrim under a raised sheet */
+    /** a footnote strip at the stage's bottom, on the scrim */
     foot?: ReactNode;
 }
 /**
  * SheetStage — a page-level overlay stage, its own 100dvh page: a Sheet over a map (or over a `hero` — one
  * thing centred in the band a half sheet leaves open), the dim page sheet
- * (`dim` + `Sheet raised`), the ask drawer (`ask` + Lift + Drawer). Full stops under the top bar's line.
+ * (`dim` + a `Modal`), the ask (`dim` + a `Modal`, which centres itself — or a Modal on a clean ground, no `dim`). Full stops under the top bar's line.
  * NEVER inside a Step — an app screen where the member acts is a Step.
  */
-export declare function SheetStage({ bg, hero, dim, ask, foot, className, children, ...rest }: SheetStageProps): import("react").JSX.Element;
+export declare function SheetStage({ bg, hero, dim, foot, className, children, ...rest }: SheetStageProps): import("react").JSX.Element;

package/dist/sheets/SheetStage.js

@@ -3,9 +3,9 @@ import { cx } from '../cx.js';
 /**
  * SheetStage — a page-level overlay stage, its own 100dvh page: a Sheet over a map (or over a `hero` — one
  * thing centred in the band a half sheet leaves open), the dim page sheet
- * (`dim` + `Sheet raised`), the ask drawer (`ask` + Lift + Drawer). Full stops under the top bar's line.
+ * (`dim` + a `Modal`), the ask (`dim` + a `Modal`, which centres itself — or a Modal on a clean ground, no `dim`). Full stops under the top bar's line.
  * NEVER inside a Step — an app screen where the member acts is a Step.
  */
-export function SheetStage({ bg, hero, dim, ask, foot, className, children, ...rest }) {
-    return (_jsxs("div", { className: cx('sheet-stage', dim && 'sheet-stage--dim', ask && 'sheet-stage--ask', className), ...rest, children: [bg != null && _jsx("div", { className: "sheet-stage__bg", children: bg }), hero != null && _jsx("div", { className: "sheet-stage__hero", children: hero }), children, foot != null && _jsx("p", { className: "sheet-stage__foot", children: foot })] }));
+export function SheetStage({ bg, hero, dim, foot, className, children, ...rest }) {
+    return (_jsxs("div", { className: cx('sheet-stage', dim && 'sheet-stage--dim', className), ...rest, children: [bg != null && _jsx("div", { className: "sheet-stage__bg", children: bg }), hero != null && _jsx("div", { className: "sheet-stage__hero", children: hero }), children, foot != null && _jsx("p", { className: "sheet-stage__foot", children: foot })] }));
 }

package/dist/sheets/StackBack.d.ts

@@ -0,0 +1,7 @@
+import type { ComponentProps } from 'react';
+export interface StackBackProps extends ComponentProps<'button'> {
+    /** accessible name */
+    label?: string;
+}
+/** StackBack — the back button a tapped stack sheet reveals in its head; first child of that sheet's CardHead. Hidden until the sheet is open. */
+export declare function StackBack({ label, className, ...rest }: StackBackProps): import("react").JSX.Element;

package/dist/sheets/StackBack.js

@@ -0,0 +1,7 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cx } from '../cx.js';
+import { Icon } from '../type/Icon.js';
+/** StackBack — the back button a tapped stack sheet reveals in its head; first child of that sheet's CardHead. Hidden until the sheet is open. */
+export function StackBack({ label = 'Back', className, ...rest }) {
+    return (_jsx("button", { type: "button", className: cx('icon-btn icon-btn--sm sheet-stack__back', className), "aria-label": label, ...rest, children: _jsx(Icon, { name: "arrow-left" }) }));
+}

package/dist/sheets/Step.d.ts

@@ -1,5 +1,5 @@
-import type { ComponentPropsWithoutRef } from 'react';
-export interface StepProps extends ComponentPropsWithoutRef<'section'> {
+import type { ComponentProps } from 'react';
+export interface StepProps extends ComponentProps<'section'> {
 }
 /**
  * Step — one screen, one task. Children: a BaseContent first (what the member READS — words on the base, not a card), an optional Sheet last

package/dist/type/Icon.d.ts

@@ -1,16 +1,31 @@
-import { type IconName } from './icons.js';
-export type { IconName };
-export interface IconProps extends Omit<React.ComponentPropsWithoutRef<'svg'>, 'children'> {
-    /** one of the 57 Lucide symbols in icons.svg (arrow-left, bell, check, chevron-down, id-card, plus, x, …) */
-    name: IconName;
+import type { ReactNode } from 'react';
+import { type IconName as StockIconName } from './icons.js';
+/** an icon's name: one of the stock symbols (autocompleted) — or any name a project registered with `registerIcons` */
+export type IconName = StockIconName | (string & {});
+/**
+ * registerIcons — a project's OWN icons, by name: after this, `icon="map-pin"` works on every component that takes an icon (Icon, IconBtn,
+ * Field, MenuItem, Tile…), exactly like a stock one. Call it once at startup. A drawing is the INSIDE of the `<svg>` as a string (paths on a
+ * 24×24 box, drawn with the shared stroke), or `{ body, attrs }` to bring its own viewBox / fill. A registered name wins over a stock one —
+ * that is how a project swaps a symbol for its own. Returns nothing; safe to call again (later drawings replace earlier ones).
+ */
+export declare function registerIcons(icons: Record<string, string | {
+    body: string;
+    attrs?: Record<string, string>;
+}>): void;
+export interface IconProps extends Omit<React.ComponentProps<'svg'>, 'children' | 'name'> {
+    /** a stock symbol (arrow-left, bell, check, chevron-down, id-card, plus, x, …) or a name the project registered (`registerIcons`). Omit it to draw with `children`. */
+    name?: IconName;
+    /** a ONE-OFF drawing: the svg's own children (`<path d="…" />`), on a 24×24 box with the shared stroke — for an icon not worth registering */
+    children?: ReactNode;
     /** xs = 16px, inside captions, chips and links · sm = in a small icon button or a field (28px today — one size everywhere, tokens.css) · md (default) = the 28px icon · lg = 32px, empty states */
     size?: 'xs' | 'sm' | 'md' | 'lg';
     /** an accessible name makes the icon meaningful (role="img"); without one it is decorative and hidden from assistive tech */
     label?: string;
 }
 /**
- * Icon — a Lucide stroke icon from the cardds sprite, inlined (no icons.svg file needed at runtime).
+ * Icon — a stroke icon, inlined (no sprite file at runtime): one of the stock Lucide symbols, one of the project's OWN (`registerIcons`), or a
+ * one-off drawn with `children`. The set is open — a project never comes to cardds for an icon.
  * Sizes are the tokens the CSS defines: `.icon` 28px, `--sm` 28px (a semantic size, same as md today), `--xs` 16px, `--lg` 32px.
  * Keep it big: inside a button or a row the default 28px icon is the norm; xs only sits in text.
  */
-export declare function Icon({ name, size, label, className, ...rest }: IconProps): import("react").JSX.Element;
+export declare function Icon({ name, children, size, label, className, ...rest }: IconProps): import("react").JSX.Element;

package/dist/type/Icon.js

@@ -1,12 +1,35 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { cx } from '../cx.js';
 import { ICONS } from './icons.js';
+/* the stroke style every stock symbol shares (Lucide): a project's drawing takes it unless it brings its own attrs */
+const STROKE = { viewBox: '0 0 24 24', fill: 'none', stroke: 'currentColor', strokeWidth: '2', strokeLinecap: 'round', strokeLinejoin: 'round' };
+const OWN = new Map();
 /**
- * Icon — a Lucide stroke icon from the cardds sprite, inlined (no icons.svg file needed at runtime).
+ * registerIcons — a project's OWN icons, by name: after this, `icon="map-pin"` works on every component that takes an icon (Icon, IconBtn,
+ * Field, MenuItem, Tile…), exactly like a stock one. Call it once at startup. A drawing is the INSIDE of the `<svg>` as a string (paths on a
+ * 24×24 box, drawn with the shared stroke), or `{ body, attrs }` to bring its own viewBox / fill. A registered name wins over a stock one —
+ * that is how a project swaps a symbol for its own. Returns nothing; safe to call again (later drawings replace earlier ones).
+ */
+export function registerIcons(icons) {
+    for (const [name, d] of Object.entries(icons))
+        OWN.set(name, typeof d === 'string' ? { attrs: STROKE, body: d } : { attrs: { ...STROKE, ...d.attrs }, body: d.body });
+}
+const warned = new Set();
+/**
+ * Icon — a stroke icon, inlined (no sprite file at runtime): one of the stock Lucide symbols, one of the project's OWN (`registerIcons`), or a
+ * one-off drawn with `children`. The set is open — a project never comes to cardds for an icon.
  * Sizes are the tokens the CSS defines: `.icon` 28px, `--sm` 28px (a semantic size, same as md today), `--xs` 16px, `--lg` 32px.
  * Keep it big: inside a button or a row the default 28px icon is the norm; xs only sits in text.
  */
-export function Icon({ name, size = 'md', label, className, ...rest }) {
-    const icon = ICONS[name];
-    return (_jsx("svg", { ...icon.attrs, className: cx('icon', size !== 'md' && `icon--${size}`, className), role: label ? 'img' : undefined, "aria-label": label, "aria-hidden": label ? undefined : true, dangerouslySetInnerHTML: { __html: icon.body }, ...rest }));
+export function Icon({ name, children, size = 'md', label, className, ...rest }) {
+    const icon = name === undefined ? undefined : OWN.get(name) ?? ICONS[name];
+    if (name !== undefined && !icon && !warned.has(name)) {
+        warned.add(name);
+        console.warn(`cardds Icon: no icon named "${name}" — a stock name is misspelt, or the project has not registered it (registerIcons)`);
+    }
+    const shared = { className: cx('icon', size !== 'md' && `icon--${size}`, className), role: label ? 'img' : undefined, 'aria-label': label, 'aria-hidden': label ? undefined : true };
+    // an unknown name draws nothing but keeps its box — a missing icon never takes a screen down
+    if (!icon)
+        return _jsx("svg", { ...STROKE, ...shared, ...rest, children: children });
+    return _jsx("svg", { ...icon.attrs, ...shared, dangerouslySetInnerHTML: { __html: icon.body }, ...rest });
 }

package/dist/type/Text.d.ts

@@ -1,5 +1,7 @@
 export type TextLevel = 'display' | 'h1' | 'h2' | 'title' | 'body' | 'label' | 'caption' | 'overline' | 'stat';
 export interface TextProps extends React.HTMLAttributes<HTMLElement> {
+    /** the element it renders (React 19 passes `ref` as a prop) */
+    ref?: React.Ref<HTMLElement>;
     /** the type level: display (hero words) · h1 · h2 (a card's heading) · title · body · label · caption · overline (small caps above a heading) · stat (a big number) */
     level: TextLevel;
     /** stat only: the one giant number on a sheet (`.t-stat--xl`) */
@@ -8,6 +10,8 @@ export interface TextProps extends React.HTMLAttributes<HTMLElement> {
     mono?: boolean;
     /** muted ink — follows the card it sits in */
     muted?: boolean;
+    /** takes the remaining room of a row (a heading beside a chip in a flex head) */
+    grow?: boolean;
     /** uppercase */
     caps?: boolean;
     /** the element; defaults per level (h2 for display/h1/h2, p for title/body/stat, span for the rest) */
@@ -18,7 +22,9 @@ export interface TextProps extends React.HTMLAttributes<HTMLElement> {
  * Headings inside a card head are h2 by default; a screen title in a TopBar is h1.
  * Everything scales from the root font-size, so there are no pixel sizes to pick.
  */
-export declare function Text({ level, xl, mono, muted, caps, as, className, ...rest }: TextProps): import("react").DetailedReactHTMLElement<{
+export declare function Text({ level, xl, mono, muted, caps, grow, as, className, ...rest }: TextProps): import("react").DetailedReactHTMLElement<{
+    /** the element it renders (React 19 passes `ref` as a prop) */
+    ref?: React.Ref<HTMLElement>;
     defaultChecked?: boolean | undefined;
     defaultValue?: string | number | readonly string[] | undefined;
     suppressContentEditableWarning?: boolean | undefined;