@dxos/react-ui-editor 0.8.4-main.3f58842 → 0.8.4-main.406dc2a

package/src/extensions/popover/popover.ts

@@ -0,0 +1,293 @@
+//
+// 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 { isNonNullable, isTruthy } from '@dxos/util';
+
+import { type Range } from '../../types';
+import { type PlaceholderOptions, placeholder } from '../autocomplete';
+
+import { modalStateField } from './modal';
+
+const DELIMITERS = [' ', ':'];
+
+export type PopoverOptions = {
+  trigger?: string | string[];
+  triggerKey?: string;
+  placeholder?: Partial<PlaceholderOptions>;
+  delimiters?: string[];
+
+  // TODO(burdon): Auto.
+  // activateOnTyping?: boolean;
+
+  // Trigger update.
+  onTextChange?: (event: { view: EditorView; pos: number; text: string; trigger?: string }) => void;
+  onClose?: (event: { view: EditorView }) => void;
+
+  // Menu specific.
+  onEnter?: (event: { view: EditorView }) => 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),
+    popoverAnchorDecoration(options),
+    modalStateField,
+    options.trigger &&
+      placeholder({
+        // TODO(burdon): Translations.
+        content: `Press '${Array.isArray(options.trigger) ? options.trigger[0] : options.trigger}' for commands`,
+        ...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 });
+    }
+  });
+
+/**
+ * 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;
+            console.log('effect', from + 1, selection.head);
+            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) {
+            view.dispatch({ changes: { from: range.from, to: range.to, insert: '' } });
+            options.onEnter?.({ view });
+            return true;
+          }
+
+          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;
+          console.log('update', showWidget, range.from, range.to + 1);
+          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 });
+          }
+        } else {
+          console.log('remove');
+        }
+
+        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/extensions/popover/usePopoverMenu.ts

@@ -0,0 +1,173 @@
+//
+// 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 { type MaybePromise } from '@dxos/util';
+
+import { type PopoverMenuGroup, type PopoverMenuItem } from './menu';
+import { filterMenuGroups, getMenuItem, getNextMenuItem, getPreviousMenuItem } from './menu';
+import { modalStateEffect } from './modal';
+import { type PopoverOptions, popover, popoverRangeEffect, popoverStateField } from './popover';
+import { type PopoverMenuProviderProps } from './PopoverMenuProvider';
+
+export type GetMenuContext = {
+  state: EditorState;
+  pos: number;
+  text: string;
+  trigger?: string;
+};
+
+export type UsePopoverMenuProps = {
+  filter?: boolean;
+  getMenu?: (context: GetMenuContext) => MaybePromise<PopoverMenuGroup[]>;
+} & Pick<PopoverOptions, 'trigger' | 'triggerKey' | 'placeholder'>;
+
+export type UsePopoverMenu = {
+  groupsRef: RefObject<PopoverMenuGroup[]>;
+  extension: Extension;
+} & Pick<PopoverMenuProviderProps, 'currentItem' | 'open' | 'onOpenChange' | 'onActivate' | 'onSelect' | 'onCancel'>;
+
+/**
+ * ```tsx
+ * const { groupsRef, extension, ...menuProps } = usePopoverMenu();
+ * const { parentRef, viewRef } = useTextEditor({ extensions: [extension] });
+ * return (
+ *   <PopoverMenuProvider view={viewRef.current} groups={groupsRef.current} {...menuProps}>
+ *     <div ref={parentRef} />
+ *   </PopoverMenuProvider>
+ * );
+ * ```
+ */
+export const usePopoverMenu = ({
+  trigger,
+  triggerKey,
+  placeholder,
+  filter = true,
+  getMenu,
+}: UsePopoverMenuProps): UsePopoverMenu => {
+  const groupsRef = useRef<PopoverMenuGroup[]>([]);
+  const currentRef = useRef<PopoverMenuItem | null>(null);
+  const [currentItem, setCurrentItem] = useState<string>();
+  const [open, setOpen] = useState(false);
+  const [_, refresh] = useState({});
+
+  /**
+   * Get filtered options.
+   */
+  const getMenuOptions = useCallback<NonNullable<UsePopoverMenuProps['getMenu']>>(
+    async ({ text, trigger, ...props }) => {
+      const groups = (await getMenu?.({ text, trigger, ...props })) ?? [];
+      return filter
+        ? filterMenuGroups(groups, (item) =>
+            text ? (item.label as string).toLowerCase().startsWith(text.toLowerCase()) : true,
+          )
+        : groups;
+    },
+    [getMenu, filter],
+  );
+
+  const handleOpenChange = useCallback<NonNullable<UsePopoverMenu['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<UsePopoverMenu['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<UsePopoverMenu['onSelect']>>(({ view, item }) => {
+    void item.onSelect?.(view, view.state.selection.main.head);
+  }, []);
+
+  const handleCancel = useCallback<NonNullable<UsePopoverMenu['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,
+      onClose: ({ view }) => handleOpenChange({ view, open: false }),
+      onEnter: ({ view }) => {
+        if (currentRef.current) {
+          handleSelect({ view, item: currentRef.current });
+        }
+      },
+      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;
+        }
+
+        refresh({});
+      },
+    });
+  }, [handleOpenChange, getMenuOptions, serializedTrigger, placeholder]);
+
+  return {
+    groupsRef,
+    extension,
+    currentItem,
+    open,
+    onOpenChange: handleOpenChange,
+    onActivate: handleActivate,
+    onSelect: handleSelect,
+    onCancel: handleCancel,
+  };
+};

