@dxos/react-ui-menu 0.7.5-main.937ce75

package/src/components/DropdownMenu.tsx

@@ -0,0 +1,104 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useControllableState } from '@radix-ui/react-use-controllable-state';
+import React, { type MouseEvent, type MutableRefObject, type PropsWithChildren, useCallback } from 'react';
+
+import { DropdownMenu as NaturalDropdownMenu, Icon } from '@dxos/react-ui';
+
+import { ActionLabel } from './ActionLabel';
+import { type MenuAction, type MenuProps } from '../defs';
+
+export type DropdownMenuProps = MenuProps &
+  PropsWithChildren<
+    Partial<{
+      defaultMenuOpen: boolean;
+      menuOpen: boolean;
+      onMenuOpenChange: (nextOpen: boolean) => void;
+      suppressNextTooltip?: MutableRefObject<boolean>;
+    }>
+  >;
+
+const DropdownMenuItem = ({
+  action,
+  onClick,
+}: {
+  action: MenuAction;
+  onClick: (action: MenuAction, event: MouseEvent) => void;
+}) => {
+  const handleClick = useCallback((event: MouseEvent) => onClick(action, event), [action, onClick]);
+  return (
+    <NaturalDropdownMenu.Item
+      onClick={handleClick}
+      classNames='gap-2'
+      disabled={action.properties?.disabled}
+      {...(action.properties?.testId && { 'data-testid': action.properties.testId })}
+    >
+      {action.properties?.icon && <Icon icon={action.properties!.icon} size={4} />}
+      <ActionLabel action={action} />
+    </NaturalDropdownMenu.Item>
+  );
+};
+
+const DropdownMenuRoot = ({
+  defaultMenuOpen,
+  actions,
+  menuOpen,
+  suppressNextTooltip,
+  onMenuOpenChange,
+  onAction,
+  children,
+}: DropdownMenuProps) => {
+  const [optionsMenuOpen, setOptionsMenuOpen] = useControllableState({
+    prop: menuOpen,
+    defaultProp: defaultMenuOpen,
+    onChange: onMenuOpenChange,
+  });
+
+  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?
+      if (suppressNextTooltip) {
+        suppressNextTooltip.current = true;
+      }
+      setOptionsMenuOpen(false);
+      onAction?.(action);
+    },
+    [onAction],
+  );
+
+  return (
+    <NaturalDropdownMenu.Root
+      {...{
+        open: optionsMenuOpen,
+        onOpenChange: (nextOpen: boolean) => {
+          if (!nextOpen && suppressNextTooltip) {
+            suppressNextTooltip.current = true;
+          }
+          return setOptionsMenuOpen(nextOpen);
+        },
+      }}
+    >
+      {children}
+      <NaturalDropdownMenu.Portal>
+        <NaturalDropdownMenu.Content>
+          <NaturalDropdownMenu.Viewport>
+            {actions?.map((action) => <DropdownMenuItem key={action.id} action={action} onClick={handleActionClick} />)}
+          </NaturalDropdownMenu.Viewport>
+          <NaturalDropdownMenu.Arrow />
+        </NaturalDropdownMenu.Content>
+      </NaturalDropdownMenu.Portal>
+    </NaturalDropdownMenu.Root>
+  );
+};
+
+export const DropdownMenu = {
+  Root: DropdownMenuRoot,
+  Trigger: NaturalDropdownMenu.Trigger,
+  VirtualTrigger: NaturalDropdownMenu.VirtualTrigger,
+};

package/src/components/Toolbar/Toolbar.tsx

