@nanisoft/prism-ui 0.10.2 → 0.15.0

package/dist/components/ui/calendar.d.ts

@@ -0,0 +1,167 @@
+/**
+ * The seven weekday headings, in the order the reader's week begins.
+ *
+ * A tuple rather than an array of strings, so the compiler refuses a caller who
+ * passed six. A grid whose header is one column short is a grid whose first and
+ * last rows are shifted by a day, and nothing on the screen shows it.
+ */
+export type CalendarWeekdays = readonly [
+    string,
+    string,
+    string,
+    string,
+    string,
+    string,
+    string
+];
+/** The props the Calendar accepts. */
+export interface CalendarProps {
+    /**
+     * The accessible name of the grid.
+     *
+     * Required. A grid with no name is a table of numbers, and a reader who cannot
+     * tell a delivery date from a return date is being asked to guess.
+     */
+    label: string;
+    /**
+     * The caption over the grid, for the month on show.
+     *
+     * A prop, and the reason it is a prop is the reason every word in this
+     * Component is one: a month name is reader-facing text in the reader's language
+     * and the reader's calendar convention, and a Component that carried a table of
+     * them would ship English and a Western year into every consumer's product.
+     * Format it with the same `Intl` call the rest of the product uses.
+     */
+    monthLabel: string;
+    /** The seven weekday headings, starting from `firstWeekday`. */
+    weekdayLabels: CalendarWeekdays;
+    /**
+     * Which day the reader's week starts on, as `Date.prototype.getDay()` numbers
+     * it, so `0` is Sunday.
+     *
+     * Defaults to Sunday because that is what `getDay` returns and a default a
+     * caller may override is the honest one. Pass it for a Monday-first locale, and
+     * order `weekdayLabels` to match: the two are the same fact and the Component
+     * cannot infer either half of it.
+     */
+    firstWeekday?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+    /** The accessible name of the control that steps back one month. */
+    previousLabel: string;
+    /** The accessible name of the control that steps forward one month. */
+    nextLabel: string;
+    /**
+     * The month on show.
+     *
+     * Controlled, and required to be, because the first month a calendar may open
+     * on is a rule about the reader's situation rather than about the calendar: a
+     * booking form opens on next month, an archive opens on the month the record is
+     * in. A calendar that kept that state would have to be told the rule twice.
+     */
+    month: Date;
+    /** Called with the first day of the month when the reader moves between months. */
+    onMonthChange: (month: Date) => void;
+    /**
+     * The chosen date, or `null` for nothing chosen.
+     *
+     * The grid marks the chosen date with `aria-selected`, so this is also what the
+     * month opens on when the reader has already answered.
+     */
+    value?: Date | null;
+    /** Called with the date the reader chooses. Never called with a disabled date. */
+    onValueChange?: (date: Date) => void;
+    /**
+     * Whether a date cannot be chosen.
+     *
+     * A disabled date stays in the grid and stays reachable by the arrow keys,
+     * announced as unavailable and refusing to be chosen. A date that is simply
+     * absent is indistinguishable from a grid that failed to draw that week, and a
+     * reader who cannot land on it cannot tell a sold-out day from a bug. Say why
+     * it is unavailable in text beside the field.
+     */
+    isDateDisabled?: (date: Date) => boolean;
+    /**
+     * The full accessible name of a day cell.
+     *
+     * A date is a phrase in the reader's language and their date convention, so it
+     * is the caller's. Without it the cell is named by its day number and its column
+     * heading, which is what grid navigation already conveys.
+     */
+    dayLabel?: (date: Date) => string;
+    /**
+     * The date to mark as today, when the reader's clock is not the renderer's.
+     *
+     * The mark is drawn and announced by `aria-current="date"`, which is a machine
+     * value, so no word is spent on it.
+     */
+    today?: Date;
+    /** Whether the reader may not change the month or choose a date. */
+    disabled?: boolean;
+    /**
+     * The form field name. The chosen date is submitted as `YYYY-MM-DD`.
+     *
+     * The field is a plain hidden input rather than a date input, so the value is
+     * one format the caller can parse without reading the reader's display
+     * convention out of the string.
+     */
+    name?: string;
+    /** Identifies the form that owns the hidden input. */
+    form?: string;
+    /** Layout only. */
+    className?: string;
+}
+/**
+ * A month grid for picking one date.
+ *
+ * **It is built here because Base UI does not ship one.** The package at 1.8.0
+ * has a combobox, a number field, an OTP field and a field, and no calendar, so
+ * there is nothing to compose and everything here is the Component's own. That is
+ * stated rather than implied because "the docs show one" is not evidence, and a
+ * wrapper around a module that is not in the installed package is the failure this
+ * Component could have shipped.
+ *
+ * **The grid is always six weeks tall.** A month that needs five rows and a month
+ * that needs six would otherwise resize as the reader pages through, which moves
+ * the dates under the pointer and under the highlight: a reader who aims at the
+ * 24th after reading its position in a five-row month clicks the 31st in a
+ * six-row one. The empty cells at the edges are marked `aria-hidden` rather than
+ * filled with the neighbouring month's dates, because a date from another month in
+ * this grid is a date the reader did not come for.
+ *
+ * **Every date, weekday name and month name is the caller's.** The caption, the
+ * seven column headings and the month the reader moves to are all reader-facing
+ * text in the reader's language, and the Component has no business carrying a
+ * table of them. What it does carry is the geometry: which column a date falls in
+ * and which day it sits on.
+ *
+ * **One cell is in the tab order, and the arrows move it.** The roving tab stop
+ * sits on the chosen date, or on today, or on the first of the month, so a reader
+ * who tabs in lands on the date they care about rather than on the 1st. The arrows
+ * step a day and a week, Home and End step to the ends of the week, and PageUp and
+ * PageDown step a month, with Shift for a year. Moving past the end of a month
+ * changes the month on show and carries the focus with it, so paging never leaves
+ * the highlight on a cell that is no longer drawn.
+ *
+ * **A disabled date is drawn, reachable and refused.** It stays in the grid and
+ * stays in the arrow path, because a date that is simply missing is
+ * indistinguishable from a grid that failed to render that week, and a reader who
+ * cannot reach it cannot tell a fully booked day from a bug. Enter, Space and a
+ * click on it do nothing, and it announces as unavailable. Explain the reason in
+ * text beside the field; a greyed cell on its own says only that it is not
+ * available.
+ *
+ * **The caption is a live region.** Paging a month changes the month with no other
+ * visible change for a reader who is on the grid, so the caption announces itself
+ * when it changes.
+ *
+ * **A coarse pointer gets the 44px floor and the desktop metrics are untouched.**
+ * Both the day cell and the two paging controls grow inside `@media (pointer: coarse)`
+ * and are 36px and 32px for a mouse and a trackpad. The grid is the densest control
+ * in this package, so the floor costs it the most: on a phone six rows of 44px is a
+ * taller panel than six rows of 36px, and that is the price the whole package has
+ * already agreed to pay for every other control rather than a reason this one is the
+ * exception. A month grid is also the control a finger is least able to aim at, so it
+ * is the last place the floor can be argued about.
+ */
+declare function Calendar({ label, monthLabel, weekdayLabels, firstWeekday, previousLabel, nextLabel, month, onMonthChange, value, onValueChange, isDateDisabled, dayLabel, today, disabled, name, form, className, }: CalendarProps): import("react").JSX.Element;
+export { Calendar };
+//# sourceMappingURL=calendar.d.ts.map

