@flood-md/react 0.2.6 → 0.2.9

package/dist/menu.js

@@ -1,42 +1,127 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { forwardRef, useCallback, useEffect, useId, useImperativeHandle, useLayoutEffect, useRef, useState } from "react";
+import { Fragment, forwardRef, useCallback, useEffect, useId, useImperativeHandle, useLayoutEffect, useRef, useState } from "react";
 import { Button, Kbd, ScrollArea } from "./index.js";
 import { positionLayer, registerLayer, returnFocus, tabbables } from "./overlay-runtime.js";
 const useBrowserLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
-export const ActionMenu = forwardRef(function ActionMenu({ label, trigger, items, onAction, open: controlled, defaultOpen, onOpenChange, disabled, side = "bottom", align = "start", controlSize = "sm", id: explicitId, className, onKeyDown, ...props }, ref) {
-    const [local, setLocal] = useState(Boolean(defaultOpen)), open = controlled ?? local;
-    const anchor = useRef(null), panel = useRef(null);
+/** Validate each level while retaining globally unique action IDs. */
+export function validateMenuTree(items) {
+    const ids = new Set();
+    const pending = [{ items, ancestors: new Set() }];
+    while (pending.length) {
+        const current = pending.pop();
+        if (current.ancestors.has(current.items))
+            throw new Error("Flood Menu does not accept recursive item arrays");
+        if (!current.items.some(item => item.type !== "separator"))
+            throw new Error("Flood Menu requires at least one action item in every menu");
+        const ancestors = new Set(current.ancestors);
+        ancestors.add(current.items);
+        const checkedGroups = new Set();
+        for (const item of current.items) {
+            if (!item.id.trim() || ids.has(item.id) || (item.type !== "separator" && !item.label.trim()))
+                throw new Error("Flood menu items need unique nonempty IDs across the tree and action labels");
+            ids.add(item.id);
+            if (item.type === "submenu")
+                pending.push({ items: item.items, ancestors });
+            if (item.type === "radio") {
+                if (!item.group.trim())
+                    throw new Error("Flood Menu radio items need a nonempty group label");
+                if (item.checked && checkedGroups.has(item.group))
+                    throw new Error("Flood Menu radio groups accept only one checked item");
+                if (item.checked)
+                    checkedGroups.add(item.group);
+            }
+        }
+    }
+}
+const ownButtons = (panel) => Array.from(panel?.querySelectorAll('[role="menuitem"], [role="menuitemcheckbox"], [role="menuitemradio"]') ?? [])
+    .filter(button => button.closest('[role="menu"]') === panel);
+export function focusMenuEdge(panel, edge = "first") {
+    const all = ownButtons(panel);
+    ((edge === "last" ? all.at(-1) : all[0]) ?? panel)?.focus({ preventScroll: true });
+}
+/** Internal native top-layer engine shared by Menu and ContextMenu. */
+export const MenuLayer = /* @__PURE__ */ forwardRef(function MenuLayerRender({ label, items, open, requestOpen, closeTree, anchor, rootAnchor, rootPanel, onAction, edge, nested = false, position, side = "bottom", align = "start", controlSize = "sm", id: explicitId, className, onKeyDown, ...props }, forwardedRef) {
     const generated = useId(), id = explicitId ?? `flood-menu-${generated}`;
-    const pending = useRef(undefined);
-    const edge = useRef("first"), search = useRef({ text: "", time: 0 });
-    if (!items.some(item => item.type !== "separator"))
-        throw new Error("Flood Menu requires at least one action item");
-    if (new Set(items.map(item => item.id)).size !== items.length || items.some(item => !item.id.trim() || (item.type !== "separator" && !item.label.trim())))
-        throw new Error("Flood menu items need unique nonempty IDs and action labels");
-    const request = (next) => {
-        if (pending.current === next)
+    const panel = useRef(null), anchors = useRef(new Map()), children = useRef(new Map());
+    const anchorRefs = useRef(new Map());
+    const childRefs = useRef(new Map());
+    const [openChild, setOpenChild] = useState(undefined);
+    const hover = useRef(undefined), pointerType = useRef("");
+    const hoverIntent = useRef(undefined);
+    const latestItems = useRef(new Map());
+    const search = useRef({ text: "", time: 0 }), pointerTarget = useRef(null);
+    const current = useRef({ open, requestOpen, closeTree, anchor, rootAnchor, rootPanel, position, edge });
+    current.current = { open, requestOpen, closeTree, anchor, rootAnchor, rootPanel, position, edge };
+    useImperativeHandle(forwardedRef, () => panel.current, []);
+    const clearHover = () => { clearTimeout(hover.current); hover.current = undefined; hoverIntent.current = undefined; };
+    useEffect(() => () => clearHover(), []);
+    useBrowserLayoutEffect(() => {
+        latestItems.current = new Map(items.map(item => [item.id, item]));
+        const intent = hoverIntent.current, target = intent && latestItems.current.get(intent.id);
+        // Ordinary host rerenders often create an equivalent array. Preserve the
+        // pending pointer intent unless the actual target can no longer receive it.
+        if (intent && (!target || target.type === "separator" || target.disabled || (target.type ?? "action") !== intent.type || !intent.node.isConnected || anchors.current.get(intent.id) !== intent.node))
+            clearHover();
+        const keys = new Set(items.filter(item => item.type !== "separator").map(item => item.id));
+        for (const key of anchorRefs.current.keys())
+            if (!keys.has(key))
+                anchorRefs.current.delete(key);
+        for (const key of childRefs.current.keys())
+            if (!keys.has(key))
+                childRefs.current.delete(key);
+    });
+    const anchorRef = (key) => {
+        if (!anchorRefs.current.has(key))
+            anchorRefs.current.set(key, node => { if (node)
+                anchors.current.set(key, node);
+            else
+                anchors.current.delete(key); });
+        return anchorRefs.current.get(key);
+    };
+    const childRef = (key) => {
+        if (!childRefs.current.has(key))
+            childRefs.current.set(key, node => { if (node)
+                children.current.set(key, node);
+            else
+                children.current.delete(key); });
+        return childRefs.current.get(key);
+    };
+    const wholePanel = () => current.current.rootPanel?.() ?? panel.current;
+    const place = (node) => {
+        const target = current.current.anchor();
+        if (!target)
             return;
-        pending.current = next;
-        queueMicrotask(() => { pending.current = undefined; });
-        if (controlled === undefined)
-            setLocal(next);
-        onOpenChange?.(next);
+        const direction = node.ownerDocument.defaultView.getComputedStyle(target).direction;
+        node.dataset.menuDirection = direction;
+        if (current.current.position) {
+            current.current.position(node);
+            return;
+        }
+        positionLayer(target, node, nested ? direction === "rtl" ? "left" : "right" : side, nested ? "start" : align);
     };
-    const current = useRef({ open, request });
-    useBrowserLayoutEffect(() => { current.current = { open, request }; });
-    const setAnchor = useCallback((node) => { anchor.current = node; }, []);
-    useImperativeHandle(ref, () => panel.current, []);
-    const buttons = () => Array.from(panel.current?.querySelectorAll('[role="menuitem"]') ?? []);
-    const focusEdge = () => { const all = buttons(); ((edge.current === "last" ? all.at(-1) : all[0]) ?? panel.current)?.focus({ preventScroll: true }); };
     useBrowserLayoutEffect(() => {
-        if (!open || !panel.current)
+        if (!open || !panel.current) {
+            clearHover();
+            if (openChild !== undefined)
+                setOpenChild(undefined);
             return;
+        }
         const element = panel.current, document = element.ownerDocument, view = document.defaultView;
         let alive = true, frame = 0, unregister = () => { };
+        const closeLevel = () => {
+            const active = document.activeElement;
+            if (nested && active && !wholePanel()?.contains(active) && !current.current.rootAnchor()?.contains(active))
+                current.current.closeTree();
+            else
+                current.current.requestOpen(false);
+        };
+        const trackPointer = (event) => { pointerTarget.current = event.target; };
+        document.addEventListener("pointerdown", trackPointer, true);
         const start = () => {
-            if (!alive || !anchor.current?.isConnected)
+            const target = current.current.anchor();
+            if (!alive || !target?.isConnected)
                 return;
-            const parent = anchor.current.closest("dialog");
+            const parent = target.closest("dialog");
             if (parent && !parent.open) {
                 frame = view.requestAnimationFrame(start);
                 return;
@@ -45,86 +130,239 @@ export const ActionMenu = forwardRef(function ActionMenu({ label, trigger, items
                 throw new Error("Flood Menu requires the native Popover API");
             element.style.visibility = "hidden";
             element.showPopover();
-            positionLayer(anchor.current, element, side, align);
-            unregister = registerLayer(document, { panel: element, anchor: () => anchor.current, close: () => current.current.request(false) });
+            place(element);
+            unregister = registerLayer(document, { panel: element, anchor: () => current.current.anchor(), close: closeLevel,
+                outside: () => {
+                    if (nested && pointerTarget.current && wholePanel()?.contains(pointerTarget.current))
+                        current.current.requestOpen(false);
+                    else
+                        current.current.closeTree();
+                } });
             search.current = { text: "", time: 0 };
-            focusEdge();
+            focusMenuEdge(element, current.current.edge?.() ?? "first");
             const update = () => { if (!alive)
-                return; if (anchor.current?.isConnected)
-                positionLayer(anchor.current, element, side, align); frame = view.requestAnimationFrame(update); };
+                return; if (current.current.anchor()?.isConnected)
+                place(element); frame = view.requestAnimationFrame(update); };
             frame = view.requestAnimationFrame(update);
         };
         start();
         const toggle = (event) => {
             if (!alive || event.newState !== "closed" || element.matches(":popover-open") || !current.current.open)
                 return;
-            current.current.request(false);
-            queueMicrotask(() => { if (alive && current.current.open && element.isConnected && !element.matches(":popover-open") && anchor.current?.isConnected) {
-                element.showPopover();
-                positionLayer(anchor.current, element, side, align);
-                focusEdge();
-            } });
+            current.current.requestOpen(false);
+            queueMicrotask(() => {
+                if (alive && current.current.open && element.isConnected && !element.matches(":popover-open") && current.current.anchor()?.isConnected) {
+                    element.showPopover();
+                    place(element);
+                    focusMenuEdge(element, current.current.edge?.() ?? "first");
+                }
+            });
         };
         element.addEventListener("toggle", toggle);
-        return () => { alive = false; view.cancelAnimationFrame(frame); unregister(); element.removeEventListener("toggle", toggle); returnFocus(element, anchor.current); if (element.matches(":popover-open"))
-            element.hidePopover(); };
-    }, [open, side, align]);
+        return () => {
+            alive = false;
+            clearHover();
+            view.cancelAnimationFrame(frame);
+            unregister();
+            document.removeEventListener("pointerdown", trackPointer, true);
+            element.removeEventListener("toggle", toggle);
+            returnFocus(element, current.current.anchor());
+            if (element.matches(":popover-open"))
+                element.hidePopover();
+        };
+    }, [open, side, align, nested]);
     useBrowserLayoutEffect(() => {
+        if (openChild && !items.some(item => item.id === openChild && item.type === "submenu" && !item.disabled))
+            setOpenChild(undefined);
         if (open && panel.current?.matches(":popover-open") && panel.current.ownerDocument.activeElement === panel.current.ownerDocument.body)
-            focusEdge();
-    }, [items, open]);
-    const triggerProps = { ref: setAnchor, type: "button", disabled, "aria-haspopup": "menu", "aria-expanded": open, "aria-controls": id,
-        onClick: () => { edge.current = "first"; request(!open); },
-        onKeyDown: event => { if (event.defaultPrevented || disabled || event.altKey || event.ctrlKey || event.metaKey || !["ArrowDown", "ArrowUp"].includes(event.key))
-            return; event.preventDefault(); edge.current = event.key === "ArrowUp" ? "last" : "first"; if (open && panel.current?.matches(":popover-open"))
-            focusEdge();
+            focusMenuEdge(panel.current, edge?.() ?? "first");
+    }, [items, open, openChild]);
+    const showChild = (item) => {
+        if (item.disabled)
+            return;
+        clearHover();
+        if (openChild === item.id)
+            focusMenuEdge(children.current.get(item.id) ?? null);
         else
-            request(true); },
+            setOpenChild(item.id);
+    };
+    const scheduleHover = (item, node) => {
+        clearHover();
+        if (!openChild && item.type !== "submenu") {
+            node.focus({ preventScroll: true });
+            return;
+        }
+        const intent = { id: item.id, type: item.type ?? "action", node };
+        hoverIntent.current = intent;
+        hover.current = setTimeout(() => {
+            if (hoverIntent.current !== intent)
+                return;
+            hover.current = undefined;
+            hoverIntent.current = undefined;
+            const target = latestItems.current.get(intent.id);
+            if (!target || target.type === "separator" || target.disabled || (target.type ?? "action") !== intent.type || !node.isConnected || anchors.current.get(intent.id) !== node || !panel.current?.matches(":popover-open"))
+                return;
+            node.focus({ preventScroll: true });
+            setOpenChild(target.type === "submenu" ? target.id : undefined);
+        }, 150);
     };
     const hasIcons = items.some(item => item.type !== "separator" && item.icon != null);
-    return _jsxs(_Fragment, { children: [trigger(triggerProps), _jsx("div", { ...props, ref: panel, id: id, popover: "manual", role: "menu", "aria-label": label, "aria-orientation": "vertical", tabIndex: -1, className: ["flood-overlay-panel", "flood-menu", className].filter(Boolean).join(" "), onKeyDown: event => {
-                    onKeyDown?.(event);
-                    if (event.defaultPrevented)
-                        return;
-                    const all = buttons(), index = all.indexOf(event.target);
-                    if (event.key === "Tab") {
-                        const button = anchor.current;
-                        if (button) {
-                            const scope = button.closest("dialog[open]") ?? button.ownerDocument.body;
-                            const stops = tabbables(scope).filter(node => !panel.current?.contains(node));
-                            const at = stops.indexOf(button), target = event.shiftKey ? button : at >= 0 ? stops[at + 1] : undefined;
-                            if (target) {
-                                event.preventDefault();
-                                target.focus();
-                            }
+    const renderItem = (item) => {
+        if (item.type === "separator")
+            return _jsx("div", { role: "separator", className: "flood-menu__separator" }, item.id);
+        const submenu = item.type === "submenu", childId = `${id}-submenu-${encodeURIComponent(item.id)}`;
+        return _jsxs(Fragment, { children: [_jsxs(Button, { ref: anchorRef(item.id), role: item.type === "checkbox" ? "menuitemcheckbox" : item.type === "radio" ? "menuitemradio" : "menuitem", "aria-checked": item.type === "checkbox" || item.type === "radio" ? item.checked : undefined, "aria-haspopup": submenu ? "menu" : undefined, "aria-expanded": submenu ? openChild === item.id && !item.disabled : undefined, "aria-controls": submenu ? childId : undefined, tabIndex: -1, variant: "ghost", size: controlSize, "aria-label": item.label, "aria-disabled": item.disabled || undefined, "data-label": item.label, "data-menu-id": item.id, "data-tone": "tone" in item ? item.tone : undefined, "data-submenu": submenu || undefined, className: "flood-menu__item", onPointerDown: event => { pointerType.current = event.pointerType; }, onPointerEnter: event => { if (event.pointerType === "mouse")
+                        scheduleHover(item, event.currentTarget); }, onPointerLeave: () => clearHover(), onPointerMove: event => {
+                        if (event.pointerType === "touch" || openChild)
+                            return;
+                        if (event.currentTarget.ownerDocument.activeElement !== event.currentTarget)
+                            event.currentTarget.focus({ preventScroll: true });
+                    }, onClick: event => {
+                        clearHover();
+                        if (item.disabled) {
+                            event.preventDefault();
+                            return;
+                        }
+                        if (item.type === "submenu") {
+                            if (event.detail > 0 && pointerType.current === "touch" && openChild === item.id)
+                                setOpenChild(undefined);
                             else
-                                button.focus();
+                                showChild(item);
                         }
-                        request(false);
-                        return;
-                    }
-                    if (event.altKey || event.ctrlKey || event.metaKey || event.nativeEvent.isComposing)
-                        return;
-                    let next = event.key === "Home" ? 0 : event.key === "End" ? all.length - 1 : event.key === "ArrowDown" ? (index + 1) % all.length : event.key === "ArrowUp" ? (index - 1 + all.length) % all.length : -1;
-                    if (["ArrowDown", "ArrowUp", "Home", "End"].includes(event.key))
-                        search.current = { text: "", time: 0 };
-                    if (event.key.length === 1 && event.key !== " ") {
-                        const now = Date.now();
-                        search.current = { text: (now - search.current.time < 700 ? search.current.text : "") + event.key.toLocaleLowerCase(), time: now };
-                        const text = Array.from(search.current.text).every(char => char === search.current.text[0]) ? search.current.text[0] : search.current.text;
-                        const start = text.length === 1 ? index + 1 : Math.max(0, index);
-                        next = Array.from({ length: all.length }, (_, offset) => (start + offset) % all.length).find(candidate => all[candidate].dataset.label?.toLocaleLowerCase().startsWith(text)) ?? -1;
-                        event.preventDefault();
-                    }
-                    if (next >= 0 && all[next]) {
+                        else if (item.type === "checkbox") {
+                            item.onCheckedChange(item.checked !== true);
+                            if (item.closeOnSelect)
+                                closeTree();
+                        }
+                        else if (item.type === "radio") {
+                            if (!item.checked)
+                                item.onCheckedChange(true);
+                            if (item.closeOnSelect)
+                                closeTree();
+                        }
+                        else {
+                            closeTree();
+                            onAction?.(item.id);
+                        }
+                    }, children: [hasIcons && _jsx("span", { className: "flood-menu__icon", "aria-hidden": "true", children: item.icon }), _jsx("span", { className: "flood-menu__label", children: item.label }), "shortcut" in item && item.shortcut && _jsx("span", { className: "flood-menu__shortcut", "aria-hidden": "true", children: _jsx(Kbd, { children: item.shortcut }) }), (item.type === "checkbox" || item.type === "radio") && _jsx("span", { className: "flood-menu__icon flood-menu__indicator", "aria-hidden": "true", children: item.checked &&
+                                _jsx("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", children: item.type === "radio" ? _jsx("circle", { cx: "12", cy: "12", r: "4", fill: "currentColor", stroke: "none" }) : item.checked === "mixed" ? _jsx("path", { d: "M6 12h12" }) : _jsx("path", { d: "m5 12 4 4L19 6" }) }) }), submenu && _jsx("span", { className: "flood-menu__icon flood-menu__submenu-indicator", "aria-hidden": "true", children: _jsx("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "1.75", strokeLinecap: "round", strokeLinejoin: "round", children: _jsx("path", { d: "m9 5 7 7-7 7" }) }) })] }), item.type === "submenu" && _jsx(MenuLayer, { id: childId, ref: childRef(item.id), label: item.label, items: item.items, open: openChild === item.id && !item.disabled, requestOpen: next => { if (next && !item.disabled)
+                        setOpenChild(item.id);
+                    else
+                        setOpenChild(current => current === item.id ? undefined : current); }, closeTree: closeTree, anchor: () => anchors.current.get(item.id) ?? null, rootAnchor: rootAnchor, rootPanel: rootPanel ?? (() => panel.current), onAction: onAction, controlSize: controlSize, nested: true })] }, item.id);
+    };
+    const rows = [];
+    for (let index = 0; index < items.length; index++) {
+        const item = items[index];
+        if (item.type !== "radio") {
+            rows.push(renderItem(item));
+            continue;
+        }
+        const group = [item];
+        while (items[index + 1]?.type === "radio" && items[index + 1].group === item.group)
+            group.push(items[++index]);
+        rows.push(_jsxs("div", { role: "group", "aria-label": item.group, children: [_jsx("div", { className: "flood-menu__group-label", "aria-hidden": "true", children: item.group }), group.map(renderItem)] }, `radio-${item.id}`));
+    }
+    return _jsx("div", { ...props, ref: panel, id: id, popover: "manual", role: "menu", "aria-label": label, "aria-orientation": "vertical", tabIndex: -1, className: ["flood-overlay-panel", "flood-menu", nested && "flood-menu--submenu", className].filter(Boolean).join(" "), onKeyDown: event => {
+            if (event.target.closest('[role="menu"]') !== panel.current)
+                return;
+            onKeyDown?.(event);
+            if (event.defaultPrevented)
+                return;
+            const all = ownButtons(panel.current), index = all.indexOf(event.target);
+            if (event.key === "Tab") {
+                clearHover();
+                const source = current.current.rootAnchor();
+                if (source) {
+                    const scope = source.closest("dialog[open]") ?? source.ownerDocument.body;
+                    const stops = tabbables(scope).filter(node => !wholePanel()?.contains(node));
+                    const at = stops.indexOf(source), target = event.shiftKey ? source : at >= 0 ? stops[at + 1] : undefined;
+                    if (target) {
                         event.preventDefault();
-                        all[next].focus({ preventScroll: true });
-                        all[next].scrollIntoView({ block: "nearest", inline: "nearest" });
+                        target.focus();
                     }
-                }, children: open && _jsx(ScrollArea, { orientation: "vertical", role: "group", tabIndex: -1, className: "flood-menu__viewport", children: items.map(item => item.type === "separator" ? _jsx("div", { role: "separator", className: "flood-menu__separator" }, item.id) :
-                        _jsxs(Button, { role: "menuitem", tabIndex: -1, variant: "ghost", size: controlSize, "aria-label": item.label, "aria-disabled": item.disabled || undefined, "data-label": item.label, "data-tone": item.tone, className: "flood-menu__item", onPointerMove: event => { if (event.pointerType !== "touch" && event.currentTarget.ownerDocument.activeElement !== event.currentTarget)
-                                event.currentTarget.focus({ preventScroll: true }); }, onClick: event => { if (item.disabled) {
-                                event.preventDefault();
-                                return;
-                            } request(false); onAction?.(item.id); }, children: [hasIcons && _jsx("span", { className: "flood-menu__icon", "aria-hidden": "true", children: item.icon }), _jsx("span", { className: "flood-menu__label", children: item.label }), item.shortcut && _jsx("span", { className: "flood-menu__shortcut", "aria-hidden": "true", children: _jsx(Kbd, { children: item.shortcut }) })] }, item.id)) }) })] });
+                    else
+                        source.focus();
+                }
+                closeTree();
+                return;
+            }
+            if (event.altKey || event.ctrlKey || event.metaKey || event.nativeEvent.isComposing)
+                return;
+            const rtl = panel.current && getComputedStyle(panel.current).direction === "rtl";
+            if (nested && event.key === (rtl ? "ArrowRight" : "ArrowLeft")) {
+                event.preventDefault();
+                event.stopPropagation();
+                requestOpen(false);
+                return;
+            }
+            if (event.key === (rtl ? "ArrowLeft" : "ArrowRight")) {
+                const item = items.find(item => item.id === all[index]?.dataset.menuId);
+                if (item?.type === "submenu") {
+                    event.preventDefault();
+                    if (!item.disabled)
+                        showChild(item);
+                }
+                return;
+            }
+            let next = event.key === "Home" ? 0 : event.key === "End" ? all.length - 1 : event.key === "ArrowDown" ? (index + 1) % all.length : event.key === "ArrowUp" ? (index - 1 + all.length) % all.length : -1;
+            if (["ArrowDown", "ArrowUp", "Home", "End"].includes(event.key)) {
+                clearHover();
+                setOpenChild(undefined);
+                search.current = { text: "", time: 0 };
+            }
+            if (event.key.length === 1 && event.key !== " ") {
+                clearHover();
+                setOpenChild(undefined);
+                const now = Date.now();
+                search.current = { text: (now - search.current.time < 700 ? search.current.text : "") + event.key.toLocaleLowerCase(), time: now };
+                const text = Array.from(search.current.text).every(char => char === search.current.text[0]) ? search.current.text[0] : search.current.text;
+                const start = text.length === 1 ? index + 1 : Math.max(0, index);
+                next = Array.from({ length: all.length }, (_, offset) => (start + offset) % all.length).find(candidate => all[candidate].dataset.label?.toLocaleLowerCase().startsWith(text)) ?? -1;
+                event.preventDefault();
+            }
+            if (next >= 0 && all[next]) {
+                event.preventDefault();
+                all[next].focus({ preventScroll: true });
+                all[next].scrollIntoView({ block: "nearest", inline: "nearest" });
+            }
+        }, children: open && _jsx(ScrollArea, { orientation: "vertical", role: "group", tabIndex: -1, className: "flood-menu__viewport", children: rows }) });
+});
+export const ActionMenu = /* @__PURE__ */ forwardRef(function ActionMenu({ label, trigger, items, onAction, open: controlled, defaultOpen, onOpenChange, disabled, side = "bottom", align = "start", controlSize = "sm", ...props }, forwardedRef) {
+    if (!label.trim())
+        throw new Error("Flood Menu requires a nonempty label");
+    validateMenuTree(items);
+    const [local, setLocal] = useState(Boolean(defaultOpen)), requestedOpen = controlled ?? local;
+    const open = !disabled && requestedOpen;
+    const anchor = useRef(null), panel = useRef(null), edge = useRef("first");
+    const pending = useRef(undefined);
+    const current = useRef({ controlled, onOpenChange });
+    current.current = { controlled, onOpenChange };
+    const request = (next) => {
+        if (pending.current === next)
+            return;
+        pending.current = next;
+        queueMicrotask(() => { pending.current = undefined; });
+        if (current.current.controlled === undefined)
+            setLocal(next);
+        current.current.onOpenChange?.(next);
+    };
+    useImperativeHandle(forwardedRef, () => panel.current, []);
+    useEffect(() => { if (disabled && requestedOpen)
+        request(false); }, [disabled, requestedOpen]);
+    const setAnchor = useCallback((node) => { anchor.current = node; }, []);
+    const triggerProps = { ref: setAnchor, type: "button", disabled, "aria-haspopup": "menu", "aria-expanded": open,
+        onClick: () => { edge.current = "first"; request(!open); },
+        onKeyDown: event => {
+            if (event.defaultPrevented || disabled || event.altKey || event.ctrlKey || event.metaKey || !["ArrowDown", "ArrowUp"].includes(event.key))
+                return;
+            event.preventDefault();
+            edge.current = event.key === "ArrowUp" ? "last" : "first";
+            if (open && panel.current?.matches(":popover-open"))
+                focusMenuEdge(panel.current, edge.current);
+            else
+                request(true);
+        } };
+    const generated = useId(), id = props.id ?? `flood-menu-${generated}`;
+    triggerProps["aria-controls"] = id;
+    return _jsxs(_Fragment, { children: [trigger(triggerProps), _jsx(MenuLayer, { ...props, id: id, ref: panel, label: label, items: items, open: open, requestOpen: request, closeTree: () => request(false), anchor: () => anchor.current, rootAnchor: () => anchor.current, onAction: onAction, edge: () => edge.current, side: side, align: align, controlSize: controlSize })] });
 });

package/dist/navigation-layout.js

@@ -6,7 +6,7 @@ function uniqueValues(items, component) {
     if (items.some(item => !item.value.trim()) || new Set(items.map(item => item.value)).size !== items.length)
         throw new Error(`Flood ${component} items require unique nonempty values`);
 }
-export const NavigationMenu = forwardRef(function NavigationMenu({ items, label, currentValue, size = "md", className, ...props }, ref) {
+export const NavigationMenu = /* @__PURE__ */ forwardRef(function NavigationMenu({ items, label, currentValue, size = "md", className, ...props }, ref) {
     uniqueValues(items, "NavigationList");
     if (!label.trim() || items.some(item => !item.label.trim() || !item.href.trim()))
         throw new Error("Flood NavigationList requires a name and labelled links with destinations");
@@ -22,7 +22,7 @@ export const NavigationMenu = forwardRef(function NavigationMenu({ items, label,
     const links = (entries) => entries.map(item => _jsx("li", { children: _jsxs("a", { ...item.linkProps, href: item.href, "aria-current": item.value === currentValue ? "page" : undefined, className: classes("flood-navigation-list__link", item.linkProps?.className), children: [item.icon != null && _jsx(IconSlot, { size: size, children: item.icon }), _jsxs("span", { className: "flood-navigation-list__text", children: [_jsx("span", { className: "flood-navigation-list__label", children: item.label }), item.description && _jsx("span", { className: "flood-navigation-list__description", children: item.description })] })] }) }, item.value));
     return _jsx("nav", { ...props, ref: ref, "aria-label": label, className: classes("flood-navigation-list", className), "data-size": size, children: _jsx("ul", { role: "list", className: "flood-navigation-list__groups", children: groups.map((group, index) => group.label ? _jsxs("li", { className: "flood-navigation-list__group", children: [_jsx("p", { className: "flood-navigation-list__group-title", id: `${id}-${index}`, children: group.label }), _jsx("ul", { role: "list", "aria-labelledby": `${id}-${index}`, children: links(group.items) })] }, index) : links(group.items)) }) });
 });
-export const StepSequence = forwardRef(function StepSequence({ items, label, currentValue = items[0]?.value, orientation = "horizontal", onStepChange, statusLabels = { complete: "Completed", current: "Current step", upcoming: "Upcoming", error: "Needs attention" }, className, ...props }, ref) {
+export const StepSequence = /* @__PURE__ */ forwardRef(function StepSequence({ items, label, currentValue = items[0]?.value, orientation = "horizontal", onStepChange, statusLabels = { complete: "Completed", current: "Current step", upcoming: "Upcoming", error: "Needs attention" }, className, ...props }, ref) {
     uniqueValues(items, "Steps");
     if (!label.trim() || items.some(item => !item.title.trim()))
         throw new Error("Flood Steps requires a sequence name and step titles");
@@ -36,20 +36,20 @@ export const StepSequence = forwardRef(function StepSequence({ items, label, cur
             return _jsx("li", { "data-state": state, "aria-current": current ? "step" : undefined, children: onStepChange ? _jsx("button", { type: "button", className: "flood-steps__content flood-steps__action", disabled: item.disabled, onClick: () => onStepChange(item.value), children: content }) : _jsx("div", { className: "flood-steps__content", children: content }) }, item.value);
         }) });
 });
-export const ContentSection = forwardRef(function ContentSection({ title, description, actions, headingLevel = 2, headingSize = "section", children, id: explicitId, className, "aria-labelledby": labelledBy, ...props }, ref) {
+export const ContentSection = /* @__PURE__ */ forwardRef(function ContentSection({ title, description, actions, headingLevel = 2, headingSize = "section", children, id: explicitId, className, "aria-labelledby": labelledBy, ...props }, ref) {
     if (!title.trim() || ![2, 3, 4, 5, 6].includes(headingLevel))
         throw new Error("Flood Section requires a nonempty title and headingLevel from 2 to 6");
     const generated = useId(), headingId = `${explicitId ?? `flood-section-${generated}`}-title`;
     return _jsxs("section", { ...props, ref: ref, id: explicitId, "aria-labelledby": labelledBy ?? headingId, className: classes("flood-section", className), children: [_jsxs("header", { className: "flood-section__header", children: [_jsxs("div", { className: "flood-section__heading", children: [_jsx(Heading, { id: headingId, level: headingLevel, size: headingSize, className: "flood-section__title", children: title }), description != null && _jsx("div", { className: "flood-section__description", children: description })] }), actions != null && _jsx("div", { className: "flood-section__actions", children: actions })] }), children != null && _jsx("div", { className: "flood-section__body", children: children })] });
 });
-export const SplitLayout = forwardRef(function SplitLayout({ main, aside, side = "end", ratio = "main", collapseAt = "md", gap = "6", className, style, ...props }, ref) {
+export const SplitLayout = /* @__PURE__ */ forwardRef(function SplitLayout({ main, aside, side = "end", ratio = "main", collapseAt = "md", gap = "6", className, style, ...props }, ref) {
     const primary = _jsx("div", { className: "flood-split__main", children: main }, "main"), secondary = _jsx("div", { className: "flood-split__aside", children: aside }, "aside");
     return _jsx("div", { ...props, ref: ref, className: classes("flood-split", className), style: { "--flood-layout-gap": `var(--flood-sys-space-${gap})`, ...style }, children: _jsx("div", { className: "flood-split__layout", "data-side": side, "data-ratio": ratio, "data-collapse": collapseAt, children: side === "start" ? [secondary, primary] : [primary, secondary] }) });
 });
-export const CenterLayout = forwardRef(function CenterLayout({ inline = false, maxWidth, minHeight, className, style, children, ...props }, ref) {
+export const CenterLayout = /* @__PURE__ */ forwardRef(function CenterLayout({ inline = false, maxWidth, minHeight, className, style, children, ...props }, ref) {
     return _jsx("div", { ...props, ref: ref, className: classes("flood-center", className), "data-inline": inline || undefined, style: { minBlockSize: minHeight, "--flood-center-max": maxWidth, ...style }, children: _jsx("div", { className: "flood-center__content", children: children }) });
 });
-export const SkipNavigation = forwardRef(function SkipNavigation({ children = "Skip to content", className, onClick, href, ...props }, ref) {
+export const SkipNavigation = /* @__PURE__ */ forwardRef(function SkipNavigation({ children = "Skip to content", className, onClick, href, ...props }, ref) {
     if (!href.startsWith("#") || href.length < 2)
         throw new Error("Flood SkipLink requires a nonempty same-page fragment href");
     return _jsx("a", { ...props, ref: ref, href: href, className: classes("flood-skip-link", className), onClick: event => {

package/dist/navigation-tree.d.ts

@@ -0,0 +1,3 @@
+import type { NavigationTreeProps } from "./index.js";
+/** Ordinary website navigation uses disclosure lists, not application tree selection semantics. */
+export declare const HierarchicalNavigation: import("react").ForwardRefExoticComponent<NavigationTreeProps & import("react").RefAttributes<HTMLElement>>;

package/dist/navigation-tree.js

@@ -0,0 +1,98 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef, useEffect, useId, useImperativeHandle, useLayoutEffect, useRef, useState } from "react";
+import { IconButton, IconSlot, Link } from "./index.js";
+const useBrowserLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
+const branch = (item) => item.children !== undefined || item.content !== undefined;
+/** Ordinary website navigation uses disclosure lists, not application tree selection semantics. */
+export const HierarchicalNavigation = /* @__PURE__ */ forwardRef(function HierarchicalNavigation({ label, items, currentValue, expandedValues, defaultExpandedValues = [], onExpandedValuesChange, expandLabel = (item, expanded) => `${expanded ? "Collapse" : "Expand"} ${item.label}`, size = "md", id: explicitId, className, tabIndex = -1, ...props }, forwardedRef) {
+    if (!label.trim())
+        throw new Error("Flood NavigationTree requires a nonempty label");
+    const generated = useId(), id = explicitId ?? `flood-navigation-tree-${generated}`;
+    const root = useRef(null);
+    useImperativeHandle(forwardedRef, () => root.current, []);
+    const [local, setLocal] = useState(() => [...new Set(defaultExpandedValues)]);
+    const expanded = new Set(expandedValues ?? local);
+    const known = new Set(), visible = new Set();
+    const parents = new Map();
+    const pending = [{ items, shown: true, ancestors: new Set() }];
+    while (pending.length) {
+        const level = pending.pop();
+        if (level.ancestors.has(level.items))
+            throw new Error("Flood NavigationTree does not accept recursive item arrays");
+        const ancestors = new Set(level.ancestors);
+        ancestors.add(level.items);
+        for (const item of level.items) {
+            if (!item.value.trim() || !item.label.trim() || known.has(item.value))
+                throw new Error("Flood NavigationTree requires globally unique nonempty values and labels");
+            known.add(item.value);
+            parents.set(item.value, level.parent);
+            if (level.shown)
+                visible.add(item.value);
+            if (item.children)
+                pending.push({ items: item.children, parent: item.value, shown: level.shown && expanded.has(item.value), ancestors });
+        }
+    }
+    const latest = useRef({ visible, parents });
+    latest.current = { visible, parents };
+    const destinations = useRef(new Map());
+    const refs = useRef(new Map());
+    const refAncestors = useRef(new Map());
+    const repair = (removed, ancestors) => {
+        const active = removed.ownerDocument.activeElement;
+        if (!active || !removed.contains(active))
+            return;
+        for (const value of ancestors) {
+            const target = destinations.current.get(`disclosure:${value}`) ?? destinations.current.get(`link:${value}`);
+            if (latest.current.visible.has(value) && target?.isConnected && !target.matches(":disabled")) {
+                target.focus({ preventScroll: true });
+                return;
+            }
+        }
+        root.current?.focus({ preventScroll: true });
+    };
+    const bind = (key, ancestors) => {
+        refAncestors.current.set(key, ancestors);
+        if (!refs.current.has(key)) {
+            let previous = null;
+            refs.current.set(key, node => {
+                if (!node && previous)
+                    repair(previous, refAncestors.current.get(key) ?? []);
+                previous = node;
+                if (node)
+                    destinations.current.set(key, node);
+                else
+                    destinations.current.delete(key);
+            });
+        }
+        return refs.current.get(key);
+    };
+    useBrowserLayoutEffect(() => {
+        for (const key of refs.current.keys())
+            if (!known.has(key.slice(key.indexOf(":") + 1))) {
+                refs.current.delete(key);
+                refAncestors.current.delete(key);
+            }
+    }, [items]);
+    const toggle = (value) => {
+        const next = new Set(expandedValues ?? local);
+        if (next.has(value))
+            next.delete(value);
+        else
+            next.add(value);
+        const values = [...next];
+        if (expandedValues === undefined)
+            setLocal(values);
+        onExpandedValuesChange?.(values);
+    };
+    const render = (entries, ancestors = []) => entries.map(item => {
+        const open = expanded.has(item.value), expandable = branch(item), current = item.value === currentValue;
+        const contentId = `${id}-branch-${encodeURIComponent(item.value)}`;
+        const disclosureLabel = expandable ? expandLabel(item, open) : "";
+        if (expandable && !disclosureLabel.trim())
+            throw new Error("Flood NavigationTree disclosure labels must be nonempty");
+        const body = _jsxs(_Fragment, { children: [item.icon != null && _jsx(IconSlot, { size: size, children: item.icon }), _jsx("span", { className: "flood-navigation-tree__label", children: item.label })] });
+        return _jsxs("li", { children: [_jsxs("div", { className: "flood-navigation-tree__row", "data-current": current || undefined, children: [item.href !== undefined && !item.disabled ? _jsx(Link, { ...item.linkProps, href: item.href, ref: bind(`link:${item.value}`, ancestors), variant: "ghost", size: size, "aria-current": current ? "page" : undefined, className: ["flood-navigation-tree__link", item.linkProps?.className].filter(Boolean).join(" "), children: body })
+                            : _jsx("span", { className: "flood-navigation-tree__text", "aria-disabled": item.disabled || undefined, "aria-current": current ? "page" : undefined, children: body }), expandable && _jsx(IconButton, { ref: bind(`disclosure:${item.value}`, ancestors), variant: "ghost", size: size, label: disclosureLabel, className: "flood-navigation-tree__disclosure", disabled: item.disabled, "aria-expanded": open, "aria-controls": open ? contentId : undefined, onClick: () => toggle(item.value), children: _jsx("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "1.75", strokeLinecap: "round", strokeLinejoin: "round", children: _jsx("path", { d: "m9 5 7 7-7 7" }) }) })] }), expandable && open && _jsxs("div", { id: contentId, ref: bind(`group:${item.value}`, [item.value, ...ancestors]), className: "flood-navigation-tree__branch", children: [item.children && item.children.length > 0 && _jsx("ul", { children: render(item.children, [item.value, ...ancestors]) }), item.content != null && _jsx("div", { className: "flood-navigation-tree__content", children: item.content })] })] }, item.value);
+    });
+    return _jsx("nav", { ...props, ref: root, id: id, "aria-label": label, tabIndex: tabIndex, "data-size": size, className: ["flood-navigation-tree", className].filter(Boolean).join(" "), children: _jsx("ul", { children: render(items) }) });
+});