@dxos/react-ui-menu 0.8.4-main.bc674ce → 0.8.4-main.c351d160a8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/react-ui-menu",
-  "version": "0.8.4-main.bc674ce",
+  "version": "0.8.4-main.c351d160a8",
   "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.bc674ce",
-    "@dxos/effect": "0.8.4-main.bc674ce",
-    "@dxos/keyboard": "0.8.4-main.bc674ce",
-    "@dxos/invariant": "0.8.4-main.bc674ce",
-    "@dxos/ui-types": "0.8.4-main.bc674ce",
-    "@dxos/react-ui-attention": "0.8.4-main.bc674ce",
-    "@dxos/util": "0.8.4-main.bc674ce"
+    "@dxos/app-graph": "0.8.4-main.c351d160a8",
+    "@dxos/effect": "0.8.4-main.c351d160a8",
+    "@dxos/invariant": "0.8.4-main.c351d160a8",
+    "@dxos/react-ui-attention": "0.8.4-main.c351d160a8",
+    "@dxos/keyboard": "0.8.4-main.c351d160a8",
+    "@dxos/log": "0.8.4-main.c351d160a8",
+    "@dxos/ui-types": "0.8.4-main.c351d160a8",
+    "@dxos/util": "0.8.4-main.c351d160a8"
   },
   "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.bc674ce",
-    "@dxos/react-ui": "0.8.4-main.bc674ce",
-    "@dxos/storybook-utils": "0.8.4-main.bc674ce",
-    "@dxos/ui-theme": "0.8.4-main.bc674ce"
+    "vite": "^7.1.11",
+    "@dxos/react-ui": "0.8.4-main.c351d160a8",
+    "@dxos/random": "0.8.4-main.c351d160a8",
+    "@dxos/storybook-utils": "0.8.4-main.c351d160a8",
+    "@dxos/ui-theme": "0.8.4-main.c351d160a8"
   },
   "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/react-ui": "0.8.4-main.bc674ce",
-    "@dxos/ui-theme": "0.8.4-main.bc674ce"
+    "@dxos/ui-theme": "0.8.4-main.c351d160a8",
+    "@dxos/react-ui": "0.8.4-main.c351d160a8"
   },
   "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.stories.tsx