package/dist/components/ui/calendar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"calendar.d.ts","sourceRoot":"","sources":["../../../src/components/ui/calendar.tsx"],"names":[],"mappings":"AAOA;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,SAAS;IACtC,MAAM;IACN,MAAM;IACN,MAAM;IACN,MAAM;IACN,MAAM;IACN,MAAM;IACN,MAAM;CACP,CAAA;AAED,sCAAsC;AACtC,MAAM,WAAW,aAAa;IAC5B;;;;;OAKG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;;OAQG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB,gEAAgE;IAChE,aAAa,EAAE,gBAAgB,CAAA;IAC/B;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IACxC,oEAAoE;IACpE,aAAa,EAAE,MAAM,CAAA;IACrB,uEAAuE;IACvE,SAAS,EAAE,MAAM,CAAA;IACjB;;;;;;;OAOG;IACH,KAAK,EAAE,IAAI,CAAA;IACX,mFAAmF;IACnF,aAAa,EAAE,CAAC,KAAK,EAAE,IAAI,KAAK,IAAI,CAAA;IACpC;;;;;OAKG;IACH,KAAK,CAAC,EAAE,IAAI,GAAG,IAAI,CAAA;IACnB,kFAAkF;IAClF,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,IAAI,CAAA;IACpC;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAA;IACxC;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,MAAM,CAAA;IACjC;;;;;OAKG;IACH,KAAK,CAAC,EAAE,IAAI,CAAA;IACZ,oEAAoE;IACpE,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,mBAAmB;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAwED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,iBAAS,QAAQ,CAAC,EAChB,KAAK,EACL,UAAU,EACV,aAAa,EACb,YAAgB,EAChB,aAAa,EACb,SAAS,EACT,KAAK,EACL,aAAa,EACb,KAAY,EACZ,aAAa,EACb,cAAc,EACd,QAAQ,EACR,KAAK,EACL,QAAgB,EAChB,IAAI,EACJ,IAAI,EACJ,SAAS,GACV,EAAE,aAAa,+BAyPf;AAED,OAAO,EAAE,QAAQ,EAAE,CAAA"}

