@dxos/react-ui-editor 0.8.4-main.fd6878d → 0.8.4-staging.60fe92afc8

package/src/components/EditorMenuProvider/popover.ts

@@ -0,0 +1,320 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { type Extension, Prec, RangeSetBuilder, StateEffect, StateField } from '@codemirror/state';
+import {
+  Decoration,
+  type DecorationSet,
+  EditorView,
+  type KeyBinding,
+  ViewPlugin,
+  type ViewUpdate,
+  keymap,
+} from '@codemirror/view';
+
+import { type PlaceholderOptions, modalStateField, placeholder } from '@dxos/ui-editor';
+import { type Range } from '@dxos/ui-editor/types';
+import { isNonNullable, isTruthy } from '@dxos/util';
+
+const DELIMITERS = [' ', ':'];
+
+export type PopoverOptions = {
+  trigger?: string | string[];
+  triggerKey?: string;
+  placeholder?: Partial<PlaceholderOptions>;
+  delimiters?: string[];
+
+  /**
+   * Open the popover automatically while typing a word (no trigger character required).
+   * The completion range covers the word under the cursor (delimited by {@link PopoverOptions.delimiters}).
+   */
+  activateOnTyping?: boolean;
+
+  // Trigger update.
+  onTextChange?: (event: { view: EditorView; pos: number; text: string; trigger?: string }) => void;
+  onClose?: (event: { view: EditorView }) => void;
+
+  // Menu specific.
+  /** Returns true when the menu consumed the key (an item was selected); false falls through. */
+  onEnter?: (event: { view: EditorView }) => boolean | void;
+  onArrowUp?: (event: { view: EditorView }) => void;
+  onArrowDown?: (event: { view: EditorView }) => void;
+};
+
+/**
+ * Creates a popover that appears when the trigger character is inserted.
+ * This can be used for context menus or autocompletion.
+ */
+export const popover = (options: PopoverOptions = {}): Extension => {
+  return [
+    Prec.highest(popoverKeymap(options)),
+    popoverStateField,
+    popoverTriggerListener(options),
+    options.activateOnTyping && popoverAutoActivate(options),
+    popoverAnchorDecoration(options),
+    modalStateField,
+    options.trigger &&
+      placeholder({
+        // TODO(burdon): Translations.
+        content: `Press '${Array.isArray(options.trigger) ? options.trigger[0] : options.trigger}' for commands`,
+        focusOnly: true,
+        ...options.placeholder,
+      }),
+  ].filter(isTruthy);
+};
+
+/**
+ * Listen for selection and document changes.
+ */
+const popoverTriggerListener = (options: PopoverOptions) =>
+  EditorView.updateListener.of(({ view, docChanged }) => {
+    const { range: activeRange, trigger } = view.state.field(popoverStateField) ?? {};
+    if (!activeRange) {
+      return;
+    }
+
+    const text = view.state.doc.sliceString(activeRange.from, activeRange.to);
+    const selection = view.state.selection.main;
+    const shouldClose =
+      // Trigger deleted.
+      (trigger ? trigger !== text[0] : false) ||
+      // Whitespace in text.
+      /\s/.test(trigger ? text.slice(1) : text) ||
+      // Cursor moved before the range.
+      selection.head < activeRange.from ||
+      // Cursor moved after the range (+1 to handle selection changing before doc).
+      selection.head > activeRange.to + 1;
+
+    const nextRange = shouldClose ? null : docChanged ? { from: activeRange.from, to: selection.head } : activeRange;
+    if (nextRange !== activeRange) {
+      view.dispatch({
+        effects: popoverRangeEffect.of(nextRange ? { range: nextRange, trigger } : null),
+      });
+    }
+
+    if (shouldClose) {
+      options.onClose?.({ view });
+    }
+  });
+
+/**
+ * Open the popover while typing a word, without requiring a trigger character. Once a range is
+ * active, {@link popoverTriggerListener} keeps it in sync and closes it (whitespace, cursor moves).
+ */
+const popoverAutoActivate = (options: PopoverOptions) =>
+  EditorView.updateListener.of(({ view, docChanged, transactions }) => {
+    // Only user input opens the popover — programmatic syncs (e.g. a controlled `value` update on
+    // mount) must not pop the menu.
+    if (!docChanged || !transactions.some((tr) => tr.isUserEvent('input')) || view.state.field(popoverStateField)) {
+      return;
+    }
+    const selection = view.state.selection.main;
+    if (!selection.empty) {
+      return;
+    }
+    const line = view.state.doc.lineAt(selection.head);
+    const before = line.text.slice(0, selection.head - line.from);
+    const idx = getLastIndexOf(before, options.delimiters ?? DELIMITERS);
+    const token = before.slice(idx + 1);
+    if (token.length === 0) {
+      return;
+    }
+    view.dispatch({
+      effects: popoverRangeEffect.of({ range: { from: line.from + idx + 1, to: selection.head } }),
+    });
+  });
+
+/**
+ * Popover navigation.
+ */
+const popoverKeymap = (options: PopoverOptions) => {
+  const triggers = Array.isArray(options.trigger) ? options.trigger : [options.trigger];
+  return keymap.of(
+    [
+      // Prefix triggers.
+      ...triggers.filter(isNonNullable).map((trigger) => ({
+        key: trigger,
+        run: (view: EditorView) => {
+          // Determine if we should trigger the popover:
+          // 1. Empty lines or at the beginning of a line.
+          // 2. When there's a preceding space.
+          const selection = view.state.selection.main;
+          const line = view.state.doc.lineAt(selection.head);
+          if (
+            line.text.trim() === '' ||
+            selection.head === line.from ||
+            (selection.head > line.from && line.text[selection.head - line.from - 1] === ' ')
+          ) {
+            // Insert and select the trigger.
+            view.dispatch({
+              changes: { from: selection.head, insert: trigger },
+              selection: { anchor: selection.head + 1, head: selection.head + 1 },
+              effects: popoverRangeEffect.of({ trigger, range: { from: selection.head, to: selection.head + 1 } }),
+            });
+
+            return true;
+          }
+
+          return false;
+        },
+      })),
+
+      //
+      // Custom trigger.
+      //
+      options.triggerKey &&
+        ({
+          key: options.triggerKey,
+          run: (view: EditorView) => {
+            const selection = view.state.selection.main;
+            const line = view.state.doc.lineAt(selection.head);
+
+            // Get last word.
+            let str = line.text.slice(0, selection.head - line.from);
+            const idx = getLastIndexOf(str, options.delimiters ?? DELIMITERS);
+            if (idx !== -1) {
+              str = str.slice(idx + 1);
+            }
+
+            // Create anchor even if zero length (append space).
+            const from = line.from + idx;
+            view.dispatch({
+              effects: popoverRangeEffect.of({ range: { from: from + 1, to: selection.head } }),
+              changes:
+                selection.head === view.state.doc.length
+                  ? { from: from + 1, to: selection.head, insert: ' ' }
+                  : undefined,
+            });
+            return true;
+          },
+        } satisfies KeyBinding),
+
+      //
+      // Nav keys.
+      //
+      {
+        key: 'ArrowUp',
+        run: (view: EditorView) => {
+          const range = view.state.field(popoverStateField)?.range;
+          if (range) {
+            options.onArrowUp?.({ view });
+            return true;
+          }
+
+          return false;
+        },
+      },
+      {
+        key: 'ArrowDown',
+        run: (view: EditorView) => {
+          const range = view.state.field(popoverStateField)?.range;
+          if (range) {
+            options.onArrowDown?.({ view });
+            return true;
+          }
+
+          return false;
+        },
+      },
+      {
+        key: 'Enter',
+        run: (view: EditorView) => {
+          const range = view.state.field(popoverStateField)?.range;
+          if (range) {
+            // The consumer deletes the range when it selects an item; when nothing is selectable
+            // (empty menu over an `activateOnTyping` range) the key must fall through so the
+            // typed text is preserved.
+            return options.onEnter?.({ view }) ?? false;
+          }
+
+          return false;
+        },
+      },
+    ].filter(isTruthy),
+  );
+};
+
+/**
+ * Creates a <dx-anchor> tag, which is used to anchor the Popver.
+ */
+const popoverAnchorDecoration = (options: PopoverOptions) => {
+  return ViewPlugin.fromClass(
+    class {
+      _decorations: DecorationSet = Decoration.none;
+
+      constructor(readonly view: EditorView) {}
+
+      // TODO(wittjosiah): The decorations are repainted on every update, this occasionally causes menu to flicker.
+      update({ view, transactions }: ViewUpdate) {
+        const builder = new RangeSetBuilder<Decoration>();
+        const { range, trigger } = view.state.field(popoverStateField) ?? {};
+        if (range) {
+          // Check if we should show the widget (only if cursor is within the active command range).
+          const selection = view.state.selection.main;
+          const showWidget = selection.head >= range.from && selection.head <= range.to;
+          if (showWidget) {
+            builder.add(
+              range.from,
+              range.to + 1,
+              Decoration.mark({
+                tagName: 'dx-anchor',
+                class: 'cm-popover-trigger',
+                attributes: {
+                  'data-visible-focus': 'false',
+                  'data-auto-trigger': 'true',
+                  'data-trigger': trigger ?? options.triggerKey ?? '',
+                },
+              }),
+            );
+          }
+
+          const rangeChanged = transactions.some((tr) => tr.effects.some((effect) => effect.is(popoverRangeEffect)));
+          if (rangeChanged) {
+            // NOTE: Content skips the trigger character.
+            const content = view.state.sliceDoc(range.from + (trigger ? trigger.length : 0), range.to);
+            options.onTextChange?.({ view, pos: selection.head, text: content, trigger });
+          }
+        }
+
+        this._decorations = builder.finish();
+      }
+    },
+    {
+      decorations: (v) => v._decorations,
+    },
+  );
+};
+
+type PopoverState = {
+  /**
+   * Trigger prefix (in document).
+   */
+  trigger?: string;
+
+  /**
+   * Current document completion range.
+   */
+  range: Range;
+};
+
+// State effects for managing popover state.
+export const popoverRangeEffect = StateEffect.define<PopoverState | null>();
+
+// State field to track the active popover trigger range.
+export const popoverStateField = StateField.define<PopoverState | null>({
+  create: () => null,
+  update: (value, tr) => {
+    let newValue = value;
+    for (const effect of tr.effects) {
+      if (effect.is(popoverRangeEffect)) {
+        newValue = effect.value;
+      }
+    }
+
+    return newValue;
+  },
+});
+
+const getLastIndexOf = (str: string, delimiters: string[]) =>
+  Math.max(...delimiters.map((delim) => str.lastIndexOf(delim)));

