@dxos/react-ui-editor 0.8.4-main.a4bbb77 → 0.8.4-main.ae835ea

package/src/extensions/popover/popover.ts

@@ -0,0 +1,289 @@
+//
+// 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;
+            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;
+          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/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

@@ -7,9 +7,12 @@ import { type EditorState, type Extension, RangeSetBuilder, StateField } from '@
 import { Decoration, type DecorationSet, EditorView, WidgetType } from '@codemirror/view';
 import { type SyntaxNode } from '@lezer/common';
 
+export type PreviewBlock = {
+  link: PreviewLinkRef;
+  el: HTMLElement;
+};
+
 export type PreviewLinkRef = {
-  /** @deprecated */
-  // TODO(burdon): Remove?
   suggest?: boolean;
   block?: boolean;
   label: string;
@@ -23,8 +26,8 @@ export type PreviewLinkTarget = {
 };
 
 export type PreviewOptions = {
-  addBlockContainer?: (link: PreviewLinkRef, el: HTMLElement) => void;
-  removeBlockContainer?: (link: PreviewLinkRef) => void;
+  addBlockContainer?: (block: PreviewBlock) => void;
+  removeBlockContainer?: (block: PreviewBlock) => void;
 };
 
 /**
@@ -180,11 +183,11 @@ class PreviewBlockWidget extends WidgetType {
   override toDOM(_view: EditorView): HTMLDivElement {
     const root = document.createElement('div');
     root.classList.add('cm-preview-block', 'density-coarse');
-    this._options.addBlockContainer?.(this._link, root);
+    this._options.addBlockContainer?.({ link: this._link, el: root });
     return root;
   }
 
-  override destroy() {
-    this._options.removeBlockContainer?.(this._link);
+  override destroy(root: HTMLDivElement) {
+    this._options.removeBlockContainer?.({ link: this._link, el: root });
   }
 }

package/src/extensions/state.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Transaction } from '@codemirror/state';
+
+export const initialSync = Transaction.userEvent.of('initial.sync');

package/src/hooks/useTextEditor.ts

@@ -4,8 +4,8 @@
 
 import { EditorState, type EditorStateConfig, type Text } from '@codemirror/state';
 import { EditorView } from '@codemirror/view';
-import { type TabsterTypes, useFocusableGroup } from '@fluentui/react-tabster';
 import {
+  type ComponentPropsWithoutRef,
   type DependencyList,
   type KeyboardEventHandler,
   type RefObject,
@@ -19,7 +19,7 @@ import {
 import { log } from '@dxos/log';
 import { type MaybeProvider, getProviderValue, isTruthy } from '@dxos/util';
 
-import { type EditorSelection, createEditorStateTransaction, documentId, editorInputMode } from '../extensions';
+import { type EditorSelection, createEditorStateTransaction, documentId, modalStateField } from '../extensions';
 import { debugDispatcher } from '../util';
 
 let instanceCount = 0;
@@ -34,13 +34,9 @@ export type CursorInfo = {
 };
 
 export type UseTextEditor = {
-  // TODO(burdon): Rename.
   parentRef: RefObject<HTMLDivElement | null>;
   view: EditorView | null;
-  focusAttributes?: TabsterTypes.TabsterDOMAttribute & {
-    tabIndex: 0;
-    onKeyUp: KeyboardEventHandler<HTMLDivElement>;
-  };
+  focusAttributes?: ComponentPropsWithoutRef<'div'>;
 };
 
 export type UseTextEditorProps = Pick<EditorStateConfig, 'extensions'> & {
@@ -143,23 +139,28 @@ export const useTextEditor = (
     }
   }, [autoFocus, view]);
 
-  const focusableGroupAttrs = useFocusableGroup({
-    tabBehavior: 'limited',
-    ignoreDefaultKeydown: {
-      Escape: view?.state.facet(editorInputMode).noTabster,
-    },
-  });
-
   // Focus editor on Enter (e.g., when tabbing to this component).
-  const handleKeyUp = useCallback<KeyboardEventHandler<HTMLDivElement>>(
+  const handleKeyDown = useCallback<KeyboardEventHandler<HTMLDivElement>>(
     (event) => {
       const { key, target, currentTarget } = event;
-      if (target === currentTarget) {
-        switch (key) {
-          case 'Enter': {
+      switch (key) {
+        case 'Escape': {
+          // Check if popover is open.
+          const modal = view?.state.field(modalStateField, false);
+          if (modal) {
+            return;
+          }
+
+          // Focus the closest focusable parent.
+          const element = view?.contentDOM.closest('[tabindex="0"]') as HTMLDivElement | null;
+          element?.focus();
+          break;
+        }
+        case 'Enter': {
+          if (target === currentTarget) {
             view?.focus();
-            break;
           }
+          break;
         }
       }
     },
@@ -171,8 +172,7 @@ export const useTextEditor = (
     view,
     focusAttributes: {
       tabIndex: 0 as const,
-      ...focusableGroupAttrs,
-      onKeyUp: handleKeyUp,
+      onKeyDown: handleKeyDown,
     },
   };
 };

package/src/stories/CommandDialog.stories.tsx

@@ -10,13 +10,12 @@ import { withTheme } from '@dxos/react-ui/testing';
 import { mx } from '@dxos/react-ui-theme';
 
 import { editorWidth } from '../defaults';
-import { type Action, commandDialog } from '../extensions';
 import { str } from '../testing';
-import { createRenderer } from '../util';
 
 import { EditorStory } from './components';
 
-const CommandDialog = ({ onAction }: { onAction: (action?: Action) => void }) => {
+// TODO(burdon): Reimplement with Popover.
+const CommandDialog = ({ onAction }: { onAction: (action?: any) => void }) => {
   const [text, setText] = useState('');
 
   const handleInsert = () => {
@@ -65,17 +64,7 @@ const CommandDialog = ({ onAction }: { onAction: (action?: Action) => void }) =>
 
 const meta = {
   title: 'ui/react-ui-editor/CommandDialog',
-  render: () => (
-    <EditorStory
-      text={str('# Command', '', '', '')}
-      extensions={[
-        commandDialog({
-          renderDialog: createRenderer(CommandDialog),
-          onHint: () => "Press '?' to ask a question",
-        }),
-      ]}
-    />
-  ),
+  render: () => <EditorStory text={str('# Command', '', '')} extensions={[]} />,
   decorators: [withTheme],
   parameters: {
     layout: 'fullscreen',