package/src/extensions/popover/util.ts

@@ -0,0 +1,29 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type EditorView } from '@codemirror/view';
+
+export const insertAtCursor = (view: EditorView, from: number, insert: string) => {
+  view.dispatch({
+    changes: { from, to: from, insert },
+    selection: { anchor: from + insert.length, head: from + insert.length },
+  });
+};
+
+/**
+ * If the cursor is at the start of a line, insert the text at the cursor.
+ * Otherwise, insert the text on a new line.
+ */
+export const insertAtLineStart = (view: EditorView, from: number, insert: string) => {
+  const line = view.state.doc.lineAt(from);
+  if (line.from === from) {
+    insertAtCursor(view, from, insert);
+  } else {
+    insert = '\n' + insert;
+    view.dispatch({
+      changes: { from: line.to, to: line.to, insert },
+      selection: { anchor: line.to + insert.length, head: line.to + insert.length },
+    });
+  }
+};

package/src/extensions/preview/index.ts

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

package/src/extensions/preview/preview.ts

@@ -2,17 +2,8 @@
 // Copyright 2023 DXOS.org
 //
 
-import '@dxos/lit-ui/dx-ref-tag.pcss';
-
 import { syntaxTree } from '@codemirror/language';
-import {
-  type EditorState,
-  type Extension,
-  type RangeSet,
-  RangeSetBuilder,
-  StateField,
-  type Transaction,
-} from '@codemirror/state';
+import { type EditorState, type Extension, RangeSetBuilder, StateField } from '@codemirror/state';
 import { Decoration, type DecorationSet, EditorView, WidgetType } from '@codemirror/view';
 import { type SyntaxNode } from '@lezer/common';
 
@@ -29,10 +20,6 @@ export type PreviewLinkTarget = {
   object?: any;
 };
 