@@ -0,0 +1,71 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { useCallback } from 'react';
+
+import { Toolbar as NaturalToolbar } from '@dxos/react-ui';
+
+import { ToolbarDropdownMenu } from './ToolbarDropdownMenu';
+import { ToolbarToggleGroup } from './ToolbarToggleGroup';
+import { isMenu, isSeparator, type ToolbarProps } from './defs';
+import { type MenuAction } from '../../defs';
+import { ActionLabel } from '../ActionLabel';
+
+const ToolbarItem = ({
+  iconSize,
+  action,
+  onAction,
+}: Pick<ToolbarProps, 'iconSize' | 'onAction'> & {
+  action: MenuAction;
+}) => {
+  const handleClick = useCallback(() => {
+    onAction?.(action);
+  }, [action, onAction]);
+  const { icon, iconOnly = true, disabled, testId } = action.properties;
+  return (
+    <NaturalToolbar.IconButton
+      key={action.id}
+      iconOnly={iconOnly}
+      variant='ghost'
+      icon={icon}
+      size={iconSize}
+      label={<ActionLabel action={action} />}
+      disabled={disabled}
+      onClick={handleClick}
+      {...(testId && { 'data-testid': testId })}
+    />
+  );
+};
+
+export const Toolbar = ({ actions: items, onAction, iconSize = 5, graph, ...props }: ToolbarProps) => {
+  return (
+    <NaturalToolbar.Root {...props}>
+      {items?.map((item, i) =>
+        isSeparator(item) ? (
+          <NaturalToolbar.Separator key={i} variant={item.properties.variant} />
+        ) : isMenu(item) ? (
+          item.properties.variant === 'dropdownMenu' ? (
+            <ToolbarDropdownMenu
+              key={item.id}
+              actionGroup={item}
+              onAction={onAction}
+              iconSize={iconSize}
+              graph={graph}
+            />
+          ) : (
+            <ToolbarToggleGroup
+              key={item.id}
+              actionGroup={item}
+              onAction={onAction}
+              iconSize={iconSize}
+              graph={graph}
+            />
+          )
+        ) : (
+          <ToolbarItem key={item.id} action={item as MenuAction} onAction={onAction} iconSize={iconSize} />
+        ),
+      )}
+    </NaturalToolbar.Root>
+  );
+};

package/src/components/Toolbar/ToolbarDropdownMenu.tsx

@@ -0,0 +1,36 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { useMemo, useRef } from 'react';
+
+import { Toolbar as NaturalToolbar } from '@dxos/react-ui';
+
+import { type ToolbarActionGroupProps } from './defs';
+import { type MenuAction } from '../../defs';
+import { ActionLabel } from '../ActionLabel';
+import { DropdownMenu } from '../DropdownMenu';
+
+export const ToolbarDropdownMenu = ({ actionGroup, graph, onAction, applyActiveIcon }: ToolbarActionGroupProps) => {
+  const menuActions = useMemo(() => (graph ? graph.actions(actionGroup) : []) as MenuAction[], [actionGroup, graph]);
+  const { icon, iconOnly = true, disabled, testId } = actionGroup.properties;
+  const suppressNextTooltip = useRef(false);
+
+  return (
+    <DropdownMenu.Root actions={menuActions} onAction={onAction} suppressNextTooltip={suppressNextTooltip}>
+      <DropdownMenu.Trigger asChild>
+        <NaturalToolbar.IconButton
+          size={5}
+          variant='ghost'
+          iconOnly={iconOnly}
+          disabled={disabled}
+          icon={(applyActiveIcon && menuActions.find((action) => !!action.properties.checked)?.properties.icon) || icon}
+          label={<ActionLabel action={actionGroup} />}
+          {...(testId && { 'data-testid': testId })}
+          suppressNextTooltip={suppressNextTooltip}
+          caretDown
+        />
+      </DropdownMenu.Trigger>
+    </DropdownMenu.Root>
+  );
+};

package/src/components/Toolbar/ToolbarToggleGroup.tsx

@@ -0,0 +1,39 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { useMemo } from 'react';
+
+import { Toolbar as NaturalToolbar } from '@dxos/react-ui';
+
+import type { ToolbarActionGroupProps } from './defs';
+import { type MenuAction } from '../../defs';
+import { ActionLabel } from '../ActionLabel';
+
+const ToolbarToggleGroupItem = ({ action }: { action: MenuAction }) => {
+  const { icon, iconOnly, disabled } = action.properties;
+  return (
+    <NaturalToolbar.ToggleGroupIconItem
+      key={action.id}
+      value={action.id}
+      icon={icon}
+      iconOnly={iconOnly}
+      disabled={disabled}
+      label={<ActionLabel action={action} />}
+    />
+  );
+};
+
+export const ToolbarToggleGroup = ({ actionGroup, graph }: ToolbarActionGroupProps) => {
+  const menuActions = useMemo(() => (graph ? (graph.actions(actionGroup) as MenuAction[]) : []), [actionGroup, graph]);
+  const { selectCardinality, value } = actionGroup.properties;
+  return (
+    // TODO(thure): This is extremely difficult to manage, what do?
+    // @ts-ignore
+    <NaturalToolbar.ToggleGroup type={selectCardinality} value={value}>
+      {menuActions.map((action) => (
+        <ToolbarToggleGroupItem key={action.id} action={action} />
+      ))}
+    </NaturalToolbar.ToggleGroup>
+  );
+};

