@dxos/react-ui-menu 0.10.0 → 0.11.0

package/dist/lib/index.mjs

@@ -0,0 +1,747 @@
+import { Atom, RegistryContext, useAtomValue } from "@effect-atom/atom-react";
+import { createContextScope } from "@radix-ui/react-context";
+import { createContext, useCallback, useContext, useMemo, useRef, useState } from "react";
+import { log } from "@dxos/log";
+import { keySymbols } from "@dxos/keyboard";
+import { DropdownMenu, Icon, Input, Toolbar, Tooltip, composable, composableProps, toLocalizedString, useTranslation } from "@dxos/react-ui";
+import * as Effect from "effect/Effect";
+import { Graph, Node } from "@dxos/app-graph";
+import { EffectEx } from "@dxos/effect";
+import { getHostPlatform } from "@dxos/util";
+import { useControllableState } from "@radix-ui/react-use-controllable-state";
+import { mx } from "@dxos/ui-theme";
+import { translationKey } from "#translations";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { useAttention } from "@dxos/react-ui-attention";
+import { Atom as Atom$1 } from "@effect-atom/atom";
+import { invariant } from "@dxos/invariant";
+//#region src/components/MenuContext.ts
+var __dxlog_file$1 = "/__w/dxos/dxos/packages/ui/react-ui-menu/src/components/MenuContext.ts";
+var MENU_NAME = "Menu";
+var [createMenuContext, createMenuScope] = createContextScope(MENU_NAME, []);
+var nullItemsAtom = Atom.make(null);
+var defaultItemsAccessor = () => nullItemsAtom;
+var menuContextDefaults = {
+	iconSize: 5,
+	items: defaultItemsAccessor,
+	onAction: void 0,
+	menuItemsAtom: Atom.make(/* @__PURE__ */ new Map()),
+	addMenuItems: () => {},
+	removeMenuItems: () => {}
+};
+var [MenuContextProvider, useMenuScoped] = createMenuContext(MENU_NAME, menuContextDefaults);
+var useMenuScope = createMenuScope();
+var MenuDropdownContext = createContext({ closeMenu: () => {} });
+var sortMenuItems = (items) => [...items].sort((a, b) => a.priority !== b.priority ? a.priority - b.priority : a.id.localeCompare(b.id));
+var resolveItems = (baseItems, group, entries) => {
+	const applicable = [...entries.values()].filter((entry) => !entry.groupFilter || entry.groupFilter(group));
+	if (applicable.length === 0) return baseItems;
+	const sorted = sortMenuItems(applicable);
+	const replacements = sorted.filter((entry) => entry.mode === "replacement");
+	if (replacements.length > 0) {
+		if (replacements.length > 1) log.warn("multiple replacement entries found", {
+			ids: replacements.map((r) => r.id).join(", "),
+			using: replacements[0].id
+		}, {
+			"~LogMeta": "~LogMeta",
+			F: __dxlog_file$1,
+			L: 84,
+			S: void 0
+		});
+		return replacements[0].items;
+	}
+	const additiveItems = sorted.filter((entry) => entry.mode === "additive").flatMap((entry) => entry.items);
+	if (!baseItems || baseItems.length === 0) return additiveItems.length > 0 ? additiveItems : null;
+	return [...baseItems, ...additiveItems];
+};
+var useMenuItems = (group, propsItems, consumerName = "useMenuItemConsumer", __menuScope) => {
+	const { items, menuItemsAtom } = useMenuScoped(consumerName, __menuScope);
+	const groupItems = useAtomValue(items(group));
+	const entries = useAtomValue(menuItemsAtom) ?? /* @__PURE__ */ new Map();
+	const baseItems = useMemo(() => propsItems ?? groupItems ?? null, [propsItems, groupItems]);
+	return useMemo(() => resolveItems(baseItems, group, entries), [
+		baseItems,
+		group,
+		entries
+	]) ?? void 0;
+};
+/** Returns the menu context without Radix scope. */
+var useMenu = (consumerName) => {
+	return useMenuScoped(consumerName, void 0);
+};
+//#endregion
+//#region src/util.ts
+/**
+* Execute a menu action's Effect with its captured context.
+* This provides the `_actionContext` layer if available.
+*/
+var executeMenuAction = async (action, params = {}) => {
+	let effect = action.data(params);
+	if (action._actionContext) effect = effect.pipe(Effect.provide(action._actionContext));
+	await EffectEx.runAndForwardErrors(effect);
+};
+var getShortcut = (action) => {
+	return typeof action.properties?.keyBinding === "string" ? action.properties.keyBinding : action.properties?.keyBinding?.[getHostPlatform()];
+};
+var createMenuAction = (id, invoke, properties) => ({
+	id,
+	type: Node.ActionType,
+	properties,
+	data: (params) => Effect.sync(() => invoke(params))
+});
+var createMenuItemGroup = (id, properties) => ({
+	id,
+	type: Node.ActionGroupType,
+	properties,
+	data: Node.actionGroupSymbol
+});
+var createGapSeparator = (id = "gap", source = "root") => ({
+	nodes: [{
+		id,
+		type: "@dxos/react-ui-toolbar/separator",
+		properties: { variant: "gap" },
+		data: void 0
+	}],
+	edges: [{
+		source,
+		target: id,
+		relation: "child"
+	}]
+});
+var createLineSeparator = (id = "line", source = "root") => ({
+	nodes: [{
+		id,
+		type: "@dxos/react-ui-toolbar/separator",
+		properties: { variant: "line" },
+		data: void 0
+	}],
+	edges: [{
+		source,
+		target: id,
+		relation: "child"
+	}]
+});
+//#endregion
+//#region src/components/action-label.ts
+var actionLabel = (action, t) => {
+	const shortcut = getShortcut(action);
+	return `${toLocalizedString(action.properties.label, t)}${shortcut ? ` (${keySymbols(shortcut).join("")})` : ""}`;
+};
+//#endregion
+//#region src/types.ts
+var MenuSeparatorType = "@dxos/react-ui-toolbar/separator";
+var isSeparator = (node) => node.type === MenuSeparatorType;
+var isMenuGroup = (node) => node.type === Node.ActionGroupType;
+//#endregion
+//#region src/components/ActionLabel.tsx
+var ActionLabel = ({ action }) => {
+	const { t } = useTranslation(translationKey);
+	const shortcut = getShortcut(action);
+	return /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx("span", {
+		className: "grow truncate",
+		children: toLocalizedString(action.properties.label, t)
+	}), shortcut && /* @__PURE__ */ jsx("span", {
+		className: mx("shrink-0", "text-description"),
+		children: keySymbols(shortcut).join("")
+	})] });
+};
+//#endregion
+//#region src/components/DropdownMenu.tsx
+var DropdownMenuItem = ({ item, group, onClick, __menuScope }) => {
+	const action = item;
+	const handleClick = useCallback((event) => onClick(action, event), [action, onClick]);
+	const { iconSize } = useMenuScoped("DropdownMenuItem", __menuScope);
+	const checkable = typeof action.properties?.checked === "boolean";
+	const role = group?.properties?.selectCardinality === "multiple" ? "menuitemcheckbox" : "menuitemradio";
+	return /* @__PURE__ */ jsxs(DropdownMenu.Item, {
+		onClick: handleClick,
+		classNames: "gap-2",
+		disabled: action.properties?.disabled,
+		...checkable && {
+			role,
+			"aria-checked": !!action.properties?.checked
+		},
+		...action.properties?.testId && { "data-testid": action.properties.testId },
+		children: [
+			action.properties?.icon && /* @__PURE__ */ jsx(Icon, {
+				icon: action.properties.icon,
+				size: iconSize,
+				classNames: mx(action.properties.spin && "animate-spin", action.properties.iconClassNames)
+			}),
+			/* @__PURE__ */ jsx(ActionLabel, { action }),
+			action.properties?.checked && /* @__PURE__ */ jsx(Icon, {
+				icon: "ph--check--regular",
+				size: iconSize,
+				classNames: "mis-auto"
+			})
+		]
+	});
+};
+var DropdownMenuRoot = ({ items: propsItems, group, open, defaultOpen, onOpenChange, caller, children, __menuScope, ...naturalProps }) => {
+	const [optionsMenuOpen, setOptionsMenuOpen] = useControllableState({
+		prop: open,
+		defaultProp: defaultOpen,
+		onChange: onOpenChange
+	});
+	const { onAction } = useMenuScoped("DropdownMenuRoot", __menuScope);
+	const handleActionClick = useCallback((action, event) => {
+		if (action.properties?.disabled) return;
+		event.stopPropagation();
+		setOptionsMenuOpen(false);
+		const params = {
+			parent: group,
+			caller,
+			modifiers: { shift: event.shiftKey }
+		};
+		if (onAction) onAction(action, params);
+		else executeMenuAction(action, params);
+	}, [
+		group,
+		caller,
+		onAction
+	]);
+	const items = useMenuItems(group, propsItems);
+	return /* @__PURE__ */ jsxs(DropdownMenu.Root, {
+		open: optionsMenuOpen,
+		onOpenChange: setOptionsMenuOpen,
+		...naturalProps,
+		children: [children, /* @__PURE__ */ jsx(DropdownMenu.Portal, { children: /* @__PURE__ */ jsxs(DropdownMenu.Content, { children: [/* @__PURE__ */ jsx(DropdownMenu.Viewport, { children: items?.map((item) => isSeparator(item) ? /* @__PURE__ */ jsx(DropdownMenu.Separator, {}, item.id) : /* @__PURE__ */ jsx(DropdownMenuItem, {
+			item,
+			group,
+			onClick: handleActionClick
+		}, item.id)) }), /* @__PURE__ */ jsx(DropdownMenu.Arrow, {})] }) })]
+	});
+};
+var DropdownMenu$1 = {
+	Root: DropdownMenuRoot,
+	Trigger: DropdownMenu.Trigger,
+	VirtualTrigger: DropdownMenu.VirtualTrigger
+};
+//#endregion
+//#region src/components/ToolbarMenu.tsx
+var ActionToolbarItem = ({ __menuScope, action }) => {
+	const { iconSize, onAction } = useMenuScoped("ActionToolbarItem", __menuScope);
+	const { t } = useTranslation(translationKey);
+	const [pending, setPending] = useState(false);
+	const pendingRef = useRef(false);
+	const { icon, iconOnly = true, disabled, testId, hidden, classNames, iconClassNames, spin } = action.properties;
+	const buttonVariant = action.properties.variant === "primary" ? "primary" : "ghost";
+	const handleClick = useCallback(() => {
+		if (pendingRef.current) return;
+		pendingRef.current = true;
+		setPending(true);
+		const done = () => {
+			pendingRef.current = false;
+			setPending(false);
+		};
+		if (onAction) Promise.resolve(onAction(action, {})).then(done, done);
+		else executeMenuAction(action).then(done, done);
+	}, [action, onAction]);
+	const commonProps = {
+		variant: buttonVariant,
+		disabled: disabled || pending,
+		classNames,
+		onClick: handleClick,
+		...testId && { "data-testid": testId }
+	};
+	if (hidden) return null;
+	return icon ? /* @__PURE__ */ jsx(Toolbar.IconButton, {
+		...commonProps,
+		icon,
+		size: iconSize,
+		iconOnly,
+		iconClassNames: mx(spin && "animate-spin", iconClassNames),
+		label: actionLabel(action, t)
+	}, action.id) : /* @__PURE__ */ jsx(Toolbar.Button, {
+		...commonProps,
+		children: /* @__PURE__ */ jsx(ActionLabel, { action })
+	}, action.id);
+};
+var SwitchToolbarItem = ({ __menuScope, action }) => {
+	const { onAction } = useMenuScoped("SwitchToolbarItem", __menuScope);
+	const { t } = useTranslation(translationKey);
+	const { label, iconOnly, disabled, testId, hidden, checked } = action.properties;
+	const labelStr = toLocalizedString(label, t);
+	const handleCheckedChange = useCallback(() => {
+		if (onAction) onAction(action, {});
+		else executeMenuAction(action);
+	}, [action, onAction]);
+	if (hidden) return null;
+	const switchInput = /* @__PURE__ */ jsx(Input.Switch, {
+		checked,
+		disabled,
+		"aria-label": iconOnly ? labelStr : void 0,
+		onCheckedChange: handleCheckedChange,
+		...testId && { "data-testid": testId }
+	});
+	return /* @__PURE__ */ jsxs(Input.Root, { children: [iconOnly ? /* @__PURE__ */ jsx(Tooltip.Trigger, {
+		asChild: true,
+		content: labelStr,
+		children: /* @__PURE__ */ jsx(Input.Block, { children: switchInput })
+	}) : /* @__PURE__ */ jsx(Input.Block, { children: switchInput }), !iconOnly && /* @__PURE__ */ jsx(Input.Label, { children: labelStr })] });
+};
+var DropdownMenuToolbarItem = ({ __menuScope, group, items: propsItems }) => {
+	const { t } = useTranslation(translationKey);
+	const { iconSize } = useMenuScoped("DropdownMenuToolbarItem", __menuScope);
+	const items = useMenuItems(group, propsItems, "DropdownMenuToolbarItem", __menuScope);
+	const { iconOnly, disabled, testId, applyActive, caretDown = true, icon: groupIcon, iconClassNames: groupIconClassNames, spin: groupSpin } = group.properties;
+	const activeItem = items?.find((item) => !!item.properties.checked);
+	const icon = applyActive && activeItem?.properties.icon || groupIcon;
+	const iconClassNames = applyActive && activeItem?.properties.iconClassNames || groupIconClassNames;
+	const spin = applyActive && activeItem?.properties.spin || groupSpin;
+	const labelAction = applyActive && activeItem ? activeItem : group;
+	return /* @__PURE__ */ jsx(DropdownMenu$1.Root, {
+		group,
+		items,
+		children: /* @__PURE__ */ jsx(DropdownMenu$1.Trigger, {
+			asChild: true,
+			children: icon ? /* @__PURE__ */ jsx(Toolbar.IconButton, {
+				variant: "ghost",
+				disabled,
+				icon,
+				size: iconSize,
+				iconOnly,
+				iconClassNames: mx(spin && "animate-spin", iconClassNames),
+				label: actionLabel(labelAction, t),
+				caretDown,
+				...testId && { "data-testid": testId }
+			}) : /* @__PURE__ */ jsx(Toolbar.Button, {
+				variant: "ghost",
+				disabled,
+				caretDown,
+				...testId && { "data-testid": testId },
+				children: /* @__PURE__ */ jsx(ActionLabel, { action: labelAction })
+			})
+		})
+	});
+};
+var ToggleGroupItem = ({ __menuScope, group, action }) => {
+	const { iconSize, onAction } = useMenuScoped("ToggleGroupItem", __menuScope);
+	const { t } = useTranslation(translationKey);
+	const { icon, iconOnly = true, disabled, testId, hidden, classNames, iconClassNames, spin } = action.properties;
+	const handleClick = useCallback(() => {
+		if (onAction) onAction(action, { parent: group });
+		else executeMenuAction(action, { parent: group });
+	}, [
+		action,
+		group,
+		onAction
+	]);
+	const commonProps = {
+		value: action.id,
+		disabled,
+		variant: "ghost",
+		classNames,
+		onClick: handleClick,
+		...testId && { "data-testid": testId }
+	};
+	return hidden ? null : icon ? /* @__PURE__ */ jsx(Toolbar.ToggleGroupIconItem, {
+		...commonProps,
+		icon,
+		size: iconSize,
+		iconOnly,
+		iconClassNames: mx(spin && "animate-spin", iconClassNames),
+		label: actionLabel(action, t)
+	}) : /* @__PURE__ */ jsx(Toolbar.ToggleGroupItem, {
+		...commonProps,
+		children: /* @__PURE__ */ jsx(ActionLabel, { action })
+	});
+};
+var ToggleGroupToolbarItem = ({ __menuScope, group, items: itemsProp }) => {
+	const items = useMenuItems(group, itemsProp, "ToggleGroupToolbarItem", __menuScope);
+	const { selectCardinality } = group.properties;
+	const children = items.map((action) => /* @__PURE__ */ jsx(ToggleGroupItem, {
+		group,
+		action
+	}, action.id));
+	if (selectCardinality === "multiple") return /* @__PURE__ */ jsx(Toolbar.ToggleGroup, {
+		type: "multiple",
+		value: group.properties.value,
+		children
+	});
+	else return /* @__PURE__ */ jsx(Toolbar.ToggleGroup, {
+		type: "single",
+		value: group.properties.value,
+		children
+	});
+};
+var ToolbarMenu = composable(({ __menuScope, children, ...props }, forwardedRef) => {
+	const items = useMenuItems(void 0, void 0, "ToolbarMenu", __menuScope);
+	const { attendableId, alwaysActive } = useMenuScoped("ToolbarMenu", __menuScope);
+	const { hasAttention } = useAttention(attendableId);
+	return /* @__PURE__ */ jsxs(Toolbar.Root, {
+		...composableProps(props, { classNames: attendableId }),
+		disabled: !alwaysActive && !hasAttention,
+		ref: forwardedRef,
+		children: [items?.map((item) => /* @__PURE__ */ jsx(ToolbarMenuItem, {
+			__menuScope,
+			item
+		}, item.id)), children]
+	});
+});
+var ToolbarMenuItem = ({ __menuScope, item }) => {
+	if (isSeparator(item)) return /* @__PURE__ */ jsx(Toolbar.Separator, { variant: item.properties.variant });
+	if (isMenuGroup(item)) {
+		if (item.properties.variant === "dropdownMenu") return /* @__PURE__ */ jsx(DropdownMenuToolbarItem, {
+			__menuScope,
+			group: item
+		});
+		return /* @__PURE__ */ jsx(ToggleGroupToolbarItem, {
+			__menuScope,
+			group: item
+		});
+	}
+	const action = item;
+	if (action.properties?.variant === "switch") return /* @__PURE__ */ jsx(SwitchToolbarItem, {
+		__menuScope,
+		action
+	});
+	if (action.properties?.variant === "custom" && action.properties.render) return /* @__PURE__ */ jsx(Fragment, { children: action.properties.render() });
+	return /* @__PURE__ */ jsx(ActionToolbarItem, {
+		__menuScope,
+		action
+	});
+};
+//#endregion
+//#region src/components/Menu.tsx
+var DEFAULT_PRIORITY = 100;
+var MenuProvider = ({ children, items = menuContextDefaults.items, iconSize = menuContextDefaults.iconSize, attendableId, alwaysActive, onAction }) => {
+	const { scope } = useMenuScope(void 0);
+	const registry = useContext(RegistryContext);
+	const menuItemsAtom = useMemo(() => Atom.make(/* @__PURE__ */ new Map()).pipe(Atom.keepAlive), []);
+	return /* @__PURE__ */ jsx(MenuContextProvider, {
+		items,
+		iconSize,
+		attendableId,
+		alwaysActive,
+		menuItemsAtom,
+		addMenuItems: useCallback((props) => {
+			const priority = props.priority ?? DEFAULT_PRIORITY;
+			const prev = registry.get(menuItemsAtom);
+			const next = new Map(prev);
+			next.set(props.id, {
+				...props,
+				priority
+			});
+			registry.set(menuItemsAtom, next);
+		}, [registry, menuItemsAtom]),
+		removeMenuItems: useCallback((id) => {
+			const prev = registry.get(menuItemsAtom);
+			const next = new Map(prev);
+			next.delete(id);
+			registry.set(menuItemsAtom, next);
+		}, [registry, menuItemsAtom]),
+		onAction,
+		scope,
+		children
+	});
+};
+/**
+* Menu context boundary.
+*
+* NOTE: This component is headless since it's root div has `contents`.
+*
+* Provides the menu context (action dispatch, contribution registry, icon size, etc.)
+* and an optional dropdown root for use with `Menu.Trigger` + `Menu.Content`.
+*/
+var MenuRoot = ({ children, open, defaultOpen, onOpenChange, caller, ...props }) => {
+	const [menuOpen, setMenuOpen] = useControllableState({
+		prop: open,
+		defaultProp: defaultOpen,
+		onChange: onOpenChange
+	});
+	const closeMenu = useCallback(() => setMenuOpen(false), [setMenuOpen]);
+	return /* @__PURE__ */ jsx(MenuProvider, {
+		...props,
+		children: /* @__PURE__ */ jsx(MenuDropdownContext.Provider, {
+			value: {
+				closeMenu,
+				caller
+			},
+			children: /* @__PURE__ */ jsx(DropdownMenu.Root, {
+				open: menuOpen,
+				onOpenChange: setMenuOpen,
+				children
+			})
+		})
+	});
+};
+var MenuContentItem = ({ item, onClick, __menuScope }) => {
+	const action = item;
+	const handleClick = useCallback((event) => onClick(action, event), [action, onClick]);
+	const { iconSize } = useMenuScoped("MenuContentItem", __menuScope);
+	return /* @__PURE__ */ jsxs(DropdownMenu.Item, {
+		onClick: handleClick,
+		classNames: "gap-2",
+		disabled: action.properties?.disabled,
+		...action.properties?.testId && { "data-testid": action.properties.testId },
+		children: [action.properties?.icon && /* @__PURE__ */ jsx(Icon, {
+			icon: action.properties.icon,
+			size: iconSize,
+			classNames: mx(action.properties.spin && "animate-spin", action.properties.iconClassNames)
+		}), /* @__PURE__ */ jsx(ActionLabel, { action })]
+	});
+};
+/**
+* Renders the dropdown menu portal, content, and graph-backed items.
+*
+* Must be a descendant of `Menu.Root`. Reads items via `useMenuItems` from the
+* nearest menu context, with optional `group`/`items` prop overrides.
+*/
+var MenuContent = ({ group, items: propsItems, caller: callerOverride, __menuScope }) => {
+	const { closeMenu, caller: contextCaller } = useContext(MenuDropdownContext);
+	const caller = callerOverride ?? contextCaller;
+	const { onAction } = useMenuScoped("MenuContent", __menuScope);
+	const resolvedItems = useMenuItems(group, propsItems, "MenuContent", __menuScope);
+	const handleActionClick = useCallback((action, event) => {
+		if (action.properties?.disabled) return;
+		event.stopPropagation();
+		closeMenu();
+		const params = {
+			parent: group,
+			caller,
+			modifiers: { shift: event.shiftKey }
+		};
+		if (onAction) onAction(action, params);
+		else executeMenuAction(action, params);
+	}, [
+		group,
+		caller,
+		onAction,
+		closeMenu
+	]);
+	return /* @__PURE__ */ jsx(DropdownMenu.Portal, { children: /* @__PURE__ */ jsxs(DropdownMenu.Content, { children: [/* @__PURE__ */ jsx(DropdownMenu.Viewport, { children: resolvedItems?.map((item) => isSeparator(item) ? /* @__PURE__ */ jsx(DropdownMenu.Separator, {}, item.id) : /* @__PURE__ */ jsx(MenuContentItem, {
+		item,
+		onClick: handleActionClick
+	}, item.id)) }), /* @__PURE__ */ jsx(DropdownMenu.Arrow, {})] }) });
+};
+/**
+* Primary namespace export for the menu system.
+*
+* - `Menu.Root` — context boundary (replaces `MenuProvider`); also provides a dropdown root.
+* - `Menu.Trigger` / `Menu.VirtualTrigger` — dropdown trigger (use with `Menu.Content`).
+* - `Menu.Content` — renders graph-backed dropdown items inside a portal.
+* - `Menu.Toolbar` — flat toolbar component with graph-backed item rendering.
+*/
+var Menu = {
+	Root: MenuRoot,
+	Trigger: DropdownMenu.Trigger,
+	Content: MenuContent,
+	VirtualTrigger: DropdownMenu.VirtualTrigger,
+	Toolbar: ToolbarMenu
+};
+//#endregion
+//#region src/presentation.ts
+/**
+* Merges an action's `presentation[surface]` chrome override (if any) into its properties, letting a
+* single action declare multiple dispositions yet render appropriately in each surface — e.g. a
+* primary toolbar button and a plain nav-tree row from the same definition.
+*/
+var applyPresentation = (action, surface) => {
+	const presentation = action.properties.presentation?.[surface];
+	if (!presentation) return action;
+	return {
+		...action,
+		properties: {
+			...action.properties,
+			...presentation
+		}
+	};
+};
+//#endregion
+//#region src/hooks/useMenuActions.ts
+var useMenuActions = (props) => {
+	const registry = useContext(RegistryContext);
+	const menuGraphProps = useAtomValue(props);
+	const graph = useMemo(() => {
+		const newGraph = Graph.make({ registry });
+		newGraph.pipe(Graph.addNodes(menuGraphProps.nodes), Graph.addEdges(menuGraphProps.edges));
+		return newGraph;
+	}, [registry, menuGraphProps]);
+	return { items: useCallback((group) => {
+		return graph.connections(group?.id || Node.RootId, "child");
+	}, [graph]) };
+};
+/**
+* Convenience wrapper around `useMenuActions` that creates the backing atom inline.
+* Pass a builder thunk and a dependency list — the hook memoizes `Atom.make(build)` and threads
+* it through `useMenuActions`. Saves the `useMemo(() => Atom.make(...), deps)` boilerplate when
+* the action graph is composed from local state (e.g. a toolbar driven by component state).
+*
+* Read reactive state via `get` inside the builder; `deps` should hold only stable references.
+*/
+var useMenuBuilder = (build, deps) => {
+	return useMenuActions(useMemo(() => Atom.make(build), deps));
+};
+//#endregion
+//#region src/hooks/useGraphMenuActions.ts
+/**
+* Flatten a node's contributed actions (and nested {@link Node.ActionGroup}s) into the
+* `{ nodes, edges }` an {@link useMenuActions} / `Menu` consumes. The action nodes are spliced
+* verbatim, so their Effect `data` (and captured `_actionContext`) execute via `executeMenuAction`
+* without any `onAction` wiring.
+*
+* Pure over a `resolve` function so it is testable without a live graph; `resolve(id)` returns the
+* direct actions for `id` (a node id at the top level, a group id when expanding a group).
+*/
+var buildGraphMenu = (resolve, nodeId, options = {}) => {
+	const { rootId = Node.RootId, filter, surface } = options;
+	const nodes = [];
+	const edges = [];
+	const seen = /* @__PURE__ */ new Set();
+	const visit = (parentId, sourceId) => {
+		for (const action of resolve(sourceId)) {
+			if (filter && !filter(action)) continue;
+			edges.push({
+				source: parentId,
+				target: action.id,
+				relation: "child"
+			});
+			if (seen.has(action.id)) continue;
+			seen.add(action.id);
+			nodes.push(surface ? applyPresentation(action, surface) : action);
+			if (Node.isActionGroup(action)) visit(action.id, action.id);
+		}
+	};
+	visit(rootId, nodeId);
+	return {
+		nodes,
+		edges
+	};
+};
+/**
+* Read a node's contributed actions from the app-graph as menu `ActionGraphProps`, for splicing into a
+* hand-built toolbar via `MenuBuilder.subgraph(graphActions(graph, get, nodeId))`. Reactive: reads the
+* graph's action atoms through `get`, so contributed actions appear/disappear as extensions update.
+*
+* @idiom org.dxos.react-ui-menu.graphActionsToolbar
+*   applies: Splicing a node's app-graph-contributed toolbar actions into a hand-built object toolbar
+*   instead-of: Reading `graph.actions(nodeId)` and filtering/wiring `nodes`/`edges` by hand in every toolbar
+*   uses: {@link graphActions}, {@link MenuBuilder}, {@link useMenuBuilder}
+*   related: org.dxos.react-ui-menu.toolbarMenu
+*/
+var graphActions = (graph, get, nodeId, options) => graph && nodeId ? buildGraphMenu((id) => get(graph.actions(id)), nodeId, options) : {
+	nodes: [],
+	edges: []
+};
+/**
+* Menu actions sourced entirely from a node's app-graph contributions — the common "show every action
+* the graph offers for this object" toolbar/menu. Compose with hand-built items via {@link graphActions}.
+*/
+var useGraphMenuActions = (graph, nodeId, options) => {
+	return useMenuActions(useMemo(() => Atom$1.make((get) => graphActions(graph, get, nodeId, options)), [
+		graph,
+		nodeId,
+		options?.rootId
+	]));
+};
+//#endregion
+//#region src/builder.ts
+var __dxlog_file = "/__w/dxos/dxos/packages/ui/react-ui-menu/src/builder.ts";
+/** Default trigger for toolbar overflow (⋮) dropdown menus. */
+var overflowMenuProperties = {
+	label: ["toolbar-overflow.menu", { ns: translationKey }],
+	icon: "ph--dots-three-vertical--regular",
+	iconOnly: true,
+	caretDown: false,
+	variant: "dropdownMenu"
+};
+var MenuBuilderImpl = class MenuBuilderImpl {
+	_data;
+	_rootId;
+	_separatorCount = 0;
+	constructor(_data, _rootId) {
+		this._data = _data;
+		this._rootId = _rootId;
+	}
+	root(props) {
+		invariant(this._rootId === "root", "Root group can only be at the top level", {
+			"~LogMeta": "~LogMeta",
+			F: __dxlog_file,
+			L: 84,
+			S: this,
+			A: ["this._rootId === 'root'", "'Root group can only be at the top level'"]
+		});
+		invariant(this._data.nodes.find((node) => node.id === "root") === void 0, "Root group can only be created once", {
+			"~LogMeta": "~LogMeta",
+			F: __dxlog_file,
+			L: 85,
+			S: this,
+			A: ["this._data.nodes.find((node) => node.id === 'root') === undefined", "'Root group can only be created once'"]
+		});
+		this._data.nodes.push(createMenuItemGroup("root", props));
+		return this;
+	}
+	build() {
+		return this._data;
+	}
+	action(id, props, invoke) {
+		this._data.nodes.push(createMenuAction(id, invoke, props));
+		this._data.edges.push({
+			source: this._rootId,
+			target: id,
+			relation: "child"
+		});
+		return this;
+	}
+	switch(id, props, invoke) {
+		return this.action(id, {
+			...props,
+			variant: "switch"
+		}, invoke);
+	}
+	group(id, props, cb) {
+		this._data.nodes.push(createMenuItemGroup(id, props));
+		this._data.edges.push({
+			source: this._rootId,
+			target: id,
+			relation: "child"
+		});
+		cb(new MenuBuilderImpl(this._data, id));
+		return this;
+	}
+	menu(id, cb, testId) {
+		return this.group(id, testId === void 0 ? overflowMenuProperties : {
+			...overflowMenuProperties,
+			testId
+		}, cb);
+	}
+	subgraph(subgraphOrCb) {
+		if (!subgraphOrCb) return this;
+		if (typeof subgraphOrCb === "function") subgraphOrCb(new MenuBuilderImpl(this._data, this._rootId));
+		else {
+			this._data.nodes.push(...subgraphOrCb.nodes);
+			this._data.edges.push(...subgraphOrCb.edges);
+		}
+		return this;
+	}
+	separator(variant = "gap") {
+		const id = `separator-${++this._separatorCount}`;
+		this._data.nodes.push({
+			id,
+			type: MenuSeparatorType,
+			properties: { variant },
+			data: void 0
+		});
+		this._data.edges.push({
+			source: this._rootId,
+			target: id,
+			relation: "child"
+		});
+		return this;
+	}
+};
+var MenuBuilder = Object.freeze({ make: () => new MenuBuilderImpl({
+	nodes: [],
+	edges: []
+}, "root") });
+//#endregion
+//#region src/toolbar.ts
+/** `disposition` value an action opts into to appear in an object toolbar (vs context-menu-only). */
+var TOOLBAR_DISPOSITION = "toolbar";
+/** Filter for {@link graphActions}: keeps only actions a producer opted into the toolbar. */
+var isToolbarAction = (action) => Node.hasDisposition(action, TOOLBAR_DISPOSITION);
+//#endregion
+export { Menu, MenuBuilder, MenuSeparatorType, TOOLBAR_DISPOSITION, actionLabel, applyPresentation, buildGraphMenu, createGapSeparator, createLineSeparator, createMenuAction, createMenuItemGroup, graphActions, isMenuGroup, isSeparator, isToolbarAction, menuContextDefaults, useGraphMenuActions, useMenu, useMenuActions, useMenuBuilder, useMenuItems, useMenuScoped };
+
+//# sourceMappingURL=index.mjs.map