@dxos/react-ui-editor 0.8.4-main.84f28bd → 0.8.4-main.937b3ca

package/src/components/EditorMenuProvider/EditorMenuProvider.tsx

@@ -0,0 +1,233 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type EditorView } from '@codemirror/view';
+import { useControllableState } from '@radix-ui/react-use-controllable-state';
+import React, { Fragment, type PropsWithChildren, useCallback, useEffect, useRef, useState } from 'react';
+
+import { addEventListener } from '@dxos/async';
+import { invariant } from '@dxos/invariant';
+import {
+  DX_ANCHOR_ACTIVATE,
+  type DxAnchorActivate,
+  Icon,
+  Popover,
+  toLocalizedString,
+  useDynamicRef,
+  useThemeContext,
+  useTranslation,
+} from '@dxos/react-ui';
+
+import { type EditorMenuGroup, type EditorMenuItem } from './menu';
+
+export type EditorMenuProviderProps = PropsWithChildren<{
+  view?: EditorView | null;
+  groups?: EditorMenuGroup[];
+  currentItem?: string;
+  open?: boolean;
+  defaultOpen?: boolean;
+  numItems?: number;
+  onOpenChange?: (event: { view: EditorView; open: boolean; trigger?: string }) => void;
+  onActivate?: (event: { view: EditorView; trigger?: string }) => void;
+  onSelect?: (event: { view: EditorView; item: EditorMenuItem }) => void;
+  onCancel?: (event: { view: EditorView }) => void;
+}>;
+
+/**
+ * Implements the Popover and listens for the `dx-anchor-activate` event from the
+ * `popover` extension's decoration.
+ *
+ * NOTE: We don't use DropdownMenu because the command menu needs to manage focus explicitly.
+ * I.e., focus must remain in the editor while displaying the menu (for type-ahead).
+ */
+export const EditorMenuProvider = ({
+  children,
+  view,
+  groups,
+  currentItem,
+  open: openProp,
+  defaultOpen,
+  numItems = 8,
+  onOpenChange,
+  onActivate,
+  onSelect,
+  onCancel,
+}: EditorMenuProviderProps) => {
+  const { tx } = useThemeContext();
+  const triggerRef = useRef<HTMLButtonElement | null>(null);
+
+  const viewRef = useDynamicRef(view);
+  const [open, setOpen] = useControllableState({
+    prop: openProp,
+    defaultProp: defaultOpen,
+    onChange: (open) => {
+      invariant(viewRef.current);
+      onOpenChange?.({ view: viewRef.current, open });
+    },
+  });
+
+  const [root, setRoot] = useState<HTMLDivElement | null>(null);
+  useEffect(() => {
+    if (!root) {
+      return;
+    }
+
+    // Listen for trigger.
+    return addEventListener(
+      root,
+      DX_ANCHOR_ACTIVATE as any,
+      (event: DxAnchorActivate) => {
+        const { trigger, refId } = event;
+
+        // If this has a `refId`, then it’s probably a URL or DXN and out of scope for this component.
+        if (!refId) {
+          triggerRef.current = trigger as HTMLButtonElement;
+          if (onActivate) {
+            onActivate({ view: viewRef.current!, trigger: trigger.getAttribute('data-trigger') ?? undefined });
+          } else {
+            requestAnimationFrame(() => setOpen(true));
+          }
+        }
+      },
+      {
+        capture: true,
+        passive: false,
+      },
+    );
+  }, [root, onActivate]);
+
+  const handleSelect = useCallback<NonNullable<MenuProps['onSelect']>>(
+    (item) => {
+      invariant(viewRef.current);
+      onSelect?.({ view: viewRef.current, item });
+    },
+    [viewRef, onSelect],
+  );
+
+  const menuGroups = groups?.filter((group) => group.items.length > 0) ?? [];
+
+  return (
+    <Popover.Root modal={false} open={open} onOpenChange={setOpen}>
+      <Popover.VirtualTrigger virtualRef={triggerRef} />
+
+      {/* Menu. */}
+      <Popover.Portal>
+        <Popover.Content
+          align='start'
+          classNames={tx('menu.content', 'menu--exotic-unfocusable', { elevation: 'positioned' }, [
+            'overflow-y-auto',
+            !menuGroups.length && 'hidden',
+          ])}
+          style={{
+            maxBlockSize: 36 * numItems + 10,
+          }}
+          /**
+           * NOTE: We keep the focus in the editor, but Radix routes escape key.
+           */
+          onEscapeKeyDown={() => {
+            // NOTE: Able to cancel if not in valid state.
+            // event.preventDefault();
+            onCancel?.({ view: view! });
+          }}
+          onOpenAutoFocus={(event) => event.preventDefault()}
+        >
+          <Popover.Viewport classNames={tx('menu.viewport', 'menu__viewport--exotic-unfocusable', {})}>
+            <Menu groups={menuGroups} currentItem={currentItem} onSelect={handleSelect} />
+          </Popover.Viewport>
+          <Popover.Arrow />
+        </Popover.Content>
+      </Popover.Portal>
+
+      {/* Content */}
+      <div ref={setRoot} role='none' className='contents'>
+        {children}
+      </div>
+    </Popover.Root>
+  );
+};
+
+//
+// Menu
+//
+
+type MenuProps = {
+  groups: EditorMenuGroup[];
+} & Pick<MenuGroupProps, 'currentItem' | 'onSelect'>;
+
+const Menu = ({ groups, currentItem, onSelect }: MenuProps) => {
+  const { tx } = useThemeContext();
+  return (
+    <ul>
+      {groups.map((group, index) => (
+        <Fragment key={group.id}>
+          <MenuGroup group={group} currentItem={currentItem} onSelect={onSelect} />
+          {index < groups.length - 1 && <div className={tx('menu.separator', 'menu__item', {})} />}
+        </Fragment>
+      ))}
+    </ul>
+  );
+};
+
+//
+// Menu Group
+//
+
+type MenuGroupProps = {
+  group: EditorMenuGroup;
+  currentItem?: string;
+} & Pick<MenuItemProps, 'onSelect'>;
+
+const MenuGroup = ({ group, currentItem, onSelect }: MenuGroupProps) => {
+  const { tx } = useThemeContext();
+  const { t } = useTranslation();
+
+  return (
+    <>
+      {group.label && (
+        <div className={tx('menu.groupLabel', 'menu__group__label', {})}>
+          <span>{toLocalizedString(group.label, t)}</span>
+        </div>
+      )}
+
+      {group.items.map((item) => (
+        <MenuItem key={item.id} item={item} current={currentItem === item.id} onSelect={onSelect} />
+      ))}
+    </>
+  );
+};
+
+//
+// Menu Item
+//
+
+type MenuItemProps = {
+  item: EditorMenuItem;
+  current: boolean;
+  onSelect?: (item: EditorMenuItem) => void;
+};
+
+const MenuItem = ({ item, current, onSelect }: MenuItemProps) => {
+  const { tx } = useThemeContext();
+  const { t } = useTranslation();
+
+  const listRef = useRef<HTMLLIElement>(null);
+  useEffect(() => {
+    if (current && listRef.current) {
+      listRef.current.scrollIntoView({ behavior: 'smooth', block: 'nearest' });
+    }
+  }, [current]);
+
+  const handleSelect = useCallback(() => onSelect?.(item), [item, onSelect]);
+
+  return (
+    <li
+      ref={listRef}
+      className={tx('menu.item', 'menu__item--exotic-unfocusable', {}, [current && 'bg-hoverSurface'])}
+      onClick={handleSelect}
+    >
+      {item.icon && <Icon icon={item.icon} size={5} />}
+      <span className='grow truncate'>{toLocalizedString(item.label, t)}</span>
+    </li>
+  );
+};

