@flood-md/react 0.2.6 → 0.2.9

package/README.md

@@ -3,9 +3,35 @@
 Original React 18.3/19 components for TypeScript and Next.js App Router. Native
 HTML semantics and refs, no third-party component library or Tailwind dependency.
 
-This package documents the **0.2.6** source API. Keep Flood package versions aligned and follow the guide matching
+Named imports support tree shaking in optimizing ES-module bundlers. Import the
+shared stylesheet explicitly; styles are not split by component.
+
+This package documents the **0.2.9** source API. Keep Flood package versions aligned and follow the guide matching
 your installed declarations; source changes do not modify an existing npm release.
 
+Version 0.2.9 improves constrained file rows, Drawer readability and Select pointer
+focus without changing public signatures or token values.
+
+Version 0.2.8 adds TimePicker, DateTimeRangePicker, unified Calendar day/month/year views,
+HoverCard, ColorSwatch, ColorPicker, TreeSelect,
+DateTimePicker, DataList, DataListItem, CheckCard, RadioCard, DataTable, FileItem/FileList, FileMeta, UploadItem/UploadList and ImagePreview. Color values are opaque RGB hex; TreeSelect selects one item;
+DateTimePicker retains separate civil date and clock fields without inferring a
+timezone. Each component has a live catalog example and public prop reference.
+
+ListBox in the 0.2.8 source also supports native required validation, descriptions,
+semantic feedback and host-owned validation messages. Readonly bypasses validity;
+disabled excludes form values. See its guide for controlled selection and reset.
+
+Version 0.2.7 adds Tree for application object selection and NavigationTree for
+nested native links. Both use globally unique item values and independent
+controlled/uncontrolled expansion. Tree keeps keyboard focus separate from
+single/multiple selection, with host-owned deferred branches. NavigationTree
+preserves native links, modifier navigation and Tab order with separate disclosure
+buttons. Neither component fetches, virtualizes or writes form values. See the
+[Tree](https://flood.md/components/tree) and
+[NavigationTree](https://flood.md/components/navigation-tree) guides; check their
+release status against your installed version.
+
 ```tsx
 import "@flood-md/react/styles.css";
 import { Button, FloodRoot, Heading, Stack, Text } from "@flood-md/react";
@@ -902,3 +928,21 @@ The CSS build assembles the original component styles into the shared stylesheet
 Section headingLevel controls native h2–h6 semantics. Its independent headingSize
 uses the existing Heading roles (section/page/large/display), defaulting to section.
 Keep document hierarchy meaningful when changing visual emphasis.
+
+## Editable and TagInput · 0.2.7
+
+Editable provides inline single-line editing with a separate draft, save/cancel actions and committed named form values. See [Editable](../../docs/components/editable.md) for controlled ownership and blur behavior. TagInput creates free-form text tokens and submits repeated named values; it is distinct from fixed-option MultiSelect. See [TagInput](../../docs/components/tag-input.md) for delimiters, paste and validation.
+
+Menu adds `MenuCheckboxItem` and `MenuRadioItem`. Both take controlled `checked` and `onCheckedChange`; radio items also require a `group` label and the host enforces one selected value per group. Checkbox `checked` also accepts `"mixed"`. Keep radio groups contiguous. Preferences stay open by default; set `closeOnSelect` to close after activation. Preference changes do not invoke `onAction`. Existing action items retain their behavior.
+
+CommandList (0.2.7) provides grouped command filtering and invocation without a modal or form value. See [CommandList](../../docs/components/command-list.md) for query ownership, keyboard navigation and loading/empty states.
+
+DateField (0.2.7) edits a Gregorian civil date through native text segments, with ISO canonical values, bounds, explicit segment order and native invalid-draft form handling. It has no operating-system date popup. See [DateField](../../docs/components/date-field.md).
+
+TimeField, Calendar and DatePicker (0.2.7) complete the first single-date/time entry family. See [TimeField](../../docs/components/time-field.md), [Calendar](../../docs/components/calendar.md) and [DatePicker](../../docs/components/date-picker.md). Calendar onDateSelect reports enabled activation, including the already selected date; onValueChange requests only changed values. DateField end accepts an optional trailing action.
+
+Popover positionReference optionally supplies a connected same-document element ref for geometry while trigger semantics, dismissal and focus restoration remain on its button. DatePicker uses this to align its panel to the whole field, tracks field width responsively and clamps to the viewport. Available in the 0.2.7 source candidate.
+
+DateRangeField, RangeCalendar and DateRangePicker (0.2.7) share ordered range values and the original Calendar grid. ResizablePanels adds real pointer/keyboard geometry above static Split. ErrorSummary links host validation to native controls. See each generated catalog page and its guide under docs/components/. DateField validationMessage adds an external native constraint after the field's own date validity.
+
+Menu (0.2.7) supports recursive submenu items and ContextMenu reuses its native layer engine. Context triggers preserve the actual pointer/keyboard source; nested searches stay scoped, Escape unwinds one level and Tab exits through the root. See docs/components/menu.md and context-menu.md.

package/dist/alert-dialog.js

@@ -2,7 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { forwardRef, useRef, useState } from "react";
 import { Button } from "./index.js";
 import { ModalOverlay } from "./overlays.js";
-export const ConfirmationDialog = forwardRef(function ConfirmationDialog({ open: controlled, defaultOpen = false, onOpenChange, onConfirm, onCancel, confirmLabel = "Continue", cancelLabel = "Cancel", confirmDisabled = false, className, ...props }, ref) {
+export const ConfirmationDialog = /* @__PURE__ */ forwardRef(function ConfirmationDialog({ open: controlled, defaultOpen = false, onOpenChange, onConfirm, onCancel, confirmLabel = "Continue", cancelLabel = "Cancel", confirmDisabled = false, className, ...props }, ref) {
     const [local, setLocal] = useState(defaultOpen);
     const cancel = useRef(null);
     const request = (next) => {

package/dist/calendar-period-grid.d.ts

@@ -0,0 +1,17 @@
+export interface CalendarPeriodChoice {
+    value: string;
+    label: string;
+    name: string;
+    selected: boolean;
+    disabled: boolean;
+}
+/** Internal Calendar view, not another picker or overlay. */
+export declare function CalendarPeriodGrid({ choices, label, onChoose, autoFocus, disabled, focusValue, readOnly }: {
+    choices: CalendarPeriodChoice[];
+    label: string;
+    onChoose: (value: string) => void;
+    autoFocus: boolean;
+    disabled: boolean;
+    focusValue?: string;
+    readOnly?: boolean;
+}): import("react").JSX.Element;

package/dist/calendar-period-grid.js

@@ -0,0 +1,13 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from "react";
+import { Button, Grid } from "./index.js";
+/** Internal Calendar view, not another picker or overlay. */
+export function CalendarPeriodGrid({ choices, label, onChoose, autoFocus, disabled, focusValue, readOnly }) {
+    const root = useRef(null);
+    const first = choices.find(choice => choice.value === focusValue && !choice.disabled) ?? choices.find(choice => choice.selected && !choice.disabled) ?? choices.find(choice => !choice.disabled);
+    const [active, setActive] = useState(first?.value);
+    const roving = choices.some(choice => choice.value === active && !choice.disabled) ? active : first?.value;
+    useEffect(() => { if (autoFocus)
+        root.current?.querySelector('button[tabindex="0"]')?.focus({ preventScroll: true }); }, [autoFocus]);
+    return _jsx(Grid, { ref: root, columns: 3, gap: "1", className: "flood-calendar__periods", role: "group", "aria-label": label, children: choices.map(choice => _jsx(Button, { "data-calendar-period": choice.value, className: "flood-calendar__period-choice", size: "sm", variant: choice.selected ? "subtle" : "ghost", tabIndex: !disabled && choice.value === roving ? 0 : -1, disabled: disabled || choice.disabled, "aria-disabled": readOnly || undefined, "aria-pressed": choice.selected, "aria-label": choice.name, onFocus: () => setActive(choice.value), onClick: () => onChoose(choice.value), children: choice.label }, choice.value)) });
+}

package/dist/calendar-value.d.ts

@@ -0,0 +1,10 @@
+import { type DateParts } from "./date-value.js";
+export declare function monthParts(month: string): DateParts | undefined;
+export declare function monthShift(month: string, delta: number): string;
+export declare function dateOrdinal(date: string): number;
+export declare const lastDateOrdinal: number;
+export declare function dateFromOrdinal(ordinal: number): string | undefined;
+export declare const dateWeekday: (date: string) => number;
+export declare function moveDateMonth(date: string, delta: number): string;
+/** Intl receives an actual UTC date without Date.UTC's special handling of years 0–99. */
+export declare function formattingDate(date: string): Date;

package/dist/calendar-value.js

@@ -0,0 +1,48 @@
+import { canonicalDate, daysInMonth, parseDate } from "./date-value.js";
+export function monthParts(month) {
+    return /^\d{4}-\d{2}$/.test(month) ? parseDate(`${month}-01`) : undefined;
+}
+export function monthShift(month, delta) {
+    const parts = monthParts(month);
+    const index = Math.min(9999 * 12 - 1, Math.max(0, (Number(parts.year) - 1) * 12 + Number(parts.month) - 1 + delta));
+    return `${String(Math.floor(index / 12) + 1).padStart(4, "0")}-${String(index % 12 + 1).padStart(2, "0")}`;
+}
+export function dateOrdinal(date) {
+    const parts = parseDate(date);
+    const year = Number(parts.year), month = Number(parts.month), previous = year - 1;
+    let days = previous * 365 + Math.floor(previous / 4) - Math.floor(previous / 100) + Math.floor(previous / 400);
+    for (let m = 1; m < month; m++)
+        days += daysInMonth(year, m);
+    return days + Number(parts.day) - 1;
+}
+export const lastDateOrdinal = dateOrdinal("9999-12-31");
+export function dateFromOrdinal(ordinal) {
+    if (ordinal < 0 || ordinal > lastDateOrdinal)
+        return;
+    let low = 1, high = 9999;
+    while (low < high) {
+        const middle = Math.ceil((low + high) / 2);
+        if (dateOrdinal(`${String(middle).padStart(4, "0")}-01-01`) <= ordinal)
+            low = middle;
+        else
+            high = middle - 1;
+    }
+    let remaining = ordinal - dateOrdinal(`${String(low).padStart(4, "0")}-01-01`), month = 1;
+    while (remaining >= daysInMonth(low, month)) {
+        remaining -= daysInMonth(low, month);
+        month++;
+    }
+    return canonicalDate({ year: String(low), month: String(month), day: String(remaining + 1) });
+}
+export const dateWeekday = (date) => (dateOrdinal(date) + 1) % 7;
+export function moveDateMonth(date, delta) {
+    const parts = parseDate(date), month = monthShift(date.slice(0, 7), delta), next = monthParts(month);
+    return `${month}-${String(Math.min(Number(parts.day), daysInMonth(Number(next.year), Number(next.month)))).padStart(2, "0")}`;
+}
+/** Intl receives an actual UTC date without Date.UTC's special handling of years 0–99. */
+export function formattingDate(date) {
+    const parts = parseDate(date), result = new Date(0);
+    result.setUTCFullYear(Number(parts.year), Number(parts.month) - 1, Number(parts.day));
+    result.setUTCHours(12, 0, 0, 0);
+    return result;
+}

package/dist/calendar.d.ts

@@ -0,0 +1,21 @@
+import type { ReactNode } from "react";
+import type { CalendarProps } from "./index.js";
+export interface CalendarDayMetadata {
+    rangeStart?: boolean;
+    rangeEnd?: boolean;
+    inRange?: boolean;
+    preview?: boolean;
+    unavailable?: boolean;
+}
+export interface CalendarGridProps extends Omit<CalendarProps, "value" | "defaultValue" | "onValueChange" | "onDateSelect"> {
+    selectedDate?: string;
+    isSelected?: (date: string) => boolean;
+    dayMetadata?: (date: string) => CalendarDayMetadata;
+    onDayActivate?: (date: string) => void;
+    onDayPreview?: (date: string | undefined) => void;
+    multiple?: boolean;
+    footer?: ReactNode;
+}
+/** One original grid/focus engine shared by single-date and range calendars. */
+export declare const CalendarGrid: import("react").ForwardRefExoticComponent<CalendarGridProps & import("react").RefAttributes<HTMLDivElement>>;
+export declare const DateCalendar: import("react").ForwardRefExoticComponent<CalendarProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/calendar.js

@@ -0,0 +1,259 @@
+import { createElement as _createElement } from "react";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef, useEffect, useId, useImperativeHandle, useMemo, useRef, useState } from "react";
+import { Button, ButtonGroup, IconButton, VisuallyHidden } from "./index.js";
+import { CalendarPeriodGrid } from "./calendar-period-grid.js";
+import { dateInRange, parseDate, daysInMonth } from "./date-value.js";
+import { dateFromOrdinal, dateOrdinal, dateWeekday, formattingDate, lastDateOrdinal, monthParts, monthShift, moveDateMonth } from "./calendar-value.js";
+const cx = (...values) => values.filter(Boolean).join(" ");
+const titleCase = (text, locale) => text.replace(/^\p{L}/u, letter => letter.toLocaleUpperCase(locale));
+/** One original grid/focus engine shared by single-date and range calendars. */
+export const CalendarGrid = /* @__PURE__ */ forwardRef(function CalendarGrid({ label, selectedDate = "", isSelected, dayMetadata, onDayActivate, onDayPreview, multiple = false, footer, visibleMonth, defaultVisibleMonth, onVisibleMonthChange, min, max, disabled = false, readOnly = false, isDateDisabled, weekStartsOn = 0, locale = "en-US", autoFocus = false, granularity = "day", showViewControls = true, viewLabels, today, previousMonthLabel = "Previous month", nextMonthLabel = "Next month", id: explicitId, className, onKeyDown, onBlur, onPointerLeave, ...props }, forwardedRef) {
+    if (!label.trim() || !previousMonthLabel.trim() || !nextMonthLabel.trim())
+        throw new Error("Flood Calendar requires nonempty calendar and navigation labels");
+    for (const [key, date] of [["selectedDate", selectedDate], ["min", min], ["max", max], ["today", today]])
+        if (date !== undefined && (date !== "" || key !== "selectedDate") && !parseDate(date))
+            throw new Error(`Flood Calendar ${key} must be a valid ISO Gregorian date`);
+    for (const month of [visibleMonth, defaultVisibleMonth])
+        if (month !== undefined && !monthParts(month))
+            throw new Error("Flood Calendar month must be YYYY-MM from 0001 to 9999");
+    if (min && max && min > max)
+        throw new Error("Flood Calendar min must not follow max");
+    if (!Number.isInteger(weekStartsOn) || weekStartsOn < 0 || weekStartsOn > 6)
+        throw new Error("Flood Calendar weekStartsOn must be 0 to 6");
+    const [clock] = useState(() => today ?? new Date().toISOString().slice(0, 10));
+    const actualToday = today ?? clock, selected = selectedDate;
+    const clampMonth = (month) => min && month < min.slice(0, 7) ? min.slice(0, 7) : max && month > max.slice(0, 7) ? max.slice(0, 7) : month;
+    const initialMonth = useRef(defaultVisibleMonth ?? clampMonth((selected || actualToday).slice(0, 7)));
+    const [localMonth, setLocalMonth] = useState(initialMonth.current), month = visibleMonth ?? localMonth;
+    const baseView = granularity === "day" ? "days" : granularity === "month" ? "months" : "years";
+    const [view, setView] = useState(baseView), [focusView, setFocusView] = useState(false);
+    const year = Number(month.slice(0, 4)), yearPage = (value) => Math.min(9988, 1 + Math.floor((value - 1) / 12) * 12);
+    const [yearStart, setYearStart] = useState(() => yearPage(year));
+    const monthName = titleCase(new Intl.DateTimeFormat(locale, { calendar: "gregory", timeZone: "UTC", month: "long" }).format(formattingDate(`${month}-01`)), locale);
+    const viewNames = { month: viewLabels?.month ?? "Month", year: viewLabels?.year ?? "Year", previous: viewLabels?.previous ?? "Previous", next: viewLabels?.next ?? "Next" };
+    if (!Object.values(viewNames).every(text => text.trim()))
+        throw new Error("Flood Calendar view labels must be nonempty");
+    const firstDate = `${month}-01`, firstOrdinal = dateOrdinal(firstDate), startOrdinal = firstOrdinal - ((dateWeekday(firstDate) - weekStartsOn + 7) % 7);
+    const [focused, setFocused] = useState(selected && selected.slice(0, 7) === month ? selected : firstDate);
+    const root = useRef(null), buttons = useRef(new Map()), pendingFocus = useRef(undefined);
+    const generated = useId(), id = explicitId ?? `flood-calendar-${generated}`;
+    useImperativeHandle(forwardedRef, () => root.current, []);
+    const [inheritedDisabled, setInheritedDisabled] = useState(false), effectiveDisabled = disabled || inheritedDisabled;
+    const [direction, setDirection] = useState(props.dir ?? "ltr");
+    const formatters = useMemo(() => ({ month: new Intl.DateTimeFormat(locale, { calendar: "gregory", timeZone: "UTC", month: "long", year: "numeric" }), day: new Intl.DateTimeFormat(locale, { calendar: "gregory", timeZone: "UTC", weekday: "long", month: "long", day: "numeric", year: "numeric" }), weekday: new Intl.DateTimeFormat(locale, { calendar: "gregory", timeZone: "UTC", weekday: "short" }), weekdayLong: new Intl.DateTimeFormat(locale, { calendar: "gregory", timeZone: "UTC", weekday: "long" }), number: new Intl.NumberFormat(locale, { useGrouping: false }) }), [locale]);
+    const monthLabel = formatters.month.format(formattingDate(firstDate));
+    const dates = Array.from({ length: 42 }, (_, index) => dateFromOrdinal(startOrdinal + index));
+    const roving = dates.includes(focused) ? focused : selected && dates.includes(selected) ? selected : firstDate;
+    const blocked = (date) => !dateInRange(date, min, max) || !!isDateDisabled?.(date);
+    const daySelected = (date) => isSelected ? isSelected(date) : selected === date;
+    const attributes = (date) => { const state = date ? dayMetadata?.(date) : undefined; return { "data-range-start": state?.rangeStart || undefined, "data-range-end": state?.rangeEnd || undefined, "data-in-range": state?.inRange || undefined, "data-range-preview": state?.preview || undefined, "data-range-unavailable": state?.unavailable || undefined }; };
+    const focusDay = (date) => { setFocused(date); root.current?.ownerDocument.defaultView?.requestAnimationFrame(() => buttons.current.get(date)?.focus({ preventScroll: true })); };
+    const requestMonth = (next) => { if (next === month)
+        return; if (visibleMonth === undefined)
+        setLocalMonth(next); onVisibleMonthChange?.(next); };
+    const switchView = (next) => { if (next === "years")
+        setYearStart(yearPage(year)); setFocusView(true); setView(next); };
+    const restoreDays = () => {
+        setView(baseView);
+        setFocusView(false);
+        root.current?.ownerDocument.defaultView?.requestAnimationFrame(() => {
+            const target = baseView === "days" ? buttons.current.get(roving) : root.current?.querySelector('[data-calendar-period][tabindex="0"]');
+            target?.focus({ preventScroll: true });
+        });
+    };
+    const choosePeriod = (period) => {
+        if (effectiveDisabled)
+            return;
+        const target = clampMonth(view === "years" ? `${period}-${month.slice(5)}` : period);
+        pendingFocus.current = undefined;
+        if ((granularity === "month" && view === "months") || granularity === "year") {
+            if (readOnly)
+                return;
+            requestMonth(target);
+            onDayActivate?.(view === "years" ? `${period}-01-01` : `${period}-01`);
+            return;
+        }
+        if (baseView === "days")
+            pendingFocus.current = `${target}-01`;
+        requestMonth(target);
+        setView(baseView);
+        setFocusView(false);
+        root.current?.ownerDocument.defaultView?.requestAnimationFrame(() => {
+            if (baseView === "days") {
+                const pending = pendingFocus.current;
+                if (pending && pending.slice(0, 7) === root.current?.dataset.calendarMonth && buttons.current.has(pending)) {
+                    pendingFocus.current = undefined;
+                    focusDay(pending);
+                }
+                else
+                    root.current?.querySelector('button[data-calendar-date][tabindex="0"]')?.focus({ preventScroll: true });
+            }
+            else
+                root.current?.querySelector('[data-calendar-period][tabindex="0"]')?.focus({ preventScroll: true });
+        });
+    };
+    useEffect(() => { setView(baseView); setYearStart(yearPage(year)); }, [granularity]);
+    useEffect(() => { if (baseView === "years")
+        setYearStart(yearPage(year)); }, [month]);
+    const move = (date) => {
+        const targetMonth = date.slice(0, 7);
+        if (targetMonth !== month) {
+            pendingFocus.current = date;
+            requestMonth(targetMonth);
+        }
+        else
+            focusDay(date);
+    };
+    useEffect(() => {
+        const pending = pendingFocus.current;
+        if (pending?.slice(0, 7) === month) {
+            pendingFocus.current = undefined;
+            focusDay(pending);
+        }
+        else
+            setFocused(selected && selected.slice(0, 7) === month ? selected : `${month}-01`);
+    }, [month]);
+    useEffect(() => {
+        if (!autoFocus || effectiveDisabled)
+            return;
+        const frame = root.current?.ownerDocument.defaultView?.requestAnimationFrame(() => { const node = root.current; if (node && node.getClientRects().length && node.ownerDocument.defaultView.getComputedStyle(node).visibility !== "hidden")
+            buttons.current.get(roving)?.focus({ preventScroll: true }); });
+        return () => { if (frame !== undefined)
+            root.current?.ownerDocument.defaultView?.cancelAnimationFrame(frame); };
+    }, [autoFocus, effectiveDisabled]);
+    useEffect(() => {
+        const node = root.current?.querySelector("input[data-calendar-disabled-probe]");
+        if (!node)
+            return;
+        const update = () => setInheritedDisabled(node.matches(":disabled"));
+        update();
+        const observer = new node.ownerDocument.defaultView.MutationObserver(update);
+        let ancestor = root.current?.parentElement;
+        while (ancestor) {
+            if (ancestor.localName === "fieldset")
+                observer.observe(ancestor, { attributes: true, attributeFilter: ["disabled"] });
+            ancestor = ancestor.parentElement;
+        }
+        return () => observer.disconnect();
+    }, [disabled]);
+    useEffect(() => {
+        const node = root.current;
+        if (!node)
+            return;
+        const update = () => setDirection(node.ownerDocument.defaultView.getComputedStyle(node).direction);
+        update();
+        const observer = new node.ownerDocument.defaultView.MutationObserver(update);
+        let ancestor = node;
+        while (ancestor) {
+            observer.observe(ancestor, { attributes: true, attributeFilter: ["dir"] });
+            ancestor = ancestor.parentElement;
+        }
+        return () => observer.disconnect();
+    }, [props.dir]);
+    const previous = clampMonth(monthShift(month, -1)), next = clampMonth(monthShift(month, 1));
+    const previousDisabled = effectiveDisabled || month === "0001-01" || !!min && month <= min.slice(0, 7), nextDisabled = effectiveDisabled || month === "9999-12" || !!max && month >= max.slice(0, 7);
+    const minYear = Number(min?.slice(0, 4) ?? 1), maxYear = Number(max?.slice(0, 4) ?? 9999);
+    const periodPreviousDisabled = effectiveDisabled || (view === "years" ? yearStart <= minYear : year <= minYear), periodNextDisabled = effectiveDisabled || (view === "years" ? yearStart + 11 >= maxYear : year >= maxYear);
+    const navigatePeriod = (offset) => { if (view === "years")
+        setYearStart(current => Math.max(1, Math.min(9988, current + offset * 12)));
+    else
+        requestMonth(clampMonth(monthShift(month, offset * 12))); };
+    const periodChoices = view === "days" ? [] : Array.from({ length: 12 }, (_, index) => {
+        const value = view === "years" ? String(yearStart + index).padStart(4, "0") : `${month.slice(0, 4)}-${String(index + 1).padStart(2, "0")}`;
+        const monthStart = `${value}-01`, monthEnd = view === "months" ? `${value}-${String(daysInMonth(year, index + 1)).padStart(2, "0")}` : "";
+        return { value, label: view === "years" ? String(yearStart + index) : titleCase(new Intl.DateTimeFormat(locale, { month: "short", calendar: "gregory", timeZone: "UTC" }).format(formattingDate(`2000-${String(index + 1).padStart(2, "0")}-01`)), locale),
+            name: view === "years" ? String(yearStart + index) : new Intl.DateTimeFormat(locale, { month: "long", year: "numeric", calendar: "gregory", timeZone: "UTC" }).format(formattingDate(monthStart)),
+            selected: view === "years" ? selected.slice(0, 4) === value : selected.slice(0, 7) === value,
+            disabled: view === "years" ? yearStart + index < minYear || yearStart + index > maxYear : Boolean(min && monthEnd < min || max && monthStart > max) };
+    });
+    const headingControls = _jsxs(_Fragment, { children: [showViewControls && granularity === "day" ? _jsx(Button, { variant: "outline", size: "sm", disabled: effectiveDisabled, "aria-label": `${viewNames.month}: ${monthName}`, "aria-pressed": view === "months", onClick: () => view === "months" ? restoreDays() : switchView("months"), children: monthName }) : granularity === "day" ? _jsx("span", { children: monthName }) : null, granularity === "day" ? " " : null, showViewControls && granularity !== "year" ? _jsx(Button, { variant: "outline", size: "sm", disabled: effectiveDisabled, "aria-label": `${viewNames.year}: ${year}`, "aria-pressed": view === "years", onClick: () => view === "years" ? restoreDays() : switchView("years"), children: view === "years" ? `${yearStart}–${Math.min(9999, yearStart + 11)}` : year }) : _jsx("span", { children: granularity === "year" ? `${yearStart}–${Math.min(9999, yearStart + 11)}` : year })] });
+    return _jsxs("div", { ...props, id: id, ref: root, className: cx("flood-calendar", className), role: "group", "aria-label": label, "data-disabled": effectiveDisabled || undefined, "data-readonly": readOnly || undefined, "data-view": view, "data-calendar-month": month, "data-calendar-direction": direction, onBlur: event => { onBlur?.(event); if (event.relatedTarget && !event.currentTarget.contains(event.relatedTarget))
+            pendingFocus.current = undefined; }, onPointerLeave: event => { onPointerLeave?.(event); if (event.defaultPrevented)
+            return; const focused = root.current?.ownerDocument.activeElement; onDayPreview?.(focused && root.current?.contains(focused) ? focused.dataset.calendarDate : undefined); }, onKeyDown: event => {
+            onKeyDown?.(event);
+            if (event.defaultPrevented || event.nativeEvent.isComposing || event.keyCode === 229 || event.altKey || event.metaKey)
+                return;
+            if (event.key === "Escape" && view !== baseView) {
+                event.preventDefault();
+                event.stopPropagation();
+                restoreDays();
+                return;
+            }
+            const period = event.target.dataset.calendarPeriod;
+            if (period && view !== "days") {
+                if (effectiveDisabled || event.ctrlKey)
+                    return;
+                const index = periodChoices.findIndex(choice => choice.value === period), rtl = direction === "rtl";
+                const step = event.key === "ArrowUp" ? -3 : event.key === "ArrowDown" ? 3 : event.key === "ArrowLeft" ? (rtl ? 1 : -1) : event.key === "ArrowRight" ? (rtl ? -1 : 1) : 0;
+                if (!step && event.key !== "Home" && event.key !== "End")
+                    return;
+                event.preventDefault();
+                let next = event.key === "Home" ? 0 : event.key === "End" ? periodChoices.length - 1 : index + step;
+                while (next >= 0 && next < periodChoices.length && periodChoices[next].disabled)
+                    next += step || (event.key === "Home" ? 1 : -1);
+                if (next >= 0 && next < periodChoices.length)
+                    root.current?.querySelector(`[data-calendar-period="${periodChoices[next].value}"]`)?.focus({ preventScroll: true });
+                return;
+            }
+            const target = event.target, date = target.dataset.calendarDate;
+            if (!date || target.matches(":disabled") || effectiveDisabled)
+                return;
+            const rtl = root.current?.ownerDocument.defaultView?.getComputedStyle(root.current).direction === "rtl";
+            let candidate;
+            const ordinal = dateOrdinal(date);
+            if (event.key === "ArrowLeft" || event.key === "ArrowRight")
+                candidate = dateFromOrdinal(Math.min(lastDateOrdinal, Math.max(0, ordinal + (event.key === "ArrowLeft" ? -1 : 1) * (rtl ? -1 : 1))));
+            else if (event.key === "ArrowUp" || event.key === "ArrowDown")
+                candidate = dateFromOrdinal(Math.min(lastDateOrdinal, Math.max(0, ordinal + (event.key === "ArrowUp" ? -7 : 7))));
+            else if (event.key === "Home" || event.key === "End") {
+                const offset = (dateWeekday(date) - weekStartsOn + 7) % 7;
+                candidate = dateFromOrdinal(Math.min(lastDateOrdinal, Math.max(0, ordinal + (event.key === "Home" ? -offset : 6 - offset))));
+            }
+            else if (event.key === "PageUp" || event.key === "PageDown")
+                candidate = moveDateMonth(date, (event.key === "PageUp" ? -1 : 1) * (event.shiftKey ? 12 : 1));
+            if (!candidate || event.ctrlKey)
+                return;
+            event.preventDefault();
+            if (min && candidate < min)
+                candidate = min;
+            if (max && candidate > max)
+                candidate = max;
+            move(candidate);
+        }, children: [_jsx("span", { id: `${id}-label`, className: "flood-visually-hidden", children: label }), _jsx("input", { type: "hidden", "data-calendar-disabled-probe": true, disabled: disabled }), _jsxs("div", { className: "flood-calendar__header", children: [_jsx(VisuallyHidden, { id: `${id}-month`, "aria-live": "polite", "aria-atomic": "true", children: view === "years" ? `${yearStart}–${Math.min(9999, yearStart + 11)}` : view === "months" ? year : monthLabel }), showViewControls && granularity !== "year" ? _jsx(ButtonGroup, { label: `${viewNames.month} / ${viewNames.year}`, className: "flood-calendar__month", children: headingControls }) : _jsx("div", { className: "flood-calendar__month", children: headingControls }), _jsxs("div", { className: "flood-calendar__navigation", children: [_jsx(IconButton, { label: view === "days" ? previousMonthLabel : `${viewNames.previous} ${viewNames.year}`, variant: "ghost", size: "sm", disabled: view === "days" ? previousDisabled : periodPreviousDisabled, onClick: event => { pendingFocus.current = undefined; if (!event.currentTarget.matches(":disabled")) {
+                                    if (view === "days")
+                                        requestMonth(previous);
+                                    else
+                                        navigatePeriod(-1);
+                                } }, children: _jsx("svg", { viewBox: "0 0 24 24", fill: "none", "aria-hidden": "true", children: _jsx("path", { d: "m14 6-6 6 6 6", stroke: "currentColor", strokeWidth: "1.5", strokeLinecap: "round", strokeLinejoin: "round" }) }) }), _jsx(IconButton, { label: view === "days" ? nextMonthLabel : `${viewNames.next} ${viewNames.year}`, variant: "ghost", size: "sm", disabled: view === "days" ? nextDisabled : periodNextDisabled, onClick: event => { pendingFocus.current = undefined; if (!event.currentTarget.matches(":disabled")) {
+                                    if (view === "days")
+                                        requestMonth(next);
+                                    else
+                                        navigatePeriod(1);
+                                } }, children: _jsx("svg", { viewBox: "0 0 24 24", fill: "none", "aria-hidden": "true", children: _jsx("path", { d: "m10 6 6 6-6 6", stroke: "currentColor", strokeWidth: "1.5", strokeLinecap: "round", strokeLinejoin: "round" }) }) })] })] }), _jsx("div", { className: "flood-calendar__body", children: view === "days" ? _jsxs("div", { className: "flood-calendar__grid", role: "grid", "aria-labelledby": `${id}-label ${id}-month`, "aria-readonly": readOnly || undefined, "aria-multiselectable": multiple || undefined, children: [_jsx("div", { className: "flood-calendar__week", role: "row", children: Array.from({ length: 7 }, (_, index) => { const date = formattingDate(dateFromOrdinal(7 + ((weekStartsOn + index + 6) % 7))); return _jsx("span", { className: "flood-calendar__weekday", role: "columnheader", children: _jsx("abbr", { title: formatters.weekdayLong.format(date), children: titleCase(formatters.weekday.format(date), locale) }) }, index); }) }), Array.from({ length: 6 }, (_, week) => _jsx("div", { className: "flood-calendar__week", role: "row", children: dates.slice(week * 7, week * 7 + 7).map((date, index) => _createElement("div", { ...attributes(date), className: "flood-calendar__cell", role: "gridcell", key: date ?? `empty-${index}`, "aria-selected": date ? daySelected(date) : undefined, "aria-disabled": date ? blocked(date) || undefined : undefined }, date && _jsx("button", { type: "button", className: "flood-calendar__day", "data-calendar-date": date, "data-selected": daySelected(date) || undefined, "data-outside": date.slice(0, 7) !== month || undefined, "data-today": date === actualToday || undefined, ref: node => { if (node)
+                                    buttons.current.set(date, node);
+                                else
+                                    buttons.current.delete(date); }, "data-flood-autofocus": autoFocus && date === roving || undefined, tabIndex: !effectiveDisabled && date === roving ? 0 : -1, disabled: disabled, "aria-disabled": blocked(date) || readOnly || undefined, "aria-label": formatters.day.format(formattingDate(date)), "aria-current": date === actualToday ? "date" : undefined, onFocus: () => { setFocused(date); if (!effectiveDisabled && !readOnly)
+                                    onDayPreview?.(date); }, onPointerEnter: event => { if (event.pointerType !== "touch" && !effectiveDisabled && !readOnly)
+                                    onDayPreview?.(date); }, onClick: event => { if (effectiveDisabled || readOnly || blocked(date) || event.currentTarget.matches(":disabled"))
+                                    return; move(date); onDayActivate?.(date); }, children: formatters.number.format(Number(date.slice(8))) }))) }, week))] })
+                    : _jsx(CalendarPeriodGrid, { focusValue: view === "years" ? String(year).padStart(4, "0") : month, choices: periodChoices, label: view === "years" ? viewNames.year : `${viewNames.month}: ${year}`, onChoose: choosePeriod, autoFocus: focusView || autoFocus, disabled: effectiveDisabled, readOnly: readOnly && (granularity === "year" || granularity === "month" && view === "months") }, view) }), footer] });
+});
+export const DateCalendar = /* @__PURE__ */ forwardRef(function DateCalendar({ value, defaultValue = "", onValueChange, onDateSelect, granularity = "day", min, max, isDateDisabled, ...props }, ref) {
+    const valid = (date) => granularity === "day" ? !!parseDate(date) : granularity === "month" ? !!monthParts(date) : /^\d{4}$/.test(date) && Number(date) >= 1 && Number(date) <= 9999;
+    if (!["day", "month", "year"].includes(granularity))
+        throw new Error("Flood Calendar granularity must be day, month or year");
+    for (const date of [value, defaultValue, min, max])
+        if (date !== undefined && date !== "" && !valid(date))
+            throw new Error("Flood Calendar values and bounds must match granularity");
+    if (isDateDisabled && granularity !== "day")
+        throw new Error("Flood Calendar isDateDisabled applies only to day selection");
+    const [local, setLocal] = useState(defaultValue), selected = value ?? local;
+    const start = (date) => granularity === "day" ? date : granularity === "month" ? `${date}-01` : `${date}-01-01`;
+    const end = (date) => granularity === "day" ? date : granularity === "year" ? `${date}-12-31` : `${date}-${String(daysInMonth(Number(date.slice(0, 4)), Number(date.slice(5)))).padStart(2, "0")}`;
+    return _jsx(CalendarGrid, { ...props, ref: ref, granularity: granularity, min: min ? start(min) : undefined, max: max ? end(max) : undefined, isDateDisabled: isDateDisabled, selectedDate: selected ? start(selected) : "", onDayActivate: date => { const next = granularity === "day" ? date : granularity === "month" ? date.slice(0, 7) : date.slice(0, 4); if (selected !== next) {
+            if (value === undefined)
+                setLocal(next);
+            onValueChange?.(next);
+        } onDateSelect?.(next); } });
+});

package/dist/checkbox.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { forwardRef, useEffect, useImperativeHandle, useLayoutEffect, useRef } from "react";
 const useBrowserLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
-export const MixedCheckbox = forwardRef(function MixedCheckbox({ indeterminate, onChange, ...props }, ref) {
+export const MixedCheckbox = /* @__PURE__ */ forwardRef(function MixedCheckbox({ indeterminate, onChange, ...props }, ref) {
     const node = useRef(null), mixed = useRef(indeterminate);
     useImperativeHandle(ref, () => node.current, []);
     useBrowserLayoutEffect(() => { mixed.current = indeterminate; if (node.current)

package/dist/choice-group.js

@@ -2,7 +2,7 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
 import { forwardRef, useEffect, useLayoutEffect, useImperativeHandle, useRef, useState } from "react";
 const useBrowserLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
 /** Private selection model; native inputs own keyboard, focus, forms and validity. */
-export const ChoiceGroup = forwardRef(function ChoiceGroup({ kind, name, options, selected, initial, onSelectionChange, required, orientation, fieldsetComponent: Group, choiceComponent: Choice, legend, ...props }, forwardedRef) {
+export const ChoiceGroup = /* @__PURE__ */ forwardRef(function ChoiceGroup({ kind, name, options, selected, initial, onSelectionChange, required, orientation, fieldsetComponent: Group, choiceComponent: Choice, legend, ...props }, forwardedRef) {
     if (new Set(options.map(option => option.value)).size !== options.length)
         throw new Error("Flood choice group option values must be unique");
     const root = useRef(null);

package/dist/collection-cards.d.ts

@@ -0,0 +1,4 @@
+import { type CheckCardProps, type RadioCardProps } from "./index.js";
+/** Cards retain native choice semantics; their content must be noninteractive. */
+export declare const CheckableCard: import("react").ForwardRefExoticComponent<CheckCardProps & import("react").RefAttributes<HTMLInputElement>>;
+export declare const ExclusiveCard: import("react").ForwardRefExoticComponent<RadioCardProps & import("react").RefAttributes<HTMLInputElement>>;

package/dist/collection-cards.js

@@ -0,0 +1,21 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef, useId } from "react";
+import { Checkbox, Radio, IconSlot } from "./index.js";
+import { hasFieldContent, mergeDescriptions } from "./field-state.js";
+/** Cards retain native choice semantics; their content must be noninteractive. */
+export const CheckableCard = /* @__PURE__ */ forwardRef(function CheckableCard({ label, description, icon, metadata, density = "comfortable", className, readOnly, onClick, onChange, "aria-describedby": describedBy, "aria-labelledby": labelledBy, "aria-label": ariaLabel, ...props }, ref) {
+    const id = useId();
+    if (!label.trim())
+        throw new Error("Flood CheckCard requires a nonempty label");
+    return _jsx(Checkbox, { ...props, ref: ref, readOnly: readOnly, required: props.required && !readOnly, "aria-disabled": readOnly || props["aria-disabled"] || undefined, "aria-label": ariaLabel, "aria-labelledby": labelledBy ?? (ariaLabel ? undefined : `${id}-title`), "aria-describedby": mergeDescriptions(describedBy, hasFieldContent(description) && `${id}-description`, hasFieldContent(metadata) && `${id}-metadata`), className: ["flood-choice-card", `flood-choice-card--${density}`, className].filter(Boolean).join(" "), onClick: event => { onClick?.(event); if (readOnly)
+            event.preventDefault(); }, onChange: event => { if (!readOnly)
+            onChange?.(event); }, label: _jsxs("span", { className: "flood-choice-card__content", children: [hasFieldContent(icon) && _jsx("span", { className: "flood-choice-card__icon", "aria-hidden": "true", children: _jsx(IconSlot, { size: "md", children: icon }) }), _jsxs("span", { className: "flood-choice-card__copy", children: [_jsx("span", { id: `${id}-title`, className: "flood-choice-card__title", children: label }), hasFieldContent(description) && _jsx("span", { id: `${id}-description`, className: "flood-choice-card__description", children: description })] }), hasFieldContent(metadata) && _jsx("span", { id: `${id}-metadata`, className: "flood-choice-card__metadata", children: metadata })] }) });
+});
+export const ExclusiveCard = /* @__PURE__ */ forwardRef(function ExclusiveCard({ label, description, icon, metadata, density = "comfortable", className, readOnly, onClick, onChange, "aria-describedby": describedBy, "aria-labelledby": labelledBy, "aria-label": ariaLabel, ...props }, ref) {
+    const id = useId();
+    if (!label.trim())
+        throw new Error("Flood RadioCard requires a nonempty label");
+    return _jsx(Radio, { ...props, ref: ref, readOnly: readOnly, required: props.required && !readOnly, "aria-disabled": readOnly || props["aria-disabled"] || undefined, "aria-label": ariaLabel, "aria-labelledby": labelledBy ?? (ariaLabel ? undefined : `${id}-title`), "aria-describedby": mergeDescriptions(describedBy, hasFieldContent(description) && `${id}-description`, hasFieldContent(metadata) && `${id}-metadata`), className: ["flood-choice-card", `flood-choice-card--${density}`, className].filter(Boolean).join(" "), onClick: event => { onClick?.(event); if (readOnly)
+            event.preventDefault(); }, onChange: event => { if (!readOnly)
+            onChange?.(event); }, label: _jsxs("span", { className: "flood-choice-card__content", children: [hasFieldContent(icon) && _jsx("span", { className: "flood-choice-card__icon", "aria-hidden": "true", children: _jsx(IconSlot, { size: "md", children: icon }) }), _jsxs("span", { className: "flood-choice-card__copy", children: [_jsx("span", { id: `${id}-title`, className: "flood-choice-card__title", children: label }), hasFieldContent(description) && _jsx("span", { id: `${id}-description`, className: "flood-choice-card__description", children: description })] }), hasFieldContent(metadata) && _jsx("span", { id: `${id}-metadata`, className: "flood-choice-card__metadata", children: metadata })] }) });
+});

package/dist/color-controls.d.ts

@@ -0,0 +1,5 @@
+import { type ColorPickerProps, type ColorSwatchProps } from "./index.js";
+/** The first color contract deliberately accepts only opaque RGB hex values. */
+export declare function normalizeHexColor(value: string): string | undefined;
+export declare const ColorPreview: import("react").ForwardRefExoticComponent<ColorSwatchProps & import("react").RefAttributes<HTMLSpanElement>>;
+export declare const ColorEditor: import("react").ForwardRefExoticComponent<ColorPickerProps & import("react").RefAttributes<HTMLInputElement>>;