@dxos/react-ui-menu 0.8.4-main.69d29f4 → 0.8.4-main.6fa680abb7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/react-ui-menu",
-  "version": "0.8.4-main.69d29f4",
+  "version": "0.8.4-main.6fa680abb7",
   "description": "Components for facilitating reactive and consistent menus.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -31,36 +31,39 @@
   "dependencies": {
     "@radix-ui/react-context": "1.1.1",
     "@radix-ui/react-use-controllable-state": "1.1.0",
-    "@dxos/app-graph": "0.8.4-main.69d29f4",
-    "@dxos/effect": "0.8.4-main.69d29f4",
-    "@dxos/invariant": "0.8.4-main.69d29f4",
-    "@dxos/keyboard": "0.8.4-main.69d29f4",
-    "@dxos/ui-types": "0.8.4-main.69d29f4",
-    "@dxos/react-ui-attention": "0.8.4-main.69d29f4",
-    "@dxos/util": "0.8.4-main.69d29f4"
+    "@dxos/app-graph": "0.8.4-main.6fa680abb7",
+    "@dxos/invariant": "0.8.4-main.6fa680abb7",
+    "@dxos/effect": "0.8.4-main.6fa680abb7",
+    "@dxos/react-ui-attention": "0.8.4-main.6fa680abb7",
+    "@dxos/ui-types": "0.8.4-main.6fa680abb7",
+    "@dxos/log": "0.8.4-main.6fa680abb7",
+    "@dxos/util": "0.8.4-main.6fa680abb7",
+    "@dxos/keyboard": "0.8.4-main.6fa680abb7"
   },
   "devDependencies": {
-    "@effect-atom/atom-react": "^0.4.6",
-    "@effect/platform": "0.93.6",
+    "@effect-atom/atom-react": "^0.5.0",
+    "@effect/platform": "0.94.4",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.0",
     "@types/react": "~19.2.7",
     "@types/react-dom": "~19.2.3",
-    "effect": "3.19.11",
+    "effect": "3.19.16",
     "react": "~19.2.3",
     "react-dom": "~19.2.3",
-    "vite": "7.1.9",
-    "@dxos/random": "0.8.4-main.69d29f4",
-    "@dxos/react-ui": "0.8.4-main.69d29f4",
-    "@dxos/ui-theme": "0.8.4-main.69d29f4",
-    "@dxos/storybook-utils": "0.8.4-main.69d29f4"
+    "vite": "^7.1.11",
+    "@dxos/random": "0.8.4-main.6fa680abb7",
+    "@dxos/react-ui": "0.8.4-main.6fa680abb7",
+    "@dxos/storybook-utils": "0.8.4-main.6fa680abb7",
+    "@dxos/ui-theme": "0.8.4-main.6fa680abb7"
   },
   "peerDependencies": {
-    "@effect-atom/atom-react": "^0.4.6",
-    "@effect/platform": "0.93.6",
-    "effect": "3.19.11",
+    "@effect-atom/atom-react": "^0.5.0",
+    "@effect/platform": "0.94.4",
+    "effect": "3.19.16",
     "react": "~19.2.3",
     "react-dom": "~19.2.3",
-    "@dxos/ui-theme": "0.8.4-main.69d29f4",
-    "@dxos/react-ui": "0.8.4-main.69d29f4"
+    "@dxos/react-ui": "0.8.4-main.6fa680abb7",
+    "@dxos/ui-theme": "0.8.4-main.6fa680abb7"
   },
   "publishConfig": {
     "access": "public"

package/src/builder.ts

@@ -6,15 +6,22 @@ import { invariant } from '@dxos/invariant';
 import type { MenuActionProperties, MenuItemGroupProperties } from '@dxos/ui-types';
 
 import type { ActionGraphProps } from './hooks';
+import { MenuSeparatorType } from './types';
 import { createMenuAction, createMenuItemGroup } from './util';
 
 export interface ActionGroupBuilder {
+  /** Add an action node as a child of the current group. */
   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: (builder: ActionGroupBuilder) => void,
   ): this;
+  /** Merge pre-built nodes and edges into this builder. */
+  subgraph(subgraph: ActionGraphProps): this;
+  /** Add a separator. */
+  separator(id?: string, variant?: 'gap' | 'line'): this;
 }
 
 export interface MenuBuilder extends ActionGroupBuilder {
@@ -22,11 +29,9 @@ export interface MenuBuilder extends ActionGroupBuilder {
   build(): ActionGraphProps;
 }
 
-export const MenuBuilder = Object.freeze({
-  make: (): MenuBuilder => new MenuBuilderImpl({ nodes: [], edges: [] }, 'root'),
-});
-
 class MenuBuilderImpl implements MenuBuilder {
+  private _separatorCount = 0;
+
   constructor(
     private readonly _data: ActionGraphProps,
     private readonly _rootId: string,
@@ -39,9 +44,13 @@ class MenuBuilderImpl implements MenuBuilder {
     return this;
   }
 
+  build(): ActionGraphProps {
+    return this._data;
+  }
+
   action<P extends {} = {}>(id: string, props: P & MenuActionProperties, invoke: () => void): this {
     this._data.nodes.push(createMenuAction(id, invoke, props));
-    this._data.edges.push({ source: this._rootId, target: id });
+    this._data.edges.push({ source: this._rootId, target: id, relation: 'child' });
     return this;
   }
 
@@ -51,12 +60,30 @@ class MenuBuilderImpl implements MenuBuilder {
     cb: (builder: ActionGroupBuilder) => void,
   ): this {
     this._data.nodes.push(createMenuItemGroup(id, props));
-    this._data.edges.push({ source: this._rootId, target: id });
+    this._data.edges.push({ source: this._rootId, target: id, relation: 'child' });
     cb(new MenuBuilderImpl(this._data, id));
     return this;
   }
 
-  build(): ActionGraphProps {
-    return this._data;
+  subgraph(subgraph: ActionGraphProps): this {
+    this._data.nodes.push(...subgraph.nodes);
+    this._data.edges.push(...subgraph.edges);
+    return this;
+  }
+
+  separator(id?: string, variant: 'gap' | 'line' = 'gap'): this {
+    id ??= `separator-${++this._separatorCount}`;
+    this._data.nodes.push({
+      id,
+      type: MenuSeparatorType,
+      properties: { variant },
+      data: undefined as never,
+    });
+    this._data.edges.push({ source: this._rootId, target: id, relation: 'child' });
+    return this;
   }
 }
+
+export const MenuBuilder = Object.freeze({
+  make: (): MenuBuilder => new MenuBuilderImpl({ nodes: [], edges: [] }, 'root'),
+});

package/src/components/ActionLabel.tsx

@@ -7,7 +7,7 @@ import React from 'react';
 import { type Node } from '@dxos/app-graph';
 import { keySymbols } from '@dxos/keyboard';
 import { type TFunction, toLocalizedString, useTranslation } from '@dxos/react-ui';
-import { descriptionText, mx } from '@dxos/ui-theme';
+import { mx } from '@dxos/ui-theme';
 import { type MenuActionProperties } from '@dxos/ui-types';
 
 import { translationKey } from '../translations';
@@ -21,7 +21,7 @@ export const ActionLabel = ({ action }: { action: Action }) => {
   return (
     <>
       <span className='grow truncate'>{toLocalizedString(action.properties!.label, t)}</span>
-      {shortcut && <span className={mx('shrink-0', descriptionText)}>{keySymbols(shortcut).join('')}</span>}
+      {shortcut && <span className={mx('shrink-0', 'text-description')}>{keySymbols(shortcut).join('')}</span>}
     </>
   );
 };

package/src/components/DropdownMenu.tsx

@@ -11,7 +11,7 @@ import { type MenuAction, type MenuItem, type MenuItemGroup } from '../types';
 import { executeMenuAction } from '../util';
 
 import { ActionLabel } from './ActionLabel';
-import { type MenuScopedProps, useMenu, useMenuItems } from './MenuContext';
+import { type MenuScopedProps, useMenuItems, useMenuScoped } from './Menu';
 
 export type DropdownMenuProps = DropdownMenuRootProps & {
   group?: MenuItemGroup;
@@ -30,7 +30,7 @@ const DropdownMenuItem = ({
   // TODO(thure): handle other items.
   const action = item as MenuAction;
   const handleClick = useCallback((event: MouseEvent) => onClick(action, event), [action, onClick]);
-  const { iconSize } = useMenu('DropdownMenuItem', __menuScope);
+  const { iconSize } = useMenuScoped('DropdownMenuItem', __menuScope);
   return (
     <NaturalDropdownMenu.Item
       onClick={handleClick}
@@ -61,7 +61,7 @@ const DropdownMenuRoot = ({
     onChange: onOpenChange,
   });
 
-  const { onAction } = useMenu('DropdownMenuRoot', __menuScope);
+  const { onAction } = useMenuScoped('DropdownMenuRoot', __menuScope);
 
   const handleActionClick = useCallback(
     (action: MenuAction, event: MouseEvent) => {

package/src/components/Menu.test.tsx

@@ -0,0 +1,448 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Atom } from '@effect-atom/atom-react';
+import { cleanup, render, renderHook, screen } from '@testing-library/react';
+import React, { type PropsWithChildren, useEffect } from 'react';
+import { afterEach, describe, test } from 'vitest';
+
+import { type MenuItem, type MenuItemsAccessor } from '../types';
+import { createMenuAction } from '../util';
+
+import { Menu, useMenu, useMenuItems } from './Menu';
+
+const TEST_CONTRIBUTOR = 'TestContributor';
+
+const createTestAction = (id: string, label: string): MenuItem =>
+  createMenuAction(id, () => {}, { label, icon: 'ph--star--regular' });
+
+const TestWrapper = ({ children }: PropsWithChildren) => {
+  return <Menu.Root>{children}</Menu.Root>;
+};
+
+const createTestWrapperWithBaseItems = (baseItems: MenuItem[]) => {
+  const baseItemsAtom = Atom.make<MenuItem[] | null>(baseItems);
+  const items: MenuItemsAccessor = () => baseItemsAtom;
+  return ({ children }: PropsWithChildren) => {
+    return <Menu.Root items={items}>{children}</Menu.Root>;
+  };
+};
+
+describe('Menu', () => {
+  afterEach(() => {
+    cleanup();
+  });
+
+  describe('imperative contribution API', () => {
+    test('contributes static items to menu', ({ expect }) => {
+      const contributedItems = [createTestAction('test-1', 'Test Action 1')];
+
+      const ContributorComponent = () => {
+        const menu = useMenu(TEST_CONTRIBUTOR);
+        useEffect(() => {
+          menu.addMenuItems({ id: 'test-contributor', mode: 'additive', items: contributedItems });
+          return () => menu.removeMenuItems('test-contributor');
+        }, [menu, contributedItems]);
+        return null;
+      };
+
+      const ConsumerComponent = () => {
+        const items = useMenuItems();
+        return (
+          <div data-testid='menu-items'>
+            {items?.map((item) => (
+              <div key={item.id} data-testid={`item-${item.id}`}>
+                {(item.properties as { label?: string })?.label}
+              </div>
+            ))}
+          </div>
+        );
+      };
+
+      render(
+        <TestWrapper>
+          <ContributorComponent />
+          <ConsumerComponent />
+        </TestWrapper>,
+      );
+
+      expect(screen.getByTestId('item-test-1')).toBeTruthy();
+      expect(screen.getByText('Test Action 1')).toBeTruthy();
+    });
+
+    test('contributes items that update when deps change', ({ expect }) => {
+      const ContributorComponent = ({ items }: { items: MenuItem[] }) => {
+        const menu = useMenu(TEST_CONTRIBUTOR);
+        useEffect(() => {
+          menu.addMenuItems({ id: 'reactive-contributor', mode: 'additive', items });
+          return () => menu.removeMenuItems('reactive-contributor');
+        }, [menu, items]);
+        return null;
+      };
+
+      const ConsumerComponent = () => {
+        const items = useMenuItems();
+        return (
+          <div data-testid='menu-items'>
+            {items?.map((item) => (
+              <div key={item.id} data-testid={`item-${item.id}`}>
+                {(item.properties as { label?: string })?.label}
+              </div>
+            ))}
+          </div>
+        );
+      };
+
+      const items = [createTestAction('reactive-1', 'Reactive 1')];
+      render(
+        <TestWrapper>
+          <ContributorComponent items={items} />
+          <ConsumerComponent />
+        </TestWrapper>,
+      );
+
+      expect(screen.getByTestId('item-reactive-1')).toBeTruthy();
+      expect(screen.getByText('Reactive 1')).toBeTruthy();
+    });
+
+    test('combines base items with contributions', ({ expect }) => {
+      const baseItems = [createTestAction('base-1', 'Base Action')];
+      const contributedItems = [createTestAction('contrib-1', 'Contributed Action')];
+
+      const ContributorComponent = () => {
+        const menu = useMenu(TEST_CONTRIBUTOR);
+        useEffect(() => {
+          menu.addMenuItems({ id: 'test-contributor', mode: 'additive', items: contributedItems });
+          return () => menu.removeMenuItems('test-contributor');
+        }, [menu, contributedItems]);
+        return null;
+      };
+
+      const ConsumerComponent = () => {
+        const items = useMenuItems();
+        return (
+          <div data-testid='menu-items'>
+            {items?.map((item) => (
+              <div key={item.id} data-testid={`item-${item.id}`}>
+                {(item.properties as { label?: string })?.label}
+              </div>
+            ))}
+          </div>
+        );
+      };
+
+      const WrapperWithBase = createTestWrapperWithBaseItems(baseItems);
+
+      render(
+        <WrapperWithBase>
+          <ContributorComponent />
+          <ConsumerComponent />
+        </WrapperWithBase>,
+      );
+
+      const menuItems = screen.getByTestId('menu-items');
+      expect(menuItems.children.length).toBe(2);
+      expect(screen.getByTestId('item-base-1')).toBeTruthy();
+      expect(screen.getByTestId('item-contrib-1')).toBeTruthy();
+    });
+
+    test('orders contributions by priority', ({ expect }) => {
+      const lowItems = [createTestAction('low', 'Low Priority')];
+      const highItems = [createTestAction('high', 'High Priority')];
+      const LowPriorityContributor = () => {
+        const menu = useMenu(TEST_CONTRIBUTOR);
+        useEffect(() => {
+          menu.addMenuItems({ id: 'low-priority', mode: 'additive', items: lowItems, priority: 200 });
+          return () => menu.removeMenuItems('low-priority');
+        }, [menu, lowItems]);
+        return null;
+      };
+
+      const HighPriorityContributor = () => {
+        const menu = useMenu(TEST_CONTRIBUTOR);
+        useEffect(() => {
+          menu.addMenuItems({ id: 'high-priority', mode: 'additive', items: highItems, priority: 50 });
+          return () => menu.removeMenuItems('high-priority');
+        }, [menu, highItems]);
+        return null;
+      };
+
+      const ConsumerComponent = () => {
+        const items = useMenuItems();
+        return (
+          <div data-testid='menu-items'>
+            {items?.map((item, index) => (
+              <div key={item.id} data-testid={`item-${index}`} data-item-id={item.id}>
+                {(item.properties as { label?: string })?.label}
+              </div>
+            ))}
+          </div>
+        );
+      };
+
+      render(
+        <TestWrapper>
+          <LowPriorityContributor />
+          <HighPriorityContributor />
+          <ConsumerComponent />
+        </TestWrapper>,
+      );
+
+      const firstItem = screen.getByTestId('item-0');
+      const secondItem = screen.getByTestId('item-1');
+
+      expect(firstItem.getAttribute('data-item-id')).toBe('high');
+      expect(secondItem.getAttribute('data-item-id')).toBe('low');
+    });
+
+    test('replacement mode overrides all items', ({ expect }) => {
+      const baseItems = [createTestAction('base-1', 'Base Action')];
+      const replacementItems = [createTestAction('replacement-1', 'Replacement Action')];
+
+      const ReplacementContributor = () => {
+        const menu = useMenu(TEST_CONTRIBUTOR);
+        useEffect(() => {
+          menu.addMenuItems({ id: 'replacement-contributor', mode: 'replacement', items: replacementItems });
+          return () => menu.removeMenuItems('replacement-contributor');
+        }, [menu, replacementItems]);
+        return null;
+      };
+
+      const ConsumerComponent = () => {
+        const items = useMenuItems();
+        return (
+          <div data-testid='menu-items'>
+            {items?.map((item) => (
+              <div key={item.id} data-testid={`item-${item.id}`}>
+                {(item.properties as { label?: string })?.label}
+              </div>
+            ))}
+          </div>
+        );
+      };
+
+      const WrapperWithBase = createTestWrapperWithBaseItems(baseItems);
+
+      render(
+        <WrapperWithBase>
+          <ReplacementContributor />
+          <ConsumerComponent />
+        </WrapperWithBase>,
+      );
+
+      expect(screen.queryByTestId('item-base-1')).toBeNull();
+      expect(screen.getByTestId('item-replacement-1')).toBeTruthy();
+    });
+
+    test('removeMenuItems on unmount clears contribution', ({ expect }) => {
+      const contributedItems = [createTestAction('unmount-test', 'Will Be Removed')];
+
+      const ContributorComponent = () => {
+        const menu = useMenu(TEST_CONTRIBUTOR);
+        useEffect(() => {
+          menu.addMenuItems({ id: 'unmount-contributor', mode: 'additive', items: contributedItems });
+          return () => menu.removeMenuItems('unmount-contributor');
+        }, [menu, contributedItems]);
+        return null;
+      };
+
+      const ConsumerComponent = () => {
+        const items = useMenuItems();
+        return (
+          <div data-testid='menu-items'>
+            {items?.map((item) => (
+              <div key={item.id} data-testid={`item-${item.id}`}>
+                {(item.properties as { label?: string })?.label}
+              </div>
+            ))}
+          </div>
+        );
+      };
+
+      const { rerender } = render(
+        <TestWrapper>
+          <ContributorComponent />
+          <ConsumerComponent />
+        </TestWrapper>,
+      );
+
+      expect(screen.getByTestId('item-unmount-test')).toBeTruthy();
+
+      rerender(
+        <TestWrapper>
+          <ConsumerComponent />
+        </TestWrapper>,
+      );
+
+      expect(screen.queryByTestId('item-unmount-test')).toBeNull();
+    });
+
+    test('deterministic ordering with same priority uses id', ({ expect }) => {
+      const itemsA = [createTestAction('item-a', 'Item A')];
+      const itemsB = [createTestAction('item-b', 'Item B')];
+      const ContributorA = () => {
+        const menu = useMenu(TEST_CONTRIBUTOR);
+        useEffect(() => {
+          menu.addMenuItems({ id: 'contributor-a', mode: 'additive', items: itemsA, priority: 100 });
+          return () => menu.removeMenuItems('contributor-a');
+        }, [menu, itemsA]);
+        return null;
+      };
+
+      const ContributorB = () => {
+        const menu = useMenu(TEST_CONTRIBUTOR);
+        useEffect(() => {
+          menu.addMenuItems({ id: 'contributor-b', mode: 'additive', items: itemsB, priority: 100 });
+          return () => menu.removeMenuItems('contributor-b');
+        }, [menu, itemsB]);
+        return null;
+      };
+
+      const ConsumerComponent = () => {
+        const items = useMenuItems();
+        return (
+          <div data-testid='menu-items'>
+            {items?.map((item, index) => (
+              <div key={item.id} data-testid={`item-${index}`} data-item-id={item.id}>
+                {(item.properties as { label?: string })?.label}
+              </div>
+            ))}
+          </div>
+        );
+      };
+
+      render(
+        <TestWrapper>
+          <ContributorB />
+          <ContributorA />
+          <ConsumerComponent />
+        </TestWrapper>,
+      );
+
+      const firstItem = screen.getByTestId('item-0');
+      const secondItem = screen.getByTestId('item-1');
+
+      expect(firstItem.getAttribute('data-item-id')).toBe('item-a');
+      expect(secondItem.getAttribute('data-item-id')).toBe('item-b');
+    });
+
+    test('groupFilter limits contribution to specific groups', ({ expect }) => {
+      const globalContributedItems = [createTestAction('global-item', 'Global Item')];
+      const groupFilteredItems = [createTestAction('group-item', 'Group Only Item')];
+
+      const GlobalContributor = () => {
+        const menu = useMenu(TEST_CONTRIBUTOR);
+        useEffect(() => {
+          menu.addMenuItems({ id: 'global-contributor', mode: 'additive', items: globalContributedItems });
+          return () => menu.removeMenuItems('global-contributor');
+        }, [menu, globalContributedItems]);
+        return null;
+      };
+
+      const FilteredContributor = () => {
+        const menu = useMenu(TEST_CONTRIBUTOR);
+        useEffect(() => {
+          menu.addMenuItems({
+            id: 'filtered-contributor',
+            mode: 'additive',
+            items: groupFilteredItems,
+            groupFilter: (group) => group?.id === 'special-group',
+          });
+          return () => menu.removeMenuItems('filtered-contributor');
+        }, [menu, groupFilteredItems]);
+        return null;
+      };
+
+      const RootConsumer = () => {
+        const items = useMenuItems();
+        return (
+          <div data-testid='root-items'>
+            {items?.map((item) => (
+              <div key={item.id} data-testid={`root-${item.id}`}>
+                {(item.properties as { label?: string })?.label}
+              </div>
+            ))}
+          </div>
+        );
+      };
+
+      render(
+        <TestWrapper>
+          <GlobalContributor />
+          <FilteredContributor />
+          <RootConsumer />
+        </TestWrapper>,
+      );
+
+      expect(screen.getByTestId('root-global-item')).toBeTruthy();
+      expect(screen.queryByTestId('root-group-item')).toBeNull();
+    });
+  });
+
+  describe('useMenuItems', () => {
+    test('returns undefined when no items available', ({ expect }) => {
+      const { result } = renderHook(() => useMenuItems(), { wrapper: TestWrapper });
+      expect(result.current).toBeUndefined();
+    });
+
+    test('returns base items from context', ({ expect }) => {
+      const baseItems = [createTestAction('context-item', 'Context Item')];
+      const wrapper = createTestWrapperWithBaseItems(baseItems);
+
+      const { result } = renderHook(() => useMenuItems(), { wrapper });
+      expect(result.current).toHaveLength(1);
+      expect(result.current?.[0].id).toBe('context-item');
+    });
+
+    test('props items take precedence over context items', ({ expect }) => {
+      const contextItems = [createTestAction('context-item', 'Context Item')];
+      const propsItems = [createTestAction('props-item', 'Props Item')];
+      const wrapper = createTestWrapperWithBaseItems(contextItems);
+
+      const { result } = renderHook(() => useMenuItems(undefined, propsItems), { wrapper });
+      expect(result.current).toHaveLength(1);
+      expect(result.current?.[0].id).toBe('props-item');
+    });
+
+    test('object-actions contribution pattern (navigate item) appears in useMenuItems', ({ expect }) => {
+      const navigateItem = createMenuAction('navigate', () => {}, {
+        label: 'Open',
+        icon: 'ph--arrow-square-out--regular',
+      });
+      const items = [navigateItem];
+
+      const ObjectActionsContributor = () => {
+        const menu = useMenu(TEST_CONTRIBUTOR);
+        useEffect(() => {
+          menu.addMenuItems({ id: 'object-actions', mode: 'additive', priority: 50, items });
+          return () => menu.removeMenuItems('object-actions');
+        }, [menu, items]);
+        return null;
+      };
+
+      const ConsumerComponent = () => {
+        const items = useMenuItems();
+        return (
+          <div data-testid='menu-items'>
+            {items?.map((item) => (
+              <div key={item.id} data-testid={`item-${item.id}`}>
+                {(item.properties as { label?: string })?.label}
+              </div>
+            ))}
+          </div>
+        );
+      };
+
+      render(
+        <TestWrapper>
+          <ObjectActionsContributor />
+          <ConsumerComponent />
+        </TestWrapper>,
+      );
+
+      expect(screen.getByTestId('item-navigate')).toBeTruthy();
+      expect(screen.getByText('Open')).toBeTruthy();
+    });
+  });
+});