package/src/components/Toolbar/defs.ts

@@ -0,0 +1,36 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Node, type ActionGroup, type Graph, ACTION_GROUP_TYPE } from '@dxos/app-graph';
+import { type ToolbarRootProps, type ToolbarSeparatorProps, type IconButtonProps } from '@dxos/react-ui';
+
+import { type MenuAction, type MenuActionProperties, type MenuProps } from '../../defs';
+
+export const ToolbarSeparatorType = '@dxos/react-ui-toolbar/separator' as const;
+
+export type ToolbarSeparatorNode = Node<never, Pick<ToolbarSeparatorProps, 'variant'>> & {
+  type: typeof ToolbarSeparatorType;
+};
+
+export const isSeparator = (node: Node): node is ToolbarSeparatorNode => node.type === ToolbarSeparatorType;
+
+export type ToolbarActionGroupProperties = Omit<MenuActionProperties, 'variant'> & {
+  variant: 'dropdownMenu' | 'toggleGroup';
+} & ({ selectCardinality?: 'single'; value?: string } | { selectCardinality?: 'multiple'; value?: string[] });
+
+export type ToolbarActionGroup = ActionGroup<ToolbarActionGroupProperties>;
+
+export const isMenu = (node: Node): node is ToolbarActionGroup => node.type === ACTION_GROUP_TYPE;
+
+export type ToolbarItem = ToolbarSeparatorNode | MenuAction | ToolbarActionGroup;
+
+export type ToolbarProps = ToolbarRootProps &
+  MenuProps<ToolbarItem, MenuAction> & { iconSize?: IconButtonProps['size']; graph?: Graph };
+
+export type ToolbarActionGroupProps = Pick<ToolbarProps, 'iconSize'> &
+  Omit<MenuProps<MenuAction>, 'actions'> & {
+    actionGroup: ToolbarActionGroup;
+    graph?: Graph;
+    applyActiveIcon?: boolean;
+  };

package/src/components/Toolbar/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './Toolbar';
+export * from './defs';

package/src/components/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './DropdownMenu';
+export * from './Toolbar';

package/src/defs.ts

@@ -0,0 +1,23 @@
+//
+// Copyright 2025 DXOS.org
+//
+import { type Node, type Action } from '@dxos/app-graph';
+import { type Label } from '@dxos/react-ui';
+
+export type MenuActionProperties = {
+  label: Label;
+  icon: string;
+  value?: string;
+  disabled?: boolean;
+  iconOnly?: boolean;
+  testId?: string;
+  variant?: 'action' | 'toggle';
+  checked?: boolean;
+};
+
+export type MenuAction = Action<MenuActionProperties>;
+
+export type MenuProps<A extends Node = Action<MenuActionProperties>, P extends Node = A> = {
+  actions?: A[];
+  onAction?: (action: P) => void;
+};

package/src/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './components';
+export * from './defs';

package/src/testing/Menus.stories.tsx

@@ -0,0 +1,55 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import '@dxos-theme';
+
+import React from 'react';
+
+import { faker } from '@dxos/random';
+import { IconButton } from '@dxos/react-ui';
+import { withTheme, withLayout, withSignals } from '@dxos/storybook-utils';
+
+import { createActions, createNestedActionGraph, useMutateActions } from './index';
+import { Toolbar as NaturalToolbar, DropdownMenu as NaturalDropdownMenu } from '../components';
+import { type MenuAction } from '../defs';
+import translations from '../translations';
+
+faker.seed(1234);
+
+export default {
+  title: 'ui/react-ui-menu/Menus',
+  component: NaturalToolbar,
+  decorators: [withTheme, withLayout({ tooltips: true }), withSignals],
+  parameters: { translations },
+};
+
+const menuActions = createActions() as MenuAction[];
+const nestedMenuActions = createNestedActionGraph();
+
+const handleAction = (action: MenuAction) => console.log('[on action]', action);
+
+export const DropdownMenu = {
+  render: () => {
+    useMutateActions(menuActions);
+    return (
+      <NaturalDropdownMenu.Root actions={menuActions} onAction={handleAction}>
+        <NaturalDropdownMenu.Trigger asChild>
+          <IconButton icon='ph--list-checks--regular' size={5} label='Options' />
+        </NaturalDropdownMenu.Trigger>
+      </NaturalDropdownMenu.Root>
+    );
+  },
+};
+
+export const Toolbar = {
+  render: () => {
+    return (
+      <NaturalToolbar
+        actions={nestedMenuActions.topLevelActions}
+        onAction={handleAction}
+        graph={nestedMenuActions.graph}
+      />
+    );
+  },
+};

