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

package/src/components/Editor/EditorView.tsx

@@ -0,0 +1,102 @@
+//
+// 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-surface focus-within:border-focus-ring-subtle',
+          classNames,
+        )}
+        {...(focusable ? focusAttributes : {})}
+        ref={parentRef}
+      />
+    );
+  },
+);
+
+export { type EditorController, createEditorController, noopController };

package/src/components/Editor/controller.ts

@@ -0,0 +1,50 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type EditorView } from '@codemirror/view';
+
+export interface EditorController {
+  get view(): EditorView | null;
+  getText: () => string;
+  setText: (text: string, focus?: boolean) => void;
+  focus: () => void;
+}
+
+export const noopController: EditorController = {
+  get view() {
+    return null;
+  },
+  getText: () => '',
+  setText: () => {},
+  focus: () => {},
+};
+
+export const createEditorController = (view: EditorView | null): EditorController => {
+  return {
+    get view() {
+      return view;
+    },
+    getText: () => {
+      return view?.state.doc.toString() ?? '';
+    },
+    setText: (text: string, focus?: boolean) => {
+      view?.dispatch({
+        changes: {
+          from: 0,
+          to: view?.state.doc.length ?? 0,
+          insert: text,
+        },
+        selection: {
+          anchor: text.length,
+          head: text.length,
+        },
+      });
+
+      if (focus) {
+        view?.focus();
+      }
+    },
+    focus: () => view?.focus(),
+  };
+};

package/src/{extensions/popover/PopoverMenuProvider.tsx → components/EditorMenuProvider/EditorMenuProvider.tsx}

