@usableapp/cardds 0.2.2 → 0.4.0

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

@@ -1,6 +1,6 @@
-import type { ComponentPropsWithoutRef } from 'react';
+import type { ComponentProps } from 'react';
 import { type IconName } from '../type/Icon.js';
-export interface NoteRowProps extends ComponentPropsWithoutRef<'div'> {
+export interface NoteRowProps extends ComponentProps<'div'> {
     icon?: IconName;
 }
 /** NoteRow — icon + caption: transit hints, fine print. */

package/dist/journey/Route.d.ts

@@ -1,4 +1,4 @@
-import type { ComponentPropsWithoutRef, ReactNode } from 'react';
+import type { ComponentProps, ReactNode } from 'react';
 import { type IconName } from '../type/Icon.js';
 export interface RoutePoint {
     /** the place name (caption) */
@@ -8,7 +8,7 @@ export interface RoutePoint {
     /** the time */
     time: ReactNode;
 }
-export interface RouteProps extends ComponentPropsWithoutRef<'div'> {
+export interface RouteProps extends ComponentProps<'div'> {
     from: RoutePoint;
     to: RoutePoint;
     /** the icon on the dotted connector (plane by default) */

package/dist/journey/TileBadge.d.ts

@@ -1,5 +1,5 @@
-import type { ComponentPropsWithoutRef, ReactNode } from 'react';
-export interface TileBadgeProps extends ComponentPropsWithoutRef<'span'> {
+import type { ComponentProps, ReactNode } from 'react';
+export interface TileBadgeProps extends ComponentProps<'span'> {
     /** the small label above ("Gate") */
     label: ReactNode;
     /** the big value ("21") */

package/dist/layover/Banner.d.ts

@@ -1,5 +1,5 @@
-import type { ComponentPropsWithoutRef, ReactNode } from 'react';
-export interface BannerProps extends ComponentPropsWithoutRef<'details'> {
+import type { ComponentProps, ReactNode } from 'react';
+export interface BannerProps extends ComponentProps<'details'> {
     /** the chip that opens it (a `Chip on` with a chevron Icon xs) */
     summary: ReactNode;
     /** the tone of the opened card */

package/dist/layover/Callout.d.ts

@@ -1,5 +1,5 @@
-import type { ComponentPropsWithoutRef, ReactNode } from 'react';
-export interface CalloutProps extends Omit<ComponentPropsWithoutRef<'div'>, 'title'> {
+import type { ComponentProps, ReactNode } from 'react';
+export interface CalloutProps extends Omit<ComponentProps<'div'>, 'title'> {
     title: ReactNode;
     sub?: ReactNode;
     /** position over the stage background (CSS lengths / percentages) */

package/dist/layover/Deck.d.ts

@@ -1,9 +1,9 @@
-import type { ComponentPropsWithoutRef } from 'react';
-export interface DeckProps extends ComponentPropsWithoutRef<'div'> {
+import type { ComponentProps } from 'react';
+export interface DeckProps extends ComponentProps<'div'> {
 }
 /** Deck — swipe cards fanned behind each other; the LAST child is on top. Children are Cards (the front one may `fold`). */
 export declare function Deck({ className, ...rest }: DeckProps): import("react").JSX.Element;
-export interface DeckActionsProps extends ComponentPropsWithoutRef<'div'> {
+export interface DeckActionsProps extends ComponentProps<'div'> {
 }
 /** DeckActions — the two big round buttons under a Deck (skip · keep). */
 export declare function DeckActions({ className, ...rest }: DeckActionsProps): import("react").JSX.Element;

package/dist/lists/Bubble.d.ts

@@ -1,9 +1,9 @@
-import type { ComponentPropsWithoutRef, ReactNode } from 'react';
-export interface ThreadProps extends ComponentPropsWithoutRef<'div'> {
+import type { ComponentProps, ReactNode } from 'react';
+export interface ThreadProps extends ComponentProps<'div'> {
 }
 /** Thread — a stack of Bubbles: a conversation. */
 export declare function Thread({ className, ...rest }: ThreadProps): import("react").JSX.Element;
-export interface BubbleProps extends ComponentPropsWithoutRef<'div'> {
+export interface BubbleProps extends ComponentProps<'div'> {
     /** whose: theirs on the left (default), mine on the right */
     side?: 'left' | 'right';
     /** the caption under the message — a time, a tick (an Icon) */

package/dist/lists/Kv.d.ts

@@ -1,12 +1,12 @@
-import type { ComponentPropsWithoutRef, ReactNode } from 'react';
+import type { ComponentProps, ReactNode } from 'react';
 import { type IconName } from '../type/Icon.js';
-export interface KvProps extends ComponentPropsWithoutRef<'dl'> {
+export interface KvProps extends ComponentProps<'dl'> {
     /** hairlines between rows */
     lined?: boolean;
 }
 /** Kv — key-value rows: label left, value right (Pay with · Time credits); children are KVRows. */
 export declare function Kv({ lined, className, ...rest }: KvProps): import("react").JSX.Element;
-export interface KvRowProps extends ComponentPropsWithoutRef<'div'> {
+export interface KvRowProps extends ComponentProps<'div'> {
     /** the key */
     label: ReactNode;
     /** the value */
@@ -14,11 +14,11 @@ export interface KvRowProps extends ComponentPropsWithoutRef<'div'> {
 }
 /** KvRow — one key · value line (48px tall); the value may hold a Chip, an Avatar, an Icon. */
 export declare function KvRow({ label, className, children, ...rest }: KvRowProps): import("react").JSX.Element;
-export interface KvGridProps extends ComponentPropsWithoutRef<'div'> {
+export interface KvGridProps extends ComponentProps<'div'> {
 }
 /** KvGrid — value-over-label cells split by a rule (Sex | Weight); children are KVCells. */
 export declare function KvGrid({ className, ...rest }: KvGridProps): import("react").JSX.Element;
-export interface KvCellProps extends ComponentPropsWithoutRef<'div'> {
+export interface KvCellProps extends ComponentProps<'div'> {
     icon?: IconName;
     value: ReactNode;
     label: ReactNode;

package/dist/lists/Legend.d.ts

@@ -1,9 +1,9 @@
-import type { ComponentPropsWithoutRef } from 'react';
-export interface LegendProps extends ComponentPropsWithoutRef<'div'> {
+import type { ComponentProps } from 'react';
+export interface LegendProps extends ComponentProps<'div'> {
 }
 /** Legend — signal dots with captions under a chart; children are LegendItems. */
 export declare function Legend({ className, ...rest }: LegendProps): import("react").JSX.Element;
-export interface LegendItemProps extends ComponentPropsWithoutRef<'span'> {
+export interface LegendItemProps extends ComponentProps<'span'> {
     /** which signal dot: `a` (default) or `b` */
     dot?: 'a' | 'b';
 }

package/dist/lists/Row.d.ts

@@ -1,6 +1,6 @@
-import { type ComponentPropsWithoutRef, type ReactNode } from 'react';
+import { type ComponentProps, type ReactNode } from 'react';
 import { type IconName } from '../type/Icon.js';
-export interface RowProps extends Omit<ComponentPropsWithoutRef<'div'>, 'title'> {
+export interface RowProps extends Omit<ComponentProps<'div'>, 'title'> {
     /** the leading visual: an Avatar, an AvatarStack, an Icon */
     lead?: ReactNode;
     /** an icon in the outlined 48px lead box (menu rows) */
@@ -264,6 +264,7 @@ export declare function Row({ lead, leadIcon, title, meta, body, end, endValue,
     onTransitionRunCapture?: import("react").TransitionEventHandler<HTMLDivElement> | undefined;
     onTransitionStart?: import("react").TransitionEventHandler<HTMLDivElement> | undefined;
     onTransitionStartCapture?: import("react").TransitionEventHandler<HTMLDivElement> | undefined;
+    ref?: import("react").Ref<HTMLDivElement> | undefined;
     key?: import("react").Key | null | undefined;
     defaultChecked?: boolean | undefined | undefined;
     defaultValue?: string | number | readonly string[] | undefined;
@@ -310,8 +311,8 @@ export declare function Row({ lead, leadIcon, title, meta, body, end, endValue,
     exportparts?: string | undefined | undefined;
     href: string | undefined;
     className: string;
-}, HTMLElement>;
-export interface RowsProps extends ComponentPropsWithoutRef<'div'> {
+}, HTMLDivElement>;
+export interface RowsProps extends ComponentProps<'div'> {
 }
 /** Rows — a list of Rows separated by hairlines. */
 export declare function Rows({ className, ...rest }: RowsProps): import("react").JSX.Element;

package/dist/lists/Timeline.d.ts

@@ -1,9 +1,9 @@
-import type { ComponentPropsWithoutRef, ReactNode } from 'react';
-export interface TimelineProps extends ComponentPropsWithoutRef<'ol'> {
+import type { ComponentProps, ReactNode } from 'react';
+export interface TimelineProps extends ComponentProps<'ol'> {
 }
 /** Timeline — a hairline with accent dots, date marks and entries to the right; children are TimelineItems. */
 export declare function Timeline({ className, ...rest }: TimelineProps): import("react").JSX.Element;
-export interface TimelineItemProps extends ComponentPropsWithoutRef<'li'> {
+export interface TimelineItemProps extends ComponentProps<'li'> {
     /** the date chip ("Wed 14") */
     mark: ReactNode;
 }

package/dist/media/MapArea.d.ts

@@ -1,5 +1,5 @@
-import type { ComponentPropsWithoutRef, ReactNode, Ref } from 'react';
-export interface MapAreaProps extends ComponentPropsWithoutRef<'div'> {
+import type { ComponentProps, ReactNode, Ref } from 'react';
+export interface MapAreaProps extends ComponentProps<'div'> {
     /** the words over the map, under the bar's line */
     hint?: ReactNode;
     /** the tile provider's credit, bottom right (OSM requires it) — a caption, never the engine's own control */

package/dist/media/Mosaic.d.ts

@@ -1,10 +1,10 @@
-import type { ComponentPropsWithoutRef } from 'react';
-export interface MosaicProps extends ComponentPropsWithoutRef<'div'> {
+import type { ComponentProps } from 'react';
+export interface MosaicProps extends ComponentProps<'div'> {
     label?: string;
 }
 /** Mosaic — one big photo + two small in a card (three Placeholders or imgs). */
 export declare function Mosaic({ label, className, ...rest }: MosaicProps): import("react").JSX.Element;
-export interface WaveProps extends ComponentPropsWithoutRef<'span'> {
+export interface WaveProps extends ComponentProps<'span'> {
     label?: string;
 }
 /** Wave — the waveform stand-in for a voice note, filling a Row's body. */

package/dist/media/Postcard.d.ts

@@ -1,5 +1,5 @@
-import type { ComponentPropsWithoutRef, ReactNode } from 'react';
-export interface PostcardProps extends ComponentPropsWithoutRef<'div'> {
+import { type ComponentProps, type ReactNode } from 'react';
+export interface PostcardProps extends ComponentProps<'div'> {
     /** the photo on the front; none = the wireframe box */
     photo?: string | null;
     alt?: string;
@@ -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/media/Quote.d.ts

@@ -1,5 +1,5 @@
-import type { ComponentPropsWithoutRef, ReactNode } from 'react';
-export interface QuoteProps extends ComponentPropsWithoutRef<'blockquote'> {
+import type { ComponentProps, ReactNode } from 'react';
+export interface QuoteProps extends ComponentProps<'blockquote'> {
     /** the words */
     text: ReactNode;
     /** the attribution */

package/dist/media/Tile.d.ts

@@ -1,13 +1,13 @@
-import { type ComponentPropsWithoutRef, type ReactNode } from 'react';
+import { type ComponentProps, type ReactNode } from 'react';
 import { type IconName } from '../type/Icon.js';
-export interface TileGridProps extends ComponentPropsWithoutRef<'div'> {
+export interface TileGridProps extends ComponentProps<'div'> {
     /** three across on a phone (attachments, upload kinds) */
     cols3?: boolean;
     bleed?: boolean;
 }
 /** TileGrid — big square Tiles in a responsive grid. */
 export declare function TileGrid({ cols3, bleed, className, ...rest }: TileGridProps): import("react").JSX.Element;
-export interface TileProps extends Omit<ComponentPropsWithoutRef<'div'>, 'onChange'> {
+export interface TileProps extends Omit<ComponentProps<'div'>, 'onChange'> {
     /** the icon at the top */
     icon?: IconName;
     /** the label at the bottom */
@@ -272,6 +272,7 @@ export declare function Tile({ icon, label, value, sub, pick, type, name, checke
     onTransitionRunCapture?: import("react").TransitionEventHandler<HTMLDivElement> | undefined;
     onTransitionStart?: import("react").TransitionEventHandler<HTMLDivElement> | undefined;
     onTransitionStartCapture?: import("react").TransitionEventHandler<HTMLDivElement> | undefined;
+    ref?: import("react").Ref<HTMLDivElement> | undefined;
     key?: import("react").Key | null | undefined;
     defaultValue?: string | number | readonly string[] | undefined;
     suppressContentEditableWarning?: boolean | undefined | undefined;
@@ -317,4 +318,4 @@ export declare function Tile({ icon, label, value, sub, pick, type, name, checke
     exportparts?: string | undefined | undefined;
     type: string | undefined;
     className: string;
-}, HTMLElement>;
+}, HTMLDivElement>;

package/dist/numbers/Badge.d.ts

@@ -1,5 +1,5 @@
-import type { ComponentPropsWithoutRef } from 'react';
-export interface BadgeProps extends ComponentPropsWithoutRef<'span'> {
+import type { ComponentProps } from 'react';
+export interface BadgeProps extends ComponentProps<'span'> {
     /** tinted instead of accent */
     soft?: boolean;
 }

package/dist/numbers/Band.d.ts

@@ -1,5 +1,5 @@
-import type { ComponentPropsWithoutRef, ReactNode } from 'react';
-export interface BandProps extends ComponentPropsWithoutRef<'article'> {
+import type { ComponentProps, ReactNode } from 'react';
+export interface BandProps extends ComponentProps<'article'> {
     /** the two-line label (use a `<br />` to break it) */
     label: ReactNode;
     /** the giant number; wrap a unit in `<small>` */
@@ -10,7 +10,7 @@ export interface BandProps extends ComponentPropsWithoutRef<'article'> {
 }
 /** Band — a data card: 2-line label · giant number · footnote. Stack several in a BandStack for one boundary with hairlines. */
 export declare function Band({ label, num, foot, tone, className, ...rest }: BandProps): import("react").JSX.Element;
-export interface BandStackProps extends ComponentPropsWithoutRef<'div'> {
+export interface BandStackProps extends ComponentProps<'div'> {
 }
 /** BandStack — several Bands as ONE card boundary, a hairline between each. */
 export declare function BandStack({ className, ...rest }: BandStackProps): import("react").JSX.Element;

package/dist/numbers/Bars.d.ts

@@ -1,11 +1,11 @@
-import type { ComponentPropsWithoutRef } from 'react';
-export interface BarsProps extends ComponentPropsWithoutRef<'div'> {
+import type { ComponentProps } from 'react';
+export interface BarsProps extends ComponentProps<'div'> {
     /** the value of the tallest bar */
     max: number;
 }
 /** Bars — three or four bars with a count on top, the glance chart; children are Bar. */
 export declare function Bars({ max, className, style, ...rest }: BarsProps): import("react").JSX.Element;
-export interface BarProps extends ComponentPropsWithoutRef<'div'> {
+export interface BarProps extends ComponentProps<'div'> {
     value: number;
     /** the highlighted bar (accent, its count in a pill) */
     on?: boolean;

package/dist/numbers/DotGrid.d.ts

@@ -1,5 +1,5 @@
-import type { ComponentPropsWithoutRef } from 'react';
-export interface DotGridProps extends ComponentPropsWithoutRef<'div'> {
+import type { ComponentProps } from 'react';
+export interface DotGridProps extends ComponentProps<'div'> {
     /** how many dots */
     total: number;
     /** how many are done (filled, from the top-left) */

package/dist/numbers/Picker.d.ts

@@ -1,13 +1,25 @@
-import { type ComponentPropsWithoutRef, type ReactNode } from 'react';
-export interface PickerProps extends ComponentPropsWithoutRef<'div'> {
+import { type ComponentProps, type ReactNode } from 'react';
+export interface PickerProps extends Omit<ComponentProps<'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<ComponentProps<'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/numbers/Ring.d.ts

@@ -1,5 +1,5 @@
-import type { ComponentPropsWithoutRef, ReactNode } from 'react';
-export interface RingProps extends ComponentPropsWithoutRef<'div'> {
+import type { ComponentProps, ReactNode } from 'react';
+export interface RingProps extends ComponentProps<'div'> {
     /** 0–100 */
     value: number;
     /** sm = an avatar-xl ring · xs = an inline counter in a head (2/3) */

package/dist/numbers/Track.d.ts

@@ -1,10 +1,10 @@
-import type { ComponentPropsWithoutRef } from 'react';
-export interface TrackProps extends ComponentPropsWithoutRef<'ol'> {
+import type { ComponentProps } from 'react';
+export interface TrackProps extends ComponentProps<'ol'> {
     label?: string;
 }
 /** Track — step progress in a dark pill: done · done · todo; children are TrackSteps holding an Icon each. */
 export declare function Track({ label, className, ...rest }: TrackProps): import("react").JSX.Element;
-export interface TrackStepProps extends ComponentPropsWithoutRef<'li'> {
+export interface TrackStepProps extends ComponentProps<'li'> {
     /** this step (and the connector into it) is done */
     done?: boolean;
 }