package/src/testing/index.ts

@@ -0,0 +1,92 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useEffect } from 'react';
+
+import { type Action, Graph, type NodeArg, ACTION_TYPE, ACTION_GROUP_TYPE, actionGroupSymbol } from '@dxos/app-graph';
+import { create } from '@dxos/live-object';
+import { faker } from '@dxos/random';
+import { type DeepWriteable } from '@dxos/util';
+
+import { type ToolbarItem } from '../components';
+import { type MenuAction } from '../defs';
+
+export type CreateActionsParams = Partial<{
+  type?: typeof ACTION_TYPE | typeof ACTION_GROUP_TYPE;
+  callback: () => void;
+  count: number;
+}>;
+
+const icons = {
+  regular: [
+    'ph--text-b--regular',
+    'ph--text-italic--regular',
+    'ph--text-h-five--regular',
+    'ph--chat-text--regular',
+    'ph--clipboard-text--regular',
+    'ph--link-simple--regular',
+  ],
+  fill: [
+    'ph--text-b--fill',
+    'ph--text-italic--fill',
+    'ph--text-h-five--fill',
+    'ph--chat-text--fill',
+    'ph--clipboard-text--fill',
+    'ph--link-simple--fill',
+  ],
+};
+
+export const createActions = (params?: CreateActionsParams) => {
+  // eslint-disable-next-line no-console
+  const { callback = () => console.log('invoke'), count = 12, type = ACTION_TYPE } = params ?? {};
+  return faker.helpers.multiple(
+    () =>
+      create({
+        id: faker.string.uuid(),
+        type,
+        data: type === ACTION_GROUP_TYPE ? actionGroupSymbol : callback,
+        properties: {
+          label: faker.lorem.words(2),
+          icon: faker.helpers.arrayElement(icons[faker.helpers.arrayElement(Object.keys(icons)) as keyof typeof icons]),
+          disabled: faker.helpers.arrayElement([true, false]),
+          ...(type === ACTION_GROUP_TYPE && { variant: 'dropdownMenu' }),
+        },
+      }),
+    { count },
+  );
+};
+
+export const createNestedActionGraph = (groupParams?: CreateActionsParams, params?: CreateActionsParams) => {
+  const graph = new Graph();
+  const actionGroups = createActions({ type: ACTION_GROUP_TYPE, ...groupParams });
+  actionGroups.forEach((group) => {
+    const actions = createActions(params);
+    // TODO(thure): these methods exist on `graph` but are marked as `@internal`; how should consumers properly build
+    //  graph “islands” for the purposes of these components?
+    // @ts-ignore
+    graph._addNodes([group as NodeArg<any>, ...(actions as NodeArg<any>[])]);
+    // @ts-ignore
+    graph._addEdges(actions.map((action) => ({ source: group.id, target: action.id })));
+    void graph.expand(group);
+  });
+  return { graph, topLevelActions: actionGroups as ToolbarItem[] };
+};
+
+export const mutateActionsOnInterval = (actions: Action[]) => {
+  let cursor = 0;
+  return setInterval(() => {
+    const action = actions[cursor] as DeepWriteable<Action>;
+    action.properties.icon = faker.helpers.arrayElement(
+      action.properties.icon.endsWith('regular') ? icons.fill : icons.regular,
+    );
+    action.properties.disabled = !action.properties.disabled;
+    cursor = (cursor + actions.length + 1) % actions.length;
+  }, 1_000);
+};
+
+export const useMutateActions = (actions: MenuAction[]) =>
+  useEffect(() => {
+    const interval = mutateActionsOnInterval(actions);
+    return () => clearInterval(interval);
+  }, []);

package/src/translations.ts

@@ -0,0 +1,13 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+export const translationKey = 'menus';
+
+export default [
+  {
+    'en-US': {
+      [translationKey]: {},
+    },
+  },
+] as const;

package/src/util.ts

@@ -0,0 +1,14 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type ActionLike } from '@dxos/app-graph';
+import { getHostPlatform } from '@dxos/util';
+
+export const getShortcut = (action: ActionLike) => {
+  return typeof action.properties?.keyBinding === 'string'
+    ? action.properties.keyBinding
+    : action.properties?.keyBinding?.[getHostPlatform()];
+};
+
+export const fallbackIcon = 'ph--placeholder--regular';