@dxos/react-ui-menu 0.10.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/react-ui-menu",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Components for facilitating reactive and consistent menus.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -19,14 +19,12 @@
     ".": {
       "source": "./src/index.ts",
       "types": "./dist/types/src/index.d.ts",
-      "browser": "./dist/lib/browser/index.mjs",
-      "node": "./dist/lib/node-esm/index.mjs"
+      "import": "./dist/lib/index.mjs"
     },
     "./translations": {
       "source": "./src/translations.ts",
       "types": "./dist/types/src/translations.d.ts",
-      "browser": "./dist/lib/browser/translations.mjs",
-      "node": "./dist/lib/node-esm/translations.mjs"
+      "import": "./dist/lib/translations.mjs"
     }
   },
   "types": "dist/types/src/index.d.ts",
@@ -35,16 +33,17 @@
     "src"
   ],
   "dependencies": {
+    "@effect-atom/atom": "^0.5.3",
     "@radix-ui/react-context": "1.1.1",
     "@radix-ui/react-use-controllable-state": "1.1.0",
-    "@dxos/app-graph": "0.10.0",
-    "@dxos/invariant": "0.10.0",
-    "@dxos/effect": "0.10.0",
-    "@dxos/keyboard": "0.10.0",
-    "@dxos/log": "0.10.0",
-    "@dxos/ui-types": "0.10.0",
-    "@dxos/util": "0.10.0",
-    "@dxos/react-ui-attention": "0.10.0"
+    "@dxos/app-graph": "0.11.0",
+    "@dxos/effect": "0.11.0",
+    "@dxos/invariant": "0.11.0",
+    "@dxos/log": "0.11.0",
+    "@dxos/keyboard": "0.11.0",
+    "@dxos/ui-types": "0.11.0",
+    "@dxos/util": "0.11.0",
+    "@dxos/react-ui-attention": "0.11.0"
   },
   "devDependencies": {
     "@effect-atom/atom-react": "^0.5.0",
@@ -56,11 +55,11 @@
     "effect": "3.21.4",
     "react": "~19.2.7",
     "react-dom": "~19.2.7",
-    "vite": "^8.0.16",
-    "@dxos/random": "0.10.0",
-    "@dxos/ui-theme": "0.10.0",
-    "@dxos/react-ui": "0.10.0",
-    "@dxos/storybook-utils": "0.10.0"
+    "vite": "^8.1.4",
+    "@dxos/random": "0.11.0",
+    "@dxos/storybook-utils": "0.11.0",
+    "@dxos/ui-theme": "0.11.0",
+    "@dxos/react-ui": "0.11.0"
   },
   "peerDependencies": {
     "@effect-atom/atom-react": "^0.5.0",
@@ -68,8 +67,8 @@
     "effect": "3.21.4",
     "react": "~19.2.7",
     "react-dom": "~19.2.7",
-    "@dxos/react-ui": "0.10.0",
-    "@dxos/ui-theme": "0.10.0"
+    "@dxos/react-ui": "^0.11.0",
+    "@dxos/ui-theme": "^0.11.0"
   },
   "publishConfig": {
     "access": "public"

package/src/builder.ts

@@ -64,7 +64,7 @@ export interface MenuBuilder extends ActionGroupBuilder {
   /**
    * Add a root-level toolbar overflow dropdown (⋮) with built-in trigger styling.
    */
-  menu(id: string, cb: ActionGroupBuilderFn): this;
+  menu(id: string, cb: ActionGroupBuilderFn, testId?: string): this;
 
   /**
    * Return the assembled action graph.
@@ -108,8 +108,8 @@ class MenuBuilderImpl implements MenuBuilder {
     return this;
   }
 
-  menu(id: string, cb: ActionGroupBuilderFn): this {
-    return this.group(id, overflowMenuProperties, cb);
+  menu(id: string, cb: ActionGroupBuilderFn, testId?: string): this {
+    return this.group(id, testId === undefined ? overflowMenuProperties : { ...overflowMenuProperties, testId }, cb);
   }
 
   subgraph(subgraphOrCb: ActionGraphProps | ActionGroupBuilderFn | false | null | undefined): this {

package/src/components/ActionLabel.tsx

@@ -6,7 +6,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 { toLocalizedString, useTranslation } from '@dxos/react-ui';
 import { mx } from '@dxos/ui-theme';
 import { type MenuActionProperties, type MenuItemChrome } from '@dxos/ui-types';
 
@@ -26,8 +26,3 @@ export const ActionLabel = ({ action }: { action: Action }) => {
     </>
   );
 };
-
-export const actionLabel = (action: Action, t: TFunction) => {
-  const shortcut = getShortcut(action);
-  return `${toLocalizedString(action.properties!.label, t)}${shortcut ? ` (${keySymbols(shortcut).join('')})` : ''}`;
-};

package/src/components/DropdownMenu.tsx

@@ -6,11 +6,12 @@ import { useControllableState } from '@radix-ui/react-use-controllable-state';
 import React, { type MouseEvent, useCallback } from 'react';
 
 import { type DropdownMenuRootProps, Icon, DropdownMenu as NaturalDropdownMenu } from '@dxos/react-ui';
+import { mx } from '@dxos/ui-theme';
 
-import { type MenuAction, type MenuItem, type MenuItemGroup } from '../types';
+import { type MenuAction, type MenuItem, type MenuItemGroup, isSeparator } from '../types';
 import { executeMenuAction } from '../util';
 import { ActionLabel } from './ActionLabel';
-import { type MenuScopedProps, useMenuItems, useMenuScoped } from './Menu';
+import { type MenuScopedProps, useMenuItems, useMenuScoped } from './MenuContext';
 
 export type DropdownMenuProps = DropdownMenuRootProps & {
   group?: MenuItemGroup;
@@ -20,25 +21,41 @@ export type DropdownMenuProps = DropdownMenuRootProps & {
 
 const DropdownMenuItem = ({
   item,
+  group,
   onClick,
   __menuScope,
 }: MenuScopedProps<{
   item: MenuItem;
+  group?: MenuItemGroup;
   onClick: (action: MenuAction, event: MouseEvent) => void;
 }>) => {
   // TODO(thure): handle other items.
   const action = item as MenuAction;
   const handleClick = useCallback((event: MouseEvent) => onClick(action, event), [action, onClick]);
   const { iconSize } = useMenuScoped('DropdownMenuItem', __menuScope);
+  // An item that declares `checked` is a select-group member: expose the checked role + state to AT so
+  // the current value is announced, not conveyed by the trailing check icon alone. Mutually-exclusive
+  // (single-select) groups use radio semantics; multi-select groups use checkbox.
+  const checkable = typeof action.properties?.checked === 'boolean';
+  const role = group?.properties?.selectCardinality === 'multiple' ? 'menuitemcheckbox' : 'menuitemradio';
   return (
     <NaturalDropdownMenu.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 })}
     >
-      {action.properties?.icon && <Icon icon={action.properties!.icon} size={iconSize} />}
+      {action.properties?.icon && (
+        <Icon
+          icon={action.properties.icon}
+          size={iconSize}
+          classNames={mx(action.properties.spin && 'animate-spin', action.properties.iconClassNames)}
+        />
+      )}
       <ActionLabel action={action} />
+      {/* Trailing check marks the current value of a single-select group (`checked`). */}
+      {action.properties?.checked && <Icon icon='ph--check--regular' size={iconSize} classNames='mis-auto' />}
     </NaturalDropdownMenu.Item>
   );
 };