package/src/components/EditorMenuProvider/useEditorMenu.ts

@@ -0,0 +1,189 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { type Extension } from '@codemirror/state';
+import { type EditorState } from '@codemirror/state';
+import { type RefObject, useCallback, useMemo, useRef, useState } from 'react';
+
+import { invariant } from '@dxos/invariant';
+import { modalStateEffect } from '@dxos/ui-editor';
+import { type MaybePromise } from '@dxos/util';
+
+import { type EditorMenuProviderProps } from './EditorMenuProvider';
+import { type EditorMenuGroup, type EditorMenuItem } from './menu';
+import { filterMenuGroups, getMenuItem, getNextMenuItem, getPreviousMenuItem } from './menu';
+import { type PopoverOptions, popover, popoverRangeEffect, popoverStateField } from './popover';
+
+export type GetMenuContext = {
+  state: EditorState;
+  pos: number;
+  text: string;
+  trigger?: string;
+};
+
+export type UseEditorMenuProps = {
+  filter?: boolean;
+  getMenu?: (context: GetMenuContext) => MaybePromise<EditorMenuGroup[]>;
+} & Pick<PopoverOptions, 'trigger' | 'triggerKey' | 'placeholder' | 'activateOnTyping'>;
+
+export type UseEditorMenu = {
+  groupsRef: RefObject<EditorMenuGroup[]>;
+  extension: Extension;
+} & Pick<EditorMenuProviderProps, 'currentItem' | 'open' | 'onOpenChange' | 'onActivate' | 'onSelect' | 'onCancel'>;
+
+/**
+ * ```tsx
+ * const { groupsRef, extension, ...menuProps } = useEditorMenu();
+ * const { parentRef, viewRef } = useTextEditor({ extensions: [extension] });
+ * return (
+ *   <EditorMenuProvider getView={() => viewRef.current} groups={groupsRef.current} {...menuProps}>
+ *     <div ref={parentRef} />
+ *   </EditorMenuProvider>
+ * );
+ * ```
+ */
+export const useEditorMenu = ({
+  trigger,
+  triggerKey,
+  placeholder,
+  activateOnTyping,
+  filter = true,
+  getMenu,
+}: UseEditorMenuProps): UseEditorMenu => {
+  const groupsRef = useRef<EditorMenuGroup[]>([]);
+  const currentRef = useRef<EditorMenuItem | null>(null);
+  const [currentItem, setCurrentItem] = useState<string>();
+  const [open, setOpen] = useState(false);
+  const [_, refresh] = useState({});
+
+  /**
+   * Get filtered options.
+   */
+  const getMenuOptions = useCallback<NonNullable<UseEditorMenuProps['getMenu']>>(
+    async ({ text, trigger, ...props }) => {
+      const groups = (await getMenu?.({ text, trigger, ...props })) ?? [];
+      // The "@" menu can use "@@" as syntax for block embeds, so it owns its own query filtering.
+      return filter && trigger !== '@'
+        ? filterMenuGroups(groups, (item) =>
+            text ? (item.label as string).toLowerCase().startsWith(text.toLowerCase()) : true,
+          )
+        : groups;
+    },
+    [getMenu, filter],
+  );
+
+  const handleOpenChange = useCallback<NonNullable<UseEditorMenu['onOpenChange']>>(
+    async ({ view, open }) => {
+      invariant(view);
+      setOpen(open);
+      if (!open) {
+        setCurrentItem(undefined);
+        view.dispatch({
+          effects: [popoverRangeEffect.of(null)],
+        });
+      }
+
+      // TODO(burdon): Possible race condition.
+      //  useTextEditor.handleKeyDown will get called after this handler completes.
+      requestAnimationFrame(() => {
+        view.dispatch({
+          effects: [modalStateEffect.of(open)],
+        });
+      });
+    },
+    [getMenuOptions],
+  );
+
+  const handleActivate = useCallback<NonNullable<UseEditorMenu['onActivate']>>(
+    async ({ view, trigger }) => {
+      const item = getMenuItem(groupsRef.current, currentItem);
+      if (item) {
+        currentRef.current = item;
+      }
+
+      if (!open) {
+        handleOpenChange({ view, open: true, trigger });
+      }
+    },
+    [open, handleOpenChange],
+  );
+
+  const handleSelect = useCallback<NonNullable<UseEditorMenu['onSelect']>>(({ view, item }) => {
+    // Delete trigger range (e.g., "/" and any typed filter text).
+    const { range } = view.state.field(popoverStateField) ?? {};
+    if (range) {
+      view.dispatch({ changes: { from: range.from, to: range.to, insert: '' } });
+    }
+    void item.onSelect?.({ view, head: view.state.selection.main.head });
+    view.focus();
+  }, []);
+
+  const handleCancel = useCallback<NonNullable<UseEditorMenu['onCancel']>>(({ view }) => {
+    // Delete trigger.
+    const { range, trigger } = view.state.field(popoverStateField) ?? {};
+    if (range && trigger) {
+      view.dispatch({
+        changes: { ...range, insert: '' },
+      });
+    }
+  }, []);
+
+  const serializedTrigger = Array.isArray(trigger) ? trigger.join(',') : trigger;
+  const extension = useMemo<Extension>(() => {
+    return popover({
+      trigger,
+      triggerKey,
+      placeholder,
+      activateOnTyping,
+      onClose: ({ view }) => handleOpenChange({ view, open: false }),
+      onEnter: ({ view }) => {
+        if (currentRef.current) {
+          handleSelect({ view, item: currentRef.current });
+          return true;
+        }
+        return false;
+      },
+      onArrowUp: () => {
+        setCurrentItem((currentItem) => {
+          const previous = getPreviousMenuItem(groupsRef.current, currentItem);
+          currentRef.current = previous;
+          return previous.id;
+        });
+      },
+      onArrowDown: () => {
+        setCurrentItem((currentItem) => {
+          const next = getNextMenuItem(groupsRef.current, currentItem);
+          currentRef.current = next;
+          return next.id;
+        });
+      },
+      onTextChange: async ({ view, pos, text, trigger }) => {
+        groupsRef.current = (await getMenuOptions({ state: view.state, pos, text, trigger })) ?? [];
+        const firstItem = groupsRef.current.filter((group) => group.items.length > 0)[0]?.items[0];
+        if (firstItem) {
+          setCurrentItem(firstItem.id);
+          currentRef.current = firstItem;
+        } else {
+          // No matches: clear the selection so Enter falls through instead of
+          // selecting a stale item from a previous query.
+          setCurrentItem(undefined);
+          currentRef.current = null;
+        }
+
+        refresh({});
+      },
+    });
+  }, [handleOpenChange, getMenuOptions, serializedTrigger, placeholder, activateOnTyping]);
+
+  return {
+    groupsRef,
+    extension,
+    currentItem,
+    open,
+    onOpenChange: handleOpenChange,
+    onActivate: handleActivate,
+    onSelect: handleSelect,
+    onCancel: handleCancel,
+  };
+};

