@dxos/react-ui-menu 0.10.0 → 0.11.0

package/src/components/ToolbarMenu.tsx

@@ -2,7 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
-import React, { useCallback } from 'react';
+import React, { useCallback, useRef, useState } from 'react';
 
 import {
   Input,
@@ -14,15 +14,17 @@ import {
 } from '@dxos/react-ui';
 import { composable, composableProps } from '@dxos/react-ui';
 import { useAttention } from '@dxos/react-ui-attention';
+import { mx } from '@dxos/ui-theme';
 import { type DropdownMenuItemGroupProperties, type ToggleGroupMenuItemGroupProperties } from '@dxos/ui-types';
 
 import { translationKey } from '#translations';
 
 import { type MenuAction, type MenuItem, type MenuItemGroup, isMenuGroup, isSeparator } from '../types';
 import { executeMenuAction } from '../util';
-import { ActionLabel, actionLabel } from './ActionLabel';
+import { actionLabel } from './action-label';
+import { ActionLabel } from './ActionLabel';
 import { DropdownMenu } from './DropdownMenu';
-import { type MenuScopedProps, useMenuItems, useMenuScoped } from './Menu';
+import { type MenuScopedProps, useMenuItems, useMenuScoped } from './MenuContext';
 
 export type ToolbarMenuDropdownMenuActionGroup = DropdownMenuItemGroupProperties;
 
@@ -55,22 +57,32 @@ export type ToolbarMenuActionProps = {
 const ActionToolbarItem = ({ __menuScope, action }: MenuScopedProps<{ action: MenuAction }>) => {
   const { iconSize, onAction } = useMenuScoped('ActionToolbarItem', __menuScope);
   const { t } = useTranslation(translationKey);
+  const [pending, setPending] = useState(false);
+  const pendingRef = useRef(false);
 
-  const { icon, iconOnly = true, disabled, testId, hidden, classNames, iconClassNames } = action.properties;
-  const buttonVariant =
-    (action.properties as { variant?: string }).variant === 'primary' ? ('primary' as const) : ('ghost' as const);
+  const { icon, iconOnly = true, disabled, testId, hidden, classNames, iconClassNames, spin } = action.properties;
+  const buttonVariant = action.properties.variant === 'primary' ? ('primary' as const) : ('ghost' as const);
 
   const handleClick = useCallback(() => {
+    if (pendingRef.current) {
+      return;
+    }
+    pendingRef.current = true;
+    setPending(true);
+    const done = () => {
+      pendingRef.current = false;
+      setPending(false);
+    };
     if (onAction) {
-      onAction(action, {});
+      Promise.resolve(onAction(action, {})).then(done, done);
     } else {
-      void executeMenuAction(action);
+      executeMenuAction(action).then(done, done);
     }
   }, [action, onAction]);
 
   const commonProps = {
     variant: buttonVariant,
-    disabled,
+    disabled: disabled || pending,
     classNames,
     onClick: handleClick,
     ...(testId && { 'data-testid': testId }),
@@ -87,7 +99,7 @@ const ActionToolbarItem = ({ __menuScope, action }: MenuScopedProps<{ action: Me
       icon={icon}
       size={iconSize}
       iconOnly={iconOnly}
-      iconClassNames={iconClassNames}
+      iconClassNames={mx(spin && 'animate-spin', iconClassNames)}
       label={actionLabel(action, t)}
     />
   ) : (
@@ -155,6 +167,7 @@ const DropdownMenuToolbarItem = ({
     caretDown = true,
     icon: groupIcon,
     iconClassNames: groupIconClassNames,
+    spin: groupSpin,
   } = group.properties;
   const activeItem = items?.find((item) => !!(item as MenuAction).properties.checked) as MenuAction | undefined;
   const icon =
@@ -164,6 +177,7 @@ const DropdownMenuToolbarItem = ({
     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 spin = (applyActive && activeItem?.properties.spin) || groupSpin;
   const labelAction = applyActive && activeItem ? activeItem : group;
 
   return (
@@ -176,7 +190,7 @@ const DropdownMenuToolbarItem = ({
             icon={icon}
             size={iconSize}
             iconOnly={iconOnly}
-            iconClassNames={iconClassNames}
+            iconClassNames={mx(spin && 'animate-spin', iconClassNames)}
             label={actionLabel(labelAction, t)}
             caretDown={caretDown}
             {...(testId && { 'data-testid': testId })}
@@ -199,7 +213,7 @@ const DropdownMenuToolbarItem = ({
 const ToggleGroupItem = ({ __menuScope, group, action }: MenuScopedProps<ToolbarMenuActionProps>) => {
   const { iconSize, onAction } = useMenuScoped('ToggleGroupItem', __menuScope);
   const { t } = useTranslation(translationKey);
-  const { icon, iconOnly = true, disabled, testId, hidden, classNames, iconClassNames } = action.properties;
+  const { icon, iconOnly = true, disabled, testId, hidden, classNames, iconClassNames, spin } = action.properties;
 
   const handleClick = useCallback(() => {
     if (onAction) {
@@ -224,7 +238,7 @@ const ToggleGroupItem = ({ __menuScope, group, action }: MenuScopedProps<Toolbar
       icon={icon}
       size={iconSize}
       iconOnly={iconOnly}
-      iconClassNames={iconClassNames}
+      iconClassNames={mx(spin && 'animate-spin', iconClassNames)}
       label={actionLabel(action, t)}
     />
   ) : (

package/src/components/action-label.ts

@@ -0,0 +1,20 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Node } from '@dxos/app-graph';
+import { keySymbols } from '@dxos/keyboard';
+import { type TFunction, toLocalizedString } from '@dxos/react-ui';
+import { type MenuActionProperties, type MenuItemChrome } from '@dxos/ui-types';
+
+import { getShortcut } from '../util';
+
+type Action = Node.Action<MenuActionProperties> | Node.ActionGroup<MenuItemChrome>;
+
+// Kept out of `ActionLabel.tsx`: react-refresh only fast-refreshes a module whose exports are all
+// components, so a value exported beside them forces a full page reload on every edit.
+
+export const actionLabel = (action: Action, t: TFunction) => {
+  const shortcut = getShortcut(action);
+  return `${toLocalizedString(action.properties!.label, t)}${shortcut ? ` (${keySymbols(shortcut).join('')})` : ''}`;
+};

package/src/components/index.ts

@@ -2,4 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
+export { type MenuScopedProps, menuContextDefaults, useMenu, useMenuItems, useMenuScoped } from './MenuContext';
+
+export { actionLabel } from './action-label';
 export * from './Menu';

package/src/hooks/useGraphMenuActions.ts

@@ -2,11 +2,12 @@
 // Copyright 2026 DXOS.org
 //
 
-import { Atom } from '@effect-atom/atom-react';
+import { Atom } from '@effect-atom/atom';
 import { useMemo } from 'react';
 
 import { type Graph, Node } from '@dxos/app-graph';
 
+import { applyPresentation } from '../presentation';
 import {
   type ActionGraphEdges,
   type ActionGraphNodes,
@@ -20,6 +21,12 @@ export type GraphMenuOptions = {
   rootId?: string;
   /** Keep only the actions the predicate accepts (e.g. by `disposition`). */
   filter?: (action: Node.ActionLike) => boolean;
+  /**
+   * Disposition key this surface renders — when set, each action's `presentation[surface]` chrome
+   * override (if any) is merged into its properties, letting one action multi-target dispositions
+   * (e.g. `['toolbar', 'list-item']`) with per-surface chrome.
+   */
+  surface?: string;
 };
 
 /**
@@ -36,7 +43,7 @@ export const buildGraphMenu = (
   nodeId: string,
   options: GraphMenuOptions = {},
 ): ActionGraphProps => {
-  const { rootId = Node.RootId, filter } = options;
+  const { rootId = Node.RootId, filter, surface } = options;
   const nodes: ActionGraphNodes = [];
   const edges: ActionGraphEdges = [];
   const seen = new Set<string>();
@@ -52,7 +59,7 @@ export const buildGraphMenu = (
         continue;
       }
       seen.add(action.id);
-      nodes.push(action as ActionGraphNodes[number]);
+      nodes.push((surface ? applyPresentation(action, surface) : 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);
@@ -68,6 +75,12 @@ export const buildGraphMenu = (
  * 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.
+ *
+ * @idiom org.dxos.react-ui-menu.graphActionsToolbar
+ *   applies: Splicing a node's app-graph-contributed toolbar actions into a hand-built object toolbar
+ *   instead-of: Reading `graph.actions(nodeId)` and filtering/wiring `nodes`/`edges` by hand in every toolbar
+ *   uses: {@link graphActions}, {@link MenuBuilder}, {@link useMenuBuilder}
+ *   related: org.dxos.react-ui-menu.toolbarMenu
  */
 export const graphActions = (
   graph: Graph.ReadableGraph | undefined,

package/src/index.ts

@@ -7,3 +7,5 @@ export * from './hooks';
 export * from './types';
 export { createGapSeparator, createLineSeparator, createMenuAction, createMenuItemGroup } from './util';
 export { type ActionGroupBuilder, type ActionGroupBuilderFn, MenuBuilder } from './builder';
+export { TOOLBAR_DISPOSITION, isToolbarAction } from './toolbar';
+export { applyPresentation } from './presentation';

package/src/presentation.ts

@@ -0,0 +1,19 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Node } from '@dxos/app-graph';
+import { type MenuActionProperties } from '@dxos/ui-types';
+
+/**
+ * Merges an action's `presentation[surface]` chrome override (if any) into its properties, letting a
+ * single action declare multiple dispositions yet render appropriately in each surface — e.g. a
+ * primary toolbar button and a plain nav-tree row from the same definition.
+ */
+export const applyPresentation = <A extends Node.ActionLike>(action: A, surface: string): A => {
+  const presentation = (action.properties as MenuActionProperties).presentation?.[surface];
+  if (!presentation) {
+    return action;
+  }
+  return { ...action, properties: { ...action.properties, ...presentation } };
+};

package/src/toolbar.ts

@@ -0,0 +1,11 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Node } from '@dxos/app-graph';
+
+/** `disposition` value an action opts into to appear in an object toolbar (vs context-menu-only). */
+export const TOOLBAR_DISPOSITION = 'toolbar';
+
+/** Filter for {@link graphActions}: keeps only actions a producer opted into the toolbar. */
+export const isToolbarAction = (action: Node.ActionLike): boolean => Node.hasDisposition(action, TOOLBAR_DISPOSITION);

package/src/types.ts

@@ -2,7 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
-import { type Atom } from '@effect-atom/atom-react';
+import { type Atom } from '@effect-atom/atom';
 
 import { Node } from '@dxos/app-graph';
 import { type IconButtonProps, type ToolbarSeparatorProps } from '@dxos/react-ui';

package/src/util.ts

@@ -36,14 +36,14 @@ export const fallbackIcon = 'ph--circle-dashed--regular';
 
 export const createMenuAction = <P extends {} = {}>(
   id: string,
-  invoke: () => void,
+  invoke: (params?: Node.InvokeProps) => void,
   properties: P & MenuActionProperties,
 ) =>
   ({
     id,
     type: Node.ActionType,
     properties,
-    data: () => Effect.sync(invoke),
+    data: (params?: Node.InvokeProps) => Effect.sync(() => invoke(params)),
   }) satisfies MenuAction;
 
 export const createMenuItemGroup = <P extends MenuItemGroupProperties>(id: string, properties: P) =>