@flood-md/react 0.2.5 → 0.2.8

package/dist/date-value.js

@@ -0,0 +1,31 @@
+export const emptyDateParts = () => ({ year: "", month: "", day: "" });
+export function daysInMonth(year, month) {
+    return month === 2 ? (year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0) ? 29 : 28) : [4, 6, 9, 11].includes(month) ? 30 : 31;
+}
+export function canonicalDate(parts) {
+    if (!/^\d{1,4}$/.test(parts.year) || !/^\d{1,2}$/.test(parts.month) || !/^\d{1,2}$/.test(parts.day))
+        return;
+    const y = Number(parts.year), m = Number(parts.month), d = Number(parts.day);
+    if (y < 1 || y > 9999 || m < 1 || m > 12 || d < 1 || d > daysInMonth(y, m))
+        return;
+    return `${String(y).padStart(4, "0")}-${String(m).padStart(2, "0")}-${String(d).padStart(2, "0")}`;
+}
+export function parseDate(value) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(value))
+        return;
+    const [year, month, day] = value.split("-");
+    const parts = { year, month, day };
+    return canonicalDate(parts) === value ? parts : undefined;
+}
+export const dateInRange = (value, min, max) => (!min || value >= min) && (!max || value <= max);
+export const isEmptyDate = (parts) => !parts.year && !parts.month && !parts.day;
+export function stepDatePart(parts, part, direction, edge) {
+    const next = { ...parts };
+    const max = part === "year" ? 9999 : part === "month" ? 12 : daysInMonth(Number(parts.year) || 2000, Number(parts.month) || 1);
+    const current = Number(parts[part]);
+    const number = edge === "start" ? 1 : edge === "end" ? max : current ? (current - 1 + direction + max) % max + 1 : direction > 0 ? 1 : max;
+    next[part] = String(number).padStart(part === "year" ? 4 : 2, "0");
+    if (part !== "day" && Number(next.day))
+        next.day = String(Math.min(Number(next.day), daysInMonth(Number(next.year) || 2000, Number(next.month) || 1))).padStart(2, "0");
+    return next;
+}

package/dist/disclosure.js

