@flood-md/react 0.2.10 → 0.2.11

package/dist/combobox.js

@@ -1,39 +1,68 @@
 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 { Input, InputGroup, IconButton, ScrollArea, Tag, Button } 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 = /* @__PURE__ */ 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) {
+export const SearchSelection = /* @__PURE__ */ forwardRef(function SearchSelection({ options, selectedOptions = [], query: controlledQuery, onQueryChange, filtering = "local", optionsQuery, loadState = "ready", loadingMessage = "Loading options…", errorMessage = "Could not load options.", onRetry, retryLabel = "Try again", freeText = false, textValue, initialText = "", onTextChange, onOptionSelect, 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()))
+    if (![emptyMessage, listLabel, toggleLabel, clearLabel, invalidSelectionMessage, loadingMessage, errorMessage, retryLabel].every(text => text.trim()))
         throw new Error("Flood Combobox messages and action labels must be nonempty");
+    if (new Set(selectedOptions.map(option => option.value)).size !== selectedOptions.length || selectedOptions.some(option => !option.value || !option.label.trim()))
+        throw new Error("Flood selectedOptions requires unique named records");
     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");
+    if (filtering === "manual" && ((freeText ? textValue : controlledQuery) === undefined || optionsQuery === undefined))
+        throw new Error("Flood manual search requires controlled text/query and optionsQuery");
     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 initial = useRef([...defaultValue]), initialFreeText = useRef(initialText);
+    const [local, setLocal] = useState(() => [...defaultValue]), [draftQuery, setDraftQuery] = useState(null);
+    const [localText, setLocalText] = useState(initialText);
+    const text = textValue ?? localText;
+    const query = freeText ? text : draftQuery === null ? null : controlledQuery ?? draftQuery;
+    const setQuery = (next) => { setDraftQuery(next); if (!freeText && next !== null)
+        onQueryChange?.(next); };
+    const publishText = (next) => { if (textValue === undefined)
+        setLocalText(next); if (next !== text)
+        onTextChange?.(next); };
     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 selections = (value ?? local).map(id => selectedOptions.find(option => option.value === 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 displayed = freeText ? text : query ?? (multiple ? "" : selected?.label ?? "");
+    const resultQuery = freeText ? text : controlledQuery ?? draftQuery ?? "";
+    const pending = loadState === "loading" || (filtering === "manual" && optionsQuery !== resultQuery);
+    const failed = loadState === "error" && !pending;
+    const resultMessage = pending ? loadingMessage : failed ? errorMessage : emptyMessage;
+    const filtered = pending || failed ? [] : filtering === "manual" || query === null ? options : options.filter(option => searchable([option.label, ...(option.keywords ?? [])].join(" ")).includes(searchable(query)));
     const enabled = filtered.filter(option => !option.disabled);
+    const groups = [];
+    for (const option of filtered) {
+        const previous = groups.at(-1);
+        if (previous && previous.label === option.group)
+            previous.options.push(option);
+        else
+            groups.push({ label: option.group, options: [option] });
+    }
     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 current = useRef({ value, textValue, selected, readOnly, disabled });
+    current.current = { value, textValue, selected, readOnly, disabled };
+    const close = () => {
+        if (panel.current?.contains(panel.current.ownerDocument.activeElement))
+            input.current?.focus({ preventScroll: true });
+        setOpen(false);
+        setQuery(null);
+    };
     const inert = () => Boolean(readOnly || disabled || input.current?.matches(":disabled"));
     const publish = (next) => {
         if (value === undefined)
@@ -43,14 +72,23 @@ export const SearchSelection = /* @__PURE__ */ forwardRef(function SearchSelecti
         setValidation("");
     };
     const remove = (id) => {
-        if (inert() || options.find(option => option.value === id)?.disabled)
+        if (inert() || selections.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)))
+        if (inert() || (next !== "" && !filtered.some(option => option.value === next && !option.disabled)))
             return;
+        if (freeText) {
+            const option = filtered.find(option => option.value === next);
+            publishText(option?.label ?? "");
+            if (option)
+                onOptionSelect?.(option);
+            close();
+            input.current?.focus({ preventScroll: true });
+            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) {
@@ -75,7 +113,7 @@ export const SearchSelection = /* @__PURE__ */ forwardRef(function SearchSelecti
     };
     useBrowserLayoutEffect(() => {
         const control = input.current;
-        control?.setCustomValidity(required && !selections.length ? invalidSelectionMessage : "");
+        control?.setCustomValidity(!freeText && required && !selections.length ? invalidSelectionMessage : "");
         if (validation && control?.validity.valid)
             setValidation("");
     });
@@ -92,6 +130,8 @@ export const SearchSelection = /* @__PURE__ */ forwardRef(function SearchSelecti
                     return;
                 if (current.current.value === undefined)
                     setLocal(initial.current);
+                if (current.current.textValue === undefined)
+                    setLocalText(initialFreeText.current);
                 setQuery(null);
                 setOpen(false);
                 setValidation("");
@@ -167,7 +207,7 @@ export const SearchSelection = /* @__PURE__ */ forwardRef(function SearchSelecti
             popup.style.visibility = "hidden";
             popup.showPopover();
             update();
-            unregister = registerLayer(document, { panel: popup, anchor: () => anchor, close: () => { setOpen(false); setQuery(null); } });
+            unregister = registerLayer(document, { panel: popup, anchor: () => anchor, close });
         };
         const toggle = (event) => { if (alive && event.newState === "closed" && !popup.matches(":popover-open")) {
             setOpen(false);
@@ -192,7 +232,8 @@ export const SearchSelection = /* @__PURE__ */ forwardRef(function SearchSelecti
     }, [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,
+        ...props, id, type: "text", value: displayed, placeholder: multiple && selections.length ? undefined : props.placeholder,
+        name: freeText ? name : undefined, 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`),
@@ -201,11 +242,14 @@ export const SearchSelection = /* @__PURE__ */ forwardRef(function SearchSelecti
             if (inert())
                 return;
             const text = event.currentTarget.value;
-            setQuery(text);
+            if (freeText)
+                publishText(text);
+            else
+                setQuery(text);
             setActiveValue(undefined);
             setOpen(true);
             setValidation("");
-            if (!multiple && text === "" && selected)
+            if (!freeText && !multiple && text === "" && selected)
                 publish([]);
         },
         onClick: event => { onClick?.(event); if (!event.defaultPrevented)
@@ -255,25 +299,28 @@ export const SearchSelection = /* @__PURE__ */ forwardRef(function SearchSelecti
                 }
             }
             else if (event.key === "Enter" && open) {
-                event.preventDefault();
+                if (!freeText || active)
+                    event.preventDefault();
                 if (active)
                     select(active.value);
+                else
+                    close();
             }
             else if (event.key === "Escape" && open) {
                 event.preventDefault();
                 event.stopPropagation();
                 close();
             }
-            else if (event.key === "Tab")
+            else if (event.key === "Tab" && !(failed && onRetry && !event.shiftKey))
                 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)
+    const actions = _jsxs("span", { className: "flood-combobox__actions", children: [clearable && _jsx(IconButton, { label: clearLabel, variant: "ghost", size: controlSize, className: !(freeText ? text : selected) ? "flood-combobox__clear-empty" : undefined, disabled: disabled || readOnly || !(freeText ? text : selected) || (multiple && !removable), "aria-hidden": !(freeText ? text : 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()) {
+    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"]), "data-has-selection": Boolean(selections.length) || undefined, "data-query": Boolean(displayed) || undefined, "data-clearable": clearable || undefined, 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 => {
@@ -300,11 +347,12 @@ export const SearchSelection = /* @__PURE__ */ forwardRef(function SearchSelecti
                                     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 })] });
+                            } }, 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 }), !freeText && (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 && _jsxs("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-busy": pending || undefined, "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: resultMessage }), groups.map((group, index) => _jsxs("div", { role: group.label ? "group" : "presentation", "aria-label": group.label, children: [group.label && _jsx("div", { className: "flood-select__group", "aria-hidden": "true", children: group.label }), group.options.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))] }, index))] }), failed && onRetry && _jsx(Button, { variant: "subtle", size: "sm", onClick: () => { input.current?.focus({ preventScroll: true }); onRetry(); }, onBlur: event => { if (!root.current?.contains(event.relatedTarget))
+                            close(); }, children: retryLabel })] }), open && !filtered.length && _jsx("span", { className: "flood-visually-hidden", role: "status", children: resultMessage }), validation && _jsx("span", { id: validationId, className: "flood-select__validation", role: "alert", children: validation })] });
 });

package/dist/command-list.d.ts

@@ -1,3 +1,7 @@
 import { type CommandListProps } from "./index.js";
+interface SearchCommandListProps extends CommandListProps {
+    integrated?: boolean;
+}
 /** Searchable action suggestions. No selected form value or modal lifecycle. */
-export declare const SearchCommandList: import("react").ForwardRefExoticComponent<CommandListProps & import("react").RefAttributes<HTMLInputElement>>;
+export declare const SearchCommandList: import("react").ForwardRefExoticComponent<SearchCommandListProps & import("react").RefAttributes<HTMLInputElement>>;
+export {};

package/dist/command-list.js

@@ -3,7 +3,7 @@ import { forwardRef, useEffect, useId, useImperativeHandle, useRef, useState } f
 import { Input, Label, ScrollArea, Surface, Text, VisuallyHidden } from "./index.js";
 const searchable = (value) => value.normalize("NFKD").replace(/\p{M}/gu, "").toLowerCase();
 /** Searchable action suggestions. No selected form value or modal lifecycle. */
-export const SearchCommandList = /* @__PURE__ */ forwardRef(function SearchCommandList({ label, hideLabel = false, items, query, defaultQuery = "", onQueryChange, onAction, disabled = false, loading = false, placeholder = "Search commands…", emptyMessage = "No commands found.", loadingMessage = "Loading commands…", controlSize = "md", id: explicitId, className, onKeyDown, ...props }, forwardedRef) {
+export const SearchCommandList = /* @__PURE__ */ forwardRef(function SearchCommandList({ label, hideLabel = false, items, query, defaultQuery = "", onQueryChange, onAction, disabled = false, loading = false, placeholder = "Search commands…", emptyMessage = "No commands found.", loadingMessage = "Loading commands…", controlSize = "md", integrated = false, id: explicitId, className, onKeyDown, ...props }, forwardedRef) {
     if (![label, emptyMessage, loadingMessage].every(value => value.trim()))
         throw new Error("Flood CommandList requires nonempty accessible labels and state messages");
     if (new Set(items.map(item => item.id)).size !== items.length || items.some(item => !item.id.trim() || !item.label.trim()))
@@ -84,7 +84,7 @@ export const SearchCommandList = /* @__PURE__ */ forwardRef(function SearchComma
             setActiveId(enabled[next].id);
         }, children: [_jsx(Label, { htmlFor: inputId, className: hideLabel ? "flood-visually-hidden" : undefined, children: label }), _jsx(Input, { ref: input, id: inputId, value: text, disabled: disabled, type: "text", controlSize: controlSize, placeholder: placeholder, autoComplete: "off", spellCheck: false, role: "combobox", "aria-autocomplete": "list", "aria-haspopup": "listbox", "aria-expanded": "true", "aria-controls": listId, "aria-activedescendant": active ? optionId(active) : undefined, onCompositionStart: () => { composing.current = true; }, onCompositionEnd: () => { composing.current = false; }, onChange: event => { const next = event.currentTarget.value; if (disabled || event.currentTarget.matches(":disabled"))
                     return; if (query === undefined)
-                    setLocalQuery(next); onQueryChange?.(next); } }), _jsx(Surface, { padding: "1", className: "flood-command-list__surface", children: _jsx(ScrollArea, { ref: viewport, id: listId, role: "listbox", "aria-label": label, "aria-busy": loading || undefined, "aria-disabled": effectiveDisabled || undefined, tabIndex: -1, className: "flood-command-list__viewport", style: { maxHeight: "18rem" }, children: status ? _jsx("div", { role: "option", "aria-disabled": "true", "aria-selected": "false", className: "flood-command-list__empty", children: _jsx(Text, { size: "compact", tone: "subtle", children: status }) }) : [...groups].map(([group, entries], groupIndex) => {
+                    setLocalQuery(next); onQueryChange?.(next); } }), _jsx(Surface, { elevation: integrated ? "overlay" : "default", padding: integrated ? "2" : "1", style: integrated ? { background: "transparent" } : undefined, className: "flood-command-list__surface", children: _jsx(ScrollArea, { ref: viewport, id: listId, role: "listbox", "aria-label": label, "aria-busy": loading || undefined, "aria-disabled": effectiveDisabled || undefined, tabIndex: -1, className: "flood-command-list__viewport", children: status ? _jsx("div", { role: "option", "aria-disabled": "true", "aria-selected": "false", className: "flood-command-list__empty", children: _jsx(Text, { size: "compact", tone: "subtle", children: status }) }) : [...groups].map(([group, entries], groupIndex) => {
                         const content = entries.map(item => _jsxs("div", { id: optionId(item), role: "option", "aria-disabled": item.disabled || effectiveDisabled || undefined, "aria-selected": item.id === active?.id, "data-active": item.id === active?.id || undefined, className: "flood-command-list__option", onPointerMove: event => { if (event.pointerType === "mouse" && !blocked() && !item.disabled)
                                 setActiveId(item.id); }, onPointerDown: event => { if (event.pointerType === "mouse")
                                 event.preventDefault(); }, onMouseDown: event => event.preventDefault(), onClick: () => invoke(item), children: [_jsx("span", { className: "flood-command-list__label", children: item.label }), item.description && _jsx("span", { className: "flood-command-list__description", children: item.description })] }, item.id));

package/dist/data-display.js

@@ -2,7 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { forwardRef } from "react";
 import { ScrollArea } from "./index.js";
 export const DescribedData = /* @__PURE__ */ forwardRef(function DescribedData({ items, layout, density, dividers, className, ...props }, ref) {
-    if (items.some(item => !item.id.trim()) || new Set(items.map(item => item.id)).size !== items.length)
+    if (items.some(item => typeof item.id !== "string" || !item.id.trim()) || new Set(items.map(item => item.id)).size !== items.length)
         throw new Error("Flood description items require unique nonempty IDs");
     return _jsx("dl", { ...props, ref: ref, className: ["flood-description-list", className].filter(Boolean).join(" "), "data-layout": layout, "data-density": density, "data-dividers": dividers, children: items.map(item => _jsxs("div", { className: "flood-description-list__item", children: [_jsx("dt", { children: item.term }), _jsx("dd", { children: item.description })] }, item.id)) });
 });

package/dist/data-table.js

@@ -1,24 +1,54 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { forwardRef, useMemo, useState } from "react";
 import { Table, Checkbox, Button, IconSlot, VisuallyHidden, Pagination, Text, Spinner, Alert, Stack } from "./index.js";
-export const ManagedDataTable = /* @__PURE__ */ forwardRef(function ManagedDataTable({ caption, hideCaption = false, columns, rows, density = "comfortable", striped = false, minWidth = "40rem", sort: controlledSort, defaultSort = null, onSortChange, locale = "en", selectable = false, selectedIds, defaultSelectedIds = [], onSelectionChange, page: controlledPage, defaultPage = 1, pageSize = 10, onPageChange, state = "ready", onRetry, labels = {}, className, ...props }, ref) {
+function activatePrimaryRowAction(event) {
+    const target = event.target;
+    const row = event.currentTarget;
+    if (!(target instanceof Element) || target.closest("tr") !== row || event.defaultPrevented ||
+        event.altKey || event.ctrlKey || event.metaKey || event.shiftKey)
+        return;
+    const control = target.closest('button,a,input,label,select,textarea,summary,[role],[tabindex],[contenteditable]:not([contenteditable="false"])');
+    if (control && row.contains(control))
+        return;
+    const selection = row.ownerDocument.getSelection();
+    if (selection && !selection.isCollapsed && selection.containsNode(row, true))
+        return;
+    const button = row.querySelector(":scope > td > .flood-stack > .flood-data-table__primary-action");
+    if (!button || button.disabled || button.getAttribute("aria-disabled") === "true")
+        return;
+    button.focus({ preventScroll: true });
+    button.click();
+}
+export const ManagedDataTable = /* @__PURE__ */ forwardRef(function ManagedDataTable({ caption, hideCaption = false, columns, rows, density = "comfortable", striped = false, minWidth = "40rem", toolbar, inset = "standard", sort: controlledSort, defaultSort = null, onSortChange, locale = "en", selectable = false, selectedIds, defaultSelectedIds = [], onSelectionChange, page: controlledPage, defaultPage = 1, pageSize = 10, onPageChange, showResults = true, paginationMode = "client", totalRows, selectionScope, state = "ready", onRetry, emptyContent, labels = {}, className, ...props }, ref) {
     if (!caption.trim() || columns.length === 0 || columns.some(column => !column.id.trim() || !column.label.trim()) || new Set(columns.map(column => column.id)).size !== columns.length)
         throw new Error("Flood DataTable requires a caption and unique named columns");
     if (rows.some(row => !row.id.trim() || (row.label !== undefined && !row.label.trim())) || new Set(rows.map(row => row.id)).size !== rows.length)
         throw new Error("Flood DataTable rows require unique nonempty IDs and labels");
+    if (rows.some(({ primaryAction }) => primaryAction && (typeof primaryAction.title !== "string" || !primaryAction.title.trim() ||
+        !columns.some(column => column.id === primaryAction.column))))
+        throw new Error("Flood DataTable primary actions require a nonempty title and an existing column");
     if (!Number.isSafeInteger(pageSize) || pageSize < 1 || !Number.isSafeInteger(defaultPage) || defaultPage < 1 || (controlledPage !== undefined && (!Number.isSafeInteger(controlledPage) || controlledPage < 1)))
         throw new Error("Flood DataTable page and pageSize must be positive safe integers");
+    const server = paginationMode === "server", scope = selectionScope ?? (server ? "page" : "dataset");
+    if (server && (controlledPage === undefined || !onPageChange || !Number.isSafeInteger(totalRows) || (totalRows ?? -1) < 0))
+        throw new Error("Flood server DataTable requires page, onPageChange and a nonnegative totalRows");
+    if (server && columns.some(column => column.sortable) && (controlledSort === undefined || !onSortChange))
+        throw new Error("Flood server sorting requires sort (or null) and onSortChange");
+    if (server && selectable && scope === "dataset" && (selectedIds === undefined || !onSelectionChange))
+        throw new Error("Flood server dataset selection must be controlled");
     const [localSort, setSort] = useState(defaultSort), [localSelected, setSelected] = useState(defaultSelectedIds), [localPage, setPage] = useState(defaultPage);
     const requestedSort = controlledSort === undefined ? localSort : controlledSort;
     const sorting = requestedSort && columns.some(column => column.id === requestedSort.column && column.sortable) ? requestedSort : null;
     const sorted = useMemo(() => {
-        if (!sorting)
+        if (server || !sorting)
             return [...rows];
         const collator = new Intl.Collator(locale, { numeric: true, sensitivity: "base" });
         const value = (row) => {
             const explicit = row.sortValues?.[sorting.column];
             if (explicit !== undefined)
                 return explicit;
+            if (row.primaryAction?.column === sorting.column)
+                return row.primaryAction.title;
             const cell = row.cells[sorting.column];
             return typeof cell === "string" || typeof cell === "number" ? cell : null;
         };
@@ -30,14 +60,17 @@ export const ManagedDataTable = /* @__PURE__ */ forwardRef(function ManagedDataT
             const comparison = typeof left === "number" && typeof right === "number" ? left - right : collator.compare(String(left), String(right));
             return comparison === 0 ? a.index - b.index : comparison * (sorting.direction === "ascending" ? 1 : -1);
         }).map(entry => entry.row);
-    }, [rows, sorting?.column, sorting?.direction, locale]);
-    const pageCount = Math.max(1, Math.ceil(rows.length / pageSize)), page = Math.min(controlledPage ?? localPage, pageCount);
-    const visible = sorted.slice((page - 1) * pageSize, page * pageSize), eligible = new Set(rows.filter(row => !row.selectionDisabled).map(row => row.id));
-    const selection = [...new Set(selectedIds ?? localSelected)].filter(id => eligible.has(id)), chosen = new Set(selection);
+    }, [rows, sorting?.column, sorting?.direction, locale, server]);
+    const total = server ? totalRows : rows.length, pageCount = Math.max(1, Math.ceil(total / pageSize)), page = server ? controlledPage : Math.min(controlledPage ?? localPage, pageCount);
+    if (server && state === "ready" && (page > pageCount || rows.length > pageSize || (page - 1) * pageSize + rows.length > total))
+        throw new Error("Flood server rows and page must match totalRows/pageSize; reconcile the page after a query change");
+    const visible = server ? sorted : sorted.slice((page - 1) * pageSize, page * pageSize), eligible = new Set((scope === "page" ? visible : rows).filter(row => !row.selectionDisabled).map(row => row.id));
+    const accepts = (id) => server && scope === "dataset" ? !rows.some(row => row.id === id && row.selectionDisabled) : eligible.has(id);
+    const selection = [...new Set(selectedIds ?? localSelected)].filter(accepts), chosen = new Set(selection);
     const pageChoices = visible.filter(row => !row.selectionDisabled), all = pageChoices.length > 0 && pageChoices.every(row => chosen.has(row.id)), some = pageChoices.some(row => chosen.has(row.id));
     const blocked = state !== "ready";
     const select = (next) => { if (blocked)
-        return; const accepted = [...new Set(next)].filter(id => eligible.has(id)); if (selectedIds === undefined)
+        return; const accepted = [...new Set(next)].filter(accepts); if (selectedIds === undefined)
         setSelected(accepted); onSelectionChange?.(accepted); };
     const changePage = (next) => { if (blocked)
         return; if (controlledPage === undefined)
@@ -53,6 +86,8 @@ export const ManagedDataTable = /* @__PURE__ */ forwardRef(function ManagedDataT
             changePage(1);
     };
     const resultLabel = labels.results ?? ((from, to, total) => `${from}–${to} of ${total}`);
-    return _jsxs("div", { ...props, ref: ref, className: ["flood-data-table", className].filter(Boolean).join(" "), "aria-busy": state === "loading" || undefined, children: [_jsxs(Table, { caption: caption, hideCaption: hideCaption, density: density, striped: striped, style: { minWidth }, children: [_jsx("thead", { children: _jsxs("tr", { children: [selectable && _jsx("th", { scope: "col", className: "flood-data-table__choice", children: _jsx(Checkbox, { label: _jsx(VisuallyHidden, { children: labels.selectPage ?? "Select rows on this page" }), checked: all, indeterminate: some && !all, disabled: blocked || pageChoices.length === 0, onChange: event => { const ids = new Set(selection); for (const row of pageChoices)
-                                            event.currentTarget.checked ? ids.add(row.id) : ids.delete(row.id); select([...ids]); } }) }), columns.map(column => _jsx("th", { scope: "col", "data-sortable": column.sortable || undefined, "aria-sort": sorting?.column === column.id ? sorting.direction : undefined, style: { textAlign: column.align ?? "start", width: column.width }, children: column.sortable ? _jsxs(Button, { variant: "ghost", size: "sm", disabled: blocked, className: "flood-data-table__sort", "aria-label": (labels.sort ?? ((label) => `Sort by ${label}`))(column.label), onClick: () => changeSort(column.id), children: [column.label, _jsx(IconSlot, { size: "sm", children: _jsx("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "1.75", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: sorting?.column === column.id ? _jsx("path", { d: sorting.direction === "ascending" ? "m7 14 5-5 5 5" : "m7 10 5 5 5-5" }) : _jsx("path", { d: "m8 8 4-4 4 4M8 16l4 4 4-4" }) }) })] }) : column.label }, column.id))] }) }), _jsx("tbody", { children: state === "ready" && visible.length > 0 ? visible.map(row => _jsxs("tr", { "data-selected": selectable && chosen.has(row.id) || undefined, children: [selectable && _jsx("td", { className: "flood-data-table__choice", children: _jsx(Checkbox, { label: _jsx(VisuallyHidden, { children: (labels.selectRow ?? ((label) => `Select ${label}`))(row.label ?? row.id) }), checked: chosen.has(row.id), disabled: Boolean(row.selectionDisabled), onChange: event => select(event.currentTarget.checked ? [...selection, row.id] : selection.filter(id => id !== row.id)) }) }), columns.map(column => _jsx("td", { style: { textAlign: column.align ?? "start" }, children: row.cells[column.id] ?? null }, column.id))] }, row.id)) : _jsx("tr", { children: _jsx("td", { colSpan: columns.length + (selectable ? 1 : 0), className: "flood-data-table__state", children: state === "loading" ? _jsx(Spinner, { label: labels.loading ?? "Loading rows…" }) : state === "error" ? _jsxs(Stack, { gap: "3", children: [_jsx(Alert, { tone: "error", announcement: "polite", children: labels.error ?? "Could not load the rows." }), onRetry && _jsx(Button, { variant: "subtle", size: "sm", onClick: onRetry, children: labels.retry ?? "Try again" })] }) : _jsx(Text, { as: "p", size: "compact", tone: "subtle", role: "status", children: labels.empty ?? "No results found." }) }) }) })] }), _jsxs("div", { className: "flood-data-table__footer", children: [_jsx(Text, { as: "p", size: "helper", tone: "subtle", children: state === "ready" ? resultLabel(rows.length ? (page - 1) * pageSize + 1 : 0, Math.min(page * pageSize, rows.length), rows.length) : "" }), selectable && _jsx(Text, { as: "p", size: "helper", tone: "subtle", role: "status", children: (labels.selection ?? ((count, total) => `${count} of ${total} selected`))(selection.length, eligible.size) }), pageCount > 1 && _jsx(Pagination, { page: page, pageCount: pageCount, onPageChange: changePage, disabled: blocked, label: labels.pagination, previousLabel: labels.previousPage, nextLabel: labels.nextPage, pageLabel: labels.page })] })] });
+    return _jsxs("div", { ...props, ref: ref, className: ["flood-data-table", className].filter(Boolean).join(" "), "data-inset": inset, "aria-busy": state === "loading" || undefined, children: [toolbar != null && _jsx("div", { className: "flood-data-table__toolbar", children: toolbar }), _jsxs(Table, { caption: caption, hideCaption: hideCaption, density: density, striped: striped, style: { minWidth }, children: [_jsx("thead", { children: _jsxs("tr", { children: [selectable && _jsx("th", { scope: "col", className: "flood-data-table__choice", children: _jsx(Checkbox, { label: _jsx(VisuallyHidden, { children: labels.selectPage ?? "Select rows on this page" }), checked: all, indeterminate: some && !all, disabled: blocked || pageChoices.length === 0, onChange: event => { const ids = new Set(selection); for (const row of pageChoices)
+                                            event.currentTarget.checked ? ids.add(row.id) : ids.delete(row.id); select([...ids]); } }) }), columns.map(column => _jsx("th", { scope: "col", "data-numeric": column.numeric || undefined, "data-align": column.align, "data-sortable": column.sortable || undefined, "aria-sort": sorting?.column === column.id ? sorting.direction : undefined, style: { width: column.width }, children: column.sortable ? _jsxs(Button, { variant: "ghost", size: "sm", disabled: blocked, className: "flood-data-table__sort", "aria-label": (labels.sort ?? ((label) => `Sort by ${label}`))(column.label), onClick: () => changeSort(column.id), children: [column.label, _jsx(IconSlot, { size: "sm", children: _jsx("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "1.75", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: sorting?.column === column.id ? _jsx("path", { d: "m7 14 5-5 5 5" }) : _jsx("path", { d: "m8 8 4-4 4 4M8 16l4 4 4-4" }) }) })] }) : column.label }, column.id))] }) }), _jsx("tbody", { children: state === "ready" && visible.length > 0 ? visible.map(row => _jsxs("tr", { "data-selected": selectable && chosen.has(row.id) || undefined, "data-primary-action": row.primaryAction && !row.primaryAction.buttonProps.disabled && row.primaryAction.buttonProps["aria-disabled"] !== "true" || undefined, onClick: row.primaryAction ? activatePrimaryRowAction : undefined, children: [selectable && _jsx("td", { className: "flood-data-table__choice", children: _jsx(Checkbox, { label: _jsx(VisuallyHidden, { children: (labels.selectRow ?? ((label) => `Select ${label}`))(row.label ?? row.id) }), checked: chosen.has(row.id), disabled: Boolean(row.selectionDisabled), onChange: event => select(event.currentTarget.checked ? [...selection, row.id] : selection.filter(id => id !== row.id)) }) }), columns.map(column => _jsx("td", { "data-numeric": column.numeric || undefined, "data-align": column.align, children: row.primaryAction?.column === column.id
+                                        ? _jsxs(Stack, { gap: "1", children: [_jsx(Button, { ...row.primaryAction.buttonProps, type: "button", variant: "ghost", size: "sm", className: ["flood-data-table__primary-action", row.primaryAction.buttonProps.className].filter(Boolean).join(" "), children: row.primaryAction.title }), row.primaryAction.description != null && _jsx(Text, { as: "div", size: "helper", tone: "subtle", children: row.primaryAction.description })] })
+                                        : row.cells[column.id] ?? null }, column.id))] }, row.id)) : _jsx("tr", { children: _jsx("td", { colSpan: columns.length + (selectable ? 1 : 0), className: "flood-data-table__state", children: state === "loading" ? _jsx(Spinner, { label: labels.loading ?? "Loading rows…" }) : state === "error" ? _jsxs(Stack, { gap: "3", children: [_jsx(Alert, { tone: "error", announcement: "polite", children: labels.error ?? "Could not load the rows." }), onRetry && _jsx(Button, { variant: "subtle", size: "sm", onClick: onRetry, children: labels.retry ?? "Try again" })] }) : emptyContent ?? _jsx(Text, { as: "p", size: "compact", tone: "subtle", role: "status", children: labels.empty ?? "No results found." }) }) }) })] }), (showResults || selectable || pageCount > 1) && _jsxs("div", { className: "flood-data-table__footer", children: [showResults && _jsx(Text, { as: "p", size: "helper", tone: "subtle", children: state === "ready" ? resultLabel(visible.length ? (page - 1) * pageSize + 1 : 0, visible.length ? (page - 1) * pageSize + visible.length : 0, total) : "" }), selectable && _jsx(Text, { as: "p", size: "helper", tone: "subtle", role: "status", children: (labels.selection ?? ((count, total) => `${count} of ${total} selected`))(selection.length, server && scope === "dataset" ? total : eligible.size) }), pageCount > 1 && _jsx(Pagination, { page: Math.min(page, pageCount), pageCount: pageCount, onPageChange: changePage, disabled: blocked, label: labels.pagination, previousLabel: labels.previousPage, nextLabel: labels.nextPage, pageLabel: labels.page })] })] });
 });

package/dist/date-picker.js

@@ -4,7 +4,7 @@ import { Calendar, DateField, IconButton, Popover } from "./index.js";
 const useBrowserLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
 const triggerSizes = { sm: "xs", md: "sm", lg: "md", xl: "lg" };
 /** Calendar selection and keyboard date entry share one DateField value/form bridge. */
-export const CalendarDatePicker = /* @__PURE__ */ forwardRef(function CalendarDatePicker({ value, defaultValue = "", onValueChange, open: controlledOpen, defaultOpen = false, onOpenChange, calendarLabel, openCalendarLabel, locale, weekStartsOn, today, previousMonthLabel, nextMonthLabel, label, disabled = false, readOnly = false, controlSize = "md", min, max, form, className, onKeyDown, ...props }, forwardedRef) {
+export const CalendarDatePicker = /* @__PURE__ */ forwardRef(function CalendarDatePicker({ value, defaultValue = "", onValueChange, open: controlledOpen, defaultOpen = false, onOpenChange, calendarLabel, openCalendarLabel, viewLabels, locale, weekStartsOn, today, previousMonthLabel, nextMonthLabel, label, disabled = false, readOnly = false, controlSize = "md", min, max, form, className, onKeyDown, ...props }, forwardedRef) {
     const panelLabel = calendarLabel ?? `${label} calendar`;
     const triggerLabel = openCalendarLabel ?? `Open calendar: ${label}`;
     if (!panelLabel.trim() || !triggerLabel.trim())
@@ -100,7 +100,7 @@ export const CalendarDatePicker = /* @__PURE__ */ forwardRef(function CalendarDa
                 event.preventDefault();
                 requestOpen(true);
             }
-        }, end: _jsx(Popover, { title: panelLabel, className: "flood-date-picker__panel", align: "end", positionReference: positionReference, style: { "--flood-date-picker-width": fieldWidth === undefined ? undefined : `${fieldWidth}px` }, open: !blocked && requestedOpen, onOpenChange: requestOpen, disabled: blocked, trigger: trigger => _jsx(IconButton, { ...trigger, label: triggerLabel, variant: "ghost", size: triggerSizes[controlSize], children: _jsxs("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "1.75", strokeLinecap: "round", strokeLinejoin: "round", children: [_jsx("rect", { x: "3", y: "5", width: "18", height: "16", rx: "2" }), _jsx("path", { d: "M16 3v4M8 3v4M3 11h18" })] }) }), children: _jsx(Calendar, { label: panelLabel, value: committed, min: min, max: max, locale: locale, weekStartsOn: weekStartsOn, today: today, previousMonthLabel: previousMonthLabel, nextMonthLabel: nextMonthLabel, autoFocus: true, onValueChange: changeDate, onDateSelect: () => {
+        }, end: _jsx(Popover, { title: panelLabel, chrome: "minimal", className: "flood-date-picker__panel", align: "end", positionReference: positionReference, style: { "--flood-date-picker-width": fieldWidth === undefined ? undefined : `${fieldWidth}px` }, open: !blocked && requestedOpen, onOpenChange: requestOpen, disabled: blocked, trigger: trigger => _jsx(IconButton, { ...trigger, label: triggerLabel, variant: "ghost", size: triggerSizes[controlSize], children: _jsxs("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "1.75", strokeLinecap: "round", strokeLinejoin: "round", children: [_jsx("rect", { x: "3", y: "5", width: "18", height: "16", rx: "2" }), _jsx("path", { d: "M16 3v4M8 3v4M3 11h18" })] }) }), children: _jsx(Calendar, { label: panelLabel, viewLabels: viewLabels, value: committed, min: min, max: max, locale: locale, weekStartsOn: weekStartsOn, today: today, previousMonthLabel: previousMonthLabel, nextMonthLabel: nextMonthLabel, autoFocus: true, onValueChange: changeDate, onDateSelect: () => {
                     if (blocked || nativeDisabled())
                         return;
                     requestOpen(false);

package/dist/date-range-picker.js

@@ -4,7 +4,7 @@ import { DateRangeField, IconButton, Popover, RangeCalendar } from "./index.js";
 import { emptyDateRange } from "./date-range-value.js";
 const useBrowserLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
 const triggerSizes = { sm: "xs", md: "sm", lg: "md", xl: "lg" };
-export const CalendarDateRangePicker = /* @__PURE__ */ forwardRef(function CalendarDateRangePicker({ value, defaultValue = emptyDateRange(), onValueChange, open: controlledOpen, defaultOpen = false, onOpenChange, label, calendarLabel, openCalendarLabel, locale, weekStartsOn, today, previousMonthLabel, nextMonthLabel, rangeLabels, disabled = false, readOnly = false, controlSize = "md", min, max, isDateDisabled, isRangeDisabled, form, className, onKeyDown, ...props }, forwardedRef) {
+export const CalendarDateRangePicker = /* @__PURE__ */ forwardRef(function CalendarDateRangePicker({ value, defaultValue = emptyDateRange(), onValueChange, open: controlledOpen, defaultOpen = false, onOpenChange, label, calendarLabel, openCalendarLabel, viewLabels, locale, weekStartsOn, today, previousMonthLabel, nextMonthLabel, rangeLabels, disabled = false, readOnly = false, controlSize = "md", min, max, isDateDisabled, isRangeDisabled, form, className, onKeyDown, ...props }, forwardedRef) {
     const panelLabel = calendarLabel ?? `${label} calendar`, triggerLabel = openCalendarLabel ?? `Open calendar: ${label}`;
     if (!panelLabel.trim() || !triggerLabel.trim())
         throw new Error("Flood DateRangePicker requires nonempty calendar and trigger labels");
@@ -76,6 +76,6 @@ export const CalendarDateRangePicker = /* @__PURE__ */ forwardRef(function Calen
                 event.preventDefault();
                 requestOpen(true);
             }
-        }, end: _jsx(Popover, { title: panelLabel, className: "flood-date-range-picker__panel", align: "end", positionReference: positionReference, style: { "--flood-date-range-picker-width": fieldWidth ? `${fieldWidth}px` : undefined }, open: !blocked && requestedOpen, onOpenChange: requestOpen, disabled: blocked, trigger: trigger => _jsx(IconButton, { ...trigger, label: triggerLabel, variant: "ghost", size: triggerSizes[controlSize], children: _jsxs("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "1.75", strokeLinecap: "round", strokeLinejoin: "round", children: [_jsx("rect", { x: "3", y: "5", width: "18", height: "16", rx: "2" }), _jsx("path", { d: "M16 3v4M8 3v4M3 11h18" })] }) }), children: _jsx(RangeCalendar, { label: panelLabel, value: committed, min: min, max: max, isDateDisabled: isDateDisabled, isRangeDisabled: isRangeDisabled, locale: locale, weekStartsOn: weekStartsOn, today: today, previousMonthLabel: previousMonthLabel, nextMonthLabel: nextMonthLabel, rangeLabels: rangeLabels, autoFocus: true, onValueChange: change, onRangeSelect: () => { if (!blocked && !nativeDisabled())
+        }, end: _jsx(Popover, { title: panelLabel, chrome: "minimal", className: "flood-date-range-picker__panel", align: "end", positionReference: positionReference, style: { "--flood-date-range-picker-width": fieldWidth ? `${fieldWidth}px` : undefined }, open: !blocked && requestedOpen, onOpenChange: requestOpen, disabled: blocked, trigger: trigger => _jsx(IconButton, { ...trigger, label: triggerLabel, variant: "ghost", size: triggerSizes[controlSize], children: _jsxs("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "1.75", strokeLinecap: "round", strokeLinejoin: "round", children: [_jsx("rect", { x: "3", y: "5", width: "18", height: "16", rx: "2" }), _jsx("path", { d: "M16 3v4M8 3v4M3 11h18" })] }) }), children: _jsx(RangeCalendar, { label: panelLabel, viewLabels: viewLabels, value: committed, min: min, max: max, isDateDisabled: isDateDisabled, isRangeDisabled: isRangeDisabled, locale: locale, weekStartsOn: weekStartsOn, today: today, previousMonthLabel: previousMonthLabel, nextMonthLabel: nextMonthLabel, rangeLabels: rangeLabels, autoFocus: true, onValueChange: change, onRangeSelect: () => { if (!blocked && !nativeDisabled())
                     requestOpen(false); } }) }) });
 });

package/dist/date-time-picker.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 { DatePicker, TimePicker, Fieldset } from "./index.js";
 /** A civil date and wall-clock time. The host owns timezone conversion. */
-export const CivilDateTimePicker = /* @__PURE__ */ forwardRef(function CivilDateTimePicker({ label, validationMessage, timeInterval, hideLabel = false, hideFieldLabels = false, value, defaultValue = { date: "", time: "" }, onValueChange, dateLabel = "Date", timeLabel = "Time", dateName, timeName, form, required = false, disabled = false, readOnly = false, controlSize = "md", precision = "minute", order = "month-day-year", locale = "en-US", minDate, maxDate, minTime, maxTime, step, status, description, className, ...props }, ref) {
+export const CivilDateTimePicker = /* @__PURE__ */ forwardRef(function CivilDateTimePicker({ label, validationMessage, timeInterval, hideLabel = false, hideFieldLabels = false, value, defaultValue = { date: "", time: "" }, onValueChange, dateLabel = "Date", timeLabel = "Time", datePickerLabels, timePickerLabels, dateName, timeName, form, required = false, disabled = false, readOnly = false, controlSize = "md", precision = "minute", order = "month-day-year", locale = "en-US", minDate, maxDate, minTime, maxTime, step, status, description, className, ...props }, ref) {
     const [local, setLocal] = useState(defaultValue);
     const root = useRef(null), initial = useRef(defaultValue);
     useImperativeHandle(ref, () => root.current, []);
@@ -27,5 +27,5 @@ export const CivilDateTimePicker = /* @__PURE__ */ forwardRef(function CivilDate
     };
     // Each field owns native validity, reset and submission. Values are deliberately
     // separate: neither a timezone nor an instant is inferred from this pair.
-    return _jsx("div", { ...props, ref: root, className: ["flood-date-time-picker", className].filter(Boolean).join(" "), children: _jsx(Fieldset, { legend: label, hideLabel: hideLabel, hint: description, disabled: disabled, children: _jsxs("div", { className: "flood-date-time-picker__fields", children: [_jsx(DatePicker, { label: dateLabel, hideLabel: hideFieldLabels, value: value === undefined ? undefined : selected.date, defaultValue: defaultValue.date, onValueChange: next => change("date", next), name: dateName, form: form, required: required, disabled: disabled, readOnly: readOnly, controlSize: controlSize, order: order, locale: locale, min: minDate, max: maxDate, status: status, validationMessage: validationMessage }), _jsx(TimePicker, { label: timeLabel, hideLabel: hideFieldLabels, value: value === undefined ? undefined : selected.time, defaultValue: defaultValue.time, onValueChange: next => change("time", next), name: timeName, form: form, required: required, disabled: disabled, readOnly: readOnly, controlSize: controlSize, precision: precision, min: minTime, max: maxTime, step: step, interval: timeInterval, status: status })] }) }) });
+    return _jsx("div", { ...props, ref: root, className: ["flood-date-time-picker", className].filter(Boolean).join(" "), children: _jsx(Fieldset, { legend: label, hideLabel: hideLabel, hint: description, disabled: disabled, children: _jsxs("div", { className: "flood-date-time-picker__fields", children: [_jsx(DatePicker, { ...datePickerLabels, label: dateLabel, hideLabel: hideFieldLabels, value: value === undefined ? undefined : selected.date, defaultValue: defaultValue.date, onValueChange: next => change("date", next), name: dateName, form: form, required: required, disabled: disabled, readOnly: readOnly, controlSize: controlSize, order: order, locale: locale, min: minDate, max: maxDate, status: status, validationMessage: validationMessage }), _jsx(TimePicker, { ...timePickerLabels, label: timeLabel, hideLabel: hideFieldLabels, value: value === undefined ? undefined : selected.time, defaultValue: defaultValue.time, onValueChange: next => change("time", next), name: timeName, form: form, required: required, disabled: disabled, readOnly: readOnly, controlSize: controlSize, precision: precision, min: minTime, max: maxTime, step: step, interval: timeInterval, status: status })] }) }) });
 });

package/dist/date-time-range-picker.js

@@ -6,7 +6,7 @@ import { parseTime, timeOnStep } from "./time-value.js";
 const empty = () => ({ start: { date: "", time: "" }, end: { date: "", time: "" } });
 const copy = (value) => ({ start: { ...value.start }, end: { ...value.end } });
 const signature = (value) => [value.start.date, value.start.time, value.end.date, value.end.time].join("|");
-export const CivilDateTimeRangePicker = /* @__PURE__ */ forwardRef(function CivilDateTimeRangePicker({ label, hideLabel = false, value, defaultValue = empty(), onValueChange, startDateName, startTimeName, endDateName, endTimeName, startLabel = "Start", endLabel = "End", startDateLabel = "Start date", startTimeLabel = "Start time", endDateLabel = "End date", endTimeLabel = "End time", form, required = false, disabled = false, readOnly = false, controlSize = "md", precision = "minute", order = "month-day-year", locale = "en-US", minDate, maxDate, step: explicitStep, interval, status, description, incompleteMessage = "Complete both dates and times.", reversedMessage = "End must not precede start.", className, onBlur, ...props }, ref) {
+export const CivilDateTimeRangePicker = /* @__PURE__ */ forwardRef(function CivilDateTimeRangePicker({ label, hideLabel = false, value, defaultValue = empty(), onValueChange, startDateName, startTimeName, endDateName, endTimeName, startLabel = "Start", endLabel = "End", startDateLabel = "Start date", startTimeLabel = "Start time", endDateLabel = "End date", endTimeLabel = "End time", startDatePickerLabels, endDatePickerLabels, startTimePickerLabels, endTimePickerLabels, form, required = false, disabled = false, readOnly = false, controlSize = "md", precision = "minute", order = "month-day-year", locale = "en-US", minDate, maxDate, step: explicitStep, interval, status, description, incompleteMessage = "Complete both dates and times.", reversedMessage = "End must not precede start.", className, onBlur, ...props }, ref) {
     if (![label, startLabel, endLabel, startDateLabel, startTimeLabel, endDateLabel, endTimeLabel, incompleteMessage, reversedMessage].every(text => text.trim()))
         throw new Error("Flood DateTimeRangePicker requires nonempty labels and messages");
     const initial = useRef(copy(defaultValue)), [local, setLocal] = useState(() => copy(defaultValue)), [proposal, setProposal] = useState();
@@ -47,5 +47,5 @@ export const CivilDateTimeRangePicker = /* @__PURE__ */ forwardRef(function Civi
             onBlur?.(event);
             if (!event.defaultPrevented && !event.currentTarget.contains(event.relatedTarget))
                 setProposal(undefined);
-        }, children: [_jsx(Fieldset, { legend: label, hideLabel: hideLabel, hint: description, disabled: disabled, children: _jsxs(Stack, { gap: "4", children: [_jsx(DateTimePicker, { ...shared, label: startLabel, dateLabel: startDateLabel, timeLabel: startTimeLabel, value: selected.start, defaultValue: initial.current.start, onValueChange: next => change("start", next), validationMessage: constraint }), _jsx(DateTimePicker, { ...shared, label: endLabel, dateLabel: endDateLabel, timeLabel: endTimeLabel, value: selected.end, defaultValue: initial.current.end, onValueChange: next => change("end", next) })] }) }), [[startDateName, selected.start.date], [startTimeName, selected.start.time], [endDateName, selected.end.date], [endTimeName, selected.end.time]].map(([name, part], index) => name && _jsx("input", { type: "hidden", name: name, form: form, value: accepted ? part : "", disabled: disabled }, index))] });
+        }, children: [_jsx(Fieldset, { legend: label, hideLabel: hideLabel, hint: description, disabled: disabled, children: _jsxs(Stack, { gap: "4", children: [_jsx(DateTimePicker, { ...shared, datePickerLabels: startDatePickerLabels, timePickerLabels: startTimePickerLabels, label: startLabel, dateLabel: startDateLabel, timeLabel: startTimeLabel, value: selected.start, defaultValue: initial.current.start, onValueChange: next => change("start", next), validationMessage: constraint }), _jsx(DateTimePicker, { ...shared, datePickerLabels: endDatePickerLabels, timePickerLabels: endTimePickerLabels, label: endLabel, dateLabel: endDateLabel, timeLabel: endTimeLabel, value: selected.end, defaultValue: initial.current.end, onValueChange: next => change("end", next) })] }) }), [[startDateName, selected.start.date], [startTimeName, selected.start.time], [endDateName, selected.end.date], [endTimeName, selected.end.time]].map(([name, part], index) => name && _jsx("input", { type: "hidden", name: name, form: form, value: accepted ? part : "", disabled: disabled }, index))] });
 });

package/dist/disclosure.d.ts

@@ -1,4 +1,4 @@
-import { type HTMLAttributes } from "react";
+import { type HTMLAttributes, type ReactNode } from "react";
 interface Props extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
     title: string;
     expanded: boolean;
@@ -6,6 +6,7 @@ interface Props extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
     disabled?: boolean;
     controlSize: "sm" | "md" | "lg" | "xl";
     headingLevel?: 2 | 3 | 4 | 5 | 6;
+    headerAction?: ReactNode;
 }
 /** Shared original disclosure anatomy. The closed panel stays mounted but hidden. */
 export declare const Disclosure: import("react").ForwardRefExoticComponent<Props & import("react").RefAttributes<HTMLDivElement>>;

package/dist/disclosure.js

@@ -1,9 +1,9 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { createElement, forwardRef, useEffect, useId, useLayoutEffect, useRef, useImperativeHandle } from "react";
-import { Button } from "./index.js";
+import { Button, IconSlot } from "./index.js";
 const useBrowserLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
 /** Shared original disclosure anatomy. The closed panel stays mounted but hidden. */
-export const Disclosure = /* @__PURE__ */ 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, headerAction, 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);
@@ -15,7 +15,7 @@ export const Disclosure = /* @__PURE__ */ forwardRef(function Disclosure({ title
         if (!expanded)
             focusedInside.current = false;
     }, [expanded, disabled]);
-    const button = _jsxs(Button, { ref: trigger, variant: "ghost", size: controlSize, id: `${id}-trigger`, type: "button", disabled: disabled, "aria-expanded": expanded, "aria-controls": `${id}-panel`, className: "flood-disclosure__trigger", onClick: () => onExpandedChange(!expanded), children: [_jsx("span", { className: "flood-disclosure__title", children: title }), _jsx("span", { className: "flood-disclosure__indicator", "aria-hidden": "true" })] });
-    return _jsxs("div", { ...props, id: id, ref: root, "data-open": expanded, className: ["flood-disclosure", `flood-control--${controlSize}`, className].filter(Boolean).join(" "), children: [createElement(headingLevel ? `h${headingLevel}` : "div", { className: "flood-disclosure__heading" }, button), _jsx("div", { ref: panel, id: `${id}-panel`, className: "flood-disclosure__panel", hidden: !expanded, onFocusCapture: () => { focusedInside.current = true; }, onBlurCapture: event => { if (event.relatedTarget && !event.currentTarget.contains(event.relatedTarget))
+    const button = _jsxs(Button, { ref: trigger, variant: "ghost", size: controlSize, id: `${id}-trigger`, type: "button", disabled: disabled, "aria-expanded": expanded, "aria-controls": `${id}-panel`, className: "flood-disclosure__trigger", onClick: () => onExpandedChange(!expanded), children: [_jsx("span", { className: "flood-disclosure__title", children: title }), _jsx(IconSlot, { size: "2xs", className: "flood-disclosure__indicator", children: _jsx("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "1.75", strokeLinecap: "round", strokeLinejoin: "round", children: _jsx("path", { d: "m3 8 9 8 9-8" }) }) })] });
+    return _jsxs("div", { ...props, id: id, ref: root, "data-open": expanded, className: ["flood-disclosure", `flood-control--${controlSize}`, className].filter(Boolean).join(" "), children: [createElement(headingLevel ? `h${headingLevel}` : "div", { className: "flood-disclosure__heading" }, button, headerAction != null && _jsx("div", { className: "flood-disclosure__action", children: headerAction })), _jsx("div", { ref: panel, id: `${id}-panel`, className: "flood-disclosure__panel", hidden: !expanded, onFocusCapture: () => { focusedInside.current = true; }, onBlurCapture: event => { if (event.relatedTarget && !event.currentTarget.contains(event.relatedTarget))
                     focusedInside.current = false; }, children: children })] });
 });

package/dist/filter-condition.d.ts

@@ -0,0 +1,3 @@
+import { type FilterConditionProps } from './index.js';
+/** One controlled finite-choice predicate. Query execution and draft/application belong to the host. */
+export declare const PredicateRow: import("react").ForwardRefExoticComponent<FilterConditionProps & import("react").RefAttributes<HTMLFieldSetElement>>;

package/dist/filter-condition.js

@@ -0,0 +1,21 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef } from 'react';
+import { Field, Fieldset, Grid, IconButton, MultiSelect, Select } from './index.js';
+/** One controlled finite-choice predicate. Query execution and draft/application belong to the host. */
+export const PredicateRow = /* @__PURE__ */ forwardRef(function PredicateRow({ label, properties, value, onValueChange, onRemove, controlSize = 'sm', labels, disabled = false, hideLabel = true, className, ...props }, ref) {
+    const property = properties.find(property => property.id === value.property);
+    if (!label.trim() || !properties.length || new Set(properties.map(property => property.id)).size !== properties.length ||
+        properties.some(property => !property.id.trim() || !property.label.trim()) || !property ||
+        !['is', 'is-not'].includes(value.operator))
+        throw new Error('Flood FilterCondition requires named unique properties and a supported predicate');
+    const names = {
+        property: `${label} property`, operator: `${label} operator`, values: `${label} values`,
+        include: 'is any of', exclude: 'is none of', placeholder: 'Choose values…', remove: `Remove ${label.charAt(0).toLowerCase()}${label.slice(1)}`,
+        ...labels,
+    };
+    return _jsx(Fieldset, { ...props, ref: ref, legend: label, hideLabel: hideLabel, disabled: disabled, className: ['flood-filter-condition', className].filter(Boolean).join(' '), "data-removable": Boolean(onRemove), children: _jsxs(Grid, { gap: "2", className: "flood-filter-condition__row", children: [_jsx(Field, { label: names.property, hideLabel: true, children: field => _jsx(Select, { ...field, controlSize: controlSize, value: value.property, disabled: disabled, onChange: event => { if (!disabled)
+                            onValueChange({ ...value, property: event.currentTarget.value, values: [] }); }, children: properties.map(property => _jsx("option", { value: property.id, disabled: property.disabled, children: property.label }, property.id)) }) }), _jsx(Field, { label: names.operator, hideLabel: true, children: field => _jsxs(Select, { ...field, controlSize: controlSize, value: value.operator, disabled: disabled, onChange: event => { if (!disabled)
+                            onValueChange({ ...value, operator: event.currentTarget.value }); }, children: [_jsx("option", { value: "is", children: names.include }), _jsx("option", { value: "is-not", children: names.exclude })] }) }), _jsx("div", { className: "flood-filter-condition__values", children: _jsx(Field, { label: names.values, hideLabel: true, children: field => _jsx(MultiSelect, { ...field, controlSize: controlSize, options: property.options, value: value.values, placeholder: names.placeholder, disabled: disabled, onValueChange: values => { if (!disabled)
+                                onValueChange({ ...value, values }); } }) }) }), onRemove && _jsx(IconButton, { label: names.remove, size: controlSize, variant: "subtle", disabled: disabled, className: "flood-filter-condition__remove", onClick: () => { if (!disabled)
+                        onRemove(); }, children: _jsx("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "1.75", strokeLinecap: "round", "aria-hidden": "true", children: _jsx("path", { d: "m6 6 12 12M18 6 6 18" }) }) })] }) });
+});

package/dist/filter-group.d.ts

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