package/dist/components/ui/calendar.js

@@ -0,0 +1,244 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ChevronLeftIcon, ChevronRightIcon } from 'lucide-react';
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { cn } from '../../lib/utils.js';
+/** `YYYY-MM-DD` in local time, which is the only date format a form should post. */
+function iso(date) {
+    return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')}`;
+}
+const addDays = (date, days) => new Date(date.getFullYear(), date.getMonth(), date.getDate() + days);
+const startOfMonth = (date) => new Date(date.getFullYear(), date.getMonth(), 1);
+const sameMonth = (a, b) => a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth();
+const sameDay = (a, b) => a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth() && a.getDate() === b.getDate();
+/**
+ * The same day of the month, `months` along.
+ *
+ * The day is clamped to the length of the month it lands in, so stepping back from
+ * the 31st lands on the 30th, the 28th or the 29th rather than rolling into the
+ * month before. A calendar that rolled would move the focus to a different month
+ * than the reader asked for, and the date would be wrong by a month with nothing
+ * on screen to say so.
+ */
+const shiftMonth = (date, months) => {
+    const target = new Date(date.getFullYear(), date.getMonth() + months, 1);
+    const lastDay = new Date(target.getFullYear(), target.getMonth() + 1, 0).getDate();
+    return new Date(target.getFullYear(), target.getMonth(), Math.min(date.getDate(), lastDay));
+};
+const DAY_CELL = 
+// `transition-colors` is a property list, which Tailwind owns; the duration and
+// the easing are the motion tokens, and neither is written here as a number.
+//
+// The `pointer-coarse:h-11` is the same step `mini-calendar.tsx` takes on the same
+// control, and it was missing here for the reason a pair of identical controls in
+// one package usually diverges: the smaller grid was written first and the floor
+// was added to it, and the fuller grid kept the 36px cell that is the same cell at
+// a different size. A month grid is the densest control in the package and the one
+// most worked with a thumb, so it is the last place the floor can be argued about.
+'text-foreground hover:bg-accent hover:text-accent-foreground flex h-9 w-full cursor-pointer items-center justify-center rounded-md text-sm tabular-nums outline-none transition-colors duration-fast ease-out pointer-coarse:h-11 focus-visible:ring-ring focus-visible:ring-[3px]';
+/**
+ * The two paging controls.
+ *
+ * Held as one string for the same reason `mini-calendar.tsx` holds its own as one:
+ * they were written twice, as `size-8` each, and the small calendar's copy grew the
+ * coarse-pointer floor while this one did not. The identical control in one package
+ * at two target sizes is the defect, not the 32px, so the two strings are written out
+ * in both files on purpose: a shared constant would couple two Components that are
+ * allowed to diverge, and the line that has to stay in step is exactly the one that
+ * should be visible at both call sites.
+ */
+const NAV_CONTROL = 'text-muted-foreground hover:bg-accent hover:text-accent-foreground inline-flex size-8 shrink-0 items-center justify-center rounded-md outline-none transition-colors duration-fast ease-out pointer-coarse:size-11 focus-visible:ring-ring focus-visible:ring-[3px]';
+/**
+ * How a day cell looks.
+ *
+ * `selected` states a fill and therefore states its own ink. `today` does not set
+ * a fill, so it does not set an ink: it is a ring inside the cell and a weight,
+ * and a ring has no foreground to keep in step with the two states above it.
+ */
+const DAY_STATE = {
+    selected: 'bg-primary text-primary-foreground hover:bg-primary hover:text-primary-foreground font-semibold',
+    today: 'ring-ring ring-1 ring-inset font-semibold',
+    unavailable: 'text-muted-foreground aria-disabled:hover:bg-transparent',
+};
+/**
+ * A month grid for picking one date.
+ *
+ * **It is built here because Base UI does not ship one.** The package at 1.8.0
+ * has a combobox, a number field, an OTP field and a field, and no calendar, so
+ * there is nothing to compose and everything here is the Component's own. That is
+ * stated rather than implied because "the docs show one" is not evidence, and a
+ * wrapper around a module that is not in the installed package is the failure this
+ * Component could have shipped.
+ *
+ * **The grid is always six weeks tall.** A month that needs five rows and a month
+ * that needs six would otherwise resize as the reader pages through, which moves
+ * the dates under the pointer and under the highlight: a reader who aims at the
+ * 24th after reading its position in a five-row month clicks the 31st in a
+ * six-row one. The empty cells at the edges are marked `aria-hidden` rather than
+ * filled with the neighbouring month's dates, because a date from another month in
+ * this grid is a date the reader did not come for.
+ *
+ * **Every date, weekday name and month name is the caller's.** The caption, the
+ * seven column headings and the month the reader moves to are all reader-facing
+ * text in the reader's language, and the Component has no business carrying a
+ * table of them. What it does carry is the geometry: which column a date falls in
+ * and which day it sits on.
+ *
+ * **One cell is in the tab order, and the arrows move it.** The roving tab stop
+ * sits on the chosen date, or on today, or on the first of the month, so a reader
+ * who tabs in lands on the date they care about rather than on the 1st. The arrows
+ * step a day and a week, Home and End step to the ends of the week, and PageUp and
+ * PageDown step a month, with Shift for a year. Moving past the end of a month
+ * changes the month on show and carries the focus with it, so paging never leaves
+ * the highlight on a cell that is no longer drawn.
+ *
+ * **A disabled date is drawn, reachable and refused.** It stays in the grid and
+ * stays in the arrow path, because a date that is simply missing is
+ * indistinguishable from a grid that failed to render that week, and a reader who
+ * cannot reach it cannot tell a fully booked day from a bug. Enter, Space and a
+ * click on it do nothing, and it announces as unavailable. Explain the reason in
+ * text beside the field; a greyed cell on its own says only that it is not
+ * available.
+ *
+ * **The caption is a live region.** Paging a month changes the month with no other
+ * visible change for a reader who is on the grid, so the caption announces itself
+ * when it changes.
+ *
+ * **A coarse pointer gets the 44px floor and the desktop metrics are untouched.**
+ * Both the day cell and the two paging controls grow inside `@media (pointer: coarse)`
+ * and are 36px and 32px for a mouse and a trackpad. The grid is the densest control
+ * in this package, so the floor costs it the most: on a phone six rows of 44px is a
+ * taller panel than six rows of 36px, and that is the price the whole package has
+ * already agreed to pay for every other control rather than a reason this one is the
+ * exception. A month grid is also the control a finger is least able to aim at, so it
+ * is the last place the floor can be argued about.
+ */
+function Calendar({ label, monthLabel, weekdayLabels, firstWeekday = 0, previousLabel, nextLabel, month, onMonthChange, value = null, onValueChange, isDateDisabled, dayLabel, today, disabled = false, name, form, className, }) {
+    const gridRef = useRef(null);
+    // `null` means "wherever the reader would expect to land", which is derived
+    // rather than stored, so an external change to `value` or `month` moves the tab
+    // stop without this Component having to watch for it.
+    const [movedTo, setMovedTo] = useState(null);
+    const isUnavailable = useMemo(() => (date) => disabled || (isDateDisabled?.(date) ?? false), [disabled, isDateDisabled]);
+    /**
+     * Six weeks from the Sunday, or the reader's first day, on or before the first
+     * of the month.
+     */
+    const cells = useMemo(() => {
+        const first = startOfMonth(month);
+        const offset = (first.getDay() - firstWeekday + 7) % 7;
+        const start = addDays(first, -offset);
+        return Array.from({ length: 42 }, (_, index) => addDays(start, index));
+    }, [month, firstWeekday]);
+    /**
+     * Where a reader who tabs into the grid lands: the chosen date, else today, else
+     * the first of the month. A month on show is never empty, so there is always an
+     * answer and the grid is always reachable by one Tab.
+     */
+    const landing = useMemo(() => {
+        if (value !== null && sameMonth(value, month))
+            return value;
+        if (today !== undefined && sameMonth(today, month))
+            return today;
+        return startOfMonth(month);
+    }, [value, today, month]);
+    const focused = movedTo !== null && sameMonth(movedTo, month) ? movedTo : landing;
+    /** Focus follows a move, because a move that changed month draws a new cell. */
+    useEffect(() => {
+        if (movedTo === null)
+            return;
+        gridRef.current?.querySelector(`[data-date="${iso(movedTo)}"]`)?.focus();
+    }, [movedTo, month]);
+    /** Moves the tab stop, and the month on show when the move crosses a month. */
+    const goTo = (date) => {
+        setMovedTo(date);
+        if (!sameMonth(date, month))
+            onMonthChange(startOfMonth(date));
+    };
+    const choose = (date) => {
+        // The tab stop follows whatever the reader last operated, so a click leaves the
+        // grid in the state the reader is now looking at rather than snapping the stop
+        // back to the landing cell.
+        setMovedTo(date);
+        if (isUnavailable(date))
+            return;
+        onValueChange?.(date);
+    };
+    /**
+     * The keys on one day cell.
+     *
+     * The date comes from the cell the event fired on rather than from state,
+     * because a reader may have reached a cell by Tab or by a click and the tab stop
+     * is the Component's own decision. Deriving the move from state would step from
+     * wherever the tab stop happened to be, which is a cell the reader is not on.
+     */
+    const onDayKeyDown = (event, date) => {
+        const row = Math.floor(cells.findIndex((entry) => sameDay(entry, date)) / 7);
+        const first = cells[row * 7];
+        const last = first === undefined ? null : addDays(first, 6);
+        // Enter by `key`, Space by `code`. The space bar's `key` has been reported as a
+        // space, as "Spacebar" and as "Space" by different engines over the years, and
+        // its `code` has been the same in all of them, so this is the one activation key
+        // whose physical position is the more reliable half of the event.
+        if (event.key === 'Enter' || event.code === 'Space') {
+            event.preventDefault();
+            choose(date);
+            return;
+        }
+        switch (event.key) {
+            case 'ArrowLeft':
+                event.preventDefault();
+                goTo(addDays(date, -1));
+                return;
+            case 'ArrowRight':
+                event.preventDefault();
+                goTo(addDays(date, 1));
+                return;
+            case 'ArrowUp':
+                event.preventDefault();
+                goTo(addDays(date, -7));
+                return;
+            case 'ArrowDown':
+                event.preventDefault();
+                goTo(addDays(date, 7));
+                return;
+            case 'Home':
+                event.preventDefault();
+                if (first !== undefined)
+                    goTo(first);
+                return;
+            case 'End':
+                event.preventDefault();
+                if (last !== null)
+                    goTo(last);
+                return;
+            case 'PageUp':
+                event.preventDefault();
+                goTo(shiftMonth(date, event.shiftKey ? -12 : -1));
+                return;
+            case 'PageDown':
+                event.preventDefault();
+                goTo(shiftMonth(date, event.shiftKey ? 12 : 1));
+                return;
+            default:
+        }
+    };
+    const focusedIso = iso(focused);
+    const chosenIso = value === null ? null : iso(value);
+    const todayIso = today === undefined ? null : iso(today);
+    return (_jsxs("div", { "data-slot": "calendar", className: cn('bg-popover text-popover-foreground w-64 rounded-md border p-3 shadow-md', className), children: [_jsxs("div", { className: "mb-2 flex items-center justify-between gap-1", children: [_jsx("button", { type: "button", "data-slot": "calendar-previous", "aria-label": previousLabel, disabled: disabled, onClick: () => onMonthChange(shiftMonth(month, -1)), className: cn(NAV_CONTROL, 'disabled:pointer-events-none disabled:opacity-50'), children: _jsx(ChevronLeftIcon, { className: "size-4" }) }), _jsx("div", { "data-slot": "calendar-caption", "aria-live": "polite", className: "text-foreground text-sm font-medium tabular-nums", children: monthLabel }), _jsx("button", { type: "button", "data-slot": "calendar-next", "aria-label": nextLabel, disabled: disabled, onClick: () => onMonthChange(shiftMonth(month, 1)), className: cn(NAV_CONTROL, 'disabled:pointer-events-none disabled:opacity-50'), children: _jsx(ChevronRightIcon, { className: "size-4" }) })] }), _jsx("div", { ref: gridRef, children: _jsxs("table", { "data-slot": "calendar-grid", role: "grid", "aria-label": label, className: "w-full border-collapse tabular-nums", children: [_jsx("thead", { children: _jsx("tr", { children: weekdayLabels.map((weekday, column) => (_jsx("th", { scope: "col", "data-slot": "calendar-weekday", className: "text-muted-foreground flex h-8 items-center justify-center text-xs font-medium", children: weekday }, `${weekday}-${column}`))) }) }), _jsx("tbody", { children: Array.from({ length: 6 }, (_, row) => (_jsx("tr", { children: cells.slice(row * 7, row * 7 + 7).map((date) => {
+                                    const key = iso(date);
+                                    if (!sameMonth(date, month)) {
+                                        // The cells that pad the month out. They are hidden from the
+                                        // accessibility tree rather than filled with the neighbouring
+                                        // month's dates, because a date from another month drawn in
+                                        // this grid is a date the reader did not come for.
+                                        return (_jsx("td", { role: "gridcell", "aria-hidden": "true", className: "p-0" }, key));
+                                    }
+                                    const unavailable = isUnavailable(date);
+                                    const isSelected = key === chosenIso;
+                                    const isToday = key === todayIso;
+                                    return (_jsx("td", { role: "gridcell", "data-slot": "calendar-day", "data-date": key, tabIndex: key === focusedIso ? 0 : -1, "aria-selected": isSelected, "aria-current": isToday ? 'date' : undefined, "aria-disabled": unavailable || undefined, ...(dayLabel === undefined ? null : { 'aria-label': dayLabel(date) }), onClick: () => choose(date), onKeyDown: (event) => onDayKeyDown(event, date), className: cn(DAY_CELL, unavailable && DAY_STATE.unavailable, isToday && !isSelected && DAY_STATE.today, isSelected && DAY_STATE.selected), children: date.getDate() }, key));
+                                }) }, row))) })] }) }), name === undefined ? null : (_jsx("input", { type: "hidden", name: name, ...(form === undefined ? null : { form }), value: chosenIso ?? '', readOnly: true }))] }));
+}
+export { Calendar };

