@usableapp/cardds 0.2.1 → 0.3.0

package/dist/cardds.css

@@ -90,6 +90,8 @@
   --chip-h: calc(var(--tap-base) * 19 / 24);  /* 38 chip height */
   --bar-h: calc(var(--tap-base) * 4 / 3);     /* 64 float bar, day cell, deck actions */
   --header-h: calc(var(--tap-base) * 5 / 4);  /* 60 top bar — .topbar and .appbar alike */
+  --card-pad-rest: var(--sp-5);  /* 20 a card's padding before any variant — .card publishes it as --card-pad; the sheet's peek strip is built from it where no card is in scope */
+  --card-gap-rest: var(--sp-4);  /* 16 …and its gap */
   --screen-pad: var(--sp-4); /* 16 the screen's inset — .sheet-stack cancels it */
   --map-ring: calc(var(--tap-base) * 10 / 3);    /* the rough-area ring on a map (sheet.css .map__ring) — a neighbourhood, not a house */
   --fab: calc(var(--tap-base) * 3 / 2); /* 72 square floating action */
@@ -521,8 +523,8 @@ button { font: inherit; cursor: pointer; }
 .card {
   --card-bg: var(--card-1-bg);   /* the slot, readable by children (avatar rings, fold) */
   --card-ink: var(--card-1-ink);
-  --card-pad: var(--sp-5);       /* published so .bleed can cancel it exactly */
-  --card-gap: var(--sp-4);       /* published so a sheet's peek strip (sheet.css) is exact */
+  --card-pad: var(--card-pad-rest);       /* published so .bleed can cancel it exactly */
+  --card-gap: var(--card-gap-rest);       /* published so a sheet's peek strip (sheet.css) is exact */
   background: var(--card-bg);
   color: var(--card-ink);
   border: var(--border-w) solid var(--card-border);
@@ -1105,7 +1107,7 @@ button { font: inherit; cursor: pointer; }
    page. Many sheets stacked as the app's menu are the other system,
    .sheet-stack (stack.css): the same material, its own class and file.
 
-   <article class="card sheet sheet--half" data-sheet-states="peek half 3q full">
+   <article class="card sheet sheet--half">
    A tap on the handle TOGGLES the sheet between its own state and peek
    (Lh 2026-09-16) — never a step-by-step climb; a drag snaps to any of
    the listed states, and the state it lands on becomes the one a tap
@@ -1123,14 +1125,12 @@ button { font: inherit; cursor: pointer; }
    ============================================================ */
 
 .sheet {
-  --_handle: var(--sp-1);
   /* the strip a peeked sheet shows: the card's own top padding, the handle,
      the gap, one title row (--tap — the head rule below makes every head at
      least that tall) and the gap under it, so the cut lands exactly where
      the first control starts and nothing of it leaks through. Published
      (and registered in tokens.css) so a sheet whose head is taller can
      retune it: .my-sheet { --sheet-peek: … } */
-  --sheet-peek: calc(var(--card-pad) + var(--_handle) + 2 * var(--card-gap) + var(--tap));
   --sheet-half: 0.5;              /* a share of the sheet's own height */
   --sheet-3q: 0.25;               /* three quarters showing: slid by a quarter */
   /* the sheet's own height, seen from inside it: the box it slides in is the
@@ -1165,14 +1165,16 @@ button { font: inherit; cursor: pointer; }
 .sheet--half { --_y: calc(var(--sheet-half) * 100%); --_cover: calc(var(--sheet-half) * var(--_box)); }
 .sheet--3q { --_y: calc(var(--sheet-3q) * 100%); --_cover: calc(var(--sheet-3q) * var(--_box)); }
 .sheet--peek { --_y: calc(100% - var(--sheet-peek)); --_cover: calc(var(--_box) - var(--sheet-peek)); }
+/* --sheet-peek is declared on the BOX the sheet slides in, not on the sheet: the words behind a peeked sheet
+   have to read it too (step.css keeps that much room under them), and a token only flows down. The sheet
+   inherits it. A sheet whose head is taller retunes it on the box. */
+:is(.step, .sheet-stage) { --_handle: var(--sp-1); --sheet-peek: calc(var(--card-pad-rest) + var(--_handle) + 2 * var(--card-gap-rest) + var(--tap)); }
+
 /* ---- called sheets (Lh, 2026-09-20): a .step whose .base-content has buttons that each CALL a sheet ----
    .sheet--away = not on the screen: slid all the way out (translate, like every state — the material never
    changes), and hidden once it has left so its shadow does not lie on the step's bottom edge; write it
-   with `inert`. A button names its sheet — <button aria-controls="when"> … <article id="when" class="card
-   sheet sheet--away" inert data-sheet-states="peek full"> — and cardds.js does the rest: a tap slides that
-   sheet up to full and sends any other one away; the handle takes it down to peek, never further, so the
-   words and the other buttons are back in reach; the same button again raises it from peek to full.
-   Nothing waits at peek before the first call. No bar on such a screen (actions.css).
+   with `inert` (the React Sheet does). WHO brings it onto the screen is the app's business — a button, a route:
+   cardds ties no component to another. Nothing waits at peek before the first call.
    WHAT IT IS FOR: the base offers WAYS IN — sign in · new phone · join — and each button calls a sheet
    that holds that way's WHOLE form, its submit on the sheet's foot, leading to the next page. The base
    carries no control. It is NOT for a form taken apart — one sheet per field, a "send" left on the base:
@@ -1202,6 +1204,12 @@ button { font: inherit; cursor: pointer; }
      the cut. A length from the box's container units (--_box), since the
      cut is a share of the SHEET's height, not of the body's. */
   scroll-padding-bottom: var(--_cover);
+  /* …and its content has to be able to LEAVE that part: the same length as bottom padding, so the last row
+     scrolls up to the visible edge at half and 3q as it does at full — everything between the head and the
+     foot can be reached at any state (Lh, 2026-09-21). Padding, not a shorter box: nothing that shows moves
+     when the state changes, only how far the body scrolls; a child that fills the body (a composer) fills
+     the part that shows. */
+  padding-bottom: var(--_cover);
 }
 /* ---- the sheet's foot: the button that FINISHES the sheet, on the sheet (Lh, 2026-09-20) ----
    A screen with a sheet has no bar in front of it: the button that completes what the sheet asks — the
@@ -1228,8 +1236,13 @@ button { font: inherit; cursor: pointer; }
 .sheet:has(> .card__foot) > .sheet__body { margin-bottom: calc(var(--_foot) - var(--card-pad)); } /* the body stops above the strip (the card's own padding is the rest) */
 .sheet.is-dragging > .card__foot { transition: none; }
 :is(.sheet--peek, .sheet--away) > .card__foot { opacity: 0; visibility: hidden; transition: translate var(--motion-sheet) ease, opacity var(--motion-sheet) ease, visibility 0s linear var(--motion-sheet); }
+/* that padding can be taller than the body's own box (a short box: a small phone with the keyboard up) and a
+   box is never smaller than its padding — so the pinned parts must not give way to it: the body runs past
+   the sheet's clipped edge instead, where nothing shows anyway. At peek and away no part of the body shows. */
+.sheet > :not(.sheet__body) { flex-shrink: 0; }
+:is(.sheet--peek, .sheet--away) > .sheet__body { padding-bottom: 0; }
 .sheet__body > * { min-width: 0; } /* as .card > *: children shrink to the track, never widen it */
-.sheet__body:last-child { margin-bottom: calc(-1 * var(--card-pad)); padding-bottom: var(--card-pad); }
+.sheet__body:last-child { margin-bottom: calc(-1 * var(--card-pad)); padding-bottom: calc(var(--card-pad) + var(--_cover)); }
 
 /* grab handle — first child of the sheet. Drawn as a small bar, but it is
    the thumb's grab area for the whole strip above the title: a pseudo widens
@@ -1390,6 +1403,12 @@ button { font: inherit; cursor: pointer; }
 /* raised: the sheet floats above a footnote strip on the scrim. Its bottom
    edge shows, so it gets its corners and border back; full still stops at
    the top bar's line, because the top edge never moved. */
+/* EVERY sheet has one shape (Lh, 2026-09-21): the handle and the head stay at the top and never scroll · the
+   foot's button stands at the bottom, and ABOVE the keyboard when there is one · everything between them
+   scrolls, as far as it needs to. In a .step the keyboard's room is the step's (--kb, step.css); on a stage
+   the sheet gives it up itself, as --_lift — the same token a raised sheet floats on. */
+.sheet-stage > .sheet { --_lift: var(--kb, 0rem); bottom: var(--_lift); }
+.sheet-stage > .sheet--raised { --_lift: calc(var(--tap-lg) + var(--kb, 0rem)); }
 .sheet--raised { --_lift: var(--tap-lg); bottom: var(--_lift); border-radius: var(--r-card); border-bottom: var(--border-w) solid var(--card-border); }
 .sheet-stage__foot {
   position: absolute;
@@ -1480,8 +1499,9 @@ button { font: inherit; cursor: pointer; }
 :has(> .action-bar) .step { margin-bottom: calc(var(--bar-reserve) + var(--kb, 0rem)); }
 /* LAYERS (Lh, 2026-09-20): the base, then the sheet over it, then the top bar. A bar is the BASE's — the
    move of a page of words — so a step with a sheet has NO bar: the sheet finishes on its own .card__foot
-   (sheet.css), and a form lives whole in ONE sheet, never item by item on the base. Should a bar be written
-   beside a sheet anyway it stands down (actions.css + cardds.js) — a net for a mistake, not a layout. */
+   (sheet.css), and a form lives whole in ONE sheet, never item by item on the base. That is how cardds's
+   own screens are composed (the guide); the framework does not police it — a component never changes
+   because another one is there. */
 
 /* the reading block: a .base-content (base.css) — the same words-on-the-base
    block as anywhere else (it was .step__card, and a .card before 2026-09-16;
@@ -1500,11 +1520,10 @@ button { font: inherit; cursor: pointer; }
   color: var(--on-surface);
 }
 /* the reading block is the .base-content — or the .pages that holds several of them, a walk of words
-   (card.css). --sheet-room: the strip a CALLED sheet keeps at peek (sheet.css, "called sheets"), published
-   on the step by cardds.js while one is on the screen, so the buttons under it can scroll clear of it;
-   nothing without one. */
+   (card.css). Behind a PEEKED sheet the words keep the strip's room under them, so whatever is down there
+   (the buttons that call the other sheets) scrolls clear of it — CSS alone: the box declares --sheet-peek. */
+.step:has(> .sheet--peek) > :is(.base-content, .pages) { padding-bottom: var(--sheet-peek); }
 .step > :is(.base-content, .pages) {
-  padding-bottom: var(--sheet-room, 0rem);
   flex: 0 1 auto;
 }
 .step > :is(.base-content, .pages) {
@@ -1879,14 +1898,9 @@ button { font: inherit; cursor: pointer; }
      <button class="icon-btn icon-btn--invert" aria-label="ถัดไป">…</button>
    </div>   — or the same two in an .action-bar__tier--pager under a control  */
 .action-bar--pager { align-items: center; }
-/* The bar belongs to the BASE (Lh, 2026-09-20): it is the move of a page of words — a pager turning
-   them, or one wide button. It is never in front of a sheet: a sheet that is on the screen covers it
-   (step.css, "layers"), a peeking one included, and the button that finishes a sheet is the sheet's own
-   foot (sheet.css). So a pager never works beside a sheet — that screen has work that cannot be walked
-   past — and neither does any other bar: while a sheet is on (only .sheet--away, a sheet not called yet,
-   is not), the bar takes no pointer here and cardds.js makes it inert, so the keyboard cannot reach what
-   the eye cannot see. */
-:has(.step > .sheet:not(.sheet--away)) > .action-bar { pointer-events: none; }
+/* The bar belongs to the BASE: the move of a page of words — a pager turning them, or one wide button. A screen
+   with a sheet finishes on the sheet's own foot instead (sheet.css). Guidance for composing, not a rule the
+   CSS enforces: a component never changes because another one is there. */
 /* the page dots: under the card in a .screen__centre group; tight gaps */
 .pager__at { flex: 0 1 auto; min-width: 0; overflow: hidden; display: flex; align-items: center; gap: var(--sp-1); }
 .pager__at > * {

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'> {
 }