package/src/components/EditorPreviewProvider/EditorPreviewProvider.tsx

@@ -0,0 +1,79 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { createContext } from '@radix-ui/react-context';
+import React, { type PropsWithChildren, type RefObject, useCallback, useEffect, useRef, useState } from 'react';
+
+import { addEventListener } from '@dxos/async';
+import { DX_ANCHOR_ACTIVATE, type DxAnchorActivate, Popover } from '@dxos/react-ui';
+import { type PreviewLinkRef, type PreviewLinkTarget } from '@dxos/ui-editor';
+
+type EditorPreviewPopoverValue = Partial<{
+  link: PreviewLinkRef;
+  target: PreviewLinkTarget;
+  pending: boolean;
+}>;
+
+const [EditorPreviewContextProvider, useEditorPreview] = createContext<EditorPreviewPopoverValue>('PreviewPopover', {});
+
+export type EditorPreviewProviderProps = PropsWithChildren<{
+  onLookup?: (link: PreviewLinkRef) => Promise<PreviewLinkTarget | null | undefined>;
+}>;
+
+/**
+ * NOTE: In Composer, the DeckPlugin provides the Popover.Root as part of the DeckLayout.
+ */
+// TOOD(burdon): Reconcile with PreviewPlugin.
+export const EditorPreviewProvider = ({ children, onLookup }: EditorPreviewProviderProps) => {
+  const triggerRef = useRef<HTMLElement | null>(null);
+  const [value, setValue] = useState<EditorPreviewPopoverValue>({});
+  const [open, setOpen] = useState(false);
+
+  const handleActivate = useCallback(
+    (event: DxAnchorActivate) => {
+      const { dxn, label, trigger } = event;
+      setValue((value) => ({
+        ...value,
+        link: { label, dxn },
+        pending: true,
+      }));
+
+      triggerRef.current = trigger;
+      queueMicrotask(() => setOpen(true));
+      void onLookup?.({ label, dxn }).then((target) =>
+        setValue((value) => ({
+          ...value,
+          target: target ?? undefined,
+          pending: false,
+        })),
+      );
+    },
+    [onLookup],
+  );
+
+  const [root, setRoot] = useState<HTMLDivElement | null>(null);
+  useEffect(() => {
+    if (!root || !handleActivate) {
+      return;
+    }
+
+    return addEventListener(root, DX_ANCHOR_ACTIVATE as any, handleActivate, {
+      capture: true,
+      passive: false,
+    });
+  }, [root, handleActivate]);
+
+  return (
+    <EditorPreviewContextProvider pending={value.pending} link={value.link} target={value.target}>
+      <Popover.Root open={open} onOpenChange={setOpen}>
+        <Popover.VirtualTrigger virtualRef={triggerRef as unknown as RefObject<HTMLButtonElement>} />
+        <div className='contents' ref={setRoot}>
+          {children}
+        </div>
+      </Popover.Root>
+    </EditorPreviewContextProvider>
+  );
+};
+
+export { useEditorPreview };

package/src/components/EditorPreviewProvider/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './EditorPreviewProvider';