package/dist/components/ui/card.d.ts

@@ -1,4 +1,5 @@
 import type { ComponentProps } from 'react';
+import type { HeadingElement } from './typography.js';
 /**
  * A bordered surface for a small group of related content.
  *
@@ -18,13 +19,24 @@ declare function CardHeader({ className, ...props }: ComponentProps<'div'>): imp
 /**
  * The card's title: the one line that names the group of related content.
  *
- * Renders a `div` rather than a heading, because a card's title is not always the
- * heading of the region it sits in: four cards in a grid are four titles under one
- * section heading, and four `h3`s under one `h2` is right while four `h2`s is
- * four sections. Pass Prism's `Heading` inside it when the card is the only thing
- * in its region and the outline should say so.
+ * Renders a `div` by default, because a card's title is not always the heading of
+ * the region it sits in: four cards in a grid are four titles under one section
+ * heading, and four `h3`s under one `h2` is right while four `h2`s is four
+ * sections. So the element is a decision the caller makes with `as`, and a Block
+ * that draws a set of titled cards passes `childLevel(headingLevel)` rather than a
+ * literal, so the titles follow the section when the block is composed one level
+ * deeper than it was written for.
+ *
+ * An earlier version of this note told a caller to pass Prism's `Heading` inside
+ * instead, and that was wrong. `Heading` is a step of the *type* scale and its
+ * floor is `lg`; a card title sits at body size, so the only way to use it was to
+ * override the size back down, which asks a type-scale component to have no opinion
+ * about type. The element and the visual step are separate questions and this is the
+ * one that answers the element.
  */