@@ -70,10 +87,11 @@ const DropdownMenuRoot = ({
       event.stopPropagation();
       // TODO(thure): Why does Dialog's modal-ness cause issues if we don't explicitly close the menu here?
       setOptionsMenuOpen(false);
+      const params = { parent: group, caller, modifiers: { shift: event.shiftKey } };
       if (onAction) {
-        onAction(action, { parent: group, caller });
+        onAction(action, params);
       } else {
-        void executeMenuAction(action, { parent: group, caller });
+        void executeMenuAction(action, params);
       }
     },
     [group, caller, onAction],
@@ -87,9 +105,13 @@ const DropdownMenuRoot = ({
       <NaturalDropdownMenu.Portal>
         <NaturalDropdownMenu.Content>
           <NaturalDropdownMenu.Viewport>
-            {items?.map((item) => (
-              <DropdownMenuItem key={item.id} item={item} onClick={handleActionClick} />
-            ))}
+            {items?.map((item) =>
+              isSeparator(item) ? (
+                <NaturalDropdownMenu.Separator key={item.id} />
+              ) : (
+                <DropdownMenuItem key={item.id} item={item} group={group} onClick={handleActionClick} />
+              ),
+            )}
           </NaturalDropdownMenu.Viewport>
           <NaturalDropdownMenu.Arrow />
         </NaturalDropdownMenu.Content>

package/src/components/Menu.stories.tsx

@@ -2,7 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Atom } from '@effect-atom/atom-react';
+import { Atom } from '@effect-atom/atom';
 import { type Meta, type StoryObj } from '@storybook/react-vite';
 import React, { useEffect, useMemo, useState } from 'react';
 import { expect, userEvent, within } from 'storybook/test';

package/src/components/Menu.test.tsx

@@ -2,14 +2,15 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Atom } from '@effect-atom/atom-react';
+import { Atom } from '@effect-atom/atom';
 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';
+import { Menu } from './Menu';
+import { useMenu, useMenuItems } from './MenuContext';
 
 const TEST_CONTRIBUTOR = 'TestContributor';
 

package/src/components/Menu.tsx

@@ -2,13 +2,12 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Atom, RegistryContext, useAtomValue } from '@effect-atom/atom-react';
-import { type Scope, createContextScope } from '@radix-ui/react-context';
+import { Atom, RegistryContext } from '@effect-atom/atom-react';
 import { useControllableState } from '@radix-ui/react-use-controllable-state';
