@flood-md/react 0.2.4 → 0.2.6

package/README.md

@@ -3,7 +3,7 @@
 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.4** API. Keep Flood package versions aligned and follow the guide matching
+This package documents the **0.2.6** source API. Keep Flood package versions aligned and follow the guide matching
 your installed declarations; source changes do not modify an existing npm release.
 
 ```tsx
@@ -812,3 +812,93 @@ original OFL notices. Color alone never communicates validation or progress.
 CodeSnippet codeDirection defaults to ltr independently of RTL parent action layout; choose rtl/auto explicitly for content that needs it. Native dir still applies to the wrapper. Protected ScrollArea reveals focused descendants fully when needed, composes the host focus handler and avoids scrolling to nested top-layer controls.
 
 Checkbox, Radio and Switch apply native hidden/dir/lang to their visible label wrapper as well as the input, so a component-local language/direction applies to its whole choice.
+
+
+0.2.5 adds NumberInput (native numeric editing and integrated step actions) and Slider (one value or an ordered pair). Use matching declarations and the numeric controls guide in docs/base-components.md. Registry publication is separate from source availability.
+
+Combobox adds editable single selection in 0.2.5. Reuse Field for the
+label, use options with stable value/label pairs, and observe onValueChange for
+the selected ID. Search query text is not form data. See docs/base-components.md
+for reset, required, read-only, localized messages and native Popover requirements.
+
+Tag and MultiSelect are compatible additions in 0.2.5.
+Tag labels an item and optionally requests host-owned removal. MultiSelect uses
+arrays of stable option IDs and composes those tags with the shared searchable
+selection model. See docs/base-components.md for keyboard behavior, locked values,
+readonly/required forms, focus recovery and relative nested geometry. Existing
+Combobox continues to accept and return a single string.
+
+
+SearchInput and PasswordInput join 0.2.5. Both compose
+InputGroup with native input props, Field feedback, ref, sizes and form ownership.
+SearchInput uses type=search and a decorative leading icon; clearable defaults to
+true and clearLabel names its sole suffix action. Clearing dispatches native input
+editing, restores input focus and respects read-only/disabled. The host owns search
+results and submission. PasswordInput keeps one visibility action; use
+visible/onVisibleChange or defaultVisible, and localize showPasswordLabel and
+hidePasswordLabel. Revealing retains the value and caret; read-only permits reveal.
+Use autocomplete appropriate to the host form. Both accept accessible names via
+Field, aria-label or aria-labelledby. These controls add no authentication logic.
+
+
+FileInput (0.2.5) composes a native file input with Flood field geometry,
+IconSlot and one optional clear IconButton. Pass Field's render props for its
+accessible name/description/status. Native name, form, required, accept, multiple,
+capture and input ref remain available. onChange is a native React change handler;
+onFilesChange receives a new readonly File array for selection and clear. Do not
+pass value/defaultValue/readOnly; FileList belongs to the browser. Uncontrolled
+form reset clears the summary; cancelling the chooser keeps its prior selection.
+Localize placeholder and clearLabel. Long names truncate visually, and the host
+owns upload, file validation and progress. accept only guides the chooser.
+
+
+FileInput multiple selection exposes a collapsible file list with full names and
+localized file sizes (lang controls number formatting), and a count in the picker.
+Translate selectionLabel and removeFileLabel. Individual removal updates the native
+FileList through DataTransfer, then emits the same change callbacks as selection.
+Focus moves to the next/previous remove action, or back to the input when empty.
+clearable=false disables individual and global removal UI. In multiple mode, picking again appends files to the current selection; cancel
+preserves it. Repeated files are deduplicated by name, size, type, lastModified and
+relative path, without reading their contents. Single mode replaces its selection. The host remains responsible for upload.
+
+
+AlertDialog (0.2.5) is a concise confirmation, composed from Flood's
+native modal layer and Button. Supply title, description, trigger and onConfirm.
+Cancel receives initial focus; Escape cancels; outside clicks do not dismiss.
+Tab containment, background inertness, scroll lock and return focus reuse Dialog.
+Translate confirmLabel/cancelLabel. onConfirm runs before requesting close, while
+onCancel covers Cancel/Escape. Use open/onOpenChange for controlled state and
+confirmDisabled to disable confirmation. Callbacks are not awaited; the host owns
+async requests, pending UI and errors. Use Dialog for forms/complex content.
+
+
+Drawer (0.2.5) reuses Dialog's modal behavior with an edge-panel layout.
+side is logical start/end (default end) or top/bottom; size sm/md/lg sets the
+cross-axis extent to 20/26/34rem within the viewport. Vertical panels fill height,
+horizontal panels fill width. Use footer for host-owned actions; only body content
+scrolls with Flood ScrollArea. Header/close action/footer remain visible. Native
+ref, controlled open/onOpenChange, outside dismissal and initialFocusRef match
+Dialog. Translate closeLabel/title/description; reduced motion disables entry
+animation. Closing is immediate. There is no swipe/drag gesture or auto-save logic.
+
+
+The 0.2.5 separates floating surfaces from modal surfaces.
+Nine additional semantic roles bring the dark profile to 193 roles; previous token
+values remain intact. surface.floating is the opaque fallback;
+surface.floating-translucent, border.floating, selection.floating, shadow.floating
+and effect.floating blur/saturation/shadow-offset/shadow-blur define the floating
+material. Select, Combobox, MultiSelect, Menu, Popover and Tooltip share it; Dialog
+and Drawer retain surface.overlay. Backdrop filtering is progressive enhancement;
+reduced transparency uses the opaque fill and forced colors use system colors.
+Keep text opaque and evaluate it against the actual composited background.
+
+
+The 0.2.5 component expansion adds native content/typography,
+collection/form controls, navigation/layout and clipboard/notification primitives.
+See docs/base-components.md and the per-component catalog for contracts and limits.
+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.

package/dist/alert-dialog.d.ts

@@ -0,0 +1,2 @@
+import type { AlertDialogProps } from "./index.js";
+export declare const ConfirmationDialog: import("react").ForwardRefExoticComponent<AlertDialogProps & import("react").RefAttributes<HTMLDialogElement>>;

package/dist/alert-dialog.js

@@ -0,0 +1,23 @@
+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) {
+    const [local, setLocal] = useState(defaultOpen);
+    const cancel = useRef(null);
+    const request = (next) => {
+        if (controlled === undefined)
+            setLocal(next);
+        onOpenChange?.(next);
+    };
+    const dismiss = () => { onCancel?.(); request(false); };
+    return _jsx(ModalOverlay, { ...props, ref: ref, role: "alertdialog", open: controlled ?? local, onOpenChange: next => { if (next)
+            request(true);
+        else
+            dismiss(); }, closeOnOutsideClick: false, showCloseButton: false, initialFocusRef: cancel, className: ["flood-alert-dialog", className].filter(Boolean).join(" "), children: _jsxs("div", { className: "flood-alert-dialog__actions", children: [_jsx(Button, { ref: cancel, type: "button", variant: "subtle", onClick: dismiss, children: cancelLabel }), _jsx(Button, { type: "button", disabled: confirmDisabled, onClick: () => {
+                        if (confirmDisabled)
+                            return;
+                        onConfirm();
+                        request(false);
+                    }, children: confirmLabel })] }) });
+});

package/dist/combobox.d.ts

@@ -0,0 +1,11 @@
+import { type ComboboxProps } from "./index.js";
+interface SearchSelectionProps extends Omit<ComboboxProps, "value" | "defaultValue" | "onValueChange"> {
+    selectedValues?: readonly string[];
+    initialValues: readonly string[];
+    onSelectionChange?: (value: string[]) => void;
+    multiple?: boolean;
+    removeItemLabel?: string;
+}
+/** Shared search/layer model. Public single and multiple value contracts stay distinct. */
+export declare const SearchSelection: import("react").ForwardRefExoticComponent<SearchSelectionProps & import("react").RefAttributes<HTMLInputElement>>;
+export {};

package/dist/combobox.js

@@ -0,0 +1,301 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef, useEffect, useId, useImperativeHandle, useLayoutEffect, useRef, useState } from "react";
+import { Input, InputGroup, IconButton, ScrollArea, Tag } from "./index.js";
+import { mergeDescriptions, resolveFieldStatus } from "./field-state.js";
+import { positionLayer, registerLayer } from "./overlay-runtime.js";
+const useBrowserLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
+const searchable = (text) => text.normalize("NFKD").replace(/\p{M}/gu, "").toLowerCase();
+/** Shared search/layer model. Public single and multiple value contracts stay distinct. */
+export const SearchSelection = forwardRef(function SearchSelection({ options, selectedValues: value, initialValues: defaultValue, onSelectionChange: onValueChange, multiple = false, removeItemLabel = "Remove", clearable = false, emptyMessage = "No results found.", listLabel = "Options", toggleLabel = "Show options", clearLabel = "Clear selection", invalidSelectionMessage = "Select an option.", controlSize = "md", readOnly, disabled, required, name, id: explicitId, className, onKeyDown, onBlur, onClick, onInvalid, autoComplete = "off", ...props }, forwardedRef) {
+    if (new Set(options.map(option => option.value)).size !== options.length || options.some(option => !option.value || !option.label.trim()))
+        throw new Error("Flood Combobox options need unique nonempty values and labels");
+    if (![emptyMessage, listLabel, toggleLabel, clearLabel, invalidSelectionMessage].every(text => text.trim()))
+        throw new Error("Flood Combobox messages and action labels must be nonempty");
+    for (const values of [defaultValue, value])
+        if (values !== undefined && (!Array.isArray(values) || new Set(values).size !== values.length || values.some(item => typeof item !== "string" || !item)))
+            throw new Error("Flood selection values must be unique nonempty strings");
+    if (multiple && !removeItemLabel.trim())
+        throw new Error("Flood MultiSelect requires an accessible removal label");
+    const generatedId = useId(), id = explicitId ?? `flood-combobox-${generatedId}`;
+    const menuId = `${id}-options`, validationId = `${id}-validation`;
+    const input = useRef(null), root = useRef(null), panel = useRef(null), viewport = useRef(null);
+    useImperativeHandle(forwardedRef, () => input.current, []);
+    const initial = useRef([...defaultValue]);
+    const [local, setLocal] = useState(() => [...defaultValue]), [query, setQuery] = useState(null);
+    const [open, setOpen] = useState(false), [activeValue, setActiveValue] = useState();
+    const [validation, setValidation] = useState("");
+    const selections = (value ?? local).map(id => options.find(option => option.value === id)).filter((option) => Boolean(option));
+    const selected = selections[0], selectedIds = selections.map(option => option.value);
+    const displayed = query ?? (multiple ? "" : selected?.label ?? "");
+    const filtered = query === null ? options : options.filter(option => searchable([option.label, ...(option.keywords ?? [])].join(" ")).includes(searchable(query)));
+    const enabled = filtered.filter(option => !option.disabled);
+    const active = enabled.find(option => option.value === activeValue) ?? enabled[0];
+    const optionId = (optionValue) => `${menuId}-${options.findIndex(option => option.value === optionValue)}`;
+    const current = useRef({ value, selected, readOnly, disabled });
+    current.current = { value, selected, readOnly, disabled };
+    const close = () => { setOpen(false); setQuery(null); };
+    const inert = () => Boolean(readOnly || disabled || input.current?.matches(":disabled"));
+    const publish = (next) => {
+        if (value === undefined)
+            setLocal(next);
+        if (next.length !== selectedIds.length || next.some((id, index) => id !== selectedIds[index]))
+            onValueChange?.([...next]);
+        setValidation("");
+    };
+    const remove = (id) => {
+        if (inert() || options.find(option => option.value === id)?.disabled)
+            return;
+        publish(selectedIds.filter(value => value !== id));
+        input.current?.focus({ preventScroll: true });
+    };
+    const select = (next) => {
+        if (inert() || (next !== "" && !options.some(option => option.value === next && !option.disabled)))
+            return;
+        if (multiple) {
+            publish(next === "" ? selections.filter(option => option.disabled).map(option => option.value) : selectedIds.includes(next) ? selectedIds.filter(id => id !== next) : [...selectedIds, next]);
+            if (next) {
+                setQuery("");
+                setActiveValue(next);
+                setOpen(true);
+            }
+            else
+                close();
+        }
+        else {
+            publish(next ? [next] : []);
+            close();
+        }
+        input.current?.focus({ preventScroll: true });
+    };
+    const show = () => {
+        if (inert())
+            return;
+        setActiveValue(selected?.value);
+        setOpen(true);
+    };
+    useBrowserLayoutEffect(() => {
+        input.current?.setCustomValidity(required && !selections.length ? invalidSelectionMessage : "");
+    }, [required, selections.length, invalidSelectionMessage]);
+    useEffect(() => {
+        const form = input.current?.form;
+        if (!form)
+            return;
+        const reset = (event) => queueMicrotask(() => {
+            if (event.defaultPrevented)
+                return;
+            if (current.current.value === undefined)
+                setLocal(initial.current);
+            setQuery(null);
+            setOpen(false);
+            setValidation("");
+        });
+        form.addEventListener("reset", reset);
+        return () => form.removeEventListener("reset", reset);
+    }, [props.form]);
+    useEffect(() => {
+        const control = input.current, Observer = control?.ownerDocument.defaultView?.MutationObserver;
+        if (!control || !Observer)
+            return;
+        const observer = new Observer(() => { if (control.matches(":disabled")) {
+            setOpen(false);
+            setQuery(null);
+        } });
+        let parent = control.parentElement;
+        while (parent) {
+            if (parent.localName === "fieldset")
+                observer.observe(parent, { attributes: true, attributeFilter: ["disabled"] });
+            parent = parent.parentElement;
+        }
+        return () => observer.disconnect();
+    }, []);
+    useEffect(() => { if (disabled || readOnly || props.hidden) {
+        setOpen(false);
+        setQuery(null);
+    } }, [disabled, readOnly, props.hidden]);
+    useBrowserLayoutEffect(() => {
+        if (!open || !panel.current || !root.current || !input.current)
+            return;
+        const popup = panel.current, anchor = root.current, control = input.current;
+        const document = popup.ownerDocument, view = document.defaultView;
+        let alive = true, frame = 0, unregister = () => { };
+        const assign = (element, property, value) => { if (element.style.getPropertyValue(property) !== value)
+            element.style.setProperty(property, value); };
+        const update = () => {
+            if (!alive)
+                return;
+            if (!anchor.isConnected || !anchor.getClientRects().length || control.matches(":disabled")) {
+                setOpen(false);
+                setQuery(null);
+                return;
+            }
+            const rect = anchor.getBoundingClientRect(), visual = view.visualViewport;
+            const rootSize = parseFloat(view.getComputedStyle(document.documentElement).fontSize);
+            const length = (name) => { const raw = view.getComputedStyle(control).getPropertyValue(name).trim(); return parseFloat(raw) * (raw.endsWith("rem") ? rootSize : 1); };
+            const gap = length("--flood-sys-space-2") || 0;
+            const width = visual?.width ?? view.innerWidth, height = visual?.height ?? view.innerHeight, top = visual?.offsetTop ?? 0;
+            const room = Math.max(top + height - rect.bottom - gap * 2, rect.top - top - gap * 2);
+            const maxHeight = Math.min(length("--flood-sys-control-md-height") * 8, Math.max(0, room));
+            assign(popup, "width", `${Math.min(rect.width, Math.max(0, width - gap * 2))}px`);
+            assign(popup, "max-height", `${maxHeight}px`);
+            assign(popup, "column-gap", "var(--flood-sys-space-2)");
+            const css = view.getComputedStyle(popup);
+            const inset = parseFloat(css.paddingTop) + parseFloat(css.paddingBottom) + parseFloat(css.borderTopWidth) + parseFloat(css.borderBottomWidth);
+            if (viewport.current)
+                assign(viewport.current, "max-height", `${Math.max(0, maxHeight - inset)}px`);
+            positionLayer(anchor, popup, "bottom", "start");
+            frame = view.requestAnimationFrame(update);
+        };
+        const start = () => {
+            if (!alive)
+                return;
+            const dialog = anchor.closest("dialog");
+            if (dialog && !dialog.open) {
+                frame = view.requestAnimationFrame(start);
+                return;
+            }
+            if (typeof popup.showPopover !== "function")
+                throw new Error("Flood Combobox requires the native Popover API");
+            popup.style.visibility = "hidden";
+            popup.showPopover();
+            update();
+            unregister = registerLayer(document, { panel: popup, anchor: () => anchor, close: () => { setOpen(false); setQuery(null); } });
+        };
+        const toggle = (event) => { if (alive && event.newState === "closed" && !popup.matches(":popover-open")) {
+            setOpen(false);
+            setQuery(null);
+        } };
+        popup.addEventListener("toggle", toggle);
+        start();
+        return () => { alive = false; view.cancelAnimationFrame(frame); unregister(); popup.removeEventListener("toggle", toggle); if (popup.matches(":popover-open"))
+            popup.hidePopover(); };
+    }, [open]);
+    useEffect(() => {
+        if (!open || !active || !viewport.current)
+            return;
+        const option = panel.current?.ownerDocument.getElementById(optionId(active.value));
+        if (!option)
+            return;
+        const area = viewport.current, a = option.getBoundingClientRect(), b = area.getBoundingClientRect();
+        if (a.top < b.top)
+            area.scrollTop -= b.top - a.top;
+        else if (a.bottom > b.bottom)
+            area.scrollTop += a.bottom - b.bottom;
+    }, [open, active?.value, query, options]);
+    const glyph = (clear) => _jsx("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "1.75", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: clear ? _jsx("path", { d: "m6 6 12 12M18 6 6 18" }) : _jsx("path", { d: "m6 9 6 6 6-6" }) });
+    const inputProps = {
+        ...props, id, type: "text", value: displayed, disabled, readOnly, required: required && (!multiple || !selections.length), controlSize, autoComplete,
+        role: "combobox", "aria-autocomplete": "list", "aria-haspopup": "listbox", "aria-expanded": open, "aria-controls": open ? menuId : undefined,
+        "aria-required": required || undefined, "aria-activedescendant": open && active ? optionId(active.value) : undefined,
+        "aria-describedby": mergeDescriptions(props["aria-describedby"], validation && validationId, multiple && Boolean(selections.length) && `${id}-selection`),
+        invalid: props.invalid || Boolean(validation),
+        onChange: event => {
+            if (inert())
+                return;
+            const text = event.currentTarget.value;
+            setQuery(text);
+            setActiveValue(undefined);
+            setOpen(true);
+            setValidation("");
+            if (!multiple && text === "" && selected)
+                publish([]);
+        },
+        onClick: event => { onClick?.(event); if (!event.defaultPrevented)
+            show(); },
+        onBlur: event => {
+            onBlur?.(event);
+            if (event.defaultPrevented || root.current?.contains(event.relatedTarget))
+                return;
+            close();
+        },
+        onInvalid: event => { onInvalid?.(event); if (!event.defaultPrevented)
+            setValidation(event.currentTarget.validationMessage); },
+        onKeyDown: event => {
+            onKeyDown?.(event);
+            if (event.defaultPrevented || event.altKey || event.ctrlKey || event.metaKey || event.nativeEvent.isComposing)
+                return;
+            // The composite owns Backspace; readonly selection must not become browser Back.
+            if (multiple && readOnly && event.key === "Backspace")
+                event.preventDefault();
+            if (inert())
+                return;
+            const rtl = event.currentTarget.ownerDocument.defaultView?.getComputedStyle(event.currentTarget).direction === "rtl";
+            if (multiple && event.key === "Backspace" && displayed === "") {
+                const last = [...selections].reverse().find(option => !option.disabled);
+                if (last) {
+                    event.preventDefault();
+                    remove(last.value);
+                }
+            }
+            else if (multiple && event.key === (rtl ? "ArrowRight" : "ArrowLeft") && event.currentTarget.selectionStart === 0 && event.currentTarget.selectionEnd === 0) {
+                const buttons = root.current?.querySelectorAll(".flood-tag__remove:not(:disabled)");
+                if (buttons?.length) {
+                    event.preventDefault();
+                    buttons[buttons.length - 1].focus();
+                }
+            }
+            else if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+                event.preventDefault();
+                if (!open) {
+                    setActiveValue(event.key === "ArrowUp" ? enabled.at(-1)?.value : selected?.value ?? enabled[0]?.value);
+                    setOpen(true);
+                }
+                else {
+                    const index = enabled.findIndex(option => option.value === active?.value);
+                    const next = (index + (event.key === "ArrowDown" ? 1 : -1) + enabled.length) % enabled.length;
+                    setActiveValue(enabled[next]?.value);
+                }
+            }
+            else if (event.key === "Enter" && open) {
+                event.preventDefault();
+                if (active)
+                    select(active.value);
+            }
+            else if (event.key === "Escape" && open) {
+                event.preventDefault();
+                event.stopPropagation();
+                close();
+            }
+            else if (event.key === "Tab")
+                close();
+        },
+    };
+    const removable = selections.some(option => !option.disabled);
+    const actions = _jsxs("span", { className: "flood-combobox__actions", children: [clearable && _jsx(IconButton, { label: clearLabel, variant: "ghost", size: controlSize, className: !selected ? "flood-combobox__clear-empty" : undefined, disabled: disabled || readOnly || !selected || (multiple && !removable), "aria-hidden": !selected || undefined, tabIndex: -1, onPointerDown: event => event.preventDefault(), onClick: () => select(""), children: glyph(true) }), _jsx(IconButton, { label: toggleLabel, variant: "ghost", size: controlSize, disabled: disabled || readOnly, tabIndex: -1, "aria-expanded": open, "aria-controls": open ? menuId : undefined, onPointerDown: event => event.preventDefault(), onClick: () => { if (open)
+                    close();
+                else
+                    show(); input.current?.focus({ preventScroll: true }); }, children: glyph(false) })] });
+    return _jsxs("div", { className: multiple ? "flood-combobox flood-multi-select" : "flood-combobox", ref: root, hidden: props.hidden, dir: props.dir, lang: props.lang, children: [multiple ? _jsxs("div", { className: ["flood-input-group", "flood-multi-select__control", `flood-control--${controlSize}`, className].filter(Boolean).join(" "), style: props.style, "data-disabled": disabled || undefined, "data-readonly": readOnly || undefined, "data-status": resolveFieldStatus(props.status, props.invalid || Boolean(validation), props["aria-invalid"]), onClick: event => { if (event.target === event.currentTarget && !inert()) {
+                    input.current?.focus();
+                    show();
+                } }, children: [selections.map(option => _jsx(Tag, { size: controlSize === "sm" ? "sm" : controlSize === "md" ? "md" : "lg", disabled: disabled || option.disabled, onRemove: readOnly ? undefined : () => remove(option.value), removeLabel: `${removeItemLabel} ${option.label}`, removeButtonProps: { tabIndex: -1, onKeyDown: event => {
+                                if (event.defaultPrevented || event.altKey || event.ctrlKey || event.metaKey || event.nativeEvent.isComposing || inert())
+                                    return;
+                                const rtl = event.currentTarget.ownerDocument.defaultView?.getComputedStyle(event.currentTarget).direction === "rtl";
+                                const buttons = [...root.current.querySelectorAll(".flood-tag__remove:not(:disabled)")];
+                                const index = buttons.indexOf(event.currentTarget);
+                                if (event.key === "Backspace" || event.key === "Delete") {
+                                    event.preventDefault();
+                                    remove(option.value);
+                                }
+                                else if (event.key === "Escape") {
+                                    event.preventDefault();
+                                    event.stopPropagation();
+                                    close();
+                                    input.current?.focus();
+                                }
+                                else if (event.key === (rtl ? "ArrowLeft" : "ArrowRight")) {
+                                    event.preventDefault();
+                                    (buttons[index + 1] ?? input.current)?.focus();
+                                }
+                                else if (event.key === (rtl ? "ArrowRight" : "ArrowLeft")) {
+                                    event.preventDefault();
+                                    (buttons[Math.max(0, index - 1)])?.focus();
+                                }
+                            } }, children: option.label }, option.value)), _jsxs("div", { className: "flood-multi-select__editor", children: [_jsx(Input, { ...inputProps, ref: input, style: undefined }), actions] })] }) : _jsx(InputGroup, { ...inputProps, ref: input, className: ["flood-combobox__control", className].filter(Boolean).join(" "), end: actions }), (multiple ? selections : [selected]).map((option, index) => _jsx("input", { type: "hidden", name: name, value: option?.value ?? "", disabled: disabled, form: props.form }, option?.value ?? index)), multiple && Boolean(selections.length) && _jsx("span", { id: `${id}-selection`, className: "flood-visually-hidden", children: selections.map(option => option.label).join(", ") }), open && _jsx("div", { ref: panel, popover: "manual", className: "flood-select__menu flood-combobox__menu", onPointerDown: event => { if (event.pointerType === "mouse")
+                    event.preventDefault(); }, children: _jsxs(ScrollArea, { ref: viewport, id: menuId, role: "listbox", "aria-label": listLabel, "aria-multiselectable": multiple || undefined, orientation: "vertical", tabIndex: -1, className: "flood-select__viewport", children: [!filtered.length && _jsx("div", { className: "flood-select__empty", role: "option", "aria-disabled": "true", "aria-selected": "false", children: emptyMessage }), filtered.map(option => _jsxs("div", { id: optionId(option.value), role: "option", "aria-selected": selectedIds.includes(option.value), "aria-disabled": option.disabled || undefined, className: "flood-select__option", "data-active": option.value === active?.value || undefined, onPointerMove: event => { if (event.pointerType === "mouse" && !option.disabled)
+                                setActiveValue(option.value); }, onPointerDown: event => {
+                                // Touch must retain its compatibility click and native scrolling.
+                                if (event.pointerType === "mouse")
+                                    event.preventDefault();
+                            }, onMouseDown: event => event.preventDefault(), onClick: () => select(option.value), children: [_jsxs("span", { className: "flood-combobox__option-text", children: [_jsx("span", { children: option.label }), option.description && _jsx("span", { className: "flood-combobox__description", children: option.description })] }), _jsx("span", { className: "flood-select__selected", "aria-hidden": "true", children: selectedIds.includes(option.value) ? "✓" : "" })] }, option.value))] }) }), open && !filtered.length && _jsx("span", { className: "flood-visually-hidden", role: "status", children: emptyMessage }), validation && _jsx("span", { id: validationId, className: "flood-select__validation", role: "alert", children: validation })] });
+});

package/dist/content-elements.d.ts

@@ -0,0 +1,8 @@
+import type { AvatarGroupProps, StatusIndicatorProps, FigureProps, BlockquoteProps, InlineCodeProps, MetricProps, TimelineProps } from "./index.js";
+export declare const GroupedAvatars: import("react").ForwardRefExoticComponent<AvatarGroupProps & import("react").RefAttributes<HTMLUListElement>>;
+export declare const NamedStatus: import("react").ForwardRefExoticComponent<StatusIndicatorProps & import("react").RefAttributes<HTMLSpanElement>>;
+export declare const CaptionedFigure: import("react").ForwardRefExoticComponent<FigureProps & import("react").RefAttributes<HTMLElement>>;
+export declare const AttributedQuote: import("react").ForwardRefExoticComponent<BlockquoteProps & import("react").RefAttributes<HTMLQuoteElement>>;
+export declare const InlineCodeText: import("react").ForwardRefExoticComponent<InlineCodeProps & import("react").RefAttributes<HTMLElement>>;
+export declare const MeasuredValue: import("react").ForwardRefExoticComponent<MetricProps & import("react").RefAttributes<HTMLDListElement>>;
+export declare const EventTimeline: import("react").ForwardRefExoticComponent<TimelineProps & import("react").RefAttributes<HTMLOListElement>>;

package/dist/content-elements.js

@@ -0,0 +1,47 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef } from "react";
+import { Avatar, VisuallyHidden } from "./index.js";
+const cx = (...parts) => parts.filter(Boolean).join(" ");
+export const GroupedAvatars = forwardRef(function GroupedAvatars({ items, label, max = 4, size = "md", overflowLabel, className, ...props }, ref) {
+    if (!Number.isInteger(max) || max < 1)
+        throw new Error("Flood AvatarGroup max must be a positive integer");
+    if (!label.trim() || items.some(item => !item.id.trim() || !item.name.trim()) || new Set(items.map(item => item.id)).size !== items.length)
+        throw new Error("Flood AvatarGroup needs a label and unique nonempty item IDs/names");
+    const visible = items.slice(0, max), remaining = items.length - visible.length;
+    if (remaining > 0 && overflowLabel !== undefined && !overflowLabel.trim())
+        throw new Error("Flood AvatarGroup overflowLabel must be nonempty");
+    return _jsxs("ul", { ...props, ref: ref, "aria-label": label, className: cx("flood-avatar-group", className), "data-size": size, children: [visible.map(item => _jsx("li", { children: _jsx(Avatar, { name: item.name, src: item.src, fallback: item.fallback, size: size }) }, item.id)), remaining > 0 && _jsx("li", { children: _jsxs("span", { className: "flood-avatar flood-avatar-group__overflow", "data-size": size, role: "img", "aria-label": overflowLabel ?? `${remaining} more people`, children: ["+", remaining] }) })] });
+});
+export const NamedStatus = forwardRef(function NamedStatus({ label, tone = "neutral", size = "md", announce = false, className, role, ...props }, ref) {
+    if (!label.trim())
+        throw new Error("Flood StatusIndicator requires a visible label");
+    return _jsxs("span", { ...props, ref: ref, role: announce ? "status" : role, className: cx("flood-status-indicator", className), "data-tone": tone, "data-size": size, children: [_jsx("span", { className: "flood-status-indicator__dot", "aria-hidden": "true" }), label] });
+});
+export const CaptionedFigure = forwardRef(function CaptionedFigure({ caption, captionPosition = "after", children, className, ...props }, ref) {
+    const content = caption !== undefined && caption !== null && caption !== false ? _jsx("figcaption", { className: "flood-figure__caption", children: caption }) : null;
+    return _jsxs("figure", { ...props, ref: ref, className: cx("flood-figure", className), children: [captionPosition === "before" && content, children, captionPosition === "after" && content] });
+});
+export const AttributedQuote = forwardRef(function AttributedQuote({ attribution, children, className, ...props }, ref) {
+    return _jsxs("blockquote", { ...props, ref: ref, className: cx("flood-blockquote", className), children: [_jsx("div", { className: "flood-blockquote__quote", children: children }), attribution !== undefined && attribution !== null && attribution !== false && _jsx("footer", { className: "flood-blockquote__attribution", children: attribution })] });
+});
+export const InlineCodeText = forwardRef(function InlineCodeText({ size = "md", wrap = true, className, ...props }, ref) {
+    return _jsx("code", { ...props, ref: ref, className: cx("flood-inline-code", className), "data-size": size, "data-wrap": wrap });
+});
+export const MeasuredValue = forwardRef(function MeasuredValue({ label, value, hint, trend, size = "md", className, ...props }, ref) {
+    if (!label.trim() || (trend && !trend.label.trim()))
+        throw new Error("Flood Metric requires a label and meaningful trend text");
+    return _jsxs("dl", { ...props, ref: ref, className: cx("flood-metric", className), "data-size": size, children: [_jsx("dt", { className: "flood-metric__label", children: label }), _jsx("dd", { className: "flood-metric__value", children: value }), trend && _jsxs("dd", { className: "flood-metric__trend", "data-tone": trend.tone ?? "neutral", children: [_jsx("span", { "aria-hidden": "true", children: trend.direction === "up" ? "↑" : trend.direction === "down" ? "↓" : "→" }), trend.label] }), hint !== undefined && hint !== null && hint !== false && _jsx("dd", { className: "flood-metric__hint", children: hint })] });
+});
+export const EventTimeline = forwardRef(function EventTimeline({ items, label, stateLabels, className, ...props }, ref) {
+    if (!label.trim() || items.some(item => !item.id.trim() || !item.title.trim()) || new Set(items.map(item => item.id)).size !== items.length)
+        throw new Error("Flood Timeline needs a label and unique nonempty item IDs/titles");
+    if (items.filter(item => item.state === "current").length > 1)
+        throw new Error("Flood Timeline has at most one current event");
+    const labels = { complete: stateLabels?.complete ?? "Complete", current: stateLabels?.current ?? "Current", upcoming: stateLabels?.upcoming ?? "Upcoming" };
+    if (Object.values(labels).some(value => !value.trim()))
+        throw new Error("Flood Timeline state labels must be nonempty");
+    return _jsx("ol", { ...props, ref: ref, "aria-label": label, className: cx("flood-timeline", className), children: items.map(item => {
+            const state = item.state ?? "upcoming";
+            return _jsxs("li", { className: "flood-timeline__item", "data-state": state, "aria-current": state === "current" ? "step" : undefined, children: [_jsx("span", { className: "flood-timeline__marker", "aria-hidden": "true", children: item.icon ?? (state === "complete" ? _jsx("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", children: _jsx("path", { d: "m6 12 4 4 8-8" }) }) : state === "current" ? _jsx("span", {}) : null) }), _jsxs("div", { className: "flood-timeline__content", children: [_jsxs("div", { className: "flood-timeline__title", children: [_jsxs(VisuallyHidden, { children: [labels[state], ": "] }), item.title] }), item.description !== undefined && item.description !== null && _jsx("div", { className: "flood-timeline__description", children: item.description }), item.timeLabel && (item.dateTime ? _jsx("time", { className: "flood-timeline__time", dateTime: item.dateTime, children: item.timeLabel }) : _jsx("span", { className: "flood-timeline__time", children: item.timeLabel }))] })] }, item.id);
+        }) });
+});

package/dist/feedback-actions.d.ts

@@ -0,0 +1,3 @@
+import type { CopyButtonProps, ToastRegionProps } from "./index.js";
+export declare const ClipboardAction: import("react").ForwardRefExoticComponent<CopyButtonProps & import("react").RefAttributes<HTMLButtonElement>>;
+export declare const NotificationRegion: import("react").ForwardRefExoticComponent<ToastRegionProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/feedback-actions.js

@@ -0,0 +1,106 @@
+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) {
+    if (!Number.isFinite(resetDelay) || resetDelay < 0)
+        throw new Error("Flood CopyButton resetDelay must be finite and nonnegative");
+    const [phase, setPhase] = useState("idle");
+    const [pending, setPending] = useState(false);
+    const timer = useRef(undefined);
+    const alive = useRef(true);
+    useEffect(() => { alive.current = true; return () => { alive.current = false; clearTimeout(timer.current); }; }, []);
+    const label = phase === "copied" ? copiedLabel : phase === "error" ? errorLabel : copyLabel;
+    const copy = async (node) => {
+        if (pending || node.matches(":disabled"))
+            return;
+        clearTimeout(timer.current);
+        setPending(true);
+        const view = node.ownerDocument.defaultView;
+        try {
+            if (!view?.navigator.clipboard?.writeText)
+                throw new Error("Clipboard writing is unavailable in this context");
+            await view.navigator.clipboard.writeText(value);
+        }
+        catch (error) {
+            if (alive.current) {
+                setPending(false);
+                setPhase("error");
+            }
+            onCopyError?.(error);
+            return;
+        }
+        if (alive.current) {
+            setPending(false);
+            setPhase("copied");
+            clearTimeout(timer.current);
+            timer.current = setTimeout(() => { if (alive.current)
+                setPhase("idle"); }, resetDelay);
+        }
+        onCopied?.();
+    };
+    return _jsxs(_Fragment, { children: [_jsx(Button, { ...props, ref: ref, type: "button", size: size, variant: variant, disabled: disabled || pending, "aria-label": accessibleLabel ? (phase === "idle" ? accessibleLabel : `${label}: ${accessibleLabel}`) : label, className: ["flood-copy-button", className].filter(Boolean).join(" "), onClick: event => { void copy(event.currentTarget); }, children: _jsx("span", { className: "flood-copy-button__labels", "aria-hidden": "true", children: [copyLabel, copiedLabel, errorLabel].map((text, index) => _jsxs("span", { "data-visible": index === (phase === "copied" ? 1 : phase === "error" ? 2 : 0) || undefined, children: [_jsx(IconSlot, { size: size, children: pending ? _jsx(Spinner, { decorative: true }) : _jsx("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "1.75", strokeLinecap: "round", strokeLinejoin: "round", children: index === 1 ? _jsx("path", { d: "m5 12 4 4L19 6" }) : index === 2 ? _jsx("path", { d: "m6 6 12 12M18 6 6 18" }) : _jsxs(_Fragment, { children: [_jsx("rect", { x: "8", y: "8", width: "12", height: "12", rx: "2" }), _jsx("path", { d: "M15 8V5a2 2 0 0 0-2-2H5a2 2 0 0 0-2 2v8a2 2 0 0 0 2 2h3" })] }) }) }), _jsx("span", { children: text })] }, index)) }) }), _jsx(VisuallyHidden, { role: "status", children: phase === "idle" ? "" : label })] });
+});
+function TimedToast({ item, closeLabel, onDismiss }) {
+    const duration = item.duration ?? (item.action || item.status === "error" ? 0 : 5000);
+    if (!Number.isFinite(duration) || duration < 0)
+        throw new Error("Flood toast duration must be finite and nonnegative");
+    const [hover, setHover] = useState(false), [focus, setFocus] = useState(false), [hidden, setHidden] = useState(false);
+    const node = useRef(null), remaining = useRef(duration), callback = useRef(onDismiss), requested = useRef(false);
+    useEffect(() => { callback.current = onDismiss; }, [onDismiss]);
+    useEffect(() => { remaining.current = duration; requested.current = false; }, [duration]);
+    useEffect(() => {
+        const document = node.current?.ownerDocument;
+        if (!document)
+            return;
+        const update = () => setHidden(document.hidden);
+        update();
+        document.addEventListener("visibilitychange", update);
+        return () => document.removeEventListener("visibilitychange", update);
+    }, []);
+    useEffect(() => {
+        if (!duration || hover || focus || hidden || requested.current)
+            return;
+        const started = Date.now();
+        const timer = setTimeout(() => { if (requested.current)
+            return; requested.current = true; callback.current(item.id); }, remaining.current);
+        return () => { clearTimeout(timer); remaining.current = Math.max(0, remaining.current - (Date.now() - started)); };
+    }, [duration, hover, focus, hidden, item.id]);
+    const dismiss = () => {
+        requested.current = true;
+        const document = node.current?.ownerDocument;
+        if (node.current?.contains(document?.activeElement ?? null)) {
+            const region = node.current?.closest(".flood-toast-region");
+            const sibling = node.current?.nextElementSibling ?? node.current?.previousElementSibling;
+            (sibling?.querySelector("button:not(:disabled)") ?? region)?.focus({ preventScroll: true });
+        }
+        onDismiss(item.id);
+    };
+    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) {
+    if (!Number.isInteger(limit) || limit < 1)
+        throw new Error("Flood ToastRegion limit must be a positive integer");
+    const ids = new Set();
+    for (const item of items) {
+        if (!item.id.trim() || ids.has(item.id) || !item.title.trim())
+            throw new Error("Flood toasts require unique nonempty IDs and titles");
+        ids.add(item.id);
+    }
+    const node = useRef(null);
+    useImperativeHandle(forwardedRef, () => node.current, []);
+    useEffect(() => {
+        const element = node.current, document = element?.ownerDocument;
+        if (!hotkey || !element || !document)
+            return;
+        const key = (event) => {
+            if (event.defaultPrevented || event.key !== "F8" || event.altKey || event.ctrlKey || event.metaKey || !element.querySelector(".flood-toast") || element.hidden || Array.from(document.querySelectorAll(".flood-toast-region")).find(region => !region.hidden && region.getClientRects().length > 0 && region.querySelector(".flood-toast")) !== element)
+                return;
+            event.preventDefault();
+            (element.querySelector('button:not(:disabled)') ?? element).focus({ preventScroll: true });
+        };
+        document.addEventListener("keydown", key);
+        return () => document.removeEventListener("keydown", key);
+    }, [hotkey]);
+    return _jsx("div", { ...props, ref: node, role: "region", "aria-label": label, tabIndex: -1, className: ["flood-toast-region", className].filter(Boolean).join(" "), "data-placement": placement, "data-inline": inline || undefined, children: _jsx("ol", { className: "flood-toast-region__list", children: items.slice(0, limit).map(item => _jsx(TimedToast, { item: item, closeLabel: closeLabel, onDismiss: onDismiss }, item.id)) }) });
+});