-declare function CardTitle({ className, ...props }: ComponentProps<'div'>): import("react").JSX.Element;
+declare function CardTitle({ className, as: Tag, ...props }: ComponentProps<'h2'> & {
+    as?: HeadingElement | 'div';
+}): import("react").JSX.Element;
 /**
  * The supporting line under a card's title: one sentence about what the card
  * holds.

package/dist/components/ui/card.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"card.d.ts","sourceRoot":"","sources":["../../../src/components/ui/card.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAA;AAI3C;;;;;;GAMG;AACH,iBAAS,IAAI,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,cAAc,CAAC,KAAK,CAAC,+BAW3D;AAED;;;;;;GAMG;AACH,iBAAS,UAAU,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,cAAc,CAAC,KAAK,CAAC,+BAWjE;AAED;;;;;;;;GAQG;AACH,iBAAS,SAAS,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,cAAc,CAAC,KAAK,CAAC,+BAQhE;AAED;;;GAGG;AACH,iBAAS,eAAe,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,cAAc,CAAC,KAAK,CAAC,+BAQtE;AAED,wEAAwE;AACxE,iBAAS,WAAW,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,cAAc,CAAC,KAAK,CAAC,+BAElE;AAED;;;GAGG;AACH,iBAAS,UAAU,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,cAAc,CAAC,KAAK,CAAC,+BAQjE;AAED,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,eAAe,EAAE,WAAW,EAAE,UAAU,EAAE,CAAA"}
+{"version":3,"file":"card.d.ts","sourceRoot":"","sources":["../../../src/components/ui/card.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAe,MAAM,OAAO,CAAA;AAExD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAIlD;;;;;;GAMG;AACH,iBAAS,IAAI,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,cAAc,CAAC,KAAK,CAAC,+BAW3D;AAED;;;;;;GAMG;AACH,iBAAS,UAAU,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,cAAc,CAAC,KAAK,CAAC,+BAWjE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,iBAAS,SAAS,CAAC,EACjB,SAAS,EACT,EAAE,EAAE,GAAW,EACf,GAAG,KAAK,EACT,EAAE,cAAc,CAAC,IAAI,CAAC,GAAG;IAAE,EAAE,CAAC,EAAE,cAAc,GAAG,KAAK,CAAA;CAAE,+BAcxD;AAED;;;GAGG;AACH,iBAAS,eAAe,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,cAAc,CAAC,KAAK,CAAC,+BAQtE;AAED,wEAAwE;AACxE,iBAAS,WAAW,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,cAAc,CAAC,KAAK,CAAC,+BAElE;AAED;;;GAGG;AACH,iBAAS,UAAU,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,cAAc,CAAC,KAAK,CAAC,+BAQjE;AAED,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,eAAe,EAAE,WAAW,EAAE,UAAU,EAAE,CAAA"}

package/dist/components/ui/card.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { cn } from '../../lib/utils';
+import { cn } from '../../lib/utils.js';
 /**
  * A bordered surface for a small group of related content.
  *
@@ -23,14 +23,29 @@ function CardHeader({ className, ...props }) {
 /**
  * The card's title: the one line that names the group of related content.
  *
- * Renders a `div` rather than a heading, because a card's title is not always the
- * heading of the region it sits in: four cards in a grid are four titles under one
- * section heading, and four `h3`s under one `h2` is right while four `h2`s is
- * four sections. Pass Prism's `Heading` inside it when the card is the only thing
- * in its region and the outline should say so.
+ * Renders a `div` by default, because a card's title is not always the heading of
+ * the region it sits in: four cards in a grid are four titles under one section
+ * heading, and four `h3`s under one `h2` is right while four `h2`s is four
+ * sections. So the element is a decision the caller makes with `as`, and a Block
+ * that draws a set of titled cards passes `childLevel(headingLevel)` rather than a
+ * literal, so the titles follow the section when the block is composed one level
+ * deeper than it was written for.
+ *
+ * An earlier version of this note told a caller to pass Prism's `Heading` inside
+ * instead, and that was wrong. `Heading` is a step of the *type* scale and its
+ * floor is `lg`; a card title sits at body size, so the only way to use it was to
+ * override the size back down, which asks a type-scale component to have no opinion
+ * about type. The element and the visual step are separate questions and this is the
+ * one that answers the element.
  */
