@dxos/react-ui-menu 0.8.4-main.f5c0578 → 0.8.4-main.fcfe5033a5

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "@dxos/react-ui-menu",
-  "version": "0.8.4-main.f5c0578",
+  "version": "0.8.4-main.fcfe5033a5",
   "description": "Components for facilitating reactive and consistent menus.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dxos/dxos"
+  },
   "license": "MIT",
   "author": "DXOS.org",
-  "sideEffects": true,
+  "sideEffects": false,
   "type": "module",
   "exports": {
     ".": {
@@ -25,39 +29,41 @@
     "src"
   ],
   "dependencies": {
-    "@preact-signals/safe-react": "^0.9.0",
-    "@preact/signals-react": "^3.2.0",
     "@radix-ui/react-context": "1.1.1",
     "@radix-ui/react-use-controllable-state": "1.1.0",
-    "@dxos/app-graph": "0.8.4-main.f5c0578",
-    "@dxos/invariant": "0.8.4-main.f5c0578",
-    "@dxos/keyboard": "0.8.4-main.f5c0578",
-    "@dxos/util": "0.8.4-main.f5c0578",
-    "@dxos/react-ui-attention": "0.8.4-main.f5c0578"
+    "@dxos/app-graph": "0.8.4-main.fcfe5033a5",
+    "@dxos/effect": "0.8.4-main.fcfe5033a5",
+    "@dxos/invariant": "0.8.4-main.fcfe5033a5",
+    "@dxos/keyboard": "0.8.4-main.fcfe5033a5",
+    "@dxos/react-ui-attention": "0.8.4-main.fcfe5033a5",
+    "@dxos/ui-types": "0.8.4-main.fcfe5033a5",
+    "@dxos/util": "0.8.4-main.fcfe5033a5",
+    "@dxos/log": "0.8.4-main.fcfe5033a5"
   },
   "devDependencies": {
-    "@effect-rx/rx-react": "0.38.0",
-    "@effect/platform": "0.90.2",
-    "@types/react": "~18.2.0",
-    "@types/react-dom": "~18.2.0",
-    "effect": "3.17.7",
-    "react": "~18.2.0",
-    "react-dom": "~18.2.0",
-    "vite": "5.4.7",
-    "@dxos/live-object": "0.8.4-main.f5c0578",
-    "@dxos/random": "0.8.4-main.f5c0578",
-    "@dxos/react-ui": "0.8.4-main.f5c0578",
-    "@dxos/react-ui-theme": "0.8.4-main.f5c0578",
-    "@dxos/storybook-utils": "0.8.4-main.f5c0578"
+    "@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.20.0",
+    "react": "~19.2.3",
+    "react-dom": "~19.2.3",
+    "vite": "^7.1.11",
+    "@dxos/random": "0.8.4-main.fcfe5033a5",
+    "@dxos/react-ui": "0.8.4-main.fcfe5033a5",
+    "@dxos/storybook-utils": "0.8.4-main.fcfe5033a5",
+    "@dxos/ui-theme": "0.8.4-main.fcfe5033a5"
   },
   "peerDependencies": {
-    "@effect-rx/rx-react": "^0.34.1",
-    "@effect/platform": "^0.80.12",
-    "effect": "^3.13.3",
-    "react": "~18.2.0",
-    "react-dom": "~18.2.0",
-    "@dxos/react-ui": "0.8.4-main.f5c0578",
-    "@dxos/react-ui-theme": "0.8.4-main.f5c0578"
+    "@effect-atom/atom-react": "^0.5.0",
+    "@effect/platform": "0.94.4",
+    "effect": "3.20.0",
+    "react": "~19.2.3",
+    "react-dom": "~19.2.3",
+    "@dxos/react-ui": "0.8.4-main.fcfe5033a5",
+    "@dxos/ui-theme": "0.8.4-main.fcfe5033a5"
   },
   "publishConfig": {
     "access": "public"

package/src/builder.test.ts

@@ -0,0 +1,224 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { Node } from '@dxos/app-graph';
+
+import { MenuBuilder } from './builder';
+import { MenuSeparatorType } from './types';
+
+describe('MenuBuilder', () => {
+  test('builds a flat menu with actions', ({ expect }) => {
+    const graph = MenuBuilder.make()
+      .root({ label: 'toolbar' })
+      .action('bold', { label: 'Bold', icon: 'ph--text-b--regular' }, () => {})
+      .action('italic', { label: 'Italic', icon: 'ph--text-italic--regular' }, () => {})
+      .build();
+
+    expect(graph.nodes).toHaveLength(3);
+    expect(graph.edges).toHaveLength(2);
+    expect(graph.edges).toEqual([
+      { source: 'root', target: 'bold', relation: 'child' },
+      { source: 'root', target: 'italic', relation: 'child' },
+    ]);
+  });
+
+  test('builds nested groups', ({ expect }) => {
+    const graph = MenuBuilder.make()
+      .root({ label: 'toolbar' })
+      .group('formatting', { label: 'Formatting' }, (group) => {
+        group
+          .action('bold', { label: 'Bold', icon: 'ph--text-b--regular' }, () => {})
+          .action('italic', { label: 'Italic', icon: 'ph--text-italic--regular' }, () => {});
+      })
+      .build();
+
+    expect(graph.nodes).toHaveLength(4);
+    expect(graph.edges).toEqual([
+      { source: 'root', target: 'formatting', relation: 'child' },
+      { source: 'formatting', target: 'bold', relation: 'child' },
+      { source: 'formatting', target: 'italic', relation: 'child' },
+    ]);
+  });
+
+  test('builds deeply nested hierarchy', ({ expect }) => {
+    const graph = MenuBuilder.make()
+      .root({ label: 'toolbar' })
+      .group('text', { label: 'Text' }, (text) => {
+        text
+          .group('headings', { label: 'Headings' }, (headings) => {
+            headings
+              .action('h1', { label: 'Heading 1', icon: 'ph--text-h-one--regular' }, () => {})
+              .action('h2', { label: 'Heading 2', icon: 'ph--text-h-two--regular' }, () => {});
+          })
+          .group('formatting', { label: 'Formatting' }, (formatting) => {
+            formatting.action('bold', { label: 'Bold', icon: 'ph--text-b--regular' }, () => {});
+          });
+      })
+      .build();
+
+    // root + text + headings + h1 + h2 + formatting + bold = 7 nodes.
+    expect(graph.nodes).toHaveLength(7);
+    expect(graph.edges).toEqual([
+      { source: 'root', target: 'text', relation: 'child' },
+      { source: 'text', target: 'headings', relation: 'child' },
+      { source: 'headings', target: 'h1', relation: 'child' },
+      { source: 'headings', target: 'h2', relation: 'child' },
+      { source: 'text', target: 'formatting', relation: 'child' },
+      { source: 'formatting', target: 'bold', relation: 'child' },
+    ]);
+  });
+
+  test('merges pre-built subgraph', ({ expect }) => {
+    const headings = MenuBuilder.make()
+      .root({ label: 'headings' })
+      .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' }, () => {});
+      })
+      .build();
+
+    const graph = MenuBuilder.make()
+      .root({ label: 'toolbar' })
+      .action('search', { label: 'Search', icon: 'ph--magnifying-glass--regular' }, () => {})
+      .subgraph(headings)
+      .build();
+
+    // root (toolbar) + search + root (headings) + headings group + h1 + h2 = 6 nodes.
+    expect(graph.nodes).toHaveLength(6);
+    // search → root, headings root→headings group, h1→headings, h2→headings.
+    const headingsEdge = graph.edges.find((edge) => edge.target === 'headings');
+    expect(headingsEdge).toEqual({ source: 'root', target: 'headings', relation: 'child' });
+  });
+
+  test('separators are inserted between groups', ({ expect }) => {
+    const graph = MenuBuilder.make()
+      .root({ label: 'toolbar' })
+      .action('bold', { label: 'Bold', icon: 'ph--text-b--regular' }, () => {})
+      .separator()
+      .action('search', { label: 'Search', icon: 'ph--magnifying-glass--regular' }, () => {})
+      .build();
+
+    const separatorNode = graph.nodes.find((node) => node.type === MenuSeparatorType);
+    expect(separatorNode).toBeDefined();
+    expect(separatorNode!.properties).toEqual({ variant: 'gap' });
+
+    const separatorEdge = graph.edges.find((edge) => edge.target === separatorNode!.id);
+    expect(separatorEdge).toEqual({ source: 'root', target: separatorNode!.id, relation: 'child' });
+  });
+
+  test('subgraph callback adds children to current group', ({ expect }) => {
+    const graph = MenuBuilder.make()
+      .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('formatting', { label: 'Formatting' }, (group) => {
+            group.action('bold', { label: 'Bold', icon: 'ph--text-b--regular' }, () => {});
+          });
+      })
+      .build();
+
+    // root + headings + h1 + h2 + formatting + bold = 6 nodes.
+    expect(graph.nodes).toHaveLength(6);
+    expect(graph.edges).toEqual([
+      { source: 'root', target: 'headings', relation: 'child' },
+      { source: 'headings', target: 'h1', relation: 'child' },
+      { source: 'headings', target: 'h2', relation: 'child' },
+      { source: 'root', target: 'formatting', relation: 'child' },
+      { source: 'formatting', target: 'bold', relation: 'child' },
+    ]);
+  });
+
+  test('subgraph callback scoped to nested group', ({ expect }) => {
+    const graph = MenuBuilder.make()
+      .root({ label: 'toolbar' })
+      .group('text', { label: 'Text' }, (text) => {
+        text.subgraph((sub) => {
+          sub.action('bold', { label: 'Bold', icon: 'ph--text-b--regular' }, () => {});
+          sub.action('italic', { label: 'Italic', icon: 'ph--text-italic--regular' }, () => {});
+        });
+      })
+      .build();
+
+    // root + text + bold + italic = 4 nodes.
+    expect(graph.nodes).toHaveLength(4);
+    expect(graph.edges).toEqual([
+      { source: 'root', target: 'text', relation: 'child' },
+      { source: 'text', target: 'bold', relation: 'child' },
+      { source: 'text', target: 'italic', relation: 'child' },
+    ]);
+  });
+
+  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' }, () => {});
+      });
+    };
+
+    const addFormattingSection = () => (builder: import('./builder').ActionGroupBuilder) => {
+      builder.group('formatting', { label: 'Formatting' }, (group) => {
+        group.action('bold', { label: 'Bold', icon: 'ph--text-b--regular' }, () => {});
+      });
+    };
+
+    const graph = MenuBuilder.make()
+      .root({ label: 'toolbar' })
+      .subgraph(addHeadingsSection())
+      .separator()
+      .subgraph(addFormattingSection())
+      .build();
+
+    expect(graph.nodes).toHaveLength(7); // root + headings + h1 + h2 + separator + formatting + bold.
+    expect(graph.edges[0]).toEqual({ source: 'root', target: 'headings', relation: 'child' });
+    expect(graph.edges[3]).toEqual({ source: 'root', target: 'separator-1', relation: 'child' });
+    expect(graph.edges[4]).toEqual({ source: 'root', target: 'formatting', relation: 'child' });
+  });
+
+  test('subgraph skips falsy values', ({ expect }) => {
+    const showHeadings = false;
+    const graph = MenuBuilder.make()
+      .root({ label: 'toolbar' })
+      .subgraph(
+        showHeadings &&
+          ((builder) => {
+            builder.group('headings', { label: 'Headings' }, () => {});
+          }),
+      )
+      .action('bold', { label: 'Bold', icon: 'ph--text-b--regular' }, () => {})
+      .subgraph(undefined)
+      .subgraph(null)
+      .build();
+
+    // root + bold = 2 nodes; headings skipped.
+    expect(graph.nodes).toHaveLength(2);
+    expect(graph.edges).toHaveLength(1);
+  });
+
+  test('nodes have correct types', ({ expect }) => {
+    const graph = MenuBuilder.make()
+      .root({ label: 'toolbar' })
+      .action('bold', { label: 'Bold', icon: 'ph--text-b--regular' }, () => {})
+      .group('headings', { label: 'Headings' }, () => {})
+      .build();
+
+    const rootNode = graph.nodes.find((node) => node.id === 'root');
+    const actionNode = graph.nodes.find((node) => node.id === 'bold');
+    const groupNode = graph.nodes.find((node) => node.id === 'headings');
+
+    expect(rootNode!.type).toBe(Node.ActionGroupType);
+    expect(actionNode!.type).toBe(Node.ActionType);
+    expect(groupNode!.type).toBe(Node.ActionGroupType);
+  });
+});

