@dxos/react-ui-menu 0.7.5-feature-compute.4d9d99a

package/src/defs.ts

@@ -0,0 +1,54 @@
+//
+// Copyright 2025 DXOS.org
+//
+import { type Node, type Action, type ActionGroup, ACTION_GROUP_TYPE } from '@dxos/app-graph';
+import { type ToolbarSeparatorProps, type Label, type IconButtonProps, type ClassNameValue } from '@dxos/react-ui';
+
+export type MenuActionProperties = {
+  label: Label;
+  icon?: string;
+  value?: string;
+  disabled?: boolean;
+  hidden?: boolean;
+  iconOnly?: boolean;
+  testId?: string;
+  variant?: 'action' | 'toggle';
+  checked?: boolean;
+  classNames?: ClassNameValue;
+};
+
+export type MenuItemGroupProperties = {
+  label: Label;
+  icon?: string;
+  iconOnly?: boolean;
+};
+
+export type MenuAction<P extends {} = {}> = Action<P & MenuActionProperties>;
+
+export type MenuActionHandler<A extends Node = MenuAction> = (action: A) => void;
+
+export const MenuSeparatorType = '@dxos/react-ui-toolbar/separator' as const;
+
+export type MenuSeparator = Node<never, Pick<ToolbarSeparatorProps, 'variant'>> & {
+  type: typeof MenuSeparatorType;
+};
+
+export const isSeparator = (node: Node): node is MenuSeparator => node.type === MenuSeparatorType;
+
+export type MenuSingleSelectActionGroup = { selectCardinality: 'single'; value: string };
+export type MenuMultipleSelectActionGroup = { selectCardinality: 'multiple'; value: string[] };
+
+export type MenuItemGroup<P extends Record<string, any> = Record<string, any>> = ActionGroup<P>;
+
+export const isMenuGroup = (node: Node): node is MenuItemGroup => node.type === ACTION_GROUP_TYPE;
+
+export type MenuItem = MenuSeparator | MenuAction | MenuItemGroup;
+
+export type MenuItemsResolver = (group?: MenuItemGroup) => MenuItem[] | null;
+
+export type MenuContextValue<A extends Node = MenuAction> = {
+  resolveGroupItems: MenuItemsResolver;
+  iconSize: IconButtonProps['size'];
+  onAction: MenuActionHandler<A>;
+  attendableId?: string;
+};

package/src/hooks.ts

@@ -0,0 +1,72 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useSignalEffect } from '@preact/signals-react';
+import { useCallback, useState } from 'react';
+
+import { Graph, type NodeArg, type Node } from '@dxos/app-graph';
+
+import { type MenuItem, type MenuItemGroup } from './defs';
+
+type Edge = { source: string; target: string };
+
+const edgesArrayToRecord = (edges: { source: string; target: string }[]): Record<string, string[]> => {
+  return Object.fromEntries(
+    Object.entries(
+      edges.reduce((acc: Record<string, { inbound: string[]; outbound: string[] }>, { source, target }) => {
+        if (!acc[source]) {
+          acc[source] = { inbound: [], outbound: [] };
+        }
+        if (!acc[target]) {
+          acc[target] = { inbound: [], outbound: [] };
+        }
+
+        const sourceEdges = acc[source];
+        if (!sourceEdges.outbound.includes(target)) {
+          sourceEdges.outbound.push(target);
+        }
+
+        const targetEdges = acc[target];
+        if (!targetEdges.inbound.includes(source)) {
+          targetEdges.inbound.push(source);
+        }
+
+        return acc;
+      }, {}),
+    ).map(([id, { outbound }]): [string, string[]] => [id, outbound]),
+  );
+};
+
+export type ActionGraphNodes = NodeArg<any>[];
+export type ActionGraphEdges = Edge[];
+export type ActionGraphProps = { nodes: ActionGraphNodes; edges: ActionGraphEdges };
+
+export const useMenuActions = (actionCreator: () => ActionGraphProps) => {
+  const initialMenuGraphProps = actionCreator();
+
+  const [graph] = useState(
+    new Graph({ nodes: initialMenuGraphProps.nodes as Node[], edges: edgesArrayToRecord(initialMenuGraphProps.edges) }),
+  );
+
+  useSignalEffect(() => {
+    const menuGraphProps = actionCreator();
+    // @ts-ignore
+    graph._addNodes(menuGraphProps.nodes);
+    // @ts-ignore
+    graph._addEdges(menuGraphProps.edges);
+  });
+
+  const resolveGroupItems = useCallback(
+    (sourceNode: MenuItemGroup = graph.root as MenuItemGroup) => {
+      if (graph) {
+        return (graph.nodes(sourceNode, { filter: (n): n is any => true }) || null) as MenuItem[] | null;
+      } else {
+        return null;
+      }
+    },
+    [graph],
+  );
+
+  return { resolveGroupItems };
+};

