@dxos/react-ui-editor 0.8.4-main.fffef41 → 0.9.0

package/src/components/Editor/EditorView.tsx

@@ -0,0 +1,99 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Transaction } from '@codemirror/state';
+import { EditorView as NaturalEditorView } from '@codemirror/view';
+import React, { forwardRef, useEffect, useImperativeHandle, useRef } from 'react';
+
+import { type ThemedClassName } from '@dxos/react-ui';
+import { initialSync } from '@dxos/ui-editor';
+import { mx } from '@dxos/ui-theme';
+
+import { type UseTextEditorProps, useTextEditor } from '../../hooks';
+import { type EditorController, createEditorController, noopController } from './controller';
+
+export type EditorViewProps = ThemedClassName<
+  {
+    focusable?: boolean;
+    value?: string;
+    onChange?: (value: string) => void;
+  } & UseTextEditorProps
+>;
+
+/**
+ * Minimal text editor.
+ * NOTE: This shouold not be used with the automerge extension.
+ */
+// TODO(burdon): Move controller to Root component, then make composable.
+export const EditorView = forwardRef<EditorController, EditorViewProps>(
+  ({ classNames, id, extensions, selectionEnd, focusable = true, value, onChange, ...props }, forwardedRef) => {
+    // Hold the latest onChange in a ref so callers may pass an inline callback
+    // without forcing the underlying editor to be destroyed and recreated on
+    // every render — which would blur the focused input on each keystroke.
+    const onChangeRef = useRef(onChange);
+    onChangeRef.current = onChange;
+
+    const { parentRef, focusAttributes, view } = useTextEditor(
+      () => ({
+        id,
+        initialValue: value,
+        selectionEnd,
+        extensions: [
+          extensions ?? [],
+          NaturalEditorView.updateListener.of(({ view, docChanged, transactions }) => {
+            const isInitialSync = transactions.some((tr) => tr.annotation(Transaction.userEvent) === initialSync.value);
+            if (!isInitialSync && docChanged) {
+              onChangeRef.current?.(view.state.doc.toString());
+            }
+          }),
+        ],
+        ...props,
+      }),
+      [id, extensions, selectionEnd],
+    );
+
+    // External controller.
+    useImperativeHandle(forwardedRef, () => {
+      return createEditorController(view);
+    }, [id, view]);
+
+    // Sync the editor doc to the controlled `value` prop, but only when they
+    // disagree. After internal typing the prop will already match the editor's
+    // doc, and dispatching anyway would race fast keystrokes — a stale rAF
+    // closure can replace doc content with an older value, dropping characters.
+    useEffect(() => {
+      if (!view) {
+        return;
+      }
+      const next = value ?? '';
+      if (view.state.doc.toString() === next) {
+        return;
+      }
+      requestAnimationFrame(() => {
+        if (view.state.doc.toString() === next) {
+          return;
+        }
+        view.dispatch({
+          annotations: initialSync,
+          changes: [{ from: 0, to: view.state.doc.length, insert: next }],
+          selection: selectionEnd ? { anchor: next.length } : undefined,
+        });
+
+        if (selectionEnd) {
+          view.focus();
+        }
+      });
+    }, [view, value, selectionEnd]);
+
+    return (
+      <div
+        className={mx('w-full outline-hidden focus:border-accent-bg focus-within:border-focus-ring-subtle', classNames)}
+        {...(focusable ? focusAttributes : {})}
+        ref={parentRef}
+      />
+    );
+  },
+);
+
+export { type EditorController, createEditorController, noopController };

package/src/components/{EditorContent → Editor}/controller.ts

@@ -11,17 +11,26 @@ export interface EditorController {
   focus: () => void;
 }
 
-export const noopController: EditorController = {
+// Hide `view` from own-enumerable traversal. Controllers are passed through React props/context, and the
+// live `EditorView` reaches the global `window` via `view.observer.win` (CodeMirror's DOMObserver). React
+// 19.2's dev render-logger walks changed props' object graphs and would otherwise descend into `window`,
+// enumerate `window[0]` (a cross-origin iframe) and throw SecurityError. Direct access is unaffected.
+const withHiddenView = (controller: EditorController): EditorController => {
+  Object.defineProperty(controller, 'view', { enumerable: false });
+  return controller;
+};
+
+export const noopController: EditorController = withHiddenView({
   get view() {
     return null;
   },
   getText: () => '',
   setText: () => {},
   focus: () => {},
-};
+});
 
 export const createEditorController = (view: EditorView | null): EditorController => {
-  return {
+  return withHiddenView({
     get view() {
       return view;
     },
@@ -46,5 +55,5 @@ export const createEditorController = (view: EditorView | null): EditorControlle
       }
     },
     focus: () => view?.focus(),
-  };
+  });
 };