package/src/builder.ts

@@ -3,41 +3,60 @@
 //
 
 import { invariant } from '@dxos/invariant';
+import type { MenuActionProperties, MenuItemGroupProperties } from '@dxos/ui-types';
 
 import type { ActionGraphProps } from './hooks';
-import type { MenuActionProperties, MenuItemGroupProperties } from './types';
+import { MenuSeparatorType } from './types';
 import { createMenuAction, createMenuItemGroup } from './util';
 
+/** Callback that populates an action group builder. */
+export type ActionGroupBuilderFn = (builder: ActionGroupBuilder) => void;
+
+/**
+ * Fluent builder for composing menu action graphs.
+ * Subgraph functions return a callback that receives the builder, enabling composition via partial application:
+ * ```ts
+ * const addHeadings = (state): ActionGroupBuilderFn => (builder) => {
+ *   builder.group('headings', { ... }, (group) => { ... });
+ * };
+ *
+ * MenuBuilder.make()
+ *   .subgraph(showHeadings && addHeadings(state))
+ *   .subgraph(showFormatting && addFormatting(state))
+ *   .build();
+ * ```
+ */
 export interface ActionGroupBuilder {
-  action<P extends {} = {}>(id: string, invoke: () => void, properties: P & MenuActionProperties): this;
-  group<P extends {} = {}>(
-    id: string,
-    properties: P & MenuItemGroupProperties,
-    cb: (builder: ActionGroupBuilder) => void,
-  ): this;
+  /** 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: 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;
+
+  /** Add a separator. */
+  separator(variant?: 'gap' | 'line'): this;
 }
 