package/src/components/EditorMenuProvider/index.ts

@@ -0,0 +1,10 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './menu';
+export * from './menu-presets';
+export * from './popover';
+
+export * from './EditorMenuProvider';
+export * from './useEditorMenu';

package/src/components/EditorMenuProvider/menu-presets.ts

@@ -0,0 +1,124 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { insertAtLineStart } from '@dxos/ui-editor';
+
+import { type EditorMenuGroup } from './menu';
+import { popoverRangeEffect } from './popover';
+
+export const formattingCommands: EditorMenuGroup = {
+  id: 'markdown',
+  label: 'Markdown',
+  items: [
+    {
+      id: 'heading-1',
+      label: 'Heading 1',
+      icon: 'ph--text-h-one--regular',
+      onSelect: ({ view, head }) => insertAtLineStart(view, head, '# '),
+    },
+    {
+      id: 'heading-2',
+      label: 'Heading 2',
+      icon: 'ph--text-h-two--regular',
+      onSelect: ({ view, head }) => insertAtLineStart(view, head, '## '),
+    },
+    {
+      id: 'heading-3',
+      label: 'Heading 3',
+      icon: 'ph--text-h-three--regular',
+      onSelect: ({ view, head }) => insertAtLineStart(view, head, '### '),
+    },
+    {
+      id: 'heading-4',
+      label: 'Heading 4',
+      icon: 'ph--text-h-four--regular',
+      onSelect: ({ view, head }) => insertAtLineStart(view, head, '#### '),
+    },
+    {
+      id: 'heading-5',
+      label: 'Heading 5',
+      icon: 'ph--text-h-five--regular',
+      onSelect: ({ view, head }) => insertAtLineStart(view, head, '##### '),
+    },
+    {
+      id: 'heading-6',
+      label: 'Heading 6',
+      icon: 'ph--text-h-six--regular',
+      onSelect: ({ view, head }) => insertAtLineStart(view, head, '###### '),
+    },
+    {
+      id: 'bullet-list',
+      label: 'Bullet List',
+      icon: 'ph--list-bullets--regular',
+      onSelect: ({ view, head }) => insertAtLineStart(view, head, '- '),
+    },
+    {
+      id: 'numbered-list',
+      label: 'Numbered List',
+      icon: 'ph--list-numbers--regular',
+      onSelect: ({ view, head }) => insertAtLineStart(view, head, '1. '),
+    },
+    {
+      id: 'task-list',
+      label: 'Task List',
+      icon: 'ph--list-checks--regular',
+      onSelect: ({ view, head }) => insertAtLineStart(view, head, '- [ ] '),
+    },
+    {
+      id: 'quote',
+      label: 'Quote',
+      icon: 'ph--quotes--regular',
+      onSelect: ({ view, head }) => insertAtLineStart(view, head, '> '),
+    },
+    {
+      id: 'code-block',
+      label: 'Code Block',
+      icon: 'ph--code-block--regular',
+      onSelect: ({ view, head }) => insertAtLineStart(view, head, '```\n\n```'),
+    },
+    {
+      id: 'table',
+      label: 'Table',
+      icon: 'ph--table--regular',
+      onSelect: ({ view, head }) => insertAtLineStart(view, head, '| | | |\n|---|---|---|\n| | | |'),
+    },
+  ],
+};
+
+export const linkSlashCommands: EditorMenuGroup = {
+  id: 'link',
+  label: 'Link',
+  items: [
+    {
+      id: 'inline-link',
+      label: 'Inline link',
+      icon: 'ph--link--regular',
+      onSelect: ({ view, head }) => {
+        view.dispatch({
+          changes: { from: head, insert: '@' },
+          selection: { anchor: head + 1, head: head + 1 },
+          effects: popoverRangeEffect.of({
+            trigger: '@',
+            range: { from: head, to: head + 1 },
+          }),
+        });
+      },
+    },
+    {
+      id: 'block-embed',
+      label: 'Block embed',
+      icon: 'ph--lego--regular',
+      onSelect: ({ view, head }) => {
+        view.dispatch({
+          changes: { from: head, insert: '@@' },
+          selection: { anchor: head + 2, head: head + 2 },
+          effects: popoverRangeEffect.of({
+            trigger: '@',
+            range: { from: head, to: head + 2 },
+          }),
+        });
+      },
+    },
+  ],
+};

