@dxos/react-ui-menu 0.9.0 → 0.9.1-main.c7dcc2e112

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/react-ui-menu",
-  "version": "0.9.0",
+  "version": "0.9.1-main.c7dcc2e112",
   "description": "Components for facilitating reactive and consistent menus.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -37,14 +37,14 @@
   "dependencies": {
     "@radix-ui/react-context": "1.1.1",
     "@radix-ui/react-use-controllable-state": "1.1.0",
-    "@dxos/app-graph": "0.9.0",
-    "@dxos/keyboard": "0.9.0",
-    "@dxos/invariant": "0.9.0",
-    "@dxos/react-ui-attention": "0.9.0",
-    "@dxos/log": "0.9.0",
-    "@dxos/effect": "0.9.0",
-    "@dxos/ui-types": "0.9.0",
-    "@dxos/util": "0.9.0"
+    "@dxos/app-graph": "0.9.1-main.c7dcc2e112",
+    "@dxos/effect": "0.9.1-main.c7dcc2e112",
+    "@dxos/invariant": "0.9.1-main.c7dcc2e112",
+    "@dxos/log": "0.9.1-main.c7dcc2e112",
+    "@dxos/react-ui-attention": "0.9.1-main.c7dcc2e112",
+    "@dxos/ui-types": "0.9.1-main.c7dcc2e112",
+    "@dxos/util": "0.9.1-main.c7dcc2e112",
+    "@dxos/keyboard": "0.9.1-main.c7dcc2e112"
   },
   "devDependencies": {
     "@effect-atom/atom-react": "^0.5.0",
@@ -57,10 +57,10 @@
     "react": "~19.2.3",
     "react-dom": "~19.2.3",
     "vite": "^8.0.16",
-    "@dxos/random": "0.9.0",
-    "@dxos/react-ui": "0.9.0",
-    "@dxos/storybook-utils": "0.9.0",
-    "@dxos/ui-theme": "0.9.0"
+    "@dxos/react-ui": "0.9.1-main.c7dcc2e112",
+    "@dxos/random": "0.9.1-main.c7dcc2e112",
+    "@dxos/ui-theme": "0.9.1-main.c7dcc2e112",
+    "@dxos/storybook-utils": "0.9.1-main.c7dcc2e112"
   },
   "peerDependencies": {
     "@effect-atom/atom-react": "^0.5.0",
@@ -68,8 +68,8 @@
     "effect": "3.21.3",
     "react": "~19.2.3",
     "react-dom": "~19.2.3",
-    "@dxos/react-ui": "0.9.0",
-    "@dxos/ui-theme": "0.9.0"
+    "@dxos/ui-theme": "0.9.1-main.c7dcc2e112",
+    "@dxos/react-ui": "0.9.1-main.c7dcc2e112"
   },
   "publishConfig": {
     "access": "public"

package/src/builder.test.ts

@@ -74,7 +74,7 @@ describe('MenuBuilder', () => {
   test('merges pre-built subgraph', ({ expect }) => {
     const headings = MenuBuilder.make()
       .root({ label: 'headings' })
-      .group('headings', { label: 'Headings', variant: 'dropdownMenu' }, (group) => {
+      .group('headings', { label: 'Headings', variant: 'dropdownMenu', icon: 'ph--text-h-one--regular' }, (group) => {
         group
           .action('h1', { label: 'H1', icon: 'ph--text-h-one--regular' }, () => {})
           .action('h2', { label: 'H2', icon: 'ph--text-h-two--regular' }, () => {});
@@ -115,11 +115,15 @@ describe('MenuBuilder', () => {
       .root({ label: 'toolbar' })
       .subgraph((sub) => {
         sub
-          .group('headings', { label: 'Headings', variant: 'dropdownMenu' }, (group) => {
-            group
-              .action('h1', { label: 'H1', icon: 'ph--text-h-one--regular' }, () => {})
-              .action('h2', { label: 'H2', icon: 'ph--text-h-two--regular' }, () => {});
-          })
+          .group(
+            'headings',
+            { label: 'Headings', variant: 'dropdownMenu', icon: 'ph--text-h-one--regular' },
+            (group) => {
+              group
+                .action('h1', { label: 'H1', icon: 'ph--text-h-one--regular' }, () => {})
+                .action('h2', { label: 'H2', icon: 'ph--text-h-two--regular' }, () => {});
+            },
+          )
           .group('formatting', { label: 'Formatting' }, (group) => {
             group.action('bold', { label: 'Bold', icon: 'ph--text-b--regular' }, () => {});
           });
@@ -160,11 +164,15 @@ describe('MenuBuilder', () => {
   test('composable curried subgraph functions', ({ expect }) => {
     // Simulates the curried pattern: addX(args) returns (builder) => void.
     const addHeadingsSection = () => (builder: import('./builder').ActionGroupBuilder) => {
-      builder.group('headings', { label: 'Headings', variant: 'dropdownMenu' }, (group) => {
-        group
-          .action('h1', { label: 'H1', icon: 'ph--text-h-one--regular' }, () => {})
-          .action('h2', { label: 'H2', icon: 'ph--text-h-two--regular' }, () => {});
-      });
+      builder.group(
+        'headings',
+        { label: 'Headings', variant: 'dropdownMenu', icon: 'ph--text-h-one--regular' },
+        (group) => {
+          group
+            .action('h1', { label: 'H1', icon: 'ph--text-h-one--regular' }, () => {})
+            .action('h2', { label: 'H2', icon: 'ph--text-h-two--regular' }, () => {});
+        },
+      );
     };
 
     const addFormattingSection = () => (builder: import('./builder').ActionGroupBuilder) => {
@@ -206,6 +214,37 @@ describe('MenuBuilder', () => {
     expect(graph.edges).toHaveLength(1);
   });
 
+  test('menu creates overflow dropdown with built-in trigger', ({ expect }) => {
+    const graph = MenuBuilder.make()
+      .root({ label: 'toolbar' })
+      .menu('more', (group) => {
+        group.action('save', { label: 'Save', icon: 'ph--cloud-arrow-up--regular' }, () => {});
+      })
+      .build();
+
+    const moreGroup = graph.nodes.find((node) => node.id === 'more');
+    expect(moreGroup).toBeDefined();
+    expect(moreGroup!.properties).toEqual({
+      label: ['toolbar-overflow.menu', { ns: '@dxos/react-ui-menu' }],
+      icon: 'ph--dots-three-vertical--regular',
+      iconOnly: true,
+      variant: 'dropdownMenu',
+      caretDown: false,
+    });
+    expect(graph.edges).toContainEqual({ source: 'root', target: 'more', relation: 'child' });
+    expect(graph.edges).toContainEqual({ source: 'more', target: 'save', relation: 'child' });
+  });
+
+  test('menu accepts custom group id', ({ expect }) => {
+    const graph = MenuBuilder.make()
+      .root({ label: 'toolbar' })
+      .menu('overflow', () => {})
+      .build();
+
+    expect(graph.nodes.find((node) => node.id === 'overflow')).toBeDefined();
+    expect(graph.nodes.find((node) => node.id === 'more')).toBeUndefined();
+  });
+
   test('nodes have correct types', ({ expect }) => {
     const graph = MenuBuilder.make()
       .root({ label: 'toolbar' })

package/src/builder.ts

@@ -3,12 +3,23 @@
 //
 
 import { invariant } from '@dxos/invariant';
-import type { MenuActionProperties, MenuItemGroupProperties } from '@dxos/ui-types';
+import type { DropdownMenuItemGroupProperties, MenuActionProperties, MenuItemGroupProperties } from '@dxos/ui-types';
+
+import { translationKey } from '#translations';
 
 import type { ActionGraphProps } from './hooks';
 import { MenuSeparatorType } from './types';
 import { createMenuAction, createMenuItemGroup } from './util';
 
+/** Default trigger for toolbar overflow (⋮) dropdown menus. */
+const overflowMenuProperties = {
+  label: ['toolbar-overflow.menu', { ns: translationKey }],
+  icon: 'ph--dots-three-vertical--regular',
+  iconOnly: true,
+  caretDown: false,
+  variant: 'dropdownMenu',
+} as const satisfies DropdownMenuItemGroupProperties;
+
 /** Callback that populates an action group builder. */
 export type ActionGroupBuilderFn = (builder: ActionGroupBuilder) => void;
 
@@ -31,7 +42,7 @@ export interface ActionGroupBuilder {
   action<P extends {} = {}>(id: string, props: P & MenuActionProperties, invoke: () => void): this;
 
   /** Add a nested action group. */
-  group<P extends {} = {}>(id: string, props: P & MenuItemGroupProperties, cb: ActionGroupBuilderFn): this;
+  group(id: string, props: MenuItemGroupProperties, cb: ActionGroupBuilderFn): this;
 
   /** Merge pre-built nodes and edges, or build a subgraph via callback scoped to the current group. Falsy values are ignored. */
   subgraph(subgraphOrCb: ActionGraphProps | ActionGroupBuilderFn | false | null | undefined): this;
@@ -42,10 +53,19 @@ export interface ActionGroupBuilder {
 
 /** Top-level builder that creates the root group and produces the final action graph. */
 export interface MenuBuilder extends ActionGroupBuilder {
-  /** Set properties on the root menu group. May only be called once. */
+  /**
+   * Set properties on the root menu group. May only be called once.
+   */
   root(props: MenuItemGroupProperties): this;
 
-  /** Return the assembled action graph. */
+  /**
+   * Add a root-level toolbar overflow dropdown (⋮) with built-in trigger styling.
+   */
+  menu(id: string, cb: ActionGroupBuilderFn): this;
+
+  /**
+   * Return the assembled action graph.
+   */
   build(): ActionGraphProps;
 }
 
@@ -74,13 +94,17 @@ class MenuBuilderImpl implements MenuBuilder {
     return this;
   }
 
-  group<P extends {} = {}>(id: string, props: P & MenuItemGroupProperties, cb: ActionGroupBuilderFn): this {
+  group(id: string, props: MenuItemGroupProperties, cb: ActionGroupBuilderFn): this {
     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: string, cb: ActionGroupBuilderFn): this {
+    return this.group(id, overflowMenuProperties, cb);
+  }
+
   subgraph(subgraphOrCb: ActionGraphProps | ActionGroupBuilderFn | false | null | undefined): this {
     if (!subgraphOrCb) {
       return this;

package/src/components/ActionLabel.tsx

@@ -8,13 +8,13 @@ import { type Node } from '@dxos/app-graph';
 import { keySymbols } from '@dxos/keyboard';
 import { type TFunction, toLocalizedString, useTranslation } from '@dxos/react-ui';
 import { mx } from '@dxos/ui-theme';
-import { type MenuActionProperties } from '@dxos/ui-types';
+import { type MenuActionProperties, type MenuItemChrome } from '@dxos/ui-types';
 
 import { translationKey } from '#translations';
 
 import { getShortcut } from '../util';
 
-type Action = Node.Action<MenuActionProperties> | Node.ActionGroup<Omit<MenuActionProperties, 'variant'>>;
+type Action = Node.Action<MenuActionProperties> | Node.ActionGroup<MenuItemChrome>;
 
 export const ActionLabel = ({ action }: { action: Action }) => {
   const { t } = useTranslation(translationKey);

package/src/components/Menu.tsx

@@ -14,8 +14,8 @@ import {
   type AddMenuItemsProps,
   type MenuAction,
   type MenuContextValue,
+  type MenuGroupContext,
   type MenuItem,
-  type MenuItemGroup,
   type MenuItems,
   type MenuItemsAccessor,
   type MenuItemsMap,
@@ -70,12 +70,7 @@ const MenuDropdownContext = createContext<MenuDropdownContextValue>({
 const DEFAULT_PRIORITY = 100;
 
 const sortMenuItems = (items: MenuItems[]) =>
-  [...items].sort((a, b) => {
-    if (a.priority !== b.priority) {
-      return a.priority - b.priority;
-    }
-    return a.id.localeCompare(b.id);
-  });
+  [...items].sort((a, b) => (a.priority !== b.priority ? a.priority - b.priority : a.id.localeCompare(b.id)));
 
 type MenuProviderProps = PropsWithChildren<Partial<MenuContextValue>>;
 
@@ -135,7 +130,7 @@ const MenuProvider = ({
 
 const resolveItems = (
   baseItems: MenuItem[] | null,
-  group: MenuItemGroup | undefined,
+  group: MenuGroupContext | undefined,
   entries: ReadonlyMap<string, MenuItems>,
 ): MenuItem[] | null => {
   const applicable = [...entries.values()].filter((entry) => !entry.groupFilter || entry.groupFilter(group));
@@ -171,7 +166,7 @@ const resolveItems = (
 //
 
 const useMenuItems = (
-  group?: MenuItemGroup,
+  group?: MenuGroupContext,
   propsItems?: MenuItem[],
   consumerName: string = 'useMenuItemConsumer',
   __menuScope?: Scope,
@@ -238,7 +233,7 @@ const MenuRoot = ({ children, open, defaultOpen, onOpenChange, caller, ...props
 //
 
 type MenuContentProps = {
-  group?: MenuItemGroup;
+  group?: MenuGroupContext;
   items?: MenuItem[];
   caller?: string;
 };

package/src/components/ToolbarMenu.tsx

@@ -4,42 +4,24 @@
 
 import React, { useCallback } from 'react';
 
-import { Icon, Toolbar as NaturalToolbar, type ToolbarRootProps, useTranslation } from '@dxos/react-ui';
+import { Toolbar as NaturalToolbar, type ToolbarRootProps, useTranslation } from '@dxos/react-ui';
 import { composable, composableProps } from '@dxos/react-ui';
 import { useAttention } from '@dxos/react-ui-attention';
-import { type MenuActionProperties } from '@dxos/ui-types';
+import { type DropdownMenuItemGroupProperties, type ToggleGroupMenuItemGroupProperties } from '@dxos/ui-types';
 
 import { translationKey } from '#translations';
 
-import {
-  type MenuAction,
-  type MenuItem,
-  type MenuItemGroup,
-  type MenuMultipleSelectActionGroup,
-  type MenuSingleSelectActionGroup,
-  isMenuGroup,
-  isSeparator,
-} from '../types';
+import { type MenuAction, type MenuItem, type MenuItemGroup, isMenuGroup, isSeparator } from '../types';
 import { executeMenuAction } from '../util';
 import { ActionLabel, actionLabel } from './ActionLabel';
 import { DropdownMenu } from './DropdownMenu';
 import { type MenuScopedProps, useMenuItems, useMenuScoped } from './Menu';
 
-export type ToolbarMenuDropdownMenuActionGroup = Omit<MenuActionProperties, 'variant' | 'icon'> & {
-  variant: 'dropdownMenu';
-  icon: string;
-  applyActive?: boolean;
-};
+export type ToolbarMenuDropdownMenuActionGroup = DropdownMenuItemGroupProperties;
 
-export type ToolbarMenuToggleGroupActionGroup = Omit<MenuActionProperties, 'variant'> & {
-  variant: 'toggleGroup';
-};
+export type ToolbarMenuToggleGroupActionGroup = ToggleGroupMenuItemGroupProperties;
 
-export type ToolbarMenuActionGroupProperties = (
-  | ToolbarMenuDropdownMenuActionGroup
-  | ToolbarMenuToggleGroupActionGroup
-) &
-  (MenuSingleSelectActionGroup | MenuMultipleSelectActionGroup);
+export type ToolbarMenuActionGroupProperties = DropdownMenuItemGroupProperties | ToggleGroupMenuItemGroupProperties;
 
 export type ToolbarMenuProps = ToolbarRootProps;
 
@@ -48,8 +30,18 @@ export type ToolbarMenuActionGroupProps = {
   items?: MenuItem[];
 };
 
+export type ToolbarMenuDropdownGroupProps = {
+  group: MenuItemGroup<DropdownMenuItemGroupProperties>;
+  items?: MenuItem[];
+};
+
+export type ToolbarMenuToggleGroupProps = {
+  group: MenuItemGroup<ToggleGroupMenuItemGroupProperties>;
+  items?: MenuItem[];
+};
+
 export type ToolbarMenuActionProps = {
-  group: MenuItemGroup<ToolbarMenuActionGroupProperties>;
+  group: MenuItemGroup<ToggleGroupMenuItemGroupProperties>;
   action: MenuAction;
 };
 
@@ -102,46 +94,54 @@ const DropdownMenuToolbarItem = ({
   __menuScope,
   group,
   items: propsItems,
-}: MenuScopedProps<ToolbarMenuActionGroupProps>) => {
-  const { iconOnly, disabled, testId } = group.properties;
+}: MenuScopedProps<ToolbarMenuDropdownGroupProps>) => {
   const { t } = useTranslation(translationKey);
   const { iconSize } = useMenuScoped('DropdownMenuToolbarItem', __menuScope);
   const items = useMenuItems(group, propsItems, 'DropdownMenuToolbarItem', __menuScope);
-  const activeItem = items?.find((item) => !!(item as MenuAction).properties.checked);
+  const {
+    iconOnly,
+    disabled,
+    testId,
+    applyActive,
+    caretDown = true,
+    icon: groupIcon,
+    iconClassNames: groupIconClassNames,
+  } = group.properties;
+  const activeItem = items?.find((item) => !!(item as MenuAction).properties.checked) as MenuAction | undefined;
   const icon =
-    ((group.properties as any).applyActive &&
+    (applyActive &&
       // TODO(thure): Handle other menu item types.
-      (activeItem as MenuAction)?.properties.icon) ||
-    group.properties.icon;
-  // Follow the same `applyActive` rule for `iconClassNames` so a per-item
-  // accent (e.g. tag colour) tracks the displayed icon.
-  const iconClassNames =
-    ((group.properties as any).applyActive && (activeItem as MenuAction)?.properties.iconClassNames) ||
-    (group.properties as { iconClassNames?: any }).iconClassNames;
-  const Root = icon ? NaturalToolbar.IconButton : NaturalToolbar.Button;
-  const labelAction = (group.properties as any).applyActive && activeItem ? (activeItem as MenuAction) : group;
-  const rootProps = icon
-    ? {
-        icon,
-        size: iconSize,
-        iconOnly,
-        iconClassNames,
-        label: actionLabel(labelAction, t),
-        caretDown: true,
-      }
-    : {
-        children: (
-          <>
-            <ActionLabel action={labelAction} />
-            <Icon size={3} icon='ph--caret-down--bold' classNames='ms-1' />
-          </>
-        ),
-      };
+      activeItem?.properties.icon) ||
+    groupIcon;
+  // Follow the same `applyActive` rule for `iconClassNames` so a per-item accent (e.g. tag colour) tracks the displayed icon.
+  const iconClassNames = (applyActive && activeItem?.properties.iconClassNames) || groupIconClassNames;
+  const labelAction = applyActive && activeItem ? activeItem : group;
 
   return (
     <DropdownMenu.Root group={group} items={items}>
       <DropdownMenu.Trigger asChild>
-        <Root variant='ghost' disabled={disabled} {...(rootProps as any)} {...(testId && { 'data-testid': testId })} />
+        {icon ? (
+          <NaturalToolbar.IconButton
+            variant='ghost'
+            disabled={disabled}
+            icon={icon}
+            size={iconSize}
+            iconOnly={iconOnly}
+            iconClassNames={iconClassNames}
+            label={actionLabel(labelAction, t)}
+            caretDown={caretDown}
+            {...(testId && { 'data-testid': testId })}
+          />
+        ) : (
+          <NaturalToolbar.Button
+            variant='ghost'
+            disabled={disabled}
+            caretDown={caretDown}
+            {...(testId && { 'data-testid': testId })}
+          >
+            <ActionLabel action={labelAction} />
+          </NaturalToolbar.Button>
+        )}
       </DropdownMenu.Trigger>
     </DropdownMenu.Root>
   );
@@ -189,7 +189,7 @@ const ToggleGroupToolbarItem = ({
   __menuScope,
   group,
   items: itemsProp,
-}: MenuScopedProps<ToolbarMenuActionGroupProps>) => {
+}: MenuScopedProps<ToolbarMenuToggleGroupProps>) => {
   const items = useMenuItems(group, itemsProp, 'ToggleGroupToolbarItem', __menuScope);
   const { selectCardinality } = group.properties;
 
@@ -244,17 +244,17 @@ const ToolbarMenuItem = ({ __menuScope, item }: MenuScopedProps<{ item: MenuItem
       return (
         <DropdownMenuToolbarItem
           __menuScope={__menuScope}
-          group={item as MenuItemGroup<ToolbarMenuActionGroupProperties>}
-        />
-      );
-    } else {
-      return (
-        <ToggleGroupToolbarItem
-          __menuScope={__menuScope}
-          group={item as MenuItemGroup<ToolbarMenuActionGroupProperties>}
+          group={item as MenuItemGroup<DropdownMenuItemGroupProperties>}
         />
       );
     }
+
+    return (
+      <ToggleGroupToolbarItem
+        __menuScope={__menuScope}
+        group={item as MenuItemGroup<ToggleGroupMenuItemGroupProperties>}
+      />
+    );
   }
 
   return <ActionToolbarItem __menuScope={__menuScope} action={item as MenuAction} />;

package/src/hooks/index.ts

@@ -2,4 +2,5 @@
 // Copyright 2025 DXOS.org
 //
 
+export * from './useGraphMenuActions';
 export * from './useMenuActions';

package/src/hooks/useGraphMenuActions.test.ts

@@ -0,0 +1,93 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import { describe, test } from 'vitest';
+
+import { Node } from '@dxos/app-graph';
+
+import { buildGraphMenu } from './useGraphMenuActions';
+
+const action = (id: string, properties: Record<string, any> = {}): Node.ActionLike => ({
+  id,
+  type: Node.ActionType,
+  properties,
+  data: () => Effect.void,
+});
+
+const group = (id: string, properties: Record<string, any> = {}): Node.ActionLike => ({
+  id,
+  type: Node.ActionGroupType,
+  properties,
+  data: Node.actionGroupSymbol,
+});
+
+const resolver =
+  (map: Record<string, Node.ActionLike[]>) =>
+  (id: string): Node.ActionLike[] =>
+    map[id] ?? [];
+
+describe('buildGraphMenu', () => {
+  test('flattens a node’s actions under the menu root', ({ expect }) => {
+    const resolve = resolver({ event: [action('delete'), action('save')] });
+    const { nodes, edges } = buildGraphMenu(resolve, 'event');
+
+    expect(nodes.map((node) => node.id)).toEqual(['delete', 'save']);
+    expect(edges).toEqual([
+      { source: Node.RootId, target: 'delete', relation: 'child' },
+      { source: Node.RootId, target: 'save', relation: 'child' },
+    ]);
+  });
+
+  test('expands nested action groups via their own id', ({ expect }) => {
+    const resolve = resolver({
+      event: [action('delete'), group('more')],
+      more: [action('archive'), action('export')],
+    });
+    const { nodes, edges } = buildGraphMenu(resolve, 'event');
+
+    // root → delete, root → more (group), more → archive, more → export.
+    expect(nodes.map((node) => node.id)).toEqual(['delete', 'more', 'archive', 'export']);
+    expect(edges).toEqual([
+      { source: Node.RootId, target: 'delete', relation: 'child' },
+      { source: Node.RootId, target: 'more', relation: 'child' },
+      { source: 'more', target: 'archive', relation: 'child' },
+      { source: 'more', target: 'export', relation: 'child' },
+    ]);
+  });
+
+  test('roots the actions at a supplied group', ({ expect }) => {
+    const resolve = resolver({ event: [action('delete')] });
+    const { edges } = buildGraphMenu(resolve, 'event', { rootId: 'overflow' });
+
+    expect(edges).toEqual([{ source: 'overflow', target: 'delete', relation: 'child' }]);
+  });
+
+  test('filters actions by predicate', ({ expect }) => {
+    const resolve = resolver({
+      event: [action('delete', { disposition: 'menu' }), action('hidden', { disposition: 'item' })],
+    });
+    const { nodes } = buildGraphMenu(resolve, 'event', {
+      filter: (node) => node.properties.disposition === 'menu',
+    });
+
+    expect(nodes.map((node) => node.id)).toEqual(['delete']);
+  });
+
+  test('keeps a shared action’s node once but records each edge, tolerating cycles', ({ expect }) => {
+    // `more` references itself; the node is emitted once while both inbound edges survive.
+    const resolve = resolver({
+      event: [group('more')],
+      more: [action('archive'), group('more')],
+    });
+    const { nodes, edges } = buildGraphMenu(resolve, 'event');
+
+    expect(nodes.map((node) => node.id)).toEqual(['more', 'archive']);
+    expect(edges).toEqual([
+      { source: Node.RootId, target: 'more', relation: 'child' },
+      { source: 'more', target: 'archive', relation: 'child' },
+      { source: 'more', target: 'more', relation: 'child' },
+    ]);
+  });
+});

package/src/hooks/useGraphMenuActions.ts

@@ -0,0 +1,96 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Atom } from '@effect-atom/atom-react';
+import { useMemo } from 'react';
+
+import { type Graph, Node } from '@dxos/app-graph';
+
+import {
+  type ActionGraphEdges,
+  type ActionGraphNodes,
+  type ActionGraphProps,
+  type MenuActions,
+  useMenuActions,
+} from './useMenuActions';
+
+export type GraphMenuOptions = {
+  /** Group the actions descend from. Defaults to the menu root (top-level toolbar items). */
+  rootId?: string;
+  /** Keep only the actions the predicate accepts (e.g. by `disposition`). */
+  filter?: (action: Node.ActionLike) => boolean;
+};
+
+/**
+ * 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).
+ */
+export const buildGraphMenu = (
+  resolve: (id: string) => Node.ActionLike[],
+  nodeId: string,
+  options: GraphMenuOptions = {},
+): ActionGraphProps => {
+  const { rootId = Node.RootId, filter } = options;
+  const nodes: ActionGraphNodes = [];
+  const edges: ActionGraphEdges = [];
+  const seen = new Set<string>();
+
+  const visit = (parentId: string, sourceId: string) => {
+    for (const action of resolve(sourceId)) {
+      if (filter && !filter(action)) {
+        continue;
+      }
+      // Always record the parent→child edge (a shared action may sit under multiple groups).
+      edges.push({ source: parentId, target: action.id, relation: 'child' });
+      if (seen.has(action.id)) {
+        continue;
+      }
+      seen.add(action.id);
+      nodes.push(action as ActionGraphNodes[number]);
+      // A group's children are the actions contributed for the group's own id.
+      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.
+ */
+export const graphActions = (
+  graph: Graph.ReadableGraph | undefined,
+  get: Atom.Context,
+  nodeId: string | undefined,
+  options?: GraphMenuOptions,
+): ActionGraphProps =>
+  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}.
+ */
+export const useGraphMenuActions = (
+  graph: Graph.ReadableGraph | undefined,
+  nodeId: string | undefined,
+  options?: GraphMenuOptions,
+): MenuActions => {
+  const atom = useMemo(
+    () => Atom.make((get) => graphActions(graph, get, nodeId, options)),
+    // `options` is expected to be stable; `rootId` participates since it reshapes the graph.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [graph, nodeId, options?.rootId],
+  );
+  return useMenuActions(atom);
+};