package/src/index.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './components';
+export * from './defs';
+export * from './hooks';
+export { createMenuAction, createMenuItemGroup, createLineSeparator, createGapSeparator } from './util';

package/src/testing/Menus.stories.tsx

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

package/src/testing/index.ts

@@ -0,0 +1,111 @@
+//
+// 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 MenuAction, type MenuItemGroup, type MenuItem } from '../defs';
+import { type ActionGraphProps } from '../hooks';
+
+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 createNestedActions = () => {
+  const result: ActionGraphProps = { edges: [], nodes: [] };
+  const actionGroups = createActions({ type: ACTION_GROUP_TYPE });
+  actionGroups.forEach((group) => {
+    const actions = createActions();
+    result.nodes.push(group, ...actions);
+    result.edges.push(
+      { source: 'root', target: group.id },
+      ...actions.map((action) => ({ source: group.id, target: action.id })),
+    );
+  });
+  return result;
+};
+
+export const createNestedActionsResolver = (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([
+      { source: 'root', target: group.id },
+      ...actions.map((action) => ({ source: group.id, target: action.id })),
+    ]);
+    void graph.expand(group);
+  });
+  const resolveGroupItems = (groupNode?: MenuItemGroup) =>
+    (graph.actions(groupNode ?? graph.root) || null) as MenuItem[] | null;
+  return { resolveGroupItems };
+};
+
+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,71 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { ACTION_GROUP_TYPE, ACTION_TYPE, actionGroupSymbol, type ActionLike } from '@dxos/app-graph';
+import { getHostPlatform } from '@dxos/util';
+
+import {
+  type MenuAction,
+  type MenuActionProperties,
+  type MenuItemGroup,
+  type MenuItemGroupProperties,
+  type MenuSeparator,
+} from './defs';
+
+export const getShortcut = (action: ActionLike) => {
+  return typeof action.properties?.keyBinding === 'string'
+    ? action.properties.keyBinding
+    : action.properties?.keyBinding?.[getHostPlatform()];
+};
+
+export const fallbackIcon = 'ph--placeholder--regular';
+
+// TODO(thure,wittjosiah): This is probably a smell; consider the whether react-ui-menu should use action nodes if the
+//  callback in `data` is never used. See https://github.com/dxos/dxos/pull/8506#discussion_r1925855118
+const noop = () => {};
+
+export const createMenuAction = <P extends {} = {}>(id: string, properties: P & MenuActionProperties) =>
+  ({
+    id,
+    type: ACTION_TYPE,
+    properties,
+    data: noop,
+  }) satisfies MenuAction;
+
+export const createMenuItemGroup = <
+  P extends MenuItemGroupProperties = MenuItemGroupProperties & Partial<MenuActionProperties>,
+>(
+  id: string,
+  properties: P,
+) =>
+  ({
+    id,
+    type: ACTION_GROUP_TYPE,
+    properties,
+    data: actionGroupSymbol,
+  }) satisfies MenuItemGroup;
+
+export const createGapSeparator = (id: string = 'gap', source: string = 'root') => ({
+  nodes: [
+    {
+      id,
+      type: '@dxos/react-ui-toolbar/separator',
+      properties: { variant: 'gap' },
+      data: undefined as never,
+    } satisfies MenuSeparator,
+  ],
+  edges: [{ source, target: id }],
+});
+
+export const createLineSeparator = (id: string = 'line', source: string = 'root') => ({
+  nodes: [
+    {
+      id,
+      type: '@dxos/react-ui-toolbar/separator',
+      properties: { variant: 'line' },
+      data: undefined as never,
+    } satisfies MenuSeparator,
+  ],
+  edges: [{ source, target: id }],
+});