@@ -0,0 +1,265 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Atom } from '@effect-atom/atom-react';
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { useEffect, useMemo, useState } from 'react';
+import { expect, userEvent, within } from 'storybook/test';
+
+import { Button, IconButton } from '@dxos/react-ui';
+import { withTheme } from '@dxos/react-ui/testing';
+import { withRegistry } from '@dxos/storybook-utils';
+
+import { Menu, useMenu } from '../components';
+import { type ActionGraphProps, useMenuActions } from '../hooks';
+import { createActions } from '../testing';
+import { translations } from '../translations';
+import { type MenuItem } from '../types';
+import { createMenuAction } from '../util';
+
+const STORY_NAME = 'StoryMenuItems';
+
+const meta = {
+  title: 'ui/react-ui-menu/MenuItems',
+  component: Menu.Root,
+  decorators: [withTheme(), withRegistry],
+  parameters: {
+    translations,
+  },
+} satisfies Meta<typeof Menu.Root>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+const createBaseActionsAtom = (count = 3) => {
+  const actions = createActions({ count });
+  return Atom.make<ActionGraphProps>({
+    nodes: actions,
+    edges: actions.map((action) => ({ source: 'root', target: action.id, relation: 'child' })),
+  }).pipe(Atom.keepAlive);
+};
+
+const openDropdown = async (canvasElement: HTMLElement) => {
+  const canvas = within(canvasElement);
+  const trigger = canvas.getByRole('button', { name: /options/i });
+  await userEvent.click(trigger);
+  const body = within(document.body);
+  return body;
+};
+
+const StaticItemsProvider = () => {
+  const menu = useMenu(STORY_NAME);
+  const items: MenuItem[] = useMemo(
+    () => [
+      createMenuAction('static-1', () => {}, {
+        label: 'Static Action 1',
+        icon: 'ph--star--regular',
+      }),
+      createMenuAction('static-2', () => {}, {
+        label: 'Static Action 2',
+        icon: 'ph--heart--regular',
+      }),
+    ],
+    [],
+  );
+
+  useEffect(() => {
+    menu.addMenuItems({ id: 'static-items', mode: 'additive', items });
+    return () => menu.removeMenuItems('static-items');
+  }, [menu, items]);
+
+  return null;
+};
+
+export const StaticItems: Story = {
+  render: () => {
+    const actionsAtom = useMemo(() => createBaseActionsAtom(2), []);
+    const menuActions = useMenuActions(actionsAtom);
+
+    return (
+      <Menu.Root {...menuActions}>
+        <StaticItemsProvider />
+        <Menu.Trigger asChild>
+          <IconButton icon='ph--list-checks--regular' label='Options' />
+        </Menu.Trigger>
+        <Menu.Content />
+      </Menu.Root>
+    );
+  },
+  play: async ({ canvasElement }) => {
+    const body = await openDropdown(canvasElement);
+    const items = await body.findAllByRole('menuitem');
+    const labels = items.map((el) => el.textContent);
+    await expect(labels).toContain('Static Action 1');
+    await expect(labels).toContain('Static Action 2');
+  },
+};
+
+const ReactiveItemsProvider = ({ items }: { items: MenuItem[] }) => {
+  const menu = useMenu(STORY_NAME);
+
+  useEffect(() => {
+    menu.addMenuItems({ id: 'reactive-items', mode: 'additive', priority: 50, items });
+    return () => menu.removeMenuItems('reactive-items');
+  }, [menu, items]);
+
+  return null;
+};
+
+export const ReactiveItems: Story = {
+  render: () => {
+    const actionsAtom = useMemo(() => createBaseActionsAtom(2), []);
+    const [count, setCount] = useState(1);
+    const reactiveItems: MenuItem[] = useMemo(
+      () => [
+        createMenuAction('reactive-1', () => {}, {
+          label: `Reactive Action (${count})`,
+          icon: 'ph--lightning--regular',
+        }),
+      ],
+      [count],
+    );
+
+    const menuActions = useMenuActions(actionsAtom);
+
+    return (
+      <div className='flex flex-col gap-4'>
+        <Menu.Root {...menuActions}>
+          <ReactiveItemsProvider items={reactiveItems} />
+          <Menu.Trigger asChild>
+            <IconButton icon='ph--list-checks--regular' label='Options' />
+          </Menu.Trigger>
+          <Menu.Content />
+        </Menu.Root>
+        <Button data-testid='update-button' onClick={() => setCount((prev) => prev + 1)}>
+          Update Reactive Item ({count})
+        </Button>
+      </div>
+    );
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    const body = await openDropdown(canvasElement);
+    const items = await body.findAllByRole('menuitem');
+    await expect(items.map((el) => el.textContent)).toContain('Reactive Action (1)');
+
+    await userEvent.keyboard('{Escape}');
+    const updateButton = canvas.getByTestId('update-button');
+    await userEvent.click(updateButton);
+
+    const body2 = await openDropdown(canvasElement);
+    const updatedItems = await body2.findAllByRole('menuitem');
+    await expect(updatedItems.map((el) => el.textContent)).toContain('Reactive Action (2)');
+  },
+};
+
+const ReplacementItemsProvider = () => {
+  const menu = useMenu(STORY_NAME);
+  const items: MenuItem[] = useMemo(
+    () => [
+      createMenuAction('replacement-1', () => {}, {
+        label: 'Replacement Only',
+        icon: 'ph--swap--regular',
+      }),
+    ],
+    [],
+  );
+
+  useEffect(() => {
+    menu.addMenuItems({ id: 'replacement-items', mode: 'replacement', items });
+    return () => menu.removeMenuItems('replacement-items');
+  }, [menu, items]);
+
+  return null;
+};
+
+export const ReplacementMode: Story = {
+  render: () => {
+    const actionsAtom = useMemo(() => createBaseActionsAtom(5), []);
+    const menuActions = useMenuActions(actionsAtom);
+
+    return (
+      <Menu.Root {...menuActions}>
+        <ReplacementItemsProvider />
+        <Menu.Trigger asChild>
+          <IconButton icon='ph--list-checks--regular' label='Options (replaced)' />
+        </Menu.Trigger>
+        <Menu.Content />
+      </Menu.Root>
+    );
+  },
+  play: async ({ canvasElement }) => {
+    const body = await openDropdown(canvasElement);
+    const items = await body.findAllByRole('menuitem');
+    await expect(items).toHaveLength(1);
+    await expect(items[0].textContent).toBe('Replacement Only');
+  },
+};
+
+const LowPriorityItemsProvider = () => {
+  const menu = useMenu(STORY_NAME);
+  const items: MenuItem[] = useMemo(
+    () => [
+      createMenuAction('low-priority', () => {}, {
+        label: 'Low Priority (150)',
+        icon: 'ph--arrow-down--regular',
+      }),
+    ],
+    [],
+  );
+
+  useEffect(() => {
+    menu.addMenuItems({ id: 'low-priority-items', mode: 'additive', items, priority: 150 });
+    return () => menu.removeMenuItems('low-priority-items');
+  }, [menu, items]);
+
+  return null;
+};
+
+const HighPriorityItemsProvider = () => {
+  const menu = useMenu(STORY_NAME);
+  const items: MenuItem[] = useMemo(
+    () => [
+      createMenuAction('high-priority', () => {}, {
+        label: 'High Priority (50)',
+        icon: 'ph--arrow-up--regular',
+      }),
+    ],
+    [],
+  );
+
+  useEffect(() => {
+    menu.addMenuItems({ id: 'high-priority-items', mode: 'additive', items, priority: 50 });
+    return () => menu.removeMenuItems('high-priority-items');
+  }, [menu, items]);
+
+  return null;
+};
+
+export const PriorityOrdering: Story = {
+  render: () => {
+    const actionsAtom = useMemo(() => createBaseActionsAtom(0), []);
+    const menuActions = useMenuActions(actionsAtom);
+
+    return (
+      <Menu.Root {...menuActions}>
+        <LowPriorityItemsProvider />
+        <HighPriorityItemsProvider />
+        <Menu.Trigger asChild>
+          <IconButton icon='ph--list-checks--regular' label='Options (priority ordered)' />
+        </Menu.Trigger>
+        <Menu.Content />
+      </Menu.Root>
+    );
+  },
+  play: async ({ canvasElement }) => {
+    const body = await openDropdown(canvasElement);
+    const items = await body.findAllByRole('menuitem');
+    await expect(items).toHaveLength(2);
+    await expect(items[0].textContent).toBe('High Priority (50)');
+    await expect(items[1].textContent).toBe('Low Priority (150)');
+  },
+};