+/** 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. */
   root(props: MenuItemGroupProperties): this;
+
+  /** Return the assembled action graph. */
   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,
   ) {}
 
-  action<P extends {} = {}>(id: string, invoke: () => void, properties: P & MenuActionProperties): this {
-    this._data.nodes.push(createMenuAction(id, invoke, properties));
-    this._data.edges.push({ source: this._rootId, target: id });
-    return this;
-  }
-
   root(props: MenuItemGroupProperties): this {
     invariant(this._rootId === 'root', 'Root group can only be at the top level');
     invariant(this._data.nodes.find((node) => node.id === 'root') === undefined, 'Root group can only be created once');
@@ -45,18 +64,49 @@ class MenuBuilderImpl implements MenuBuilder {
     return this;
   }
 
-  group<P extends {} = {}>(
-    id: string,
-    properties: P & MenuItemGroupProperties,
-    cb: (builder: ActionGroupBuilder) => void,
-  ): this {
-    this._data.nodes.push(createMenuItemGroup(id, properties));
-    this._data.edges.push({ source: this._rootId, target: id });
+  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, relation: 'child' });
+    return this;
+  }
+
+  group<P extends {} = {}>(id: string, props: P & 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;
   }
 
-  build(): ActionGraphProps {
-    return this._data;
+  subgraph(subgraphOrCb: ActionGraphProps | ActionGroupBuilderFn | false | null | undefined): this {
+    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' | 'line' = 'gap'): this {
+    const 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

@@ -4,16 +4,16 @@
 
 import React from 'react';
 
-import { type ActionGroup, type Action as GraphAction } from '@dxos/app-graph';
+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/react-ui-theme';
+import { mx } from '@dxos/ui-theme';
+import { type MenuActionProperties } from '@dxos/ui-types';
 
 import { translationKey } from '../translations';
-import { type MenuActionProperties } from '../types';
 import { getShortcut } from '../util';
 
-type Action = GraphAction<MenuActionProperties> | ActionGroup<Omit<MenuActionProperties, 'variant'>>;
+type Action = Node.Action<MenuActionProperties> | Node.ActionGroup<Omit<MenuActionProperties, 'variant'>>;
 
 export const ActionLabel = ({ action }: { action: Action }) => {
   const { t } = useTranslation(translationKey);
@@ -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

@@ -8,9 +8,9 @@ import React, { type MouseEvent, useCallback } from 'react';
 import { type DropdownMenuRootProps, Icon, DropdownMenu as NaturalDropdownMenu } from '@dxos/react-ui';
 
 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;
@@ -29,7 +29,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}
@@ -60,17 +60,23 @@ const DropdownMenuRoot = ({
     onChange: onOpenChange,
   });
 
+  const { onAction } = useMenuScoped('DropdownMenuRoot', __menuScope);
+
   const handleActionClick = useCallback(
     (action: MenuAction, event: MouseEvent) => {
       if (action.properties?.disabled) {
         return;
       }
       event.stopPropagation();
-      // TODO(thure): Why does Dialog’s modal-ness cause issues if we don’t explicitly close the menu here?
+      // TODO(thure): Why does Dialog's modal-ness cause issues if we don't explicitly close the menu here?
       setOptionsMenuOpen(false);
-      void action.data?.({ parent: group, caller });
+      if (onAction) {
+        onAction(action, { parent: group, caller });
+      } else {
+        void executeMenuAction(action, { parent: group, caller });
+      }
     },
-    [group, caller],
+    [group, caller, onAction],
   );
 
   const items = useMenuItems(group, propsItems);