package/src/components/EditorMenuProvider/EditorMenuProvider.tsx

@@ -13,6 +13,7 @@ import {
   type DxAnchorActivate,
   Icon,
   Popover,
+  ScrollArea,
   toLocalizedString,
   useDynamicRef,
   useThemeContext,
@@ -22,7 +23,9 @@ import {
 import { type EditorMenuGroup, type EditorMenuItem } from './menu';
 
 export type EditorMenuProviderProps = PropsWithChildren<{
-  view?: EditorView | null;
+  // Provided as a getter (not a value prop) so the live `EditorView` is never carried in a React prop that
+  // the dev render-logger would walk into a cross-origin frame. See `controller.ts` for the full rationale.
+  getView?: () => EditorView | null;
   groups?: EditorMenuGroup[];
   currentItem?: string;
   open?: boolean;
@@ -35,18 +38,16 @@ export type EditorMenuProviderProps = PropsWithChildren<{
 }>;
 
 /**
- * Implements the Popover and listens for the `dx-anchor-activate` event from the
- * `popover` extension's decoration.
- *
+ * 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,
+  getView,
   groups,
   currentItem,
-  open: openParam,
+  open: openProp,
   defaultOpen,
   numItems = 8,
   onOpenChange,
@@ -57,13 +58,15 @@ export const EditorMenuProvider = ({
   const { tx } = useThemeContext();
   const triggerRef = useRef<HTMLButtonElement | null>(null);
 
-  const viewRef = useDynamicRef(view);
+  // Hold the latest `getView` so callbacks/effects always read the current view without re-subscribing.
+  const getViewRef = useDynamicRef(getView);
   const [open, setOpen] = useControllableState({
-    prop: openParam,
+    prop: openProp,
     defaultProp: defaultOpen,
     onChange: (open) => {
-      invariant(viewRef.current);
-      onOpenChange?.({ view: viewRef.current, open });
+      const view = getViewRef.current?.();
+      invariant(view);
+      onOpenChange?.({ view, open });
     },
   });
 
@@ -78,13 +81,14 @@ export const EditorMenuProvider = ({
       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) {
+        const { trigger, dxn } = event;
+        if (!dxn) {
           triggerRef.current = trigger as HTMLButtonElement;
           if (onActivate) {
-            onActivate({ view: viewRef.current!, trigger: trigger.getAttribute('data-trigger') ?? undefined });
+            const view = getViewRef.current?.();
+            if (view) {
+              onActivate({ view, trigger: trigger.getAttribute('data-trigger') ?? undefined });
+            }
           } else {
             requestAnimationFrame(() => setOpen(true));
           }
@@ -99,10 +103,11 @@ export const EditorMenuProvider = ({
 
   const handleSelect = useCallback<NonNullable<MenuProps['onSelect']>>(
     (item) => {
-      invariant(viewRef.current);
-      onSelect?.({ view: viewRef.current, item });
+      const view = getViewRef.current?.();
+      invariant(view);
+      onSelect?.({ view, item });
     },
-    [viewRef, onSelect],
+    [getViewRef, onSelect],
   );
 
   const menuGroups = groups?.filter((group) => group.items.length > 0) ?? [];
@@ -115,32 +120,32 @@ export const EditorMenuProvider = ({
       <Popover.Portal>
         <Popover.Content
           align='start'
-          classNames={tx('menu.content', 'menu--exotic-unfocusable', { elevation: 'positioned' }, [
-            'overflow-y-auto',
-            !menuGroups.length && 'hidden',
-          ])}
+          classNames={['flex flex-col', !menuGroups.length && 'hidden']}
           style={{
             maxBlockSize: 36 * numItems + 10,
           }}
-          /**
-           * NOTE: We keep the focus in the editor, but Radix routes escape key.
-           */
+          // 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! });
+            const currentView = getViewRef.current?.();
+            if (currentView) {
+              onCancel?.({ view: currentView });
+            }
           }}
           onOpenAutoFocus={(event) => event.preventDefault()}
         >
-          <Popover.Viewport classNames={tx('menu.viewport', 'menu__viewport--exotic-unfocusable', {})}>
-            <Menu groups={menuGroups} currentItem={currentItem} onSelect={handleSelect} />
+          <Popover.Viewport asChild classNames='dx-container'>
+            <ScrollArea.Root thin>
+              <ScrollArea.Viewport>
+                <Menu groups={menuGroups} currentItem={currentItem} onSelect={handleSelect} />
+              </ScrollArea.Viewport>
+            </ScrollArea.Root>
           </Popover.Viewport>
           <Popover.Arrow />
         </Popover.Content>
       </Popover.Portal>
 
       {/* Content */}
-      <div ref={setRoot} role='none' className='contents'>
+      <div className='contents' ref={setRoot}>
         {children}
       </div>
     </Popover.Root>
@@ -162,7 +167,7 @@ const Menu = ({ groups, currentItem, onSelect }: MenuProps) => {
       {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', {})} />}
+          {index < groups.length - 1 && <div className={tx('menu.separator', {})} />}
         </Fragment>
       ))}
     </ul>