package/src/components/EditorMenuProvider/menu.ts

@@ -0,0 +1,70 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type EditorView } from '@codemirror/view';
+
+import { type Label } from '@dxos/react-ui';
+import { insertAtCursor } from '@dxos/ui-editor';
+import { type MaybePromise } from '@dxos/util';
+
+export type EditorMenuGroup = {
+  id: string;
+  label?: Label;
+  items: EditorMenuItem[];
+};
+
+export type EditorMenuItem = {
+  id: string;
+  label: Label;
+  icon?: string;
+  onSelect?: (event: { view: EditorView; head: number }) => MaybePromise<void>;
+};
+
+export const getMenuItem = (groups: EditorMenuGroup[], id?: string): EditorMenuItem | undefined => {
+  return groups.flatMap((group) => group.items).find((item) => item.id === id);
+};
+
+export const getNextMenuItem = (groups: EditorMenuGroup[], id?: string): EditorMenuItem => {
+  const items = groups.flatMap((group) => group.items);
+  const index = items.findIndex((item) => item.id === id);
+  return index < items.length - 1 ? items[index + 1] : items[index];
+};
+
+export const getPreviousMenuItem = (groups: EditorMenuGroup[], id?: string): EditorMenuItem => {
+  const items = groups.flatMap((group) => group.items);
+  const index = items.findIndex((item) => item.id === id);
+  return index > 0 ? items[index - 1] : items[index];
+};
+
+export const createMenuGroup = ({
+  id = 'menu',
+  label,
+  filter,
+  items,
+}: {
+  id?: string;
+  label?: Label;
+  filter?: string;
+  items: string[];
+}): EditorMenuGroup => ({
+  id,
+  label,
+  items: items
+    .filter((item) => !filter || item.toLowerCase().includes(filter.toLowerCase()))
+    .map((item, i) => ({
+      id: `${id}-${i}`,
+      label: item,
+      onSelect: ({ view, head }) => insertAtCursor(view, head, item),
+    })),
+});
+
+export const filterMenuGroups = (
+  groups: EditorMenuGroup[],
+  filter: (item: EditorMenuItem) => boolean,
+): EditorMenuGroup[] => {
+  return groups.map((group) => ({
+    ...group,
+    items: group.items.filter(filter),
+  }));
+};