-// TODO(wittjosiah): Remove.
-// TODO(burdon): Handle error.
-export type PreviewLookup = (link: PreviewLinkRef) => Promise<PreviewLinkTarget | null | undefined>;
-
 export type PreviewOptions = {
   addBlockContainer?: (link: PreviewLinkRef, el: HTMLElement) => void;
   removeBlockContainer?: (link: PreviewLinkRef) => void;
@@ -44,10 +31,16 @@ export type PreviewOptions = {
 export const preview = (options: PreviewOptions = {}): Extension => {
   return [
     // NOTE: Atomic block decorations must be created from a state field, now a widget, otherwise it results in the following error:
-    // "Block decorations may not be specified via plugins"
+    // "Block decorations may not be specified via plugins".
     StateField.define<DecorationSet>({
       create: (state) => buildDecorations(state, options),
-      update: (_: RangeSet<Decoration>, tr: Transaction) => buildDecorations(tr.state, options),
+      update: (decorations, tr) => {
+        if (tr.docChanged) {
+          return buildDecorations(tr.state, options);
+        }
+
+        return decorations.map(tr.changes);
+      },
       provide: (field) => [
         EditorView.decorations.from(field),
         EditorView.atomicRanges.of((view) => view.state.field(field)),
@@ -56,42 +49,19 @@ export const preview = (options: PreviewOptions = {}): Extension => {
   ];
 };
 
-/**
- * Link references.
- *
- *  [Label][dxn:echo:123]    Inline reference
- * ![Label][dxn:echo:123]    Block reference
- * ![Label][?dxn:echo:123]   Suggestion
- */
-export const getLinkRef = (state: EditorState, node: SyntaxNode): PreviewLinkRef | undefined => {
-  const mark = node.getChild('LinkMark');
-  const label = node.getChild('LinkLabel');
-  if (mark && label) {
-    const ref = state.sliceDoc(label.from + 1, label.to - 1);
-    return {
-      suggest: ref.startsWith('?'),
-      block: state.sliceDoc(mark.from, mark.from + 1) === '!',
-      label: state.sliceDoc(mark.to, label.from - 1),
-      ref: ref.startsWith('?') ? ref.slice(1) : ref,
-    };
-  }
-};
-
 /**
  * Echo references are represented as markdown reference links.
  * https://www.markdownguide.org/basic-syntax/#reference-style-links
- * [Label|block][dxn:echo:123]
- * [Label|inline][dxn:echo:123]
  */
-const buildDecorations = (state: EditorState, options: PreviewOptions) => {
+const buildDecorations = (state: EditorState, options: PreviewOptions): DecorationSet => {
   const builder = new RangeSetBuilder<Decoration>();
 
   syntaxTree(state).iterate({
     enter: (node) => {
       switch (node.name) {
         //
-        // Decoration.
-        // [Label][dxn:echo:123]
+        // Inline widget.
+        // [Label](dxn:echo:123)
         //
         case 'Link': {
           const link = getLinkRef(state, node.node);
@@ -101,29 +71,32 @@ const buildDecorations = (state: EditorState, options: PreviewOptions) => {
               node.to,
               Decoration.replace({
                 widget: new PreviewInlineWidget(options, link),
+                side: 1,
               }),
             );
           }
-          break;
+          return false;
         }
+
         //
-        // Block widget.
-        // ![Label][dxn:echo:123]
+        // Block widget (transclusion).
+        // ![Label](dxn:echo:123)
         //
         case 'Image': {
-          const link = getLinkRef(state, node.node);
-          if (options.addBlockContainer && options.removeBlockContainer && link) {
-            builder.add(
-              node.from,
-              node.to,
-              Decoration.replace({
-                block: true,
-                // atomic: true,
-                widget: new PreviewBlockWidget(options, link),
-              }),
-            );
+          if (options.addBlockContainer && options.removeBlockContainer) {
+            const link = getLinkRef(state, node.node);
+            if (link) {
+              builder.add(
+                node.from,
+                node.to,
+                Decoration.replace({
+                  block: true,
+                  widget: new PreviewBlockWidget(options, link),
+                }),
+              );
+            }
           }
-          break;
+          return false;
         }
       }
     },
@@ -132,9 +105,30 @@ const buildDecorations = (state: EditorState, options: PreviewOptions) => {
   return builder.finish();
 };
 
+/**
+ * Link references.
+ *  [Label](dxn:echo:123) Inline reference
+ * ![Label](dxn:echo:123) Block reference
+ */
+export const getLinkRef = (state: EditorState, node: SyntaxNode): PreviewLinkRef | undefined => {
+  const mark = node.getChildren('LinkMark');
+  const urlNode = node.getChild('URL');
+  if (mark && urlNode) {
+    const url = state.sliceDoc(urlNode.from, urlNode.to);
+    if (url.startsWith('dxn:')) {
+      const label = state.sliceDoc(mark[0].to, mark[1].from);
+      return {
+        block: state.sliceDoc(mark[0].from, mark[0].from + 1) === '!',
+        label,
+        ref: url,
+      };
+    }
+  }
+};
+
 /**
  * Inline widget.
- * [Label][dxn:echo:123]
+ *  [Label](dxn:echo:123)
  */
 class PreviewInlineWidget extends WidgetType {
   constructor(
@@ -152,8 +146,9 @@ class PreviewInlineWidget extends WidgetType {
     return this._link.ref === other._link.ref && this._link.label === other._link.label;
   }
 
-  override toDOM(view: EditorView): HTMLElement {
-    const root = document.createElement('dx-ref-tag');
+  override toDOM(_view: EditorView): HTMLElement {
+    const root = document.createElement('dx-anchor');
+    root.classList.add('dx-tag--anchor');
     root.textContent = this._link.label;
     root.setAttribute('refId', this._link.ref);
     return root;
@@ -161,7 +156,7 @@ class PreviewInlineWidget extends WidgetType {
 }
 
 /**
- * Block widget.
+ * Block widget (e.g., for surfaces).
  * ![Label][dxn:echo:123]
  */
 class PreviewBlockWidget extends WidgetType {
@@ -180,7 +175,7 @@ class PreviewBlockWidget extends WidgetType {
     return this._link.ref === other._link.ref;
   }
 
-  override toDOM(view: EditorView): HTMLDivElement {
+  override toDOM(_view: EditorView): HTMLDivElement {
     const root = document.createElement('div');
     root.classList.add('cm-preview-block', 'density-coarse');
     this._options.addBlockContainer?.(this._link, root);