-function CardTitle({ className, ...props }) {
-    return (_jsx("div", { "data-slot": "card-title", className: cn('font-semibold leading-none', className), ...props }));
+function CardTitle({ className, as: Tag = 'div', ...props }) {
+    // The same cast `Heading` makes, and for the same reason: the element is chosen
+    // at runtime, so the union of the six headings and a `div` is not one prop type.
+    // The props are typed from `h2` rather than `div` because every prop a caller
+    // passes to a card title is valid on a heading, and typing from `h2` would stop a
+    // caller passing one that only a `div` takes.
+    const Element = Tag;
+    return (_jsx(Element, { "data-slot": "card-title", className: cn('font-semibold leading-none', className), ...props }));
 }
 /**
  * The supporting line under a card's title: one sentence about what the card

package/dist/components/ui/carousel.d.ts

@@ -0,0 +1,125 @@
+import { type ComponentProps, type ReactNode } from 'react';
+/** One slide, and the words a reader is given for it. */
+export type CarouselSlide = {
+    /** A stable key. A slide's key must not change as the reader moves. */
+    id: string;
+    /** The slide's content. */
+    children: ReactNode;
+    /**
+     * The accessible name of this slide.
+     *
+     * A carousel hides its content, so this is often the only way a reader knows
+     * which slide they are on before they read it. It is required for the same
+     * reason a region's name is: it is the caller's word, and a slide announced only
+     * by its content is a slide a reader cannot skip past by name.
+     */
+    label: string;
+};
+/** The props the Carousel accepts. */
+export interface CarouselProps extends Omit<ComponentProps<'div'>, 'children'> {
+    /** The slides, in the order a reader meets them. */
+    slides: readonly CarouselSlide[];
+    /**
+     * The accessible name of the carousel.
+     *
+     * Required rather than defaulted. A carousel is a region, and a page with two is
+     * a page where a reader cannot tell which set of slides they are in. The name is
+     * the caller's word.
+     */
+    label: string;
+    /**
+     * The words read for a slide position, given its one-based index and the total.
+     *
+     * Required, and required as a function rather than a string, because a position
+     * has to be a sentence and the sentence is different in every language. It is
+     * also the answer to the only real defect a carousel has: one with no position
+     * indicator is a guessing game, because a reader who has been moved three times
+     * with nothing telling them where they are has no way to know how much is left.
+     *
+     * The function receives the index of the slide the control moves *to*, so the
+     * words always describe where the reader will be rather than where they are.
+     */
+    position: (index: number, total: number) => string;
+    /**
+     * What a reader is told when there is nothing to show.
+     *
+     * A carousel with no slides is a frame with controls in it that move nowhere, so
+     * the case is authored rather than left to a caller to notice.
+     */
+    empty?: ReactNode;
+    /** The words read for the control that moves back. @defaultValue 'Previous slide' */
+    previousLabel?: string;
+    /** The words read for the control that moves forward. @defaultValue 'Next slide' */
+    nextLabel?: string;
+    /**
+     * The slide to show first.
+     *
+     * Omit it and the first slide is shown. It is a prop because a carousel dropped
+     * into the middle of a page is often a deep link's target, and a Component that
+     * always opened on slide one would show the reader a different slide from the
+     * one the address names.
+     */
+    initialIndex?: number;
+    /** The slide the reader is on, when the caller owns it. */
+    index?: number;
+    /** Called with the index of the slide the reader moves to. */
+    onIndexChange?: (index: number) => void;
+    /** Layout only. */
+    className?: string;
+}
+/**
+ * A set of slides with controls that move between them.
+ *
+ * **A carousel hides content, so it must never be the only route to it.** That is
+ * the decision worth making, and it is a constraint on the caller as much as on
+ * this Component. Everything a carousel shows, a reader must be able to reach some
+ * other way: a tab, a section below it, a list. A carousel used as the only
+ * presentation of a set of images is a set of images a reader on a keyboard, on a
+ * screen reader, or with the controls hidden by a stylesheet cannot see at all,
+ * and the Component cannot detect that case. So the rule is here, in the
+ * documentation, where a caller meets it, rather than assumed.
+ *
+ * **The controls say where the reader is, and the position is a sentence the
+ * caller writes.** `position` is required and is a function of the index and the
+ * total, so a reader is told "3 of 7" rather than being left to infer it. A
+ * carousel with no position indicator is a guessing game: a reader moved three
+ * times with nothing counting has no way to know whether there are three slides
+ * left or three hundred, and the only way to find out is to keep pressing. The
+ * current position is also in `aria-live="polite"` on the position, because a
+ * carousel that moves silently under a reader who did not press anything is a
+ * carousel a reader cannot follow.
+ *
+ * **One slide is the whole content, with no controls.** A carousel of one slide is
+ * a picture with two buttons that do nothing, and it is the state a filtered or
+ * partially-loaded set passes through. The controls are absent rather than
+ * disabled, and the position says 1 of 1, because "there is one slide and you are
+ * on it" is a true and useful thing to tell a reader.
+ *
+ * **No slide is authored rather than rendered as an empty frame.** Zero slides is
+ * a state a caller reaches before their data arrives or after a filter excludes
+ * everything, and a region with an empty track and two dead controls is a gap
+ * rather than a state.
+ *
+ * **It is operable from the keyboard, and the arrow keys do what a reader
+ * expects.** Left and Right move between slides when the carousel has focus, Home
+ * and End jump to the first and last, and the controls are real buttons so Tab
+ * reaches them and Enter and Space press them. Nothing here is a div with a
+ * handler, which is the version a consumer cannot assemble for themselves because
+ * every one of those keys is a chance to get one wrong.
+ *
+ * **A slide that is holding the caret keeps the keys.** The handler is on the
+ * region, so it sees everything that bubbles out of a slide, and a slide is the
+ * caller's slot: it can hold a field, a `select` or an editable region, and in all
+ * three those four keys belong to the value. So a key is answered only when it did
+ * not land in one of them, which is the discipline `ResizableHandle` applies to the
+ * same keys on the other axis.
+ *
+ * **The slide transition is a state change and not an entrance.** The track moves
+ * with `duration-base ease-out`, which is the reader's own press being reported
+ * back, and there is no fade on mount and no motion a reader did not ask for.
+ *
+ * It is a client Component, because a carousel holds a position and answers keys.
+ */
+declare function Carousel({ slides, label, position, className, empty, previousLabel, nextLabel, initialIndex, index, onIndexChange, ...props }: CarouselProps): import("react").JSX.Element;
+export { Carousel };
+//# sourceMappingURL=carousel.d.ts.map

package/dist/components/ui/carousel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"carousel.d.ts","sourceRoot":"","sources":["../../../src/components/ui/carousel.tsx"],"names":[],"mappings":"AAGA,OAAO,EAML,KAAK,cAAc,EAEnB,KAAK,SAAS,EACf,MAAM,OAAO,CAAA;AAId,yDAAyD;AACzD,MAAM,MAAM,aAAa,GAAG;IAC1B,uEAAuE;IACvE,EAAE,EAAE,MAAM,CAAA;IACV,2BAA2B;IAC3B,QAAQ,EAAE,SAAS,CAAA;IACnB;;;;;;;OAOG;IACH,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED,sCAAsC;AACtC,MAAM,WAAW,aAAc,SAAQ,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IAC5E,oDAAoD;IACpD,MAAM,EAAE,SAAS,aAAa,EAAE,CAAA;IAChC;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;;;;;OAWG;IACH,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IAClD;;;;;OAKG;IACH,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,qFAAqF;IACrF,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,oFAAoF;IACpF,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,8DAA8D;IAC9D,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACvC,mBAAmB;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,iBAAS,QAAQ,CAAC,EAChB,MAAM,EACN,KAAK,EACL,QAAQ,EACR,SAAS,EACT,KAAK,EACL,aAAgC,EAChC,SAAwB,EACxB,YAAgB,EAChB,KAAK,EACL,aAAa,EACb,GAAG,KAAK,EACT,EAAE,aAAa,+BA0Of;AAiCD,OAAO,EAAE,QAAQ,EAAE,CAAA"}