@mistriwork/ui 0.0.0-stage → 1.0.0-rc.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Baljinder Randhawa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,51 @@
-# Temporary Holding Version
+<img src="mark.svg" alt="mistri" width="48" height="48" />
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @mistriwork/ui
+
+The standalone React primitives both shells, mistri's and tablewalk's, are
+drawn with: Modal, DropMenu, Dropdown, Typeahead, Button, Field, Icon and
+DateField over [Base UI](https://base-ui.com), the tokens and stylesheet they
+are drawn with, and the zoom-aware ruler their popups are placed by.
+
+The form controls are built on them (**Preview**: @mistriwork/ui is Preview at 1.0): `TextField`, `MaskedField`,
+`MoneyField`, `SensitiveField`, `Select`, `MultiSelect`, `YesNo`, `ChoiceCards`, `Checkbox`, `Consent`, `Slider`,
+`HelpTip`, `ProgressBar`, `StepHeader`, `ActionBar`, `Columns` and `ReviewList`, with the `masks` they take
+(`phone`, `date`, `month`, `ssn`, `zip`, `money`). Each takes a value and an `onChange` and draws what it is told. A
+typed MM/DD/YYYY date is `MaskedField` with `masks.date` (and `isoDay` to read it); the calendar field is `DateField`.
+The landing hero's blocks are in the same Preview: `Badge` (a few words and an optional icon in a pill), `PhotoTiles`
+(two to four photos in a mosaic, sized before they arrive) and `IconRows` (up to four rows of an icon and a line), their
+rules in `hero.css`; the icons, the words and the image addresses are props.
+
+A control is a Field, so its label, hint and problem are wired into it, and its problem's line is kept in the flow so
+saying it moves nothing. A theme restyles them all together through `--field-fill`, `--control-h`,
+`--control-border-w` and `--field-radius`, and a field label's weight is the theme's label role.
+
+A primitive reads no data, address or message catalog: its words, its icons,
+its answers and its hooks are props, and it renders with no server behind it.
+React, React DOM and Base UI are peers: a project drawing with these installs
+them.
+
+```tsx
+import '@mistriwork/ui/style.css';
+import { Button, Modal } from '@mistriwork/ui';
+```
+
+`style.css` is the tokens (`tokens.css`), the primitives' own rules
+(`primitives.css`) and the form controls' (`forms.css`) in a `mistri-ui` cascade layer, so any rule of the page's
+own wins over them. A page with a layered stylesheet of its own can take the
+files into a layer it names instead (`@import '@mistriwork/ui/tokens.css'
+layer(base);`). An Icon draws the glyphs registered with `registerIcons`; a
+DateField says the `words` it is given, as do Carousel, Resizable and Pagination (a
+`words` object over English defaults). One rule names the rest: a name no one sees is
+`ariaLabel` (Modal, Tabs, Popover, Carousel, Resizable, ScrollArea, Pagination, Drawer),
+and `label` is only ever text drawn on the page. A Field's `optional` is the word drawn
+beside the label of a field that is not required.
+
+## Exports
+
+Its exports are its public API, and nothing else is: `@mistriwork/ui` (every
+primitive), each module by its path (`@mistriwork/ui/Button.js`,
+`@mistriwork/ui/internal/datePickerModel.js`, …), and the four stylesheets.
+
+Part of [mistri](https://mistriwork.dev);
+[source](https://github.com/rbaljinder/mistri/tree/main/packages/ui).

package/dist/Avatar.d.ts

@@ -0,0 +1,11 @@
+export type AvatarSize = 'sm' | 'md' | 'lg';
+export interface AvatarProps {
+    /** The person's name, for the fallback initials. */
+    name?: string;
+    /** The picture's address; absent, the fallback shows at once. */
+    src?: string;
+    size?: AvatarSize;
+    className?: string;
+}
+export declare function initialsOf(name: string): string;
+export declare function Avatar({ name, src, size, className }: AvatarProps): import("react").JSX.Element;

package/dist/Avatar.js

@@ -0,0 +1,28 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * An avatar: a person's picture, or their initials where there is none.
+ * Over Base UI's Avatar, which shows the fallback only while the picture
+ * loads or fails, so a slow picture never leaves a blank disc. The
+ * initials are the first letters of the first two words of the name
+ * ("Ada Lovelace" → "AL", "Ada" → "A"); the disc itself is decorative,
+ * and a name that matters is said beside it by the caller, never by the
+ * disc's title. Sizes are the house ones: `sm` 28px, `md` 36px, `lg` 48px.
+ */
+import { Avatar as BaseAvatar } from '@base-ui/react/avatar';
+const graphemes = typeof Intl !== 'undefined' && 'Segmenter' in Intl ? new Intl.Segmenter(undefined, { granularity: 'grapheme' }) : null;
+/* A letter is a grapheme, not a UTF-16 unit: `slice(0, 1)` splits an emoji or an astral letter into a lone surrogate. */
+function firstLetter(word) {
+    const first = graphemes ? graphemes.segment(word)[Symbol.iterator]().next().value?.segment : Array.from(word)[0];
+    return (first ?? '').toUpperCase();
+}
+export function initialsOf(name) {
+    const words = name.trim().split(/\s+/).filter(Boolean);
+    if (!words.length)
+        return '';
+    if (words.length === 1)
+        return firstLetter(words[0]);
+    return firstLetter(words[0]) + firstLetter(words[1]);
+}
+export function Avatar({ name, src, size = 'md', className }) {
+    return (_jsxs(BaseAvatar.Root, { className: ['ui-avatar', `ui-avatar-${size}`, className].filter(Boolean).join(' '), children: [src ? _jsx(BaseAvatar.Image, { className: "ui-avatar-image", src: src, alt: "" }) : null, _jsx(BaseAvatar.Fallback, { className: "ui-avatar-fallback", "aria-hidden": "true", children: name ? initialsOf(name) : '' })] }));
+}

package/dist/Button.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The one button: an intent, a size, and the states the platform already
+ * has. Every look dresses the classes it renders — `primary`, `ghost` and
+ * `danger` are what the looks' rules already name, `btn` and its modifiers
+ * are the primitive's own — so a form, a dialog and the sign-in card draw the
+ * same control instead of each dressing a `<button>` of its own.
+ *
+ * Busy is not disabled (docs/design.md, Access): a disabled button drops the
+ * focus it holds, so a busy one says `aria-disabled` and refuses the press
+ * itself — a click, and the implicit submission Enter makes through it.
+ */
+import type { ButtonHTMLAttributes, ReactNode, Ref } from 'react';
+export type ButtonIntent = 'primary' | 'secondary' | 'quiet' | 'danger';
+export type ButtonSize = 'compact' | 'default' | 'large';
+interface ButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'type'> {
+    /** Primary is the one filled action; secondary the outlined rest; quiet a word in the link ink; danger what cannot be taken back. */
+    intent?: ButtonIntent;
+    size?: ButtonSize;
+    /** Working: pressed once already. Says so and refuses another press, keeping the focus. */
+    busy?: boolean;
+    /** What the button says while busy ("Saving…"); its own words otherwise. */
+    busyLabel?: ReactNode;
+    /** Full width of its row: the phone's actions, the sign-in card's submit. */
+    block?: boolean;
+    type?: 'button' | 'submit' | 'reset';
+    ref?: Ref<HTMLButtonElement>;
+}
+/** The classes, for the few controls that must stay another element (a link dressed as a button). */
+export declare function buttonClass({ intent, size, block, className, }?: {
+    intent?: ButtonIntent;
+    size?: ButtonSize;
+    block?: boolean;
+    className?: string;
+}): string;
+export declare function Button({ intent, size, busy, busyLabel, block, type, className, onClick, children, ref, ...rest }: ButtonProps): import("react").JSX.Element;
+export {};

package/dist/Button.js

@@ -0,0 +1,22 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/* The class a look already dresses for each intent, beside the primitive's own. */
+const DRESS = {
+    primary: 'primary btn-primary',
+    secondary: 'ghost btn-secondary',
+    quiet: 'btn-quiet',
+    danger: 'danger btn-danger',
+};
+/** The classes, for the few controls that must stay another element (a link dressed as a button). */
+export function buttonClass({ intent = 'secondary', size = 'default', block = false, className = '', } = {}) {
+    return ['btn', DRESS[intent], size === 'default' ? '' : `btn-${size}`, block ? 'btn-block' : '', className].filter(Boolean).join(' ');
+}
+export function Button({ intent = 'secondary', size = 'default', busy = false, busyLabel, block = false, type = 'button', className, onClick, children, ref, ...rest }) {
+    const press = (event) => {
+        if (busy) {
+            event.preventDefault();
+            return;
+        }
+        onClick?.(event);
+    };
+    return (_jsx("button", { ...rest, ref: ref, type: type, className: buttonClass({ intent, size, block, className }), "aria-disabled": busy || rest['aria-disabled'] || undefined, "data-busy": busy || undefined, onClick: press, children: busy && busyLabel !== undefined ? busyLabel : children }));
+}

package/dist/Carousel.d.ts

@@ -0,0 +1,52 @@
+/**
+ * A carousel: one slide at a time from a row of them, chosen with Previous
+ * and Next or with a dot per slide. Plain React — Base UI has no carousel,
+ * and one slide, two steps and a dot row is all one is. The slides are the
+ * caller's array (the Tabs pattern), not children kept in step by hand.
+ * Controlled with `index`/`onIndexChange`, uncontrolled with
+ * `defaultIndex`. The ends do not wrap: Previous disables on the first
+ * slide and Next on the last, so the row keeps its shape and a reader is
+ * never spun back to the start without asking. Only the current slide is
+ * exposed to assistive tech (the rest are `aria-hidden`); the arrow keys
+ * on the region move, Home goes first, End goes last — only while focus
+ * is on the carousel or its own controls, so a widget inside a slide
+ * keeps its keys — and
+ * the slide's movement is silenced for a reader who asked for reduced
+ * motion (the track's transition lives under `no-preference` in
+ * standalone.css). A step button that disables under a focused finger
+ * hands focus to the other step, never to nowhere.
+ */
+import { type ReactNode } from 'react';
+export interface CarouselSlide {
+    /** The slide's short name, said after its number ("1 of 3: Studio"). */
+    label?: string;
+    children: ReactNode;
+}
+export interface CarouselProps {
+    slides: readonly CarouselSlide[];
+    index?: number;
+    defaultIndex?: number;
+    onIndexChange?: (index: number) => void;
+    /** The region's accessible name, where the carousel needs one ("Project photos"). */
+    ariaLabel?: string;
+    /** Every word the carousel says, in the caller's language; any left out are English. */
+    words?: Partial<CarouselWords>;
+    className?: string;
+}
+interface CarouselWords {
+    /** The region's name when `ariaLabel` is not given. */
+    region: string;
+    /** The step buttons' visible words. */
+    previous: ReactNode;
+    next: ReactNode;
+    /** The dot row's name. */
+    chooseSlide: string;
+    /** A slide's name: "1 of 3: Studio". */
+    slide: (number: number, total: number, label?: string) => string;
+    /** A dot's name: "Go to slide 2: Studio". */
+    goToSlide: (number: number, label?: string) => string;
+    /** The polite status line read as the slide changes. */
+    status: (number: number, total: number, label?: string) => string;
+}
+export declare function Carousel({ slides, index, defaultIndex, onIndexChange, ariaLabel, words: given, className }: CarouselProps): import("react").JSX.Element | null;
+export {};

package/dist/Carousel.js

@@ -0,0 +1,110 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * A carousel: one slide at a time from a row of them, chosen with Previous
+ * and Next or with a dot per slide. Plain React — Base UI has no carousel,
+ * and one slide, two steps and a dot row is all one is. The slides are the
+ * caller's array (the Tabs pattern), not children kept in step by hand.
+ * Controlled with `index`/`onIndexChange`, uncontrolled with
+ * `defaultIndex`. The ends do not wrap: Previous disables on the first
+ * slide and Next on the last, so the row keeps its shape and a reader is
+ * never spun back to the start without asking. Only the current slide is
+ * exposed to assistive tech (the rest are `aria-hidden`); the arrow keys
+ * on the region move, Home goes first, End goes last — only while focus
+ * is on the carousel or its own controls, so a widget inside a slide
+ * keeps its keys — and
+ * the slide's movement is silenced for a reader who asked for reduced
+ * motion (the track's transition lives under `no-preference` in
+ * standalone.css). A step button that disables under a focused finger
+ * hands focus to the other step, never to nowhere.
+ */
+import { useEffect, useRef, useState } from 'react';
+const ENGLISH = {
+    region: 'Carousel',
+    previous: 'Previous slide',
+    next: 'Next slide',
+    chooseSlide: 'Choose a slide',
+    slide: (n, total, label) => `${n} of ${total}${label ? `: ${label}` : ''}`,
+    goToSlide: (n, label) => `Go to slide ${n}${label ? `: ${label}` : ''}`,
+    status: (n, total, label) => `Slide ${n} of ${total}${label ? `: ${label}` : ''}`,
+};
+export function Carousel({ slides, index, defaultIndex = 0, onIndexChange, ariaLabel, words: given, className }) {
+    const words = { ...ENGLISH, ...given };
+    const [uncontrolled, setUncontrolled] = useState(defaultIndex);
+    const prevRef = useRef(null);
+    const nextRef = useRef(null);
+    const regionRef = useRef(null);
+    const controlsRef = useRef(null);
+    /* The step last focused, so a step that disables under it is rescued
+       even where the browser already moved focus to the body on disable. */
+    const lastStepRef = useRef(null);
+    const current = slides.length ? Math.min(Math.max(index ?? uncontrolled, 0), slides.length - 1) : 0;
+    const go = (next) => {
+        const clamped = Math.min(Math.max(next, 0), slides.length - 1);
+        if (index === undefined)
+            setUncontrolled(clamped);
+        onIndexChange?.(clamped);
+    };
+    /* A step that disables under its own focus hands focus on: the other
+       step where it is live, the region itself where both ends are shut
+       (one slide). Rescue runs only while focus is still on that step or
+       has already fallen to the body — a reader who tabbed onward is never
+       pulled back, and a caller-driven index change moves nothing. */
+    useEffect(() => {
+        if (!slides.length)
+            return;
+        const active = document.activeElement;
+        const lost = active === document.body;
+        /* The rescued step becomes the last-focused one: the next disable
+           under it rescues again, even where the rescue focus itself is
+           what set the ref (the null-after-focus ordering bug, otherwise). */
+        const focusStep = (step) => {
+            const other = step === 'prev' ? prevRef.current : nextRef.current;
+            if (other && !other.disabled) {
+                other.focus();
+                lastStepRef.current = step;
+            }
+            else {
+                regionRef.current?.focus();
+                lastStepRef.current = null;
+            }
+        };
+        if (current === 0 && lastStepRef.current === 'prev' && (lost || active === prevRef.current))
+            focusStep('next');
+        else if (current === slides.length - 1 && lastStepRef.current === 'next' && (lost || active === nextRef.current))
+            focusStep('prev');
+    }, [current, slides.length]);
+    if (!slides.length)
+        return null;
+    const onRegionKeyDown = (event) => {
+        /* The keys are the carousel's only while focus is on the carousel itself or its own controls. A widget inside a
+           slide (an input's caret, a slider, a tab list, a menu) owns them, and so does anything drawn in a portal: React
+           delivers a portal's events up through this tree, so the DOM, not the React tree, says whose they are. */
+        const target = event.target;
+        if (target !== regionRef.current && !(target && controlsRef.current?.contains(target)))
+            return;
+        if (event.key === 'ArrowLeft') {
+            event.preventDefault();
+            go(current - 1);
+        }
+        else if (event.key === 'ArrowRight') {
+            event.preventDefault();
+            go(current + 1);
+        }
+        else if (event.key === 'Home') {
+            event.preventDefault();
+            go(0);
+        }
+        else if (event.key === 'End') {
+            event.preventDefault();
+            go(slides.length - 1);
+        }
+    };
+    return (_jsxs("section", { ref: regionRef, className: ['ui-carousel', className].filter(Boolean).join(' '), "aria-roledescription": "carousel", "aria-label": ariaLabel ?? words.region, 
+        /* Programmatic focus only, for the step-disable rescue above:
+           -1 is no tab stop. */
+        tabIndex: -1, onKeyDown: onRegionKeyDown, children: [_jsx("div", { className: "ui-carousel-viewport", children: _jsx("div", { className: "ui-carousel-track", style: { transform: `translateX(-${current * 100}%)` }, children: slides.map((slide, i) => (_jsx("div", { className: "ui-carousel-slide", role: "group", "aria-roledescription": "slide", "aria-label": words.slide(i + 1, slides.length, slide.label), "aria-hidden": i !== current || undefined, inert: i !== current || undefined, children: slide.children }, i))) }) }), _jsxs("div", { className: "ui-carousel-controls", ref: controlsRef, children: [_jsx("button", { ref: prevRef, type: "button", className: "ui-carousel-step", disabled: current === 0, onFocus: () => {
+                            lastStepRef.current = 'prev';
+                        }, onClick: () => go(current - 1), children: words.previous }), _jsx("span", { className: "ui-carousel-dots", role: "group", "aria-label": words.chooseSlide, children: slides.map((slide, i) => (_jsx("button", { type: "button", className: "ui-carousel-dot", "aria-label": words.goToSlide(i + 1, slide.label), "aria-current": i === current || undefined, onClick: () => go(i) }, i))) }), _jsx("button", { ref: nextRef, type: "button", className: "ui-carousel-step", disabled: current === slides.length - 1, onFocus: () => {
+                            lastStepRef.current = 'next';
+                        }, onClick: () => go(current + 1), children: words.next })] }), _jsx("p", { className: "ui-carousel-status", "aria-live": "polite", children: words.status(current + 1, slides.length, slides[current]?.label) })] }));
+}

package/dist/Choices.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Choices drawn as buttons, cards and checkboxes: Yes/No, icon cards (one or several), a checkbox and a consent. One
+ * answer is a native radio dressed, so the arrows, Space and the form's own semantics are the browser's, and the focus
+ * ring shows on the face when the keyboard is on the input. Several cards are one group as the radios are (CheckCards):
+ * one Tab stop, the arrows move between them, Space turns one on or off, and each says `aria-checked`. Props only.
+ * Preview: @mistriwork/ui is Preview at 1.0.
+ */
+import { type AriaAttributes, type ReactNode } from 'react';
+import { type FieldFrame } from './fieldFrame.js';
+export interface ChoiceOption {
+    value: string;
+    label: string;
+    /** A picture for a card. */
+    icon?: ReactNode;
+}
+export interface YesNoProps extends Omit<FieldFrame, 'label'> {
+    /** The question. */
+    label: ReactNode;
+    value: 'yes' | 'no' | '';
+    onChange: (value: 'yes' | 'no') => void;
+    /** The two words, in the caller's language. */
+    yes: string;
+    no: string;
+}
+/** Two buttons answering a question. */
+export declare function YesNo(props: YesNoProps): ReactNode;
+export interface ChoiceCardsProps extends FieldFrame {
+    options: ChoiceOption[];
+    value: string[];
+    onChange: (value: string[]) => void;
+    /** Several may be on. */
+    multiple?: boolean;
+    /** The card that stands alone ("None"): choosing it clears the rest, and choosing another clears it. */
+    exclusive?: string;
+}
+/** Cards with an icon, a label and a box. One choice is a radio group; `multiple` a group of checkboxes. */
+export declare function ChoiceCards(props: ChoiceCardsProps): ReactNode;
+/** One card of several: its words, its picture and whether it is on. */
+export interface CheckCard {
+    key: string;
+    label: ReactNode;
+    icon?: ReactNode;
+    /** A line under the label. */
+    help?: ReactNode;
+    on: boolean;
+}
+export interface CheckCardsProps {
+    cards: readonly CheckCard[];
+    /** The card at `index` turned on or off. */
+    onToggle: (index: number, on: boolean) => void;
+    id?: string;
+    disabled?: boolean;
+    'aria-labelledby'?: string;
+    'aria-describedby'?: string;
+    'aria-invalid'?: AriaAttributes['aria-invalid'];
+    /** How short every card's words are, so a wide page can set them side by side (`data-fit`; the page's stylesheet
+     * decides what that means): `short` is a label alone, `brief` a label and a line that fit half a column. */
+    fit?: 'short' | 'brief';
+}
+/**
+ * Several cards, any of them on: full-width cards, each an icon, its words and a square at its end that fills when it
+ * is on. They are one group to the keyboard, as radios are — one Tab stop (the card last moved to, else the first one
+ * on, else the first), the arrows and Home and End move between them, and Space turns the one in hand on or off — and
+ * each is a `checkbox` saying `aria-checked`, so a screen reader hears "checked" as it moves.
+ */
+export declare function CheckCards(props: CheckCardsProps): ReactNode;
+export interface CheckboxProps extends Omit<FieldFrame, 'label'> {
+    checked: boolean;
+    onChange: (on: boolean) => void;
+    /** The text beside the box; it is the label, so it is a click target too. */
+    label: ReactNode;
+    disabled?: boolean;
+}
+/** A checkbox beside its text. */
+export declare function Checkbox(props: CheckboxProps): ReactNode;
+/** A checkbox for a long notice: the paragraph is the label, in the body's weight. */
+export declare function Consent(props: CheckboxProps): ReactNode;

package/dist/Choices.js

@@ -0,0 +1,88 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Choices drawn as buttons, cards and checkboxes: Yes/No, icon cards (one or several), a checkbox and a consent. One
+ * answer is a native radio dressed, so the arrows, Space and the form's own semantics are the browser's, and the focus
+ * ring shows on the face when the keyboard is on the input. Several cards are one group as the radios are (CheckCards):
+ * one Tab stop, the arrows move between them, Space turns one on or off, and each says `aria-checked`. Props only.
+ * Preview: @mistriwork/ui is Preview at 1.0.
+ */
+import { useId, useRef, useState } from 'react';
+import { Field } from './Field.js';
+import { frameOf } from './fieldFrame.js';
+/** Two buttons answering a question. */
+export function YesNo(props) {
+    const name = useId();
+    return (_jsx(Field, { ...frameOf(props), group: true, children: (control) => (_jsx("div", { className: "choice-pair", role: "radiogroup", "aria-labelledby": control['aria-labelledby'], "aria-describedby": control['aria-describedby'], "aria-invalid": control['aria-invalid'], children: ['yes', 'no'].map((v) => (_jsxs("label", { className: `choice-pick${props.value === v ? ' is-on' : ''}`, children: [_jsx("input", { type: "radio", name: name, className: "choice-input", checked: props.value === v, onChange: () => props.onChange(v) }), props[v]] }, v))) })) }));
+}
+/** Cards with an icon, a label and a box. One choice is a radio group; `multiple` a group of checkboxes. */
+export function ChoiceCards(props) {
+    const name = useId();
+    const toggle = (v, on) => {
+        if (!props.multiple)
+            return props.onChange(on ? [v] : []);
+        if (v === props.exclusive)
+            return props.onChange(on ? [v] : []);
+        const rest = props.value.filter((x) => x !== v && x !== props.exclusive);
+        props.onChange(on ? props.options.map((o) => o.value).filter((x) => x === v || rest.includes(x)) : rest);
+    };
+    if (props.multiple)
+        return (_jsx(Field, { ...frameOf(props), group: true, children: (control) => (_jsx(CheckCards, { "aria-labelledby": control['aria-labelledby'], "aria-describedby": control['aria-describedby'], "aria-invalid": control['aria-invalid'], cards: props.options.map((o) => ({ key: o.value, label: o.label, icon: o.icon, on: props.value.includes(o.value) })), onToggle: (index, on) => toggle(props.options[index].value, on) })) }));
+    return (_jsx(Field, { ...frameOf(props), group: true, children: (control) => (_jsx("div", { className: "choice-cards", role: "radiogroup", "aria-labelledby": control['aria-labelledby'], "aria-describedby": control['aria-describedby'], "aria-invalid": control['aria-invalid'], children: props.options.map((o) => {
+                const on = props.value.includes(o.value);
+                return (_jsxs("label", { className: `choice-card${on ? ' is-on' : ''}`, children: [o.icon ? (_jsx("span", { className: "choice-card-icon", "aria-hidden": "true", children: o.icon })) : null, _jsx("span", { className: "choice-card-label", children: o.label }), _jsx("input", { type: "radio", name: name, className: "choice-input", checked: on, onChange: (e) => toggle(o.value, e.target.checked) }), _jsx("span", { className: "choice-box", "aria-hidden": "true" })] }, o.value));
+            }) })) }));
+}
+/**
+ * Several cards, any of them on: full-width cards, each an icon, its words and a square at its end that fills when it
+ * is on. They are one group to the keyboard, as radios are — one Tab stop (the card last moved to, else the first one
+ * on, else the first), the arrows and Home and End move between them, and Space turns the one in hand on or off — and
+ * each is a `checkbox` saying `aria-checked`, so a screen reader hears "checked" as it moves.
+ */
+export function CheckCards(props) {
+    const { cards } = props;
+    const [held, setHeld] = useState(undefined);
+    const faces = useRef([]);
+    const first = cards.findIndex((card) => card.on);
+    const stop = held !== undefined && held < cards.length ? held : Math.max(first, 0);
+    const move = (to) => {
+        const next = (to + cards.length) % cards.length;
+        setHeld(next);
+        faces.current[next]?.focus();
+    };
+    const keys = (event, index) => {
+        const to = event.key === 'ArrowDown' || event.key === 'ArrowRight'
+            ? index + 1
+            : event.key === 'ArrowUp' || event.key === 'ArrowLeft'
+                ? index - 1
+                : event.key === 'Home'
+                    ? 0
+                    : event.key === 'End'
+                        ? cards.length - 1
+                        : undefined;
+        if (to !== undefined) {
+            event.preventDefault();
+            move(to);
+        }
+        else if (event.key === ' ') {
+            // Space is the box's own key; the page does not scroll under it.
+            event.preventDefault();
+            if (!props.disabled)
+                props.onToggle(index, !cards[index].on);
+        }
+    };
+    return (_jsx("div", { className: "choice-cards", role: "group", "data-fit": props.fit, id: props.id, "aria-labelledby": props['aria-labelledby'], "aria-describedby": props['aria-describedby'], "aria-invalid": props['aria-invalid'], children: cards.map((card, index) => (_jsxs("div", { ref: (face) => {
+                faces.current[index] = face;
+            }, role: "checkbox", "aria-checked": card.on, "aria-disabled": props.disabled || undefined, tabIndex: index === stop ? 0 : -1, className: `choice-card${card.on ? ' is-on' : ''}`, onClick: () => {
+                setHeld(index);
+                if (!props.disabled)
+                    props.onToggle(index, !card.on);
+            }, onFocus: () => setHeld(index), onKeyDown: (event) => keys(event, index), children: [card.icon ? (_jsx("span", { className: "choice-card-icon", "aria-hidden": "true", children: card.icon })) : null, _jsxs("span", { className: "choice-card-label", children: [card.label, card.help ? _jsx("span", { className: "choice-card-help", children: card.help }) : null] }), _jsx("span", { className: "choice-box", "aria-hidden": "true" })] }, card.key))) }));
+}
+/** A checkbox beside its text. */
+export function Checkbox(props) {
+    return (_jsx(Field, { ...frameOf(props), check: true, children: (control) => (_jsx("input", { ...control, type: "checkbox", className: "field-check", checked: props.checked, disabled: props.disabled, onChange: (e) => props.onChange(e.target.checked) })) }));
+}
+/** A checkbox for a long notice: the paragraph is the label, in the body's weight. */
+export function Consent(props) {
+    return _jsx(Checkbox, { ...props, className: ['form-field-consent', props.className].filter(Boolean).join(' ') });
+}

package/dist/DateField.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The themed calendar field: editable ISO text beside a calendar popover,
+ * for a date, or with `withTime` for a date and a wall-clock time. The text
+ * is the value — typed drafts survive, the calendar only ever writes the
+ * date part — and nothing here converts a value through an instant. The
+ * arithmetic and the bounds are datePickerModel.ts's. Its words and the
+ * calendar button's icon are props: the kit lends its catalog's and its icon.
+ */
+import { type AriaAttributes, type KeyboardEvent, type ReactNode, type Ref } from 'react';
+/** What a date field says. A `format` is the locale's numeric date pattern ("MM/DD/YYYY"). */
+export interface DateFieldWords {
+    /** The placeholder and the format a date and a time are typed in. */
+    dateTimePattern: string;
+    /** The box's complaint at a date and time it cannot take. */
+    enterDateAndTime: string;
+    /** The box's complaint at a date it cannot take. */
+    enterDate: (format: string) => string;
+    /** The hint read with the box: its format, for a date and a time. */
+    dateAndTimeFormat: string;
+    /** The hint read with the box: its format, for a date. */
+    dateFormat: (format: string) => string;
+    /** The hint's second sentence: the key that opens the calendar. */
+    openWithKeys: string;
+    /** The calendar button's name, with the field's label when it has one. */
+    chooseDate: (label?: string) => string;
+    /** The calendar's name, with the field's label when it has one. */
+    calendar: (label?: string) => string;
+    previousMonth: string;
+    nextMonth: string;
+    clear: string;
+    today: string;
+}
+export interface DateFieldProps {
+    id: string;
+    words: DateFieldWords;
+    /** Drawn in the calendar button. */
+    calendarIcon: ReactNode;
+    value: string;
+    /** Typed text is preserved, including an incomplete date; callers validate on commit. */
+    onChange: (value: string) => void;
+    /** Composite blur: never fired while focus moves between the input and calendar. */
+    onBlur?: () => void;
+    onKeyDown?: (event: KeyboardEvent<HTMLInputElement>) => void;
+    disabled?: boolean;
+    required?: boolean;
+    min?: string;
+    max?: string;
+    locale?: string;
+    timezone?: string;
+    firstDay?: number;
+    className?: string;
+    name?: string;
+    inputRef?: Ref<HTMLInputElement>;
+    placeholder?: string;
+    /** A date and a wall-clock time (`YYYY-MM-DD HH:MM`, as the box says it; the `T` a datetime-local control writes is read too): the calendar
+        picks the date and keeps the time typed. `min` and `max` then bound the whole value. */
+    withTime?: boolean;
+    /** The calendar is drawn in a portal; an owner that watches focus (an autosaving field) is told where. */
+    popupRef?: (node: HTMLDivElement | null) => void;
+    onOpenChange?: (open: boolean) => void;
+    'aria-label'?: string;
+    'aria-invalid'?: AriaAttributes['aria-invalid'];
+    'aria-describedby'?: string;
+}
+/** A date field, or a date and a wall-clock time. No input is parsed as an instant or shifted by a timezone. */
+export declare function DateField({ id, words, calendarIcon, value, onChange, onBlur, onKeyDown, disabled, required, min, max, locale, timezone, firstDay, className, name, inputRef, placeholder, withTime, popupRef, onOpenChange, 'aria-label': label, 'aria-invalid': invalid, 'aria-describedby': describedBy, }: DateFieldProps): import("react").JSX.Element;