@@ -9,56 +9,56 @@ import React, { Fragment, type PropsWithChildren, useCallback, useEffect, useRef
 import { addEventListener } from '@dxos/async';
 import { invariant } from '@dxos/invariant';
 import {
+  DX_ANCHOR_ACTIVATE,
   type DxAnchorActivate,
   Icon,
   Popover,
+  ScrollArea,
   toLocalizedString,
   useDynamicRef,
   useThemeContext,
   useTranslation,
 } from '@dxos/react-ui';
 
-import { type PopoverMenuGroup, type PopoverMenuItem } from './menu';
+import { type EditorMenuGroup, type EditorMenuItem } from './menu';
 
-export type PopoverMenuProviderProps = PropsWithChildren<{
+export type EditorMenuProviderProps = PropsWithChildren<{
   view?: EditorView | null;
-  groups?: PopoverMenuGroup[];
+  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: PopoverMenuItem }) => 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.
- *
+ * 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 PopoverMenuProvider = ({
+export const EditorMenuProvider = ({
   children,
   view,
   groups,
   currentItem,
-  open: openParam,
+  open: openProp,
   defaultOpen,
   numItems = 8,
   onOpenChange,
   onActivate,
   onSelect,
   onCancel,
-}: PopoverMenuProviderProps) => {
+}: EditorMenuProviderProps) => {
   const { tx } = useThemeContext();
   const triggerRef = useRef<HTMLButtonElement | null>(null);
-  const [root, setRoot] = useState<HTMLDivElement | null>(null);
+
   const viewRef = useDynamicRef(view);
   const [open, setOpen] = useControllableState({
-    prop: openParam,
+    prop: openProp,
     defaultProp: defaultOpen,
     onChange: (open) => {
       invariant(viewRef.current);
@@ -66,6 +66,7 @@ export const PopoverMenuProvider = ({
     },
   });
 
+  const [root, setRoot] = useState<HTMLDivElement | null>(null);
   useEffect(() => {
     if (!root) {
       return;
@@ -74,12 +75,10 @@ export const PopoverMenuProvider = ({
     // Listen for trigger.
     return addEventListener(
       root,
-      'dx-anchor-activate' as any,
+      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 });
@@ -108,34 +107,37 @@ export const PopoverMenuProvider = ({
   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',
-          ])}
+          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 = viewRef.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>
 
-      <div ref={setRoot} role='none' className='contents'>
+      {/* Content */}
+      <div className='contents' ref={setRoot}>
         {children}
       </div>
     </Popover.Root>
@@ -147,7 +149,7 @@ export const PopoverMenuProvider = ({
 //
 
 type MenuProps = {
-  groups: PopoverMenuGroup[];
+  groups: EditorMenuGroup[];
 } & Pick<MenuGroupProps, 'currentItem' | 'onSelect'>;
 
 const Menu = ({ groups, currentItem, onSelect }: MenuProps) => {
@@ -157,15 +159,19 @@ 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>
   );
 };
 
+//
+// Menu Group
+//
+
 type MenuGroupProps = {
-  group: PopoverMenuGroup;
+  group: EditorMenuGroup;
   currentItem?: string;
 } & Pick<MenuItemProps, 'onSelect'>;
 
@@ -176,7 +182,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>
       )}
@@ -188,10 +194,14 @@ const MenuGroup = ({ group, currentItem, onSelect }: MenuGroupProps) => {
   );
 };
 
+//
+// Menu Item
+//
+
 type MenuItemProps = {
-  item: PopoverMenuItem;
+  item: EditorMenuItem;
   current: boolean;
-  onSelect?: (item: PopoverMenuItem) => void;
+  onSelect?: (item: EditorMenuItem) => void;
 };
 
 const MenuItem = ({ item, current, onSelect }: MenuItemProps) => {
@@ -208,12 +218,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

@@ -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/{extensions/popover → components/EditorMenuProvider}/menu-presets.ts

@@ -2,12 +2,12 @@
 // Copyright 2025 DXOS.org
 //
 
-import { popoverRangeEffect } from '../../extensions';
+import { insertAtLineStart } from '@dxos/ui-editor';
 
-import { type PopoverMenuGroup } from './menu';
-import { insertAtLineStart } from './util';
+import { type EditorMenuGroup } from './menu';
+import { popoverRangeEffect } from './popover';
 
-export const formattingCommands: PopoverMenuGroup = {
+export const formattingCommands: EditorMenuGroup = {
   id: 'markdown',
   label: 'Markdown',
   items: [
@@ -15,78 +15,78 @@ export const formattingCommands: PopoverMenuGroup = {
       id: 'heading-1',
       label: 'Heading 1',
       icon: 'ph--text-h-one--regular',
-      onSelect: (view, head) => insertAtLineStart(view, head, '# '),
+      onSelect: ({ view, head }) => insertAtLineStart(view, head, '# '),
     },
     {
       id: 'heading-2',
       label: 'Heading 2',
       icon: 'ph--text-h-two--regular',
-      onSelect: (view, head) => insertAtLineStart(view, head, '## '),
+      onSelect: ({ view, head }) => insertAtLineStart(view, head, '## '),
     },
     {
       id: 'heading-3',
       label: 'Heading 3',
       icon: 'ph--text-h-three--regular',
-      onSelect: (view, head) => insertAtLineStart(view, head, '### '),
+      onSelect: ({ view, head }) => insertAtLineStart(view, head, '### '),
     },
     {
       id: 'heading-4',
       label: 'Heading 4',
       icon: 'ph--text-h-four--regular',
-      onSelect: (view, head) => insertAtLineStart(view, head, '#### '),
+      onSelect: ({ view, head }) => insertAtLineStart(view, head, '#### '),
     },
     {
       id: 'heading-5',
       label: 'Heading 5',
       icon: 'ph--text-h-five--regular',
-      onSelect: (view, head) => insertAtLineStart(view, head, '##### '),
+      onSelect: ({ view, head }) => insertAtLineStart(view, head, '##### '),
     },
     {
       id: 'heading-6',
       label: 'Heading 6',
       icon: 'ph--text-h-six--regular',
-      onSelect: (view, head) => insertAtLineStart(view, head, '###### '),
+      onSelect: ({ view, head }) => insertAtLineStart(view, head, '###### '),
     },
     {
       id: 'bullet-list',
       label: 'Bullet List',
       icon: 'ph--list-bullets--regular',
-      onSelect: (view, head) => insertAtLineStart(view, head, '- '),
+      onSelect: ({ view, head }) => insertAtLineStart(view, head, '- '),
     },
     {
       id: 'numbered-list',
       label: 'Numbered List',
       icon: 'ph--list-numbers--regular',
-      onSelect: (view, head) => insertAtLineStart(view, head, '1. '),
+      onSelect: ({ view, head }) => insertAtLineStart(view, head, '1. '),
     },
     {
       id: 'task-list',
       label: 'Task List',
       icon: 'ph--list-checks--regular',
-      onSelect: (view, head) => insertAtLineStart(view, head, '- [ ] '),
+      onSelect: ({ view, head }) => insertAtLineStart(view, head, '- [ ] '),
     },
     {
       id: 'quote',
       label: 'Quote',
       icon: 'ph--quotes--regular',
-      onSelect: (view, head) => insertAtLineStart(view, head, '> '),
+      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```'),
+      onSelect: ({ view, head }) => insertAtLineStart(view, head, '```\n\n```'),
     },
     {
       id: 'table',
       label: 'Table',
       icon: 'ph--table--regular',
-      onSelect: (view, head) => insertAtLineStart(view, head, '| | | |\n|---|---|---|\n| | | |'),
+      onSelect: ({ view, head }) => insertAtLineStart(view, head, '| | | |\n|---|---|---|\n| | | |'),
     },
   ],
 };
 
-export const linkSlashCommands: PopoverMenuGroup = {
+export const linkSlashCommands: EditorMenuGroup = {
   id: 'link',
   label: 'Link',
   items: [
@@ -94,7 +94,7 @@ export const linkSlashCommands: PopoverMenuGroup = {
       id: 'inline-link',
       label: 'Inline link',
       icon: 'ph--link--regular',
-      onSelect: (view, head) => {
+      onSelect: ({ view, head }) => {
         view.dispatch({
           changes: { from: head, insert: '@' },
           selection: { anchor: head + 1, head: head + 1 },
@@ -109,7 +109,8 @@ export const linkSlashCommands: PopoverMenuGroup = {
       id: 'block-embed',
       label: 'Block embed',
       icon: 'ph--lego--regular',
-      onSelect: (view, head) => {
+      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/{extensions/popover → components/EditorMenuProvider}/menu.ts

@@ -5,34 +5,33 @@
 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 PopoverMenuGroup = {
+export type EditorMenuGroup = {
   id: string;
   label?: Label;
-  items: PopoverMenuItem[];
+  items: EditorMenuItem[];
 };
 
-export type PopoverMenuItem = {
+export type EditorMenuItem = {
   id: string;
   label: Label;
   icon?: string;
-  onSelect?: (view: EditorView, head: number) => MaybePromise<void>;
+  onSelect?: (event: { view: EditorView; head: number }) => MaybePromise<void>;
 };
 
-export const getMenuItem = (groups: PopoverMenuGroup[], id?: string): PopoverMenuItem | undefined => {
+export const getMenuItem = (groups: EditorMenuGroup[], id?: string): EditorMenuItem | undefined => {
   return groups.flatMap((group) => group.items).find((item) => item.id === id);
 };
 
-export const getNextMenuItem = (groups: PopoverMenuGroup[], id?: string): PopoverMenuItem => {
+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: PopoverMenuGroup[], id?: string): PopoverMenuItem => {
+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];
@@ -41,25 +40,29 @@ export const getPreviousMenuItem = (groups: PopoverMenuGroup[], id?: string): Po
 export const createMenuGroup = ({
   id = 'menu',
   label,
+  filter,
   items,
 }: {
   id?: string;
   label?: Label;
+  filter?: string;
   items: string[];
-}): PopoverMenuGroup => ({
+}): EditorMenuGroup => ({
   id,
   label,
-  items: items.map((item, i) => ({
-    id: `${id}-${i}`,
-    label: item,
-    onSelect: (view, head) => insertAtCursor(view, head, item),
-  })),
+  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: PopoverMenuGroup[],
-  filter: (item: PopoverMenuItem) => boolean,
-): PopoverMenuGroup[] => {
+  groups: EditorMenuGroup[],
+  filter: (item: EditorMenuItem) => boolean,
+): EditorMenuGroup[] => {
   return groups.map((group) => ({
     ...group,
     items: group.items.filter(filter),

package/src/{extensions/popover → components/EditorMenuProvider}/popover.ts

@@ -13,13 +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 Range } from '../../types';
-import { type PlaceholderOptions, placeholder } from '../autocomplete';
-
-import { modalStateField } from './modal';
-
 const DELIMITERS = [' ', ':'];
 
 export type PopoverOptions = {
@@ -56,6 +53,7 @@ export const popover = (options: PopoverOptions = {}): Extension => {
       placeholder({
         // TODO(burdon): Translations.
         content: `Press '${Array.isArray(options.trigger) ? options.trigger[0] : options.trigger}' for commands`,
+        focusOnly: true,
         ...options.placeholder,
       }),
   ].filter(isTruthy);
@@ -107,8 +105,8 @@ const popoverKeymap = (options: PopoverOptions) => {
         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
+          // 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 (