@flood-md/react 0.2.10 → 0.2.12

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

@@ -1,11 +1,35 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { forwardRef } from "react";
+import { forwardRef, useEffect, useRef } 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)) });
 });
-export const TabularData = /* @__PURE__ */ forwardRef(function TabularData({ caption, children, hideCaption, density, striped, scrollLabel, cellVerticalAlign, className, hidden, dir, lang, ...props }, ref) {
-    return _jsx("div", { className: "flood-table-container", hidden: hidden, dir: dir, lang: lang, children: _jsx(ScrollArea, { orientation: "horizontal", "aria-label": scrollLabel ?? caption, children: _jsxs("table", { ...props, ref: ref, hidden: hidden, dir: dir, lang: lang, className: ["flood-table", className].filter(Boolean).join(" "), "data-density": density, "data-striped": striped, "data-cell-vertical-align": cellVerticalAlign, children: [_jsx("caption", { className: hideCaption ? "flood-visually-hidden" : undefined, children: caption }), children] }) }) });
+export const TabularData = /* @__PURE__ */ forwardRef(function TabularData({ caption, children, hideCaption, density, striped, scrollLabel, cellVerticalAlign, maxViewportHeight, stickyHeader, className, hidden, dir, lang, ...props }, ref) {
+    const viewport = useRef(null);
+    const scrollVertically = maxViewportHeight !== undefined;
+    const pinHeader = scrollVertically && stickyHeader;
+    useEffect(() => {
+        const node = viewport.current;
+        const header = node?.querySelector("table")?.tHead;
+        if (!pinHeader || !node || !header)
+            return;
+        const update = () => { node.style.scrollPaddingBlockStart = `${header.offsetHeight}px`; };
+        update();
+        const observer = new ResizeObserver(update);
+        observer.observe(header);
+        return () => {
+            observer.disconnect();
+            node.style.removeProperty("scroll-padding-block-start");
+        };
+    }, [pinHeader, children]);
+    return _jsx("div", { className: "flood-table-container", hidden: hidden, dir: dir, lang: lang, children: _jsx(ScrollArea, { ref: viewport, orientation: scrollVertically ? "both" : "horizontal", contentInset: scrollVertically ? "scrollbar" : undefined, tabIndex: scrollVertically ? 0 : undefined, style: scrollVertically ? { maxBlockSize: maxViewportHeight } : undefined, "aria-label": scrollLabel ?? caption, onFocus: pinHeader ? event => {
+                const target = event.target;
+                const header = event.currentTarget.querySelector("table")?.tHead;
+                if (header && target !== event.currentTarget && !header.contains(target) &&
+                    !target.closest("[popover], dialog[open]") && target.getBoundingClientRect().top < header.getBoundingClientRect().bottom) {
+                    target.scrollIntoView({ block: "nearest", inline: "nearest" });
+                }
+            } : undefined, children: _jsxs("table", { ...props, ref: ref, hidden: hidden, dir: dir, lang: lang, className: ["flood-table", className].filter(Boolean).join(" "), "data-density": density, "data-striped": striped, "data-cell-vertical-align": cellVerticalAlign, "data-sticky-header": pinHeader || undefined, children: [_jsx("caption", { className: hideCaption ? "flood-visually-hidden" : undefined, children: caption }), children] }) }) });
 });

package/dist/data-table-columns.d.ts

@@ -0,0 +1,25 @@
+import { type CSSProperties } from "react";
+import { type DataTableColumn, type DataTableProps } from "./index.js";
+export declare function useDataTableColumnLayout(columns: readonly DataTableColumn[], visibleColumns: readonly DataTableColumn[], { columnWidths, defaultColumnWidths, onColumnWidthsChange, measureViewport, }: Pick<DataTableProps, "columnWidths" | "defaultColumnWidths" | "onColumnWidthsChange"> & {
+    measureViewport?: boolean;
+}): {
+    table: import("react").RefObject<HTMLTableElement | null>;
+    fixedWidth: number | undefined;
+    viewportWidth: number | undefined;
+    disclosureWidth: number | undefined;
+    atDefaults: boolean;
+    reset: () => void;
+    utilityCell: (id: string, header?: boolean) => {
+        "data-pin-edge": "end" | "start" | undefined;
+        "data-pin-boundary": true | undefined;
+        style: CSSProperties | undefined;
+        "data-data-table-utility": string;
+    };
+    columnCell: (column: DataTableColumn, header?: boolean) => {
+        "data-pin-edge": "end" | "start" | undefined;
+        "data-pin-boundary": true | undefined;
+        style: CSSProperties | undefined;
+        "data-data-table-column": string;
+    };
+    renderHandle: (column: DataTableColumn, label: string, disabled: boolean) => false | import("react").JSX.Element | undefined;
+};

package/dist/data-table-columns.js

@@ -0,0 +1,271 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useLayoutEffect, useRef, useState } from "react";
+import { IconSlot } from "./index.js";
+const defaultMinWidth = 64;
+const defaultMaxWidth = 960;
+const columnKey = (id) => `column:${id}`;
+const utilityKey = (id) => `utility:${id}`;
+const validWidth = (value) => typeof value === "number" && Number.isFinite(value) && value > 0;
+function bounds(column) {
+    const min = validWidth(column.minWidth) ? Math.ceil(column.minWidth) : defaultMinWidth;
+    const max = validWidth(column.maxWidth) ? Math.floor(column.maxWidth) : defaultMaxWidth;
+    return { min, max: Math.max(min, max) };
+}
+function clampWidth(value, { min, max }) {
+    return Math.max(min, Math.min(max, Math.round(value)));
+}
+function normalizeWidths(columns, widths) {
+    return new Map(columns.flatMap(column => {
+        const value = widths && Object.prototype.hasOwnProperty.call(widths, column.id) ? widths[column.id] : undefined;
+        return column.resizable && validWidth(value) ? [[column.id, clampWidth(value, bounds(column))]] : [];
+    }));
+}
+function equalWidths(a, b) {
+    return a.size === b.size && [...a].every(([key, width]) => b.get(key) === width);
+}
+function measuredColumnWidth(header) {
+    const style = header.ownerDocument.defaultView?.getComputedStyle(header);
+    if (!style)
+        return header.offsetWidth;
+    const inlineSize = Number.parseFloat(style.inlineSize);
+    if (!Number.isFinite(inlineSize))
+        return header.offsetWidth;
+    const borderBox = style.boxSizing === "border-box" ? inlineSize : inlineSize +
+        Number.parseFloat(style.paddingInlineStart) + Number.parseFloat(style.paddingInlineEnd) +
+        Number.parseFloat(style.borderInlineStartWidth) + Number.parseFloat(style.borderInlineEndWidth);
+    // Avoid shaving a fraction of a pixel from untouched labels when switching to fixed tracks.
+    return Math.ceil(borderBox * 100) / 100;
+}
+function ColumnResizeHandle({ column, label, width, disabled, onPreview, onResize }) {
+    const gesture = useRef(null);
+    const [dragging, setDragging] = useState(false);
+    const limits = bounds(column);
+    const direction = (node) => {
+        const rtl = node.ownerDocument.defaultView?.getComputedStyle(node).direction === "rtl";
+        return (rtl ? -1 : 1) * (column.pinned === "end" ? -1 : 1);
+    };
+    const cancel = () => {
+        const active = gesture.current;
+        if (!active)
+            return;
+        gesture.current = null;
+        if (active.handle.hasPointerCapture(active.id))
+            active.handle.releasePointerCapture(active.id);
+        setDragging(false);
+        onPreview(undefined);
+    };
+    useEffect(() => {
+        if (disabled)
+            cancel();
+    }, [disabled]);
+    useEffect(() => () => {
+        if (gesture.current)
+            onPreview(undefined);
+    }, []);
+    useEffect(() => {
+        if (!dragging)
+            return;
+        const document = gesture.current?.handle.ownerDocument;
+        const view = document?.defaultView;
+        const hide = () => { if (document?.hidden)
+            cancel(); };
+        view?.addEventListener("blur", cancel);
+        document?.addEventListener("visibilitychange", hide);
+        return () => {
+            view?.removeEventListener("blur", cancel);
+            document?.removeEventListener("visibilitychange", hide);
+        };
+    }, [dragging]);
+    const requestedWidth = (event) => {
+        const active = gesture.current;
+        if (active?.id !== event.pointerId)
+            return undefined;
+        return clampWidth(active.width + (event.clientX - active.origin) * active.direction / active.scale, limits);
+    };
+    const value = width === undefined ? limits.min : clampWidth(width, limits);
+    return _jsx("div", { role: "separator", "aria-label": label, title: label, "aria-orientation": "vertical", "aria-valuemin": limits.min, "aria-valuemax": limits.max, "aria-valuenow": value, "aria-valuetext": `${value} px`, tabIndex: disabled ? -1 : 0, "aria-disabled": disabled || undefined, className: "flood-data-table__resize", "data-dragging": dragging || undefined, onKeyDown: event => {
+            if (event.defaultPrevented || disabled || event.altKey || event.ctrlKey || event.metaKey || event.nativeEvent.isComposing)
+                return;
+            if (event.key === "Escape" && gesture.current) {
+                event.preventDefault();
+                cancel();
+                return;
+            }
+            if (gesture.current)
+                return;
+            let next;
+            if (event.key === "Home")
+                next = limits.min;
+            else if (event.key === "End")
+                next = limits.max;
+            else if (event.key === "ArrowLeft" || event.key === "ArrowRight") {
+                const step = event.shiftKey ? 24 : 8;
+                next = clampWidth((width ?? value) + (event.key === "ArrowRight" ? step : -step) * direction(event.currentTarget), limits);
+            }
+            else
+                return;
+            event.preventDefault();
+            if (next !== width)
+                onResize(next);
+        }, onPointerDown: event => {
+            const handle = event.currentTarget;
+            const header = handle.closest("th");
+            if (event.defaultPrevented || disabled || gesture.current || event.button !== 0 || !event.isPrimary || !header?.offsetWidth)
+                return;
+            try {
+                handle.setPointerCapture(event.pointerId);
+            }
+            catch {
+                return;
+            }
+            event.preventDefault();
+            handle.focus({ preventScroll: true });
+            gesture.current = {
+                handle, id: event.pointerId, origin: event.clientX, width: header.offsetWidth,
+                direction: direction(handle), scale: header.getBoundingClientRect().width / header.offsetWidth || 1,
+            };
+            setDragging(true);
+        }, onPointerMove: event => {
+            const next = requestedWidth(event);
+            if (next !== undefined && !disabled)
+                onPreview(event.clientX === gesture.current?.origin ? undefined : next);
+        }, onPointerUp: event => {
+            const next = requestedWidth(event);
+            if (next === undefined)
+                return;
+            const moved = event.clientX !== gesture.current?.origin && next !== gesture.current?.width;
+            cancel();
+            if (!disabled && moved)
+                onResize(next);
+        }, onPointerCancel: event => { if (gesture.current?.id === event.pointerId)
+            cancel(); }, onLostPointerCapture: event => { if (gesture.current?.id === event.pointerId)
+            cancel(); }, children: _jsx("span", { className: "flood-data-table__resize-icon", children: _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: _jsx("path", { d: "M3 12h18m-14-4-4 4 4 4m10-8 4 4-4 4" }) }) }) }) });
+}
+export function useDataTableColumnLayout(columns, visibleColumns, { columnWidths, defaultColumnWidths, onColumnWidthsChange, measureViewport = false, }) {
+    const [local, setLocal] = useState(defaultColumnWidths);
+    const [draft, setDraft] = useState();
+    const [metrics, setMetrics] = useState({ widths: new Map(), utilityKeys: [], viewport: 0 });
+    const table = useRef(null);
+    const baseline = useRef(new Map());
+    const accepted = normalizeWidths(columns, columnWidths ?? local);
+    const defaults = normalizeWidths(columns, defaultColumnWidths);
+    const activeDraft = draft && visibleColumns.some(column => column.resizable && column.id === draft.id) ? draft : undefined;
+    const visibleSizes = new Map(visibleColumns.flatMap(column => {
+        const width = activeDraft?.id === column.id ? activeDraft.width : accepted.get(column.id);
+        return width === undefined ? [] : [[columnKey(column.id), width]];
+    }));
+    const active = measureViewport || columns.some(column => column.resizable || column.pinned);
+    const hasSizes = visibleSizes.size > 0;
+    const columnOrder = JSON.stringify(visibleColumns.map(column => column.id));
+    useLayoutEffect(() => {
+        const node = table.current;
+        const viewport = node?.closest(".flood-scroll-area__viewport");
+        const headerRow = node?.tHead?.rows[0];
+        if (!active || !node || !viewport || !headerRow)
+            return;
+        let headers = Array.from(headerRow.cells);
+        const measure = () => {
+            const widths = new Map();
+            const utilityKeys = [];
+            for (const header of headers) {
+                const id = header.dataset.dataTableColumn;
+                const utility = header.dataset.dataTableUtility;
+                const key = id !== undefined ? columnKey(id) : utilityKey(utility ?? `unknown-${header.cellIndex}`);
+                if (id === undefined)
+                    utilityKeys.push(key);
+                if (header.offsetWidth === 0)
+                    continue;
+                widths.set(key, header.offsetWidth);
+                if (!hasSizes || !baseline.current.has(key))
+                    baseline.current.set(key, measuredColumnWidth(header));
+            }
+            setMetrics(previous => previous.viewport === viewport.clientWidth && equalWidths(previous.widths, widths) &&
+                previous.utilityKeys.join("|") === utilityKeys.join("|")
+                ? previous : { widths, utilityKeys, viewport: viewport.clientWidth });
+        };
+        measure();
+        const Observer = node.ownerDocument.defaultView?.ResizeObserver;
+        if (!Observer)
+            return;
+        const observer = new Observer(measure);
+        const observeHeaders = () => {
+            observer.disconnect();
+            headers = Array.from(headerRow.cells);
+            observer.observe(viewport);
+            for (const header of headers)
+                observer.observe(header, { box: "border-box" });
+            measure();
+        };
+        observeHeaders();
+        const HeaderObserver = node.ownerDocument.defaultView?.MutationObserver;
+        const headerObserver = HeaderObserver && new HeaderObserver(observeHeaders);
+        headerObserver?.observe(headerRow, { childList: true });
+        return () => {
+            observer.disconnect();
+            headerObserver?.disconnect();
+        };
+    }, [active, hasSizes, columnOrder]);
+    const sizes = hasSizes ? new Map([...baseline.current, ...visibleSizes]) : metrics.widths;
+    const keys = [...metrics.utilityKeys, ...visibleColumns.map(column => columnKey(column.id))];
+    const fixedWidth = hasSizes && keys.every(key => sizes.has(key))
+        ? keys.reduce((total, key) => total + sizes.get(key), 0)
+        : undefined;
+    const start = visibleColumns.filter(column => column.pinned === "start").map(column => columnKey(column.id));
+    const end = visibleColumns.filter(column => column.pinned === "end").map(column => columnKey(column.id)).reverse();
+    if (start.length)
+        start.unshift(...metrics.utilityKeys);
+    const pinned = new Map();
+    const pinnedKeys = [...start, ...end];
+    const pinnedWidth = pinnedKeys.reduce((total, key) => total + (metrics.widths.get(key) ?? 0), 0);
+    if (pinnedKeys.every(key => metrics.widths.has(key)) && pinnedWidth + defaultMinWidth <= metrics.viewport) {
+        for (const [edge, group] of [["start", start], ["end", end]]) {
+            let offset = 0;
+            group.forEach((key, index) => {
+                pinned.set(key, { edge, offset, boundary: index === group.length - 1 });
+                offset += metrics.widths.get(key);
+            });
+        }
+    }
+    function cell(key, header, width) {
+        const pin = pinned.get(key);
+        const inlineSize = header ? (fixedWidth === undefined ? width : sizes.get(key)) : undefined;
+        return {
+            "data-pin-edge": pin?.edge,
+            "data-pin-boundary": pin?.boundary || undefined,
+            style: inlineSize !== undefined || pin
+                ? { inlineSize, "--flood-data-table-pin-offset": pin ? `${pin.offset}px` : undefined }
+                : undefined,
+        };
+    }
+    function publish(next) {
+        if (equalWidths(accepted, next))
+            return;
+        const widths = Object.fromEntries(next);
+        if (columnWidths === undefined)
+            setLocal(widths);
+        onColumnWidthsChange?.(widths);
+    }
+    return {
+        table, fixedWidth,
+        viewportWidth: metrics.viewport || undefined,
+        disclosureWidth: metrics.widths.get(utilityKey("expansion")),
+        atDefaults: equalWidths(accepted, defaults),
+        reset: () => { setDraft(undefined); publish(defaults); },
+        utilityCell: (id, header = false) => ({
+            ...cell(utilityKey(id), header),
+            "data-data-table-utility": id,
+        }),
+        columnCell: (column, header = false) => ({
+            ...cell(columnKey(column.id), header, header ? (accepted.get(column.id) ?? column.width) : undefined),
+            "data-data-table-column": column.id,
+        }),
+        renderHandle: (column, label, disabled) => column.resizable &&
+            _jsx(ColumnResizeHandle, { column: column, label: label, disabled: disabled, width: visibleSizes.get(columnKey(column.id)) ?? metrics.widths.get(columnKey(column.id)), onPreview: width => setDraft(previous => {
+                    if (width === undefined)
+                        return previous?.id === column.id ? undefined : previous;
+                    if (previous?.id === column.id && previous.width === width)
+                        return previous;
+                    return { id: column.id, width };
+                }), onResize: width => publish(new Map(accepted).set(column.id, width)) }),
+    };
+}

package/dist/data-table-expansion.d.ts

@@ -0,0 +1,21 @@
+import { type ReactNode, type TdHTMLAttributes } from "react";
+import { type DataTableLabels, type DataTableRow } from "./index.js";
+export declare function useDataTableExpansion(rows: readonly DataTableRow[], expandedIds: readonly string[] | undefined, defaultExpandedIds: readonly string[] | undefined, onExpandedChange: ((ids: string[]) => void) | undefined): {
+    enabled: boolean;
+    expanded: Set<string>;
+    toggle: (id: string) => void;
+};
+interface DataTableExpandableRowProps {
+    row: DataTableRow;
+    showDisclosure: boolean;
+    expanded: boolean;
+    colSpan: number;
+    labels: DataTableLabels;
+    onToggle: () => void;
+    disclosureCellProps?: TdHTMLAttributes<HTMLTableCellElement>;
+    viewportWidth?: number;
+    disclosureWidth?: number;
+    children: (disclosureCell: ReactNode) => ReactNode;
+}
+export declare function DataTableExpandableRow({ row, showDisclosure, expanded, colSpan, labels, onToggle, disclosureCellProps, viewportWidth, disclosureWidth, children }: DataTableExpandableRowProps): import("react").JSX.Element;
+export {};