@@ -185,7 +190,7 @@ const MenuGroup = ({ group, currentItem, onSelect }: MenuGroupProps) => {
   return (
     <>
       {group.label && (
-        <div className={tx('menu.groupLabel', 'menu__group__label', {})}>
+        <div className={tx('menu.groupLabel', {})}>
           <span>{toLocalizedString(group.label, t)}</span>
         </div>
       )}
@@ -221,12 +226,8 @@ const MenuItem = ({ item, current, onSelect }: MenuItemProps) => {
   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} />}
+    <li ref={listRef} className={tx('menu.item', {}, [current && 'bg-hover-surface'])} onClick={handleSelect}>
+      {item.icon && <Icon icon={item.icon} />}
       <span className='grow truncate'>{toLocalizedString(item.label, t)}</span>
     </li>
   );

package/src/components/EditorMenuProvider/index.ts

@@ -5,7 +5,6 @@
 export * from './menu';
 export * from './menu-presets';
 export * from './popover';
-export * from './util';
 
 export * from './EditorMenuProvider';
 export * from './useEditorMenu';

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

@@ -2,9 +2,10 @@
 // Copyright 2025 DXOS.org
 //
 
+import { insertAtLineStart } from '@dxos/ui-editor';
+
 import { type EditorMenuGroup } from './menu';
 import { popoverRangeEffect } from './popover';