@@ -3,7 +3,7 @@ import { createElement, forwardRef, useEffect, useId, useLayoutEffect, useRef, u
 import { Button } from "./index.js";
 const useBrowserLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
 /** Shared original disclosure anatomy. The closed panel stays mounted but hidden. */
-export const Disclosure = forwardRef(function Disclosure({ title, expanded, onExpandedChange, disabled, controlSize, headingLevel, className, children, id: explicitId, ...props }, ref) {
+export const Disclosure = /* @__PURE__ */ forwardRef(function Disclosure({ title, expanded, onExpandedChange, disabled, controlSize, headingLevel, className, children, id: explicitId, ...props }, ref) {
     const generatedId = useId(), id = explicitId ?? `flood-disclosure-${generatedId}`;
     const root = useRef(null), panel = useRef(null), trigger = useRef(null);
     const focusedInside = useRef(false);

package/dist/editable.d.ts

@@ -0,0 +1,3 @@
+import type { EditableProps } from "./index.js";
+/** A draft is private until explicitly committed; native forms receive committed text. */
+export declare const InlineEditable: import("react").ForwardRefExoticComponent<EditableProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/editable.js

@@ -0,0 +1,135 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef, useEffect, useId, useImperativeHandle, useLayoutEffect, useRef, useState } from "react";
+import { Button, IconButton, IconSlot, Input, InputGroup } from "./index.js";
+const useBrowserLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
+const cx = (...values) => values.filter(Boolean).join(" ");
+/** A draft is private until explicitly committed; native forms receive committed text. */
+export const InlineEditable = /* @__PURE__ */ forwardRef(function InlineEditable({ label, hideLabel = false, value, defaultValue = "", onValueChange, editing, defaultEditing = false, onEditingChange, onCommit, onCancel, blurAction = "commit", readOnly = false, disabled = false, placeholder = "Empty", controlSize = "md", showActions = true, editLabel = "Edit", saveLabel = "Save", cancelLabel = "Cancel", inputRef, name, form, id: explicitId, className, onBlur, onKeyDown, ...props }, forwardedRef) {
+    if (![label, editLabel, saveLabel, cancelLabel].every(text => text.trim()))
+        throw new Error("Flood Editable requires nonempty control and action labels");
+    const initial = useRef(defaultValue), [local, setLocal] = useState(defaultValue);
+    const committed = value ?? local;
+    const [localEditing, setLocalEditing] = useState(defaultEditing);
+    const requested = editing ?? localEditing, active = requested && !disabled && !readOnly;
+    const [draft, setDraft] = useState(committed);
+    const root = useRef(null), editor = useRef(null), bridge = useRef(null), preview = useRef(null);
+    const current = useRef({ committed, active, draft, value, editing, onValueChange, onEditingChange, onCommit, onCancel });
+    current.current = { committed, active, draft, value, editing, onValueChange, onEditingChange, onCommit, onCancel };
+    const composing = useRef(false), resolved = useRef(false), wasActive = useRef(false);
+    const generated = useId(), id = explicitId ?? `flood-editable-${generated}`, inputId = `${id}-input`, previewId = `${id}-preview`;
+    useImperativeHandle(forwardedRef, () => root.current, []);
+    useImperativeHandle(inputRef, () => editor.current, [active, readOnly]);
+    const requestEditing = (next) => {
+        if (current.current.editing === undefined)
+            setLocalEditing(next);
+        current.current.onEditingChange?.(next);
+    };
+    const start = () => {
+        if (disabled || readOnly || current.current.active || preview.current?.matches(":disabled"))
+            return;
+        setDraft(current.current.committed);
+        resolved.current = false;
+        requestEditing(true);
+    };
+    const finish = (action, restoreFocus) => {
+        if (!current.current.active || resolved.current || (composing.current && action === "commit") || editor.current?.matches(":disabled"))
+            return;
+        resolved.current = true;
+        const next = current.current.draft;
+        if (action === "commit") {
+            if (next !== current.current.committed) {
+                if (current.current.value === undefined)
+                    setLocal(next);
+                current.current.onValueChange?.(next);
+            }
+            current.current.onCommit?.(next);
+        }
+        else {
+            setDraft(current.current.committed);
+            current.current.onCancel?.();
+        }
+        requestEditing(false);
+        if (restoreFocus) {
+            const document = root.current?.ownerDocument;
+            document?.defaultView?.requestAnimationFrame(() => {
+                if (current.current.active || !preview.current?.isConnected || preview.current.matches(":disabled"))
+                    return;
+                const focused = document.activeElement;
+                if (focused === document.body || root.current?.contains(focused))
+                    preview.current.focus({ preventScroll: true });
+            });
+        }
+        // A controlled host may refuse to close and allow a later deliberate attempt.
+        queueMicrotask(() => { resolved.current = false; });
+    };
+    useBrowserLayoutEffect(() => {
+        let frame = 0;
+        if (active && !wasActive.current) {
+            setDraft(current.current.committed);
+            resolved.current = false;
+            composing.current = false;
+            const view = editor.current?.ownerDocument.defaultView;
+            if (view)
+                frame = view.requestAnimationFrame(() => { if (current.current.active && editor.current && !editor.current.matches(":disabled")) {
+                    editor.current.focus();
+                    editor.current.select();
+                } });
+        }
+        if (!active && wasActive.current) {
+            composing.current = false;
+            setDraft(current.current.committed);
+        }
+        wasActive.current = active;
+        return () => { editor.current?.ownerDocument.defaultView?.cancelAnimationFrame(frame); };
+    }, [active]);
+    useEffect(() => {
+        if ((disabled || readOnly) && requested)
+            requestEditing(false);
+    }, [disabled, readOnly, requested]);
+    useEffect(() => {
+        const owner = bridge.current?.form;
+        if (!owner)
+            return;
+        let timer;
+        const reset = (event) => {
+            timer = setTimeout(() => {
+                if (event.defaultPrevented || !root.current)
+                    return;
+                if (current.current.value === undefined)
+                    setLocal(initial.current);
+                setDraft(current.current.value === undefined ? initial.current : current.current.committed);
+                if (current.current.active)
+                    requestEditing(false);
+            }, 0);
+        };
+        owner.addEventListener("reset", reset);
+        return () => { owner.removeEventListener("reset", reset); clearTimeout(timer); };
+    }, [form]);
+    const glyph = (kind) => _jsx("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "1.75", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: kind === "save" ? _jsx("path", { d: "m5 12 4 4L19 6" }) : kind === "cancel" ? _jsx("path", { d: "m6 6 12 12M18 6 6 18" }) : _jsx(_Fragment, { children: _jsx("path", { d: "m15 5 4 4M4 20l4-1L20 7a2.1 2.1 0 0 0-3-3L5 16l-1 4Z" }) }) });
+    const editorProps = { id: inputId, "aria-describedby": props["aria-describedby"], "aria-invalid": props["aria-invalid"], controlSize, disabled };
+    return _jsxs("div", { ...props, ref: root, id: id, className: cx("flood-editable", className), "data-editing": active || undefined, "data-disabled": disabled || undefined, "data-readonly": readOnly || undefined, onKeyDown: event => {
+            onKeyDown?.(event);
+            if (event.defaultPrevented || !current.current.active || event.target !== editor.current || event.nativeEvent.isComposing || composing.current || event.keyCode === 229 || event.altKey || event.ctrlKey || event.metaKey || event.shiftKey)
+                return;
+            if (event.key === "Enter" || event.key === "Escape") {
+                event.preventDefault();
+                finish(event.key === "Enter" ? "commit" : "cancel", true);
+            }
+        }, onBlur: event => {
+            onBlur?.(event);
+            if (event.defaultPrevented || !current.current.active || event.currentTarget.contains(event.relatedTarget) || blurAction === "none")
+                return;
+            finish(blurAction, false);
+        }, children: [_jsx("label", { htmlFor: active || readOnly ? inputId : previewId, className: cx("flood-label", hideLabel && "flood-visually-hidden"), children: label }), _jsx("input", { ref: bridge, type: "hidden", name: name, form: form, value: committed, disabled: disabled }), active ? _jsx(InputGroup, { ...editorProps, ref: editor, value: draft, placeholder: placeholder, onChange: event => { setDraft(event.currentTarget.value); current.current.draft = event.currentTarget.value; }, onCompositionStart: () => { composing.current = true; }, onCompositionEnd: event => {
+                    composing.current = false;
+                    setDraft(event.currentTarget.value);
+                    current.current.draft = event.currentTarget.value;
+                    const document = event.currentTarget.ownerDocument;
+                    if (blurAction !== "none" && !root.current?.contains(document.activeElement))
+                        queueMicrotask(() => finish(blurAction, false));
+                }, end: showActions ? _jsxs("div", { className: "flood-editable__actions", children: [_jsx(IconButton, { type: "button", label: saveLabel, size: controlSize, variant: "ghost", onPointerDown: event => { if (event.pointerType === "mouse")
+                                event.preventDefault(); }, onMouseDown: event => event.preventDefault(), onClick: () => finish("commit", true), children: glyph("save") }), _jsx(IconButton, { type: "button", label: cancelLabel, size: controlSize, variant: "ghost", onPointerDown: event => { if (event.pointerType === "mouse")
+                                event.preventDefault(); }, onMouseDown: event => event.preventDefault(), onClick: () => finish("cancel", true), children: glyph("cancel") })] }) : undefined })
+                : readOnly ? _jsx(Input, { ...editorProps, ref: editor, value: committed, readOnly: true })
+                    : _jsxs(Button, { ref: preview, id: previewId, type: "button", variant: "subtle", size: controlSize, disabled: disabled, className: "flood-editable__preview", "aria-describedby": props["aria-describedby"], "aria-label": `${editLabel}: ${label}. ${committed || placeholder}`, onClick: start, children: [_jsx("span", { className: "flood-editable__value", "data-empty": !committed || undefined, children: committed || placeholder }), _jsx(IconSlot, { size: controlSize, children: glyph("edit") })] })] });
+});

package/dist/error-summary.d.ts

@@ -0,0 +1,3 @@
+import type { ErrorSummaryProps } from "./index.js";
+/** A host-owned validation summary; errors are never inferred from the form. */
+export declare const ValidationErrorSummary: import("react").ForwardRefExoticComponent<ErrorSummaryProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/error-summary.js

@@ -0,0 +1,39 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef, useEffect, useId, useImperativeHandle, useRef } from "react";
+import { Alert, Link, List, Text } from "./index.js";
+import { hasFieldContent, mergeDescriptions } from "./field-state.js";
+/** A host-owned validation summary; errors are never inferred from the form. */
+export const ValidationErrorSummary = /* @__PURE__ */ forwardRef(function ValidationErrorSummary({ title, errors, description, announcement = "off", autoFocus = false, onSelect, className, id: explicitId, tabIndex = -1, "aria-labelledby": labelledBy, "aria-describedby": describedBy, ...props }, forwardedRef) {
+    if (!title.trim())
+        throw new Error("Flood ErrorSummary requires a nonempty title");
+    if (errors.some(error => !error.id.trim() || !error.fieldId.trim() || !error.message.trim()) || new Set(errors.map(error => error.id)).size !== errors.length)
+        throw new Error("Flood ErrorSummary requires unique nonempty error IDs, target IDs and messages");
+    if (!["off", "polite", "assertive"].includes(announcement))
+        throw new Error("Flood ErrorSummary announcement is unsupported");
+    const generated = useId(), id = explicitId ?? `flood-error-summary-${generated}`;
+    const root = useRef(null), present = errors.length > 0;
+    useImperativeHandle(forwardedRef, () => root.current, [present]);
+    const hasDescription = hasFieldContent(description), descriptionId = hasDescription ? `${id}-description` : undefined;
+    const live = autoFocus ? "off" : announcement;
+    useEffect(() => {
+        if (autoFocus && present)
+            root.current?.focus({ preventScroll: true });
+    }, [autoFocus, present]);
+    if (!present)
+        return null;
+    return _jsx("div", { ...props, id: id, ref: root, role: "region", tabIndex: tabIndex, "aria-labelledby": labelledBy ?? `${id}-title`, "aria-describedby": mergeDescriptions(describedBy, descriptionId), "aria-live": live === "off" ? undefined : live, "aria-atomic": live === "off" ? undefined : true, className: ["flood-error-summary", className].filter(Boolean).join(" "), children: _jsxs(Alert, { tone: "error", announcement: "off", children: [_jsx(Text, { as: "div", size: "label", id: `${id}-title`, className: "flood-error-summary__title", children: title }), hasDescription && _jsx(Text, { as: "div", size: "compact", tone: "subtle", id: descriptionId, className: "flood-error-summary__description", children: description }), _jsx(List, { gap: "1", className: "flood-error-summary__list", children: errors.map(error => _jsx("li", { children: _jsx(Link, { href: `#${encodeURIComponent(error.fieldId)}`, onClick: event => {
+                                onSelect?.(error, event);
+                                if (event.defaultPrevented || event.button !== 0 || event.altKey || event.ctrlKey || event.metaKey || event.shiftKey)
+                                    return;
+                                const document = event.currentTarget.ownerDocument, target = document.getElementById(error.fieldId);
+                                if (!target || typeof target.focus !== "function" || target.matches(":disabled") || target.closest("[inert]"))
+                                    return;
+                                const before = document.activeElement;
+                                target.focus({ preventScroll: true });
+                                const focused = document.activeElement;
+                                // Hidden native bridges can redirect focus to their visible Flood control.
+                                if (focused && focused !== before && focused !== event.currentTarget && "scrollIntoView" in focused)
+                                    focused.scrollIntoView({ block: "nearest", behavior: "auto" });
+                                // Keep native fragment navigation and modifier/new-tab behavior intact.
+                            }, children: error.message }) }, error.id)) })] }) });
+});

package/dist/feedback-actions.js

@@ -1,7 +1,7 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { forwardRef, useEffect, useImperativeHandle, useRef, useState } from "react";
 import { Button, IconButton, IconSlot, Spinner, VisuallyHidden } from "./index.js";
-export const ClipboardAction = forwardRef(function ClipboardAction({ value, copyLabel = "Copy", copiedLabel = "Copied", errorLabel = "Failed", resetDelay = 2000, onCopied, onCopyError, className, disabled, size = "md", variant = "subtle", "aria-label": accessibleLabel, ...props }, ref) {
+export const ClipboardAction = /* @__PURE__ */ forwardRef(function ClipboardAction({ value, copyLabel = "Copy", copiedLabel = "Copied", errorLabel = "Failed", resetDelay = 2000, onCopied, onCopyError, className, disabled, size = "md", variant = "subtle", "aria-label": accessibleLabel, ...props }, ref) {
     if (!Number.isFinite(resetDelay) || resetDelay < 0)
         throw new Error("Flood CopyButton resetDelay must be finite and nonnegative");
     const [phase, setPhase] = useState("idle");
@@ -78,7 +78,7 @@ function TimedToast({ item, closeLabel, onDismiss }) {
     return _jsxs("li", { ref: node, className: "flood-toast", "data-status": item.status ?? "neutral", onPointerEnter: () => setHover(true), onPointerLeave: () => setHover(false), onFocusCapture: () => setFocus(true), onBlurCapture: event => { if (!event.currentTarget.contains(event.relatedTarget))
             setFocus(false); }, children: [_jsxs("div", { className: "flood-toast__message", role: item.status === "error" ? "alert" : "status", "aria-atomic": "true", children: [_jsx("div", { className: "flood-toast__title", children: item.title }), item.description && _jsx("div", { className: "flood-toast__description", children: item.description })] }), _jsx(IconButton, { label: `${closeLabel}: ${item.title}`, size: "sm", variant: "ghost", className: "flood-toast__close", onClick: dismiss, children: _jsx("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "1.75", strokeLinecap: "round", children: _jsx("path", { d: "m6 6 12 12M18 6 6 18" }) }) }), item.action && _jsx(Button, { size: "sm", variant: "subtle", className: "flood-toast__action", onClick: item.action.onClick, children: item.action.label })] });
 }
-export const NotificationRegion = forwardRef(function NotificationRegion({ items, onDismiss, label = "Notifications", closeLabel = "Dismiss notification", placement = "bottom-end", limit = 3, inline = false, hotkey = true, className, ...props }, forwardedRef) {
+export const NotificationRegion = /* @__PURE__ */ forwardRef(function NotificationRegion({ items, onDismiss, label = "Notifications", closeLabel = "Dismiss notification", placement = "bottom-end", limit = 3, inline = false, hotkey = true, className, ...props }, forwardedRef) {
     if (!Number.isInteger(limit) || limit < 1)
         throw new Error("Flood ToastRegion limit must be a positive integer");
     const ids = new Set();

package/dist/feedback.js

@@ -9,7 +9,7 @@ export function validateRange(value, min, max, allowUnknown) {
     if (value === undefined || !Number.isFinite(value) || value < min || value > max)
         throw new RangeError("Flood indicator value must be finite and within its range");
 }
-export const ValueIndicator = forwardRef(function ValueIndicator({ kind, label, value, min, max, valueText, size, tone, hideLabel, className, ...props }, ref) {
+export const ValueIndicator = /* @__PURE__ */ forwardRef(function ValueIndicator({ kind, label, value, min, max, valueText, size, tone, hideLabel, className, ...props }, ref) {
     const labelId = `flood-indicator-${useId()}`;
     validateRange(value, min, max, kind === "progress");
     const unknown = value === undefined;
@@ -23,7 +23,7 @@ function StatusGlyph({ tone }) {
                 tone === "error" ? _jsxs(_Fragment, { children: [_jsx("circle", { cx: "12", cy: "12", r: "9" }), _jsx("path", { d: "m9 9 6 6m0-6-6 6" })] }) :
                     _jsxs(_Fragment, { children: [_jsx("circle", { cx: "12", cy: "12", r: "9" }), _jsx("path", { d: "M12 11v5m0-9h.01" })] }) });
 }
-export const FeedbackMessage = forwardRef(function FeedbackMessage({ title, tone, icon, announcement, children, className, ...props }, ref) {
+export const FeedbackMessage = /* @__PURE__ */ forwardRef(function FeedbackMessage({ title, tone, icon, announcement, children, className, ...props }, ref) {
     const artwork = icon === undefined ? _jsx(StatusGlyph, { tone: tone }) : icon;
     return _jsxs("div", { ...props, ref: ref, className: ["flood-alert", className].filter(Boolean).join(" "), "data-tone": tone, role: announcement === "assertive" ? "alert" : announcement === "polite" ? "status" : undefined, "aria-atomic": announcement === "off" ? undefined : true, children: [artwork != null && _jsx("span", { className: "flood-alert__icon", "aria-hidden": "true", children: artwork }), _jsxs("div", { className: "flood-alert__content", children: [title && _jsx("p", { className: "flood-alert__title", children: title }), children != null && _jsx("div", { className: "flood-alert__body", children: children })] })] });
 });

package/dist/file-input.js

@@ -2,7 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { forwardRef, useEffect, useImperativeHandle, useRef, useState } from "react";
 import { resolveFieldStatus } from "./field-state.js";
 /** FileList and native form submission stay owned by the browser. */
-export const FilePicker = forwardRef(function FilePicker({ actionComponent: Action, iconComponent: Icon, clearable = true, clearLabel = "Clear files", selectionLabel = "Selected files", removeFileLabel = "Remove file", placeholder, controlSize = "md", className, style, status, invalid, disabled, multiple, onChange, onFilesChange, ...props }, ref) {
+export const FilePicker = /* @__PURE__ */ forwardRef(function FilePicker({ actionComponent: Action, iconComponent: Icon, clearable = true, clearLabel = "Clear files", selectionLabel = "Selected files", removeFileLabel = "Remove file", placeholder, controlSize = "md", className, style, status, invalid, disabled, multiple, onChange, onFilesChange, ...props }, ref) {
     const input = useRef(null);
     useImperativeHandle(ref, () => input.current, []);
     const [files, setFiles] = useState([]);

package/dist/file-records.d.ts

@@ -0,0 +1,5 @@
+import { type FileMetaProps, type FileItemProps, type UploadItemProps, type ImagePreviewProps } from "./index.js";
+export declare const FileMetadata: import("react").ForwardRefExoticComponent<FileMetaProps & import("react").RefAttributes<HTMLSpanElement>>;
+export declare const FileRecord: import("react").ForwardRefExoticComponent<FileItemProps & import("react").RefAttributes<HTMLLIElement>>;
+export declare const UploadRecord: import("react").ForwardRefExoticComponent<UploadItemProps & import("react").RefAttributes<HTMLLIElement>>;
+export declare const ModalImagePreview: import("react").ForwardRefExoticComponent<ImagePreviewProps & import("react").RefAttributes<HTMLDialogElement>>;

package/dist/file-records.js

@@ -0,0 +1,55 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef, useState } from "react";
+import { DataListItem, IconSlot, IconButton, Link, Badge, FileMeta, StatusIndicator, Progress, Dialog, Image, Spinner, Text } from "./index.js";
+import { hasFieldContent } from "./field-state.js";
+const cx = (...parts) => parts.filter(Boolean).join(" ");
+function sizeText(bytes, locale) {
+    if (!Number.isFinite(bytes) || bytes < 0)
+        throw new Error("Flood file size must be finite and nonnegative");
+    const units = ["B", "kB", "MB", "GB", "TB"], unit = bytes === 0 ? 0 : Math.max(0, Math.min(4, Math.floor(Math.log10(bytes) / 3)));
+    return `${new Intl.NumberFormat(locale, { maximumFractionDigits: 1 }).format(bytes / 1000 ** unit)} ${units[unit]}`;
+}
+export const FileMetadata = /* @__PURE__ */ forwardRef(function FileMetadata({ format, size, formatSize, className, ...props }, ref) {
+    if (format !== undefined && !format.trim())
+        throw new Error("Flood FileMeta format must be nonempty when supplied");
+    if (size !== undefined && (!Number.isFinite(size) || size < 0))
+        throw new Error("Flood file size must be finite and nonnegative");
+    if (format === undefined && size === undefined)
+        return null;
+    const bytes = size === undefined ? undefined : (formatSize ?? ((value) => sizeText(value, props.lang)))(size);
+    return _jsxs(Badge, { ...props, ref: ref, size: "sm", tone: "neutral", className: cx("flood-file-meta", className), children: [format && _jsx("span", { children: format }), format && bytes && _jsx("span", { "aria-hidden": "true", children: "\u00B7" }), bytes && _jsx("span", { children: bytes })] });
+});
+function Glyph({ kind }) {
+    return _jsx("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "1.75", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: kind === "file" ? _jsxs(_Fragment, { children: [_jsx("path", { d: "M14 3H6a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V9Z" }), _jsx("path", { d: "M14 3v6h6M8 13h8M8 17h5" })] }) :
+            kind === "preview" ? _jsxs(_Fragment, { children: [_jsx("path", { d: "M2 12s3.5-7 10-7 10 7 10 7-3.5 7-10 7S2 12 2 12Z" }), _jsx("circle", { cx: "12", cy: "12", r: "3" })] }) :
+                kind === "retry" ? _jsx(_Fragment, { children: _jsx("path", { d: "M3 10a9 9 0 1 1 2 8M3 4v6h6" }) }) : _jsx("path", { d: "m6 6 12 12M18 6 6 18" }) });
+}
+const FileRow = /* @__PURE__ */ forwardRef(function FileRow({ name, size, mimeType, format, thumbnail, description, href, download = false, onPreview, onRemove, disabled = false, labels = {}, formatSize, className, extraActions, ...props }, ref) {
+    if (!name.trim())
+        throw new Error("Flood FileItem requires a nonempty file name");
+    if (size !== undefined && (!Number.isFinite(size) || size < 0))
+        throw new Error("Flood file size must be finite and nonnegative");
+    const extension = name.lastIndexOf(".") > 0 ? name.slice(name.lastIndexOf(".") + 1) : "";
+    const displayedFormat = format === null ? undefined : format ?? mimeType ?? (/^[a-z0-9]{1,12}$/i.test(extension) ? extension.toUpperCase() : undefined);
+    return _jsx(DataListItem, { ...props, ref: ref, className: cx("flood-file-item", className), media: _jsx("span", { className: "flood-file-item__thumbnail", "aria-hidden": "true", children: hasFieldContent(thumbnail) ? thumbnail : _jsx(IconSlot, { size: "lg", children: _jsx(Glyph, { kind: "file" }) }) }), title: _jsxs("span", { className: "flood-file-item__heading", children: [href && !disabled ? _jsx(Link, { href: href, download: download ? name : undefined, className: "flood-file-item__name", children: name }) : _jsx("span", { className: "flood-file-item__name", dir: "auto", children: name }), _jsx(FileMeta, { format: displayedFormat, size: size, formatSize: formatSize, lang: props.lang })] }), description: hasFieldContent(description) ? description : undefined, actions: (onPreview || onRemove || hasFieldContent(extraActions)) ? _jsxs(_Fragment, { children: [onPreview && _jsx(IconButton, { label: `${labels.preview ?? "Preview"}: ${name}`, variant: "ghost", size: "sm", disabled: disabled, onClick: onPreview, children: _jsx(Glyph, { kind: "preview" }) }), extraActions, onRemove && _jsx(IconButton, { label: `${labels.remove ?? "Remove"}: ${name}`, variant: "ghost", size: "sm", disabled: disabled, onClick: onRemove, children: _jsx(Glyph, { kind: "remove" }) })] }) : undefined });
+});
+export const FileRecord = /* @__PURE__ */ forwardRef(function FileRecord(props, ref) { return _jsx(FileRow, { ...props, ref: ref }); });
+export const UploadRecord = /* @__PURE__ */ forwardRef(function UploadRecord({ state, progress, error, onCancel, onRetry, onPreview, onRemove, href, labels = {}, disabled = false, className, ...props }, ref) {
+    if (!["queued", "uploading", "success", "error", "cancelled"].includes(state))
+        throw new Error("Flood UploadItem requires a supported state");
+    if (progress !== undefined && (!Number.isFinite(progress) || progress < 0 || progress > 100))
+        throw new Error("Flood upload progress must be between 0 and 100");
+    const active = state === "queued" || state === "uploading", retry = state === "error" || state === "cancelled";
+    const status = state === "error" ? (error || labels.error || "Upload failed") : labels[state] ?? ({ queued: "Waiting to upload", uploading: "Uploading", success: "Uploaded", error: "Upload failed", cancelled: "Cancelled" }[state]);
+    const percent = state === "uploading" && progress !== undefined ? ` · ${new Intl.NumberFormat(props.lang, { maximumFractionDigits: 0 }).format(progress)}%` : "";
+    return _jsx(FileRow, { ...props, ref: ref, labels: labels, disabled: disabled, href: state === "success" ? href : undefined, onPreview: state === "success" ? onPreview : undefined, onRemove: active ? undefined : onRemove, className: cx("flood-upload-item", className), "data-upload-state": state, description: _jsxs("div", { className: "flood-upload-item__status-row", "data-progress": state === "uploading" || undefined, children: [_jsx(StatusIndicator, { label: status + percent, tone: state === "error" ? "error" : state === "success" ? "success" : "neutral", size: "sm" }), state === "uploading" && _jsx(Progress, { label: `${labels.uploading ?? "Uploading"}: ${props.name}`, value: progress, size: "sm", hideLabel: true })] }), extraActions: (active && onCancel || retry && onRetry) ? _jsxs(_Fragment, { children: [active && onCancel && _jsx(IconButton, { label: `${labels.cancel ?? "Cancel upload"}: ${props.name}`, variant: "ghost", size: "sm", disabled: disabled, onClick: onCancel, children: _jsx(Glyph, { kind: "cancel" }) }), retry && onRetry && _jsx(IconButton, { label: `${labels.retry ?? "Retry upload"}: ${props.name}`, variant: "ghost", size: "sm", disabled: disabled, onClick: onRetry, children: _jsx(Glyph, { kind: "retry" }) })] }) : undefined });
+});
+function PreviewContent({ src, alt, caption, loadingLabel, errorLabel }) {
+    const [state, setState] = useState("loading");
+    return _jsxs("figure", { className: "flood-image-preview__figure", children: [_jsxs("div", { className: "flood-image-preview__media", "data-state": state, children: [_jsx(Image, { src: src, alt: alt, hidden: state === "error", className: "flood-image-preview__image", onLoad: () => setState("loaded"), onError: () => setState("error") }), state === "loading" && _jsx(Spinner, { label: loadingLabel }), state === "error" && _jsx(Text, { as: "p", size: "compact", tone: "subtle", role: "status", children: errorLabel })] }), hasFieldContent(caption) && _jsx("figcaption", { className: "flood-image-preview__caption", children: caption })] });
+}
+export const ModalImagePreview = /* @__PURE__ */ forwardRef(function ModalImagePreview({ src, alt, caption, downloadHref, downloadLabel = "Download image", loadingLabel = "Loading image…", errorLabel = "Could not load the image.", className, ...props }, ref) {
+    if (!src.trim() || typeof alt !== "string" || ![downloadLabel, loadingLabel, errorLabel].every(label => label.trim()))
+        throw new Error("Flood ImagePreview requires a source, explicit alt text and nonempty labels");
+    return _jsxs(Dialog, { ...props, ref: ref, className: cx("flood-image-preview", className), children: [_jsx(PreviewContent, { src: src, alt: alt, caption: caption, loadingLabel: loadingLabel, errorLabel: errorLabel }, src), downloadHref && _jsx("div", { className: "flood-image-preview__actions", children: _jsx(Link, { href: downloadHref, download: true, variant: "subtle", size: "sm", children: downloadLabel }) })] });
+});

package/dist/form-controls.js

@@ -1,8 +1,9 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { forwardRef, useEffect, useId, useImperativeHandle, useRef, useState } from "react";
-import { FileInput } from "./index.js";
+import { forwardRef, useEffect, useLayoutEffect, useId, useImperativeHandle, useRef, useState } from "react";
+import { FileInput, Label, Text } from "./index.js";
 import { resolveFieldStatus, mergeDescriptions } from "./field-state.js";
 const cx = (...values) => values.filter(Boolean).join(" ");
+const useBrowserLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
 function useNativeReset(ref, form, reset) {
     const callback = useRef(reset);
     useEffect(() => { callback.current = reset; }, [reset]);
@@ -36,9 +37,12 @@ function useInheritedDisabled(ref, disabled) {
     }, [ref, disabled]);
     return disabled || inherited;
 }
-export const CollectionListBox = forwardRef(function CollectionListBox({ label, hideLabel = false, options, value, defaultValue, onValueChange, multiple = false, disabled = false, readOnly = false, name, form, controlSize = "md", id: explicitId, className, onKeyDown, onFocus, ...props }, forwardedRef) {
+export const CollectionListBox = /* @__PURE__ */ forwardRef(function CollectionListBox({ label, hideLabel = false, options, value, defaultValue, onValueChange, multiple = false, selectionBehavior = "automatic", appearance = "surface", disabled = false, readOnly = false, name, form, controlSize = "md", id: explicitId, required = false, requiredMessage = "Choose at least one option.", validationMessage, description, message, status, invalid, className, onKeyDown, onFocus, onBlur, onInvalid, ...props }, forwardedRef) {
     const generated = useId(), id = explicitId ?? `flood-list-box-${generated}`;
     const root = useRef(null), bridge = useRef(null);
+    const [touched, setTouched] = useState(false);
+    if (!label.trim() || !requiredMessage.trim())
+        throw new Error("Flood ListBox requires a nonempty label and required message");
     useImperativeHandle(forwardedRef, () => root.current, []);
     const unique = new Set();
     for (const option of options) {
@@ -56,11 +60,15 @@ export const CollectionListBox = forwardRef(function CollectionListBox({ label,
     const first = Math.max(0, options.findIndex(option => !option.disabled));
     const [active, setActive] = useState(() => { const index = options.findIndex(option => selected.includes(option.value) && !option.disabled); return index < 0 ? first : index; });
     const effectiveDisabled = useInheritedDisabled(bridge, disabled);
+    const constraint = readOnly ? "" : validationMessage || (required && !selected.length ? requiredMessage : "");
+    const error = touched && !effectiveDisabled ? constraint : "", resolvedStatus = resolveFieldStatus(status, invalid || Boolean(error), props["aria-invalid"]);
+    const describedBy = mergeDescriptions(props["aria-describedby"], Boolean(description) && `${id}-description`, Boolean(error || message) && `${id}-message`);
+    useBrowserLayoutEffect(() => { bridge.current?.setCustomValidity(constraint); }, [constraint]);
     const search = useRef({ text: "", time: 0 });
     useNativeReset(bridge, form, () => { if (value === undefined) {
         setLocal(normalize(initial.current));
         setActive(first);
-    } });
+    } setTouched(false); });
     const blocked = () => effectiveDisabled || bridge.current?.matches(":disabled");
     const commit = (index) => {
         const option = options[index];
@@ -71,15 +79,19 @@ export const CollectionListBox = forwardRef(function CollectionListBox({ label,
             setLocal(next);
         onValueChange?.(multiple ? [...next] : next[0] ?? "");
     };
-    const move = (index, choose = !multiple) => {
+    const move = (index, choose = !multiple && selectionBehavior === "automatic") => {
         setActive(index);
         if (choose)
             commit(index);
         const target = root.current?.ownerDocument.getElementById(`${id}-option-${index}`);
         target?.scrollIntoView({ block: "nearest" });
     };
-    return _jsxs("div", { className: "flood-list-box-field", hidden: props.hidden, dir: props.dir, lang: props.lang, children: [_jsx("span", { id: `${id}-label`, className: cx("flood-form-control__label", hideLabel && "flood-form-control__sr-only"), children: label }), _jsxs("div", { ...props, ref: root, id: id, role: "listbox", tabIndex: effectiveDisabled ? -1 : props.tabIndex ?? 0, "aria-label": props["aria-label"], "aria-labelledby": props["aria-label"] ? undefined : props["aria-labelledby"] ?? `${id}-label`, "aria-multiselectable": multiple || undefined, "aria-disabled": effectiveDisabled || undefined, "aria-readonly": readOnly || undefined, "aria-activedescendant": options[active] ? `${id}-option-${active}` : undefined, className: cx("flood-list-box", `flood-control--${controlSize}`, className), onFocus: event => { onFocus?.(event); if (!options[active] || options[active].disabled)
-                    setActive(first); }, onKeyDown: event => {
+    return _jsxs("div", { className: "flood-list-box-field", hidden: props.hidden, dir: props.dir, lang: props.lang, children: [_jsx(Label, { htmlFor: `${id}-validation`, id: `${id}-label`, required: required, className: cx("flood-form-control__label", hideLabel && "flood-form-control__sr-only"), children: label }), _jsxs("div", { ...props, ref: root, id: id, role: "listbox", tabIndex: effectiveDisabled ? -1 : props.tabIndex ?? 0, "aria-label": props["aria-label"], "aria-labelledby": props["aria-label"] ? undefined : props["aria-labelledby"] ?? `${id}-label`, "aria-multiselectable": multiple || undefined, "aria-disabled": effectiveDisabled || undefined, "aria-readonly": readOnly || undefined, "aria-required": required || undefined, "aria-invalid": resolvedStatus === "error" || undefined, "aria-describedby": describedBy, "aria-activedescendant": options[active] ? `${id}-option-${active}` : undefined, "data-status": resolvedStatus, "data-appearance": appearance, className: cx("flood-list-box", `flood-control--${controlSize}`, className), onBlur: event => { onBlur?.(event); if (!event.defaultPrevented && !event.currentTarget.contains(event.relatedTarget))
+                    setTouched(true); }, onInvalid: event => { onInvalid?.(event); if (event.defaultPrevented)
+                    return; event.preventDefault(); setTouched(true); root.current?.focus(); }, onFocus: event => { onFocus?.(event); if (!options[active] || options[active].disabled)
+                    setActive(first);
+                else
+                    root.current?.querySelector(`[id="${id}-option-${active}"]`)?.scrollIntoView({ block: "nearest" }); }, onKeyDown: event => {
                     onKeyDown?.(event);
                     if (event.defaultPrevented || event.altKey || event.ctrlKey || event.metaKey || event.nativeEvent.isComposing || blocked())
                         return;
@@ -108,10 +120,10 @@ export const CollectionListBox = forwardRef(function CollectionListBox({ label,
                         if (match !== undefined)
                             move(match);
                     }
-                }, children: [options.map((option, index) => _jsxs("div", { id: `${id}-option-${index}`, role: "option", "aria-selected": selected.includes(option.value), "aria-disabled": option.disabled || undefined, "data-active": index === active || undefined, className: "flood-list-box__option", onClick: () => { if (blocked())
-                            return; root.current?.focus(); setActive(index); commit(index); }, children: [_jsxs("span", { className: "flood-list-box__copy", children: [_jsx("span", { children: option.label }), option.description && _jsx("span", { className: "flood-list-box__description", children: option.description })] }), _jsx("span", { className: "flood-list-box__check", "aria-hidden": "true", children: selected.includes(option.value) ? "✓" : "" })] }, option.value)), !options.length && _jsx("div", { role: "option", "aria-disabled": "true", className: "flood-list-box__option", children: "No options" })] }), _jsx("input", { ref: bridge, type: "hidden", form: form, disabled: disabled }), name && selected.map(entry => _jsx("input", { type: "hidden", name: name, value: entry, form: form, disabled: disabled }, entry))] });
+                }, children: [_jsx("input", { ref: bridge, id: `${id}-validation`, type: "text", className: "flood-form-control__sr-only", tabIndex: -1, "aria-hidden": "true", autoComplete: "off", form: form, disabled: disabled, readOnly: readOnly, required: required && !readOnly, value: selected.join("\u001f"), onChange: () => { }, onFocus: event => { event.stopPropagation(); root.current?.focus(); } }), options.map((option, index) => _jsxs("div", { id: `${id}-option-${index}`, role: "option", "aria-selected": selected.includes(option.value), "aria-disabled": option.disabled || undefined, "data-active": index === active || undefined, className: "flood-list-box__option", onClick: () => { if (blocked())
+                            return; root.current?.focus(); setActive(index); commit(index); }, children: [_jsxs("span", { className: "flood-list-box__copy", children: [_jsx("span", { children: option.label }), option.description && _jsx("span", { className: "flood-list-box__description", children: option.description })] }), _jsx("span", { className: "flood-list-box__check", "aria-hidden": "true", children: selected.includes(option.value) ? "✓" : "" })] }, option.value)), !options.length && _jsx("div", { role: "option", "aria-disabled": "true", className: "flood-list-box__option", children: "No options" })] }), description && _jsx(Text, { as: "div", id: `${id}-description`, size: "helper", tone: "subtle", className: "flood-list-box__feedback", children: description }), (error || message) && _jsx(Text, { as: "div", id: `${id}-message`, size: "helper", tone: error ? "error" : resolvedStatus ?? "subtle", role: error ? "alert" : undefined, className: "flood-list-box__feedback", children: error || message }), name && selected.map(entry => _jsx("input", { type: "hidden", name: name, value: entry, form: form, disabled: disabled }, entry))] });
 });
-export const SegmentedPinInput = forwardRef(function SegmentedPinInput({ label, hideLabel = false, length = 6, mode = "numeric", mask = false, value, defaultValue = "", onValueChange, controlSize = "md", disabled, readOnly, className, style, status, invalid, id: explicitId, onFocus, onBlur, onSelect, onPointerDown, onPaste, onKeyUp, autoComplete = "one-time-code", inputMode, ...props }, forwardedRef) {
+export const SegmentedPinInput = /* @__PURE__ */ forwardRef(function SegmentedPinInput({ label, hideLabel = false, length = 6, mode = "numeric", mask = false, value, defaultValue = "", onValueChange, controlSize = "md", disabled, readOnly, className, style, status, invalid, id: explicitId, onFocus, onBlur, onSelect, onPointerDown, onPaste, onKeyUp, autoComplete = "one-time-code", inputMode, ...props }, forwardedRef) {
     if (!Number.isInteger(length) || length < 1 || length > 12)
         throw new Error("Flood PinInput length must be an integer from 1 to 12");
     const clean = (text) => text.replace(mode === "numeric" ? /[^0-9]/g : /[^a-zA-Z0-9]/g, "").slice(0, length);
@@ -160,7 +172,7 @@ export const SegmentedPinInput = forwardRef(function SegmentedPinInput({ label,
                             insert(next, Math.min(start + pasted.length, length));
                         } }), Array.from({ length }, (_, index) => _jsx("span", { "data-pin-slot": "", "aria-hidden": "true", className: "flood-pin-input__slot", "data-active": focused && index === active || undefined, children: text[index] ? mask ? "•" : text[index] : "" }, index))] })] });
 });
-export const StarRating = forwardRef(function StarRating({ label, hideLabel = false, value, defaultValue = 0, max = 5, onValueChange, getValueLabel, readOnly = false, required, name, form, size = "md", disabled, className, onKeyDown, ...props }, forwardedRef) {
+export const StarRating = /* @__PURE__ */ forwardRef(function StarRating({ label, hideLabel = false, value, defaultValue = 0, max = 5, onValueChange, getValueLabel, readOnly = false, required, name, form, size = "md", disabled, className, onKeyDown, ...props }, forwardedRef) {
     if (!name?.trim())
         throw new Error("Flood Rating requires a nonempty native group name");
     if (!Number.isInteger(max) || max < 1 || max > 10)
@@ -212,7 +224,7 @@ export const StarRating = forwardRef(function StarRating({ label, hideLabel = fa
                                     event.preventDefault(); }, onChange: () => change(number) }), _jsx("svg", { "aria-hidden": "true", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "1.6", strokeLinejoin: "round", children: _jsx("path", { d: "m12 3 2.8 5.8 6.4.9-4.6 4.5 1.1 6.4-5.7-3-5.7 3 1.1-6.4-4.6-4.5 6.4-.9L12 3Z" }) })] }, number);
                 }) })] });
 });
-export const FileDropzone = forwardRef(function FileDropzone({ label, description = "Drop files here or choose from your device.", multiple = true, disabled, className, style, id: explicitId, status, invalid, ...props }, forwardedRef) {
+export const FileDropzone = /* @__PURE__ */ forwardRef(function FileDropzone({ label, description = "Drop files here or choose from your device.", multiple = true, disabled, className, style, id: explicitId, status, invalid, ...props }, forwardedRef) {
     const input = useRef(null), generated = useId(), id = explicitId ?? `flood-dropzone-${generated}`;
     useImperativeHandle(forwardedRef, () => input.current, []);
     const [dragging, setDragging] = useState(false), depth = useRef(0);
@@ -240,7 +252,7 @@ export const FileDropzone = forwardRef(function FileDropzone({ label, descriptio
             node.dispatchEvent(new node.ownerDocument.defaultView.Event("change", { bubbles: true }));
         }, children: [_jsxs("div", { className: "flood-dropzone__intro", children: [_jsxs("label", { htmlFor: id, className: "flood-dropzone__label", children: [_jsx("svg", { "aria-hidden": "true", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "1.75", strokeLinecap: "round", strokeLinejoin: "round", children: _jsx("path", { d: "M12 16V3m-4 4 4-4 4 4M4 15v5a1 1 0 0 0 1 1h14a1 1 0 0 0 1-1v-5" }) }), _jsx("span", { children: label })] }), description && _jsx("p", { id: `${id}-description`, className: "flood-dropzone__description", children: description })] }), _jsx(FileInput, { ...props, ref: input, id: id, multiple: multiple, disabled: disabled, status: status, invalid: invalid, "aria-describedby": mergeDescriptions(props["aria-describedby"], Boolean(description) && `${id}-description`) })] });
 });
-export const SupportingCharacterCount = forwardRef(function SupportingCharacterCount({ value = "", count, max, mode = "count", label = "Characters", overLimitLabel = "Over limit", className, ...props }, ref) {
+export const SupportingCharacterCount = /* @__PURE__ */ forwardRef(function SupportingCharacterCount({ value = "", count, max, mode = "count", label = "Characters", overLimitLabel = "Over limit", className, ...props }, ref) {
     const current = count ?? [...value].length;
     if (!Number.isInteger(current) || current < 0 || max !== undefined && (!Number.isInteger(max) || max < 0))
         throw new Error("Flood CharacterCount requires nonnegative integer counts and limits");