-import React, { type MouseEvent, type PropsWithChildren, createContext, useCallback, useContext, useMemo } from 'react';
+import React, { type MouseEvent, type PropsWithChildren, useCallback, useContext, useMemo } from 'react';
 
-import { log } from '@dxos/log';
 import { type DropdownMenuRootProps, Icon, DropdownMenu as NaturalDropdownMenu } from '@dxos/react-ui';
+import { mx } from '@dxos/ui-theme';
 
 import {
   type AddMenuItemsProps,
@@ -16,62 +15,28 @@ import {
   type MenuContextValue,
   type MenuGroupContext,
   type MenuItem,
-  type MenuItems,
-  type MenuItemsAccessor,
   type MenuItemsMap,
+  isSeparator,
 } from '../types';
 import { executeMenuAction } from '../util';
 import { ActionLabel } from './ActionLabel';
+import {
+  MenuContextProvider,
+  MenuDropdownContext,
+  type MenuScopedProps,
+  menuContextDefaults,
+  useMenuItems,
+  useMenuScope,
+  useMenuScoped,
+} from './MenuContext';
 import { ToolbarMenu } from './ToolbarMenu';
 
-//
-// Scoped context.
-//
-
-type MenuScopedProps<P> = P & { __menuScope?: Scope };
-
-const MENU_NAME = 'Menu';
-
-const [createMenuContext, createMenuScope] = createContextScope(MENU_NAME, []);
-
-const nullItemsAtom = Atom.make<MenuItem[] | null>(null);
-const defaultItemsAccessor: MenuItemsAccessor = () => nullItemsAtom;
-
-const menuContextDefaults: MenuContextValue = {
-  iconSize: 5,
-  items: defaultItemsAccessor,
-  onAction: undefined,
-  menuItemsAtom: Atom.make<MenuItemsMap>(new Map()),
-  addMenuItems: () => {},
-  removeMenuItems: () => {},
-};
-
-const [MenuContextProvider, useMenuScoped] = createMenuContext<MenuContextValue>(MENU_NAME, menuContextDefaults);
-
-const useMenuScope = createMenuScope();
-
-//
-// Dropdown context (internal) — allows Menu.Content to close the parent dropdown.
-//
-
-type MenuDropdownContextValue = {
-  closeMenu: () => void;
-  caller?: string;
-};
-
-const MenuDropdownContext = createContext<MenuDropdownContextValue>({
-  closeMenu: () => {},
-});
-
 //
 // MenuProvider (internal) — the context provider used by Menu.Root.
 //
 
 const DEFAULT_PRIORITY = 100;
 
-const sortMenuItems = (items: MenuItems[]) =>
-  [...items].sort((a, b) => (a.priority !== b.priority ? a.priority - b.priority : a.id.localeCompare(b.id)));
-
 type MenuProviderProps = PropsWithChildren<Partial<MenuContextValue>>;
 
 const MenuProvider = ({
@@ -124,72 +89,6 @@ const MenuProvider = ({
   );
 };
 
-//
-// Item resolution.
-//
-
-const resolveItems = (
-  baseItems: MenuItem[] | null,
-  group: MenuGroupContext | undefined,
-  entries: ReadonlyMap<string, MenuItems>,
-): MenuItem[] | null => {
-  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,
-      });
-    }
-    return replacements[0].items;
-  }
-
-  const additive = sorted.filter((entry) => entry.mode === 'additive');
-  const additiveItems = additive.flatMap((entry) => entry.items);
-
-  if (!baseItems || baseItems.length === 0) {
-    return additiveItems.length > 0 ? additiveItems : null;
-  }
-
-  return [...baseItems, ...additiveItems];
-};
-
-//
-// Public hooks.
-//
-
-const useMenuItems = (
-  group?: MenuGroupContext,
-  propsItems?: MenuItem[],
-  consumerName: string = 'useMenuItemConsumer',
-  __menuScope?: Scope,
-) => {
-  const { items, menuItemsAtom } = useMenuScoped(consumerName, __menuScope);
-  const groupItems = useAtomValue(items(group));
-  const entries = useAtomValue(menuItemsAtom) ?? new Map();
-
-  const baseItems = useMemo(() => propsItems ?? groupItems ?? null, [propsItems, groupItems]);
-
-  const resolved = useMemo(
-    () => resolveItems(baseItems, group, entries as ReadonlyMap<string, MenuItems>),
-    [baseItems, group, entries],
-  );
-
-  return resolved ?? undefined;
-};
-
-/** Returns the menu context without Radix scope. */
-const useMenu = (consumerName: string): MenuContextValue => {
-  return useMenuScoped(consumerName, undefined);
-};
-
 //
 // Menu.Root
 //
@@ -256,7 +155,13 @@ const MenuContentItem = ({
       disabled={action.properties?.disabled}
       {...(action.properties?.testId && { 'data-testid': action.properties.testId })}
     >
-      {action.properties?.icon && <Icon icon={action.properties!.icon} size={iconSize} />}
+      {action.properties?.icon && (
+        <Icon
+          icon={action.properties.icon}
+          size={iconSize}
+          classNames={mx(action.properties.spin && 'animate-spin', action.properties.iconClassNames)}
+        />
+      )}
       <ActionLabel action={action} />
     </NaturalDropdownMenu.Item>
   );
@@ -286,10 +191,11 @@ const MenuContent = ({
       }
       event.stopPropagation();
       closeMenu();
+      const params = { parent: group, caller, modifiers: { shift: event.shiftKey } };
       if (onAction) {
-        onAction(action, { parent: group, caller });
+        onAction(action, params);
       } else {
-        void executeMenuAction(action, { parent: group, caller });
+        void executeMenuAction(action, params);
       }
     },
     [group, caller, onAction, closeMenu],
@@ -299,9 +205,13 @@ const MenuContent = ({
     <NaturalDropdownMenu.Portal>
       <NaturalDropdownMenu.Content>
         <NaturalDropdownMenu.Viewport>
-          {resolvedItems?.map((item) => (
-            <MenuContentItem key={item.id} item={item} onClick={handleActionClick} />
-          ))}
+          {resolvedItems?.map((item) =>
+            isSeparator(item) ? (
+              <NaturalDropdownMenu.Separator key={item.id} />
+            ) : (
+              <MenuContentItem key={item.id} item={item} onClick={handleActionClick} />
+            ),
+          )}
         </NaturalDropdownMenu.Viewport>
         <NaturalDropdownMenu.Arrow />
       </NaturalDropdownMenu.Content>
@@ -329,9 +239,9 @@ const Menu = {
   Toolbar: ToolbarMenu,
 };
 
-export { Menu, menuContextDefaults, useMenu, useMenuItems, useMenuScoped };
+export { Menu };
 
-export type { MenuContentProps, MenuRootProps, MenuScopedProps };
+export type { MenuContentProps, MenuRootProps };
 
 export type {
   ToolbarMenuActionGroupProperties,

package/src/components/MenuContext.ts

@@ -0,0 +1,129 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Atom, useAtomValue } from '@effect-atom/atom-react';
+import { type Scope, createContextScope } from '@radix-ui/react-context';
+import { createContext, useMemo } from 'react';
+
+import { log } from '@dxos/log';
+
+import {
+  type MenuContextValue,
+  type MenuGroupContext,
+  type MenuItem,
+  type MenuItems,
+  type MenuItemsAccessor,
+  type MenuItemsMap,
+} from '../types';
+
+// Kept out of `Menu.tsx`: react-refresh only fast-refreshes a module whose exports are all
+// components, so contexts and hooks exported beside them force a full page reload on every edit.
+
+//
+// Scoped context.
+//
+
+export type MenuScopedProps<P> = P & { __menuScope?: Scope };
+
+export const MENU_NAME = 'Menu';
+
+export const [createMenuContext, createMenuScope] = createContextScope(MENU_NAME, []);
+
+const nullItemsAtom = Atom.make<MenuItem[] | null>(null);
+const defaultItemsAccessor: MenuItemsAccessor = () => nullItemsAtom;
+
+export const menuContextDefaults: MenuContextValue = {
+  iconSize: 5,
+  items: defaultItemsAccessor,
+  onAction: undefined,
+  menuItemsAtom: Atom.make<MenuItemsMap>(new Map()),
+  addMenuItems: () => {},
+  removeMenuItems: () => {},
+};
+
+export const [MenuContextProvider, useMenuScoped] = createMenuContext<MenuContextValue>(MENU_NAME, menuContextDefaults);
+
+export const useMenuScope = createMenuScope();
+
+//
+// Dropdown context (internal) — allows Menu.Content to close the parent dropdown.
+//
+
+export type MenuDropdownContextValue = {
+  closeMenu: () => void;
+  caller?: string;
+};
+
+export const MenuDropdownContext = createContext<MenuDropdownContextValue>({
+  closeMenu: () => {},
+});
+
+//
+// Item resolution.
+//
+
+const sortMenuItems = (items: MenuItems[]) =>
+  [...items].sort((a, b) => (a.priority !== b.priority ? a.priority - b.priority : a.id.localeCompare(b.id)));
+
+export const resolveItems = (
+  baseItems: MenuItem[] | null,
+  group: MenuGroupContext | undefined,
+  entries: ReadonlyMap<string, MenuItems>,
+): MenuItem[] | null => {
+  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,
+      });
+    }
+    return replacements[0].items;
+  }
+
+  const additive = sorted.filter((entry) => entry.mode === 'additive');
+  const additiveItems = additive.flatMap((entry) => entry.items);
+
+  if (!baseItems || baseItems.length === 0) {
+    return additiveItems.length > 0 ? additiveItems : null;
+  }
+
+  return [...baseItems, ...additiveItems];
+};
+
+//
+// Public hooks.
+//
+
+export const useMenuItems = (
+  group?: MenuGroupContext,
+  propsItems?: MenuItem[],
+  consumerName: string = 'useMenuItemConsumer',
+  __menuScope?: Scope,
+) => {
+  const { items, menuItemsAtom } = useMenuScoped(consumerName, __menuScope);
+  const groupItems = useAtomValue(items(group));
+  const entries = useAtomValue(menuItemsAtom) ?? new Map();
+
+  const baseItems = useMemo(() => propsItems ?? groupItems ?? null, [propsItems, groupItems]);
+
+  const resolved = useMemo(
+    () => resolveItems(baseItems, group, entries as ReadonlyMap<string, MenuItems>),
+    [baseItems, group, entries],
+  );
+
+  return resolved ?? undefined;
+};
+
+/** Returns the menu context without Radix scope. */
+export const useMenu = (consumerName: string): MenuContextValue => {
+  return useMenuScoped(consumerName, undefined);
+};