-import { insertAtLineStart } from './util';
 
 export const formattingCommands: EditorMenuGroup = {
   id: 'markdown',
@@ -109,6 +110,7 @@ export const linkSlashCommands: EditorMenuGroup = {
       label: 'Block embed',
       icon: 'ph--lego--regular',
       onSelect: ({ view, head }) => {
+        // Seed the same query shape as typing "@@" manually.
         view.dispatch({
           changes: { from: head, insert: '@@' },
           selection: { anchor: head + 2, head: head + 2 },

package/src/components/EditorMenuProvider/menu.ts

@@ -5,10 +5,9 @@
 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';
 
-import { insertAtCursor } from './util';
-
 export type EditorMenuGroup = {
   id: string;
   label?: Label;

package/src/components/EditorMenuProvider/popover.ts

@@ -13,11 +13,10 @@ import {
   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';
 
-import { type PlaceholderOptions, modalStateField, placeholder } from '../../extensions';
-import { type Range } from '../../types';
-
 const DELIMITERS = [' ', ':'];
 
 export type PopoverOptions = {
@@ -26,15 +25,19 @@ export type PopoverOptions = {
   placeholder?: Partial<PlaceholderOptions>;
   delimiters?: string[];
 
-  // TODO(burdon): Auto.
-  // activateOnTyping?: boolean;
+  /**
+   * 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.
-  onEnter?: (event: { view: EditorView }) => void;
+  /** 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;
 };
@@ -48,12 +51,14 @@ export const popover = (options: PopoverOptions = {}): Extension => {
     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);
@@ -93,6 +98,33 @@ const popoverTriggerListener = (options: PopoverOptions) =>
     }
   });
 
+/**
+ * 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.
  */
@@ -190,9 +222,10 @@ const popoverKeymap = (options: PopoverOptions) => {
         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;
+            // 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;

package/src/components/EditorMenuProvider/useEditorMenu.ts

@@ -7,10 +7,9 @@ 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 { modalStateEffect } from '../../extensions';
-
 import { type EditorMenuProviderProps } from './EditorMenuProvider';
 import { type EditorMenuGroup, type EditorMenuItem } from './menu';
 import { filterMenuGroups, getMenuItem, getNextMenuItem, getPreviousMenuItem } from './menu';
@@ -26,7 +25,7 @@ export type GetMenuContext = {
 export type UseEditorMenuProps = {
   filter?: boolean;
   getMenu?: (context: GetMenuContext) => MaybePromise<EditorMenuGroup[]>;
-} & Pick<PopoverOptions, 'trigger' | 'triggerKey' | 'placeholder'>;
+} & Pick<PopoverOptions, 'trigger' | 'triggerKey' | 'placeholder' | 'activateOnTyping'>;
 
 export type UseEditorMenu = {
   groupsRef: RefObject<EditorMenuGroup[]>;
@@ -38,7 +37,7 @@ export type UseEditorMenu = {
  * const { groupsRef, extension, ...menuProps } = useEditorMenu();
  * const { parentRef, viewRef } = useTextEditor({ extensions: [extension] });
  * return (
- *   <EditorMenuProvider view={viewRef.current} groups={groupsRef.current} {...menuProps}>
+ *   <EditorMenuProvider getView={() => viewRef.current} groups={groupsRef.current} {...menuProps}>
  *     <div ref={parentRef} />
  *   </EditorMenuProvider>
  * );
@@ -48,6 +47,7 @@ export const useEditorMenu = ({
   trigger,
   triggerKey,
   placeholder,
+  activateOnTyping,
   filter = true,
   getMenu,
 }: UseEditorMenuProps): UseEditorMenu => {
@@ -63,7 +63,8 @@ export const useEditorMenu = ({
   const getMenuOptions = useCallback<NonNullable<UseEditorMenuProps['getMenu']>>(
     async ({ text, trigger, ...props }) => {
       const groups = (await getMenu?.({ text, trigger, ...props })) ?? [];
-      return filter
+      // 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,
           )
@@ -74,7 +75,6 @@ export const useEditorMenu = ({
 
   const handleOpenChange = useCallback<NonNullable<UseEditorMenu['onOpenChange']>>(
     async ({ view, open }) => {
-      console.log(view, open);
       invariant(view);
       setOpen(open);
       if (!open) {
@@ -110,7 +110,13 @@ export const useEditorMenu = ({
   );
 
   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 }) => {
@@ -129,11 +135,14 @@ export const useEditorMenu = ({
       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) => {
@@ -155,12 +164,17 @@ export const useEditorMenu = ({
         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]);
+  }, [handleOpenChange, getMenuOptions, serializedTrigger, placeholder, activateOnTyping]);
 
   return {
     groupsRef,

package/src/components/EditorPreviewProvider/EditorPreviewProvider.tsx

@@ -7,8 +7,7 @@ import React, { type PropsWithChildren, type RefObject, useCallback, useEffect,
 
 import { addEventListener } from '@dxos/async';
 import { DX_ANCHOR_ACTIVATE, type DxAnchorActivate, Popover } from '@dxos/react-ui';
-
-import { type PreviewLinkRef, type PreviewLinkTarget } from '../../extensions';
+import { type PreviewLinkRef, type PreviewLinkTarget } from '@dxos/ui-editor';
 
 type EditorPreviewPopoverValue = Partial<{
   link: PreviewLinkRef;
@@ -33,16 +32,16 @@ export const EditorPreviewProvider = ({ children, onLookup }: EditorPreviewProvi
 
   const handleActivate = useCallback(
     (event: DxAnchorActivate) => {
-      const { refId, label, trigger: dxTrigger } = event;
+      const { dxn, label, trigger } = event;
       setValue((value) => ({
         ...value,
-        link: { label, ref: refId },
+        link: { label, dxn },
         pending: true,
       }));
 
-      triggerRef.current = dxTrigger;
+      triggerRef.current = trigger;
       queueMicrotask(() => setOpen(true));
-      void onLookup?.({ label, ref: refId }).then((target) =>
+      void onLookup?.({ label, dxn }).then((target) =>
         setValue((value) => ({
           ...value,
           target: target ?? undefined,
@@ -69,9 +68,7 @@ export const EditorPreviewProvider = ({ children, onLookup }: EditorPreviewProvi
     <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>} />
-
-        {/* Content */}
-        <div ref={setRoot} role='none' className='contents'>
+        <div className='contents' ref={setRoot}>
           {children}
         </div>
       </Popover.Root>