@usableapp/cardds 0.2.2 → 0.3.0

package/dist/choice/Calendar.d.ts

@@ -1,13 +1,23 @@
-import type { ComponentPropsWithoutRef, ReactNode } from 'react';
-export interface CalendarProps extends Omit<ComponentPropsWithoutRef<'div'>, 'title'> {
+import { type ComponentPropsWithoutRef, type ReactNode } from 'react';
+export interface CalendarProps extends Omit<ComponentPropsWithoutRef<'div'>, 'title' | 'onSelect'> {
     /** the month shown ("June") */
     title: ReactNode;
     /** days in the month */
     days?: number;
     /** weekday column of the 1st (1 = first column) */
     start?: number;
-    /** the selected day */
-    selected?: number;
+    /** CONTROLLED: the picked day, or `null` for none. The app owns it — pair it with `onSelect`. (`undefined` = uncontrolled.) */
+    selected?: number | null;
+    /** UNCONTROLLED: the day picked on arrival; the calendar then keeps its own */
+    defaultSelected?: number;
+    /** a day was tapped */
+    onSelect?: (day: number) => void;
+    /** the head's two buttons: the app turns the month (it owns `title`, `days`, `start`) */
+    onPrev?: () => void;
+    onNext?: () => void;
+    /** their accessible names */
+    prevLabel?: string;
+    nextLabel?: string;
     /** softly marked days */
     marks?: number[];
     /** strongly marked days */
@@ -19,5 +29,6 @@ export interface CalendarProps extends Omit<ComponentPropsWithoutRef<'div'>, 'ti
     /** replace the default prev/next icon buttons */
     nav?: ReactNode;
 }
-/** Calendar — a month grid of 44px round cells: one accent day, optional marks; prev/next in the head. */
-export declare function Calendar({ title, days, start, selected, marks, marks2, disabled, weekdays, nav, className, ...rest }: CalendarProps): import("react").JSX.Element;
+/** Calendar — a month grid of 44px round cells: one accent day, optional marks; prev/next in the head. It shows ONE month and knows no dates:
+ *  the app owns which month (`title`, `days`, `start` + `onPrev` / `onNext`) and which day (`selected` + `onSelect`, or `defaultSelected`). */
+export declare function Calendar({ title, days, start, selected, defaultSelected, onSelect, onPrev, onNext, prevLabel, nextLabel, marks, marks2, disabled, weekdays, nav, className, ...rest }: CalendarProps): import("react").JSX.Element;

package/dist/choice/Calendar.js

@@ -1,7 +1,13 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
 import { cx } from '../cx.js';
 import { IconBtn } from '../actions/IconBtn.js';
-/** Calendar — a month grid of 44px round cells: one accent day, optional marks; prev/next in the head. */
-export function Calendar({ title, days = 30, start = 1, selected, marks = [], marks2 = [], disabled = [], weekdays = ['Su', 'Mo', 'Tu', 'We', 'Th', 'Fr', 'Sa'], nav, className, ...rest }) {
-    return (_jsxs("div", { className: cx('calendar', className), ...rest, children: [_jsxs("div", { className: "calendar__head", children: [_jsx("span", { className: "t-title", children: title }), nav ?? (_jsxs("span", { className: "icon-row", children: [_jsx(IconBtn, { sm: true, icon: "chevron-left", label: "Previous" }), _jsx(IconBtn, { sm: true, icon: "chevron-right", label: "Next" })] }))] }), _jsxs("div", { className: "calendar__grid", children: [weekdays.map((d) => _jsx("span", { className: "calendar__wd", children: d }, d)), Array.from({ length: days }, (_, i) => i + 1).map((d) => (_jsx("button", { type: "button", className: cx('calendar__day', marks.includes(d) && 'calendar__day--mark', marks2.includes(d) && 'calendar__day--mark2'), "aria-selected": d === selected ? 'true' : undefined, disabled: disabled.includes(d), style: d === 1 ? { '--start': start } : undefined, children: d }, d)))] })] }));
+/** Calendar — a month grid of 44px round cells: one accent day, optional marks; prev/next in the head. It shows ONE month and knows no dates:
+ *  the app owns which month (`title`, `days`, `start` + `onPrev` / `onNext`) and which day (`selected` + `onSelect`, or `defaultSelected`). */
+export function Calendar({ title, days = 30, start = 1, selected, defaultSelected, onSelect, onPrev, onNext, prevLabel = 'Previous', nextLabel = 'Next', marks = [], marks2 = [], disabled = [], weekdays = ['Su', 'Mo', 'Tu', 'We', 'Th', 'Fr', 'Sa'], nav, className, ...rest }) {
+    const [inner, setInner] = useState(defaultSelected);
+    const day = selected !== undefined ? selected : inner;
+    const pick = (d) => { if (selected === undefined)
+        setInner(d); onSelect?.(d); };
+    return (_jsxs("div", { className: cx('calendar', className), ...rest, children: [_jsxs("div", { className: "calendar__head", children: [_jsx("span", { className: "t-title", children: title }), nav ?? (_jsxs("span", { className: "icon-row", children: [_jsx(IconBtn, { sm: true, icon: "chevron-left", label: prevLabel, onClick: onPrev }), _jsx(IconBtn, { sm: true, icon: "chevron-right", label: nextLabel, onClick: onNext })] }))] }), _jsxs("div", { className: "calendar__grid", children: [weekdays.map((d) => _jsx("span", { className: "calendar__wd", children: d }, d)), Array.from({ length: days }, (_, i) => i + 1).map((d) => (_jsx("button", { type: "button", className: cx('calendar__day', marks.includes(d) && 'calendar__day--mark', marks2.includes(d) && 'calendar__day--mark2'), "aria-selected": d === day ? 'true' : undefined, onClick: () => pick(d), disabled: disabled.includes(d), style: d === 1 ? { '--start': start } : undefined, children: d }, d)))] })] }));
 }

package/dist/choice/Slider.d.ts

@@ -8,4 +8,4 @@ export interface SliderProps extends Omit<ComponentPropsWithoutRef<'input'>, 'cl
     style?: React.CSSProperties;
 }
 /** Slider — one value along a hairline rail with a 48px knob; the whole range is thumb-tall. */
-export declare function Slider({ label, glyph, className, style, ...input }: SliderProps): import("react").JSX.Element;
+export declare function Slider({ label, glyph, className, style, onInput, ...input }: SliderProps): import("react").JSX.Element;

package/dist/choice/Slider.js

@@ -2,13 +2,17 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useRef } from 'react';
 import { cx } from '../cx.js';
 /** Slider — one value along a hairline rail with a 48px knob; the whole range is thumb-tall. */
-export function Slider({ label, glyph, className, style, ...input }) {
+export function Slider({ label, glyph, className, style, onInput, ...input }) {
     const range = useRef(null);
-    // the knob's place is published by cardds.js on every input event; on mount it publishes once
-    // for the value the slider starts at, so a glyph sits on the knob before the first move
-    useEffect(() => {
-        if (glyph != null && range.current)
-            range.current.dispatchEvent(new Event('input', { bubbles: true }));
-    }, [glyph]);
-    return (_jsxs("label", { className: cx('slider', className), style: style, children: [label != null && _jsx("span", { className: "slider__label", children: label }), glyph != null && _jsx("span", { className: "slider__glyph", "aria-hidden": "true", children: glyph }), _jsx("input", { ref: range, className: "slider__range", type: "range", ...input })] }));
+    const box = useRef(null);
+    // the knob's place along the rail, 0..1, published on the slider as --slider-at so the glyph can ride the knob (choice.css)
+    const place = () => {
+        const r = range.current;
+        if (!r || !box.current)
+            return;
+        const min = Number(r.min) || 0, max = Number(r.max) || 100;
+        box.current.style.setProperty('--slider-at', String(max > min ? Math.min(1, Math.max(0, (Number(r.value) - min) / (max - min))) : 0));
+    };
+    useEffect(place); // after every render: a controlled value, a new min / max
+    return (_jsxs("label", { ref: box, className: cx('slider', className), style: style, children: [label != null && _jsx("span", { className: "slider__label", children: label }), glyph != null && _jsx("span", { className: "slider__glyph", "aria-hidden": "true", children: glyph }), _jsx("input", { ref: range, className: "slider__range", type: "range", onInput: (e) => { place(); onInput?.(e); }, ...input })] }));
 }

package/dist/forms/Pin.d.ts

@@ -1,19 +1,22 @@
 import { type ComponentPropsWithoutRef } from 'react';
-export interface PinProps extends Omit<ComponentPropsWithoutRef<'div'>, 'onChange'> {
+export interface PinProps extends Omit<ComponentPropsWithoutRef<'div'>, 'onChange' | 'defaultValue'> {
     /** how many digits (4 or 6) */
     length?: number;
-    /** digits already typed, left to right ("03") */
+    /** CONTROLLED: the digits so far, left to right ("03"). The app owns it — pair it with `onChange`. */
     value?: string;
+    /** UNCONTROLLED: the digits it starts with; the Pin then keeps its own */
+    defaultValue?: string;
     /** accessible name prefix for each cell ("Digit" → "Digit 1") */
     label?: string;
-    /** the code so far, after every keystroke; `complete` once every cell holds a digit */
+    /** the code so far, after every change; `complete` once every cell holds a digit */
     onChange?: (code: string, complete: boolean) => void;
     /** focus the first empty cell on mount */
     autoFocus?: boolean;
 }
 /**
  * Pin — big code entry, one digit per pill; a filled cell turns accent. Lives in a Sheet.
- * Typing a digit moves to the next cell, Backspace in an empty cell moves back, a pasted code fills every cell
- * (cardds.js, delegated — the cells stay plain inputs). The first cell takes the SMS one-time-code autofill.
+ * Its own behaviour, inside it: typing a digit moves to the next cell, Backspace in an empty cell moves back and clears, the
+ * arrows walk the cells, a pasted code fills them from the one it landed in; only digits stay. The first cell takes the SMS
+ * one-time-code autofill. The code is a VALUE, controlled like an input: `value` + `onChange`, or `defaultValue`.
  */
-export declare function Pin({ length, value, label, onChange, autoFocus, className, ...rest }: PinProps): import("react").JSX.Element;
+export declare function Pin({ length, value, defaultValue, label, onChange, autoFocus, className, ...rest }: PinProps): import("react").JSX.Element;

package/dist/forms/Pin.js

@@ -1,27 +1,56 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useEffect, useRef } from 'react';
+import { useEffect, useRef, useState } from 'react';
 import { cx } from '../cx.js';
 /**
  * Pin — big code entry, one digit per pill; a filled cell turns accent. Lives in a Sheet.
- * Typing a digit moves to the next cell, Backspace in an empty cell moves back, a pasted code fills every cell
- * (cardds.js, delegated — the cells stay plain inputs). The first cell takes the SMS one-time-code autofill.
+ * Its own behaviour, inside it: typing a digit moves to the next cell, Backspace in an empty cell moves back and clears, the
+ * arrows walk the cells, a pasted code fills them from the one it landed in; only digits stay. The first cell takes the SMS
+ * one-time-code autofill. The code is a VALUE, controlled like an input: `value` + `onChange`, or `defaultValue`.
  */
-export function Pin({ length = 6, value = '', label = 'Digit', onChange, autoFocus, className, ...rest }) {
+export function Pin({ length = 6, value, defaultValue = '', label = 'Digit', onChange, autoFocus, className, ...rest }) {
     const ref = useRef(null);
+    const [inner, setInner] = useState(defaultValue);
+    const code = (value ?? inner).replace(/\D/g, '').slice(0, length);
+    const cell = (i) => ref.current?.querySelectorAll('.pin__cell')[i];
+    const set = (next) => {
+        next = next.slice(0, length);
+        if (value === undefined)
+            setInner(next);
+        if (next !== code)
+            onChange?.(next, next.length === length);
+    };
     useEffect(() => {
-        const el = ref.current;
-        if (!el || !onChange)
-            return;
-        const on = (e) => { const d = e.detail; onChange(d.code, d.complete); };
-        el.addEventListener('cardds:pin', on);
-        return () => el.removeEventListener('cardds:pin', on);
-    }, [onChange]);
-    useEffect(() => {
-        if (!autoFocus)
-            return;
-        const cells = ref.current?.querySelectorAll('.pin__cell');
-        if (cells)
-            ([...cells].find((c) => !c.value) ?? cells[cells.length - 1])?.focus();
+        if (autoFocus)
+            cell(Math.min(code.length, length - 1))?.focus();
+        // eslint-disable-next-line react-hooks/exhaustive-deps -- on mount only
     }, [autoFocus]);
-    return (_jsx("div", { ref: ref, className: cx('pin', className), ...rest, children: Array.from({ length }, (_, i) => (_jsx("input", { className: "pin__cell", inputMode: "numeric", pattern: "[0-9]*", placeholder: " ", defaultValue: value[i] ?? '', "aria-label": `${label} ${i + 1}`, autoComplete: i === 0 ? 'one-time-code' : 'off' }, i))) }));
+    const input = (i) => (e) => {
+        const digits = e.target.value.replace(/\D/g, '');
+        const at = Math.min(i, code.length); // a code has no gaps: a digit typed further along lands in the first empty cell
+        if (!digits) {
+            set(code.slice(0, at) + code.slice(at + 1));
+            return;
+        }
+        set(code.slice(0, at) + digits + code.slice(at + digits.length)); // a paste (or a typed run) spills over the cells that follow
+        cell(Math.min(at + digits.length, length - 1))?.focus();
+    };
+    const key = (i) => (e) => {
+        if (e.key === 'Backspace' && !e.currentTarget.value && i > 0) {
+            e.preventDefault();
+            set(code.slice(0, i - 1) + code.slice(i));
+            cell(i - 1)?.focus();
+        }
+        else if (e.key === 'ArrowLeft' && i > 0) {
+            e.preventDefault();
+            cell(i - 1)?.focus();
+        }
+        else if (e.key === 'ArrowRight' && i < length - 1) {
+            e.preventDefault();
+            cell(i + 1)?.focus();
+        }
+    };
+    return (_jsx("div", { ref: ref, className: cx('pin', className), ...rest, children: Array.from({ length }, (_, i) => (
+        // no maxLength: the browser would cut a pasted code before this ever saw it. A cell holds one digit — typing into a full one
+        // replaces it, so its digit is selected whenever the cell takes the focus
+        _jsx("input", { className: "pin__cell", inputMode: "numeric", pattern: "[0-9]*", placeholder: " ", value: code[i] ?? '', "aria-label": `${label} ${i + 1}`, autoComplete: i === 0 ? 'one-time-code' : 'off', onChange: input(i), onKeyDown: key(i), onFocus: (e) => e.currentTarget.select() }, i))) }));
 }

package/dist/media/Postcard.d.ts

@@ -1,4 +1,4 @@
-import type { ComponentPropsWithoutRef, ReactNode } from 'react';
+import { type ComponentPropsWithoutRef, type ReactNode } from 'react';
 export interface PostcardProps extends ComponentPropsWithoutRef<'div'> {
     /** the photo on the front; none = the wireframe box */
     photo?: string | null;
@@ -7,14 +7,18 @@ export interface PostcardProps extends ComponentPropsWithoutRef<'div'> {
     name: ReactNode;
     /** the words on the back */
     caption?: ReactNode;
-    /** start turned over */
+    /** CONTROLLED: the back is showing. The app owns it — pair it with `onFlip`. */
     flipped?: boolean;
+    /** UNCONTROLLED: start turned over; the card then keeps its own side */
+    defaultFlipped?: boolean;
+    /** a face was tapped: the side it asks to show */
+    onFlip?: (flipped: boolean) => void;
     frontLabel?: string;
     backLabel?: string;
 }
 /**
  * Postcard — a member's introduction as a card in the hand: the photo (or the wireframe box) with the name in front,
- * the caption on the back; a tap on either face turns it over (cardds.js toggles `is-flipped`, `--motion-flip`).
+ * the caption on the back; a tap on either face turns it over (`--motion-flip`). Which side shows is a state: `flipped` + `onFlip`, or `defaultFlipped`.
  * A voice note, a like, a reply go OUTSIDE it, in a Row under it — a face is a button and holds no button.
  */
-export declare function Postcard({ photo, alt, name, caption, flipped, frontLabel, backLabel, className, ...rest }: PostcardProps): import("react").JSX.Element;
+export declare function Postcard({ photo, alt, name, caption, flipped, defaultFlipped, onFlip, frontLabel, backLabel, className, ...rest }: PostcardProps): import("react").JSX.Element;

package/dist/media/Postcard.js

@@ -1,10 +1,15 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
 import { cx } from '../cx.js';
 /**
  * Postcard — a member's introduction as a card in the hand: the photo (or the wireframe box) with the name in front,
- * the caption on the back; a tap on either face turns it over (cardds.js toggles `is-flipped`, `--motion-flip`).
+ * the caption on the back; a tap on either face turns it over (`--motion-flip`). Which side shows is a state: `flipped` + `onFlip`, or `defaultFlipped`.
  * A voice note, a like, a reply go OUTSIDE it, in a Row under it — a face is a button and holds no button.
  */
-export function Postcard({ photo, alt = '', name, caption, flipped, frontLabel = 'พลิกดูด้านหลัง', backLabel = 'พลิกดูด้านหน้า', className, ...rest }) {
-    return (_jsxs("div", { className: cx('postcard', flipped && 'is-flipped', className), ...rest, children: [_jsxs("button", { className: "postcard__face postcard__front", type: "button", "aria-label": frontLabel, children: [photo ? _jsx("img", { src: photo, alt: alt }) : alt ? _jsx("div", { className: "ph", role: "img", "aria-label": alt }) : _jsx("div", { className: "ph" }), _jsx("span", { className: "postcard__label", children: name })] }), _jsxs("button", { className: "postcard__face postcard__back", type: "button", "aria-label": backLabel, children: [caption != null && _jsx("p", { className: "postcard__caption", children: caption }), _jsx("span", { className: "postcard__label", children: name })] })] }));
+export function Postcard({ photo, alt = '', name, caption, flipped, defaultFlipped = false, onFlip, frontLabel = 'พลิกดูด้านหลัง', backLabel = 'พลิกดูด้านหน้า', className, ...rest }) {
+    const [inner, setInner] = useState(defaultFlipped);
+    const back = flipped ?? inner;
+    const turn = () => { if (flipped === undefined)
+        setInner(!back); onFlip?.(!back); };
+    return (_jsxs("div", { className: cx('postcard', back && 'is-flipped', className), ...rest, children: [_jsxs("button", { className: "postcard__face postcard__front", type: "button", "aria-label": frontLabel, onClick: turn, children: [photo ? _jsx("img", { src: photo, alt: alt }) : alt ? _jsx("div", { className: "ph", role: "img", "aria-label": alt }) : _jsx("div", { className: "ph" }), _jsx("span", { className: "postcard__label", children: name })] }), _jsxs("button", { className: "postcard__face postcard__back", type: "button", "aria-label": backLabel, onClick: turn, children: [caption != null && _jsx("p", { className: "postcard__caption", children: caption }), _jsx("span", { className: "postcard__label", children: name })] })] }));
 }

package/dist/numbers/Picker.d.ts

@@ -1,13 +1,25 @@
 import { type ComponentPropsWithoutRef, type ReactNode } from 'react';
-export interface PickerProps extends ComponentPropsWithoutRef<'div'> {
+export interface PickerProps extends Omit<ComponentPropsWithoutRef<'div'>, 'onChange' | 'defaultValue'> {
+    /** CONTROLLED: the chosen PickerItem's `value`. The app owns it — pair it with `onChange`. */
+    value?: string;
+    /** UNCONTROLLED: the value it starts on; the picker then keeps its own */
+    defaultValue?: string;
+    /** the member settled on a value — scrolled the rail to it, or tapped it */
+    onChange?: (value: string) => void;
     /** the unit under the rail ("hours") */
     unit?: ReactNode;
     label?: string;
 }
-/** Picker — a horizontal snap picker, the centre value big between two accent rules; children are PickerItems. */
-export declare function Picker({ unit, label, className, children, ...rest }: PickerProps): import("react").JSX.Element;
-export interface PickerItemProps extends ComponentPropsWithoutRef<'button'> {
-    selected?: boolean;
+/**
+ * Picker — a horizontal snap picker, the centre value big between two accent rules; children are PickerItems.
+ * It holds a VALUE, controlled like an input: `value` + `onChange`, or `defaultValue`. The value IS the item standing in the centre
+ * of the rail: the picker scrolls the chosen one there, and when the member scrolls (or taps an item) it asks for the one that
+ * settled in the centre. The CSS lights the centred item by scroll position; the app never reads the DOM to know what was picked.
+ */
+export declare function Picker({ value, defaultValue, onChange, unit, label, className, children, ...rest }: PickerProps): import("react").JSX.Element;
+export interface PickerItemProps extends Omit<ComponentPropsWithoutRef<'button'>, 'value'> {
+    /** what choosing this item reports; default = its own text */
+    value?: string;
 }
-/** PickerItem — one value on the Picker rail. */
-export declare function PickerItem({ selected, className, ...rest }: PickerItemProps): import("react").JSX.Element;
+/** PickerItem — one value on the Picker rail; a tap brings it to the centre. */
+export declare function PickerItem({ value, className, children, onClick, ...rest }: PickerItemProps): import("react").JSX.Element;

package/dist/numbers/Picker.js

@@ -1,18 +1,56 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useRef } from 'react';
+import { createContext, useContext, useEffect, useLayoutEffect, useRef, useState } from 'react';
 import { cx } from '../cx.js';
-/** Picker — a horizontal snap picker, the centre value big between two accent rules; children are PickerItems. */
-export function Picker({ unit, label, className, children, ...rest }) {
+const PickerContext = createContext(null);
+/**
+ * Picker — a horizontal snap picker, the centre value big between two accent rules; children are PickerItems.
+ * It holds a VALUE, controlled like an input: `value` + `onChange`, or `defaultValue`. The value IS the item standing in the centre
+ * of the rail: the picker scrolls the chosen one there, and when the member scrolls (or taps an item) it asks for the one that
+ * settled in the centre. The CSS lights the centred item by scroll position; the app never reads the DOM to know what was picked.
+ */
+export function Picker({ value, defaultValue, onChange, unit, label, className, children, ...rest }) {
+    const [inner, setInner] = useState(defaultValue);
+    const current = value ?? inner;
     const rail = useRef(null);
-    useEffect(() => {
-        // start on the selected value, as the demo page does: the CSS lights the item by scroll position
-        const r = rail.current, on = r?.querySelector('[aria-selected="true"]');
-        if (r && on)
-            r.scrollLeft = on.offsetLeft - r.clientWidth / 3;
-    }, []);
-    return (_jsxs("div", { className: cx('picker', className), "aria-label": label, ...rest, children: [_jsx("div", { className: "picker__rail", role: "listbox", ref: rail, children: children }), unit != null && _jsx("span", { className: "picker__unit", children: unit })] }));
+    const mounted = useRef(false);
+    const settle = useRef(null);
+    const pick = (next) => {
+        if (next === current)
+            return;
+        if (value === undefined)
+            setInner(next);
+        onChange?.(next);
+    };
+    const items = () => [...(rail.current?.querySelectorAll(':scope > .picker__item') ?? [])];
+    const column = () => (rail.current ? rail.current.clientWidth / 3 : 0); // the rail is three columns wide; item i stands in the centre at i × one column
+    /* the chosen value stands in the centre — at once on arrival, sliding after */
+    useLayoutEffect(() => {
+        const r = rail.current, i = items().findIndex((el) => el.dataset.value === current);
+        if (r && i >= 0 && Math.abs(r.scrollLeft - i * column()) > 1)
+            r.scrollTo({ left: i * column(), behavior: mounted.current ? 'smooth' : 'auto' });
+        mounted.current = true;
+    });
+    useEffect(() => () => { if (settle.current)
+        clearTimeout(settle.current); }, []);
+    /* the rail came to rest: whatever stands in the centre is what the member chose */
+    const scrolled = () => {
+        if (settle.current)
+            clearTimeout(settle.current);
+        settle.current = setTimeout(() => {
+            const r = rail.current, col = column();
+            if (!r || !col)
+                return;
+            const at = items()[Math.round(r.scrollLeft / col)]?.dataset.value;
+            if (at !== undefined)
+                pick(at);
+        }, 120);
+    };
+    return (_jsx(PickerContext.Provider, { value: { value: current, pick }, children: _jsxs("div", { className: cx('picker', className), "aria-label": label, "data-value": current, ...rest, children: [_jsx("div", { className: "picker__rail", role: "listbox", ref: rail, onScroll: scrolled, children: children }), unit != null && _jsx("span", { className: "picker__unit", children: unit })] }) }));
 }
-/** PickerItem — one value on the Picker rail. */
-export function PickerItem({ selected, className, ...rest }) {
-    return _jsx("button", { type: "button", role: "option", "aria-selected": selected ? 'true' : 'false', className: cx('picker__item', className), ...rest });
+/** PickerItem — one value on the Picker rail; a tap brings it to the centre. */
+export function PickerItem({ value, className, children, onClick, ...rest }) {
+    const picker = useContext(PickerContext);
+    const own = value ?? (typeof children === 'string' || typeof children === 'number' ? String(children) : undefined);
+    return (_jsx("button", { type: "button", role: "option", "data-value": own, "aria-selected": own !== undefined && picker?.value === own ? 'true' : 'false', className: cx('picker__item', className), onClick: (e) => { onClick?.(e); if (!e.defaultPrevented && own !== undefined)
+            picker?.pick(own); }, ...rest, children: children }));
 }

package/dist/scaffold/BaseContent.d.ts

@@ -6,12 +6,12 @@ export interface BaseContentProps extends ComponentPropsWithoutRef<'section'> {
  * maybe a CtaPack. Content has three homes (Card · Sheet · the base); this is the third one, named.
  * Was Section (and, inside a Step, StepCard) until 2026-09-16 — one block, one name.
  * In a Step it is the reading block (first child; the step's MOVE goes to the ActionBar, never here). It can move two ways
- * (Lh 2026-09-20): several of them in a `Pages` = a walk of words the round pager turns (slideTo); or a CtaPack of CALLERS —
- * `Btn aria-controls={a Sheet's id}` — WAYS IN (sign in · new phone · join), each calling a `Sheet state="away"` that holds that way's
- * whole form and its submit. The base itself carries no control; a form is never taken apart across it. Never both: a pager never works beside a sheet.
+ * (Lh 2026-09-20): several of them in a `Pages` = a walk of words the round pager turns (slideTo); or a CtaPack of WAYS IN
+ * (sign in · new phone · join) — plain `Btn`s; what each one opens (a `Sheet` holding that way's whole form) is the APP's wiring, not
+ * cardds's. The base itself carries no control; a form is never taken apart across it. Never both: a pager never works beside a sheet.
  */
 export declare function BaseContent({ className, ...rest }: BaseContentProps): import("react").JSX.Element;
 export interface CtaPackProps extends ComponentPropsWithoutRef<'div'> {
 }
-/** CtaPack — the buttons under a BaseContent's words, wrapping on one line. In a Step it holds CALLERS only (buttons that call a sheet, `aria-controls`) — the Step's move is its ActionBar. */
+/** CtaPack — the buttons under a BaseContent's words, wrapping on one line. In a Step it holds ways in (each opens a sheet — the app wires that); the Step's own move is never here. */
 export declare function CtaPack({ className, ...rest }: CtaPackProps): import("react").JSX.Element;

package/dist/scaffold/BaseContent.js

@@ -5,14 +5,14 @@ import { cx } from '../cx.js';
  * maybe a CtaPack. Content has three homes (Card · Sheet · the base); this is the third one, named.
  * Was Section (and, inside a Step, StepCard) until 2026-09-16 — one block, one name.
  * In a Step it is the reading block (first child; the step's MOVE goes to the ActionBar, never here). It can move two ways
- * (Lh 2026-09-20): several of them in a `Pages` = a walk of words the round pager turns (slideTo); or a CtaPack of CALLERS —
- * `Btn aria-controls={a Sheet's id}` — WAYS IN (sign in · new phone · join), each calling a `Sheet state="away"` that holds that way's
- * whole form and its submit. The base itself carries no control; a form is never taken apart across it. Never both: a pager never works beside a sheet.
+ * (Lh 2026-09-20): several of them in a `Pages` = a walk of words the round pager turns (slideTo); or a CtaPack of WAYS IN
+ * (sign in · new phone · join) — plain `Btn`s; what each one opens (a `Sheet` holding that way's whole form) is the APP's wiring, not
+ * cardds's. The base itself carries no control; a form is never taken apart across it. Never both: a pager never works beside a sheet.
  */
 export function BaseContent({ className, ...rest }) {
     return _jsx("section", { className: cx('base-content', className), ...rest });
 }
-/** CtaPack — the buttons under a BaseContent's words, wrapping on one line. In a Step it holds CALLERS only (buttons that call a sheet, `aria-controls`) — the Step's move is its ActionBar. */
+/** CtaPack — the buttons under a BaseContent's words, wrapping on one line. In a Step it holds ways in (each opens a sheet — the app wires that); the Step's own move is never here. */
 export function CtaPack({ className, ...rest }) {
     return _jsx("div", { className: cx('cta-pack', className), ...rest });
 }

package/dist/sheets/Drawer.d.ts

@@ -1,8 +1,19 @@
 import { type ComponentPropsWithoutRef, type ReactNode } from 'react';
 export interface ModalProps extends ComponentPropsWithoutRef<'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;
+/**
+ * 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 ComponentPropsWithoutRef<'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. */
@@ -13,7 +24,7 @@ export interface DrawerProps extends Omit<ComponentPropsWithoutRef<'div'>, 'titl
     /** 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'> {
 }

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';
+/** 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<ComponentPropsWithoutRef<'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 {};