@dxos/react-ui-editor 0.10.0 → 0.11.0

package/src/components/EditorMenuProvider/menu.ts

@@ -25,13 +25,15 @@ export const getMenuItem = (groups: EditorMenuGroup[], id?: string): EditorMenuI
   return groups.flatMap((group) => group.items).find((item) => item.id === id);
 };
 
-export const getNextMenuItem = (groups: EditorMenuGroup[], id?: string): EditorMenuItem => {
+/** Undefined when the menu is empty; at either end the current item is returned unchanged. */
+export const getNextMenuItem = (groups: EditorMenuGroup[], id?: string): EditorMenuItem | undefined => {
   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: EditorMenuGroup[], id?: string): EditorMenuItem => {
+/** Undefined when the menu is empty; at either end the current item is returned unchanged. */
+export const getPreviousMenuItem = (groups: EditorMenuGroup[], id?: string): EditorMenuItem | undefined => {
   const items = groups.flatMap((group) => group.items);
   const index = items.findIndex((item) => item.id === id);
   return index > 0 ? items[index - 1] : items[index];

package/src/components/EditorMenuProvider/useEditorMenu.ts

@@ -4,6 +4,7 @@
 
 import { type Extension } from '@codemirror/state';
 import { type EditorState } from '@codemirror/state';
+import { type EditorView } from '@codemirror/view';
 import { type RefObject, useCallback, useMemo, useRef, useState } from 'react';
 
 import { invariant } from '@dxos/invariant';
@@ -24,13 +25,30 @@ export type GetMenuContext = {
 
 export type UseEditorMenuProps = {
   filter?: boolean;
+  /**
+   * Triggers whose menu is rendered as a combobox: the popover owns a search input and the query is
+   * typed there rather than into the document.
+   */
+  searchTriggers?: string[];
   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'>;
+} & Pick<
+  EditorMenuProviderProps,
+  | 'currentItem'
+  | 'open'
+  | 'search'
+  | 'query'
+  | 'onOpenChange'
+  | 'onActivate'
+  | 'onSelect'
+  | 'onCancel'
+  | 'onQueryChange'
+  | 'onNavigate'
+>;
 
 /**
  * ```tsx
@@ -49,14 +67,24 @@ export const useEditorMenu = ({
   placeholder,
   activateOnTyping,
   filter = true,
+  searchTriggers,
   getMenu,
 }: UseEditorMenuProps): UseEditorMenu => {
   const groupsRef = useRef<EditorMenuGroup[]>([]);
   const currentRef = useRef<EditorMenuItem | null>(null);
   const [currentItem, setCurrentItem] = useState<string>();
   const [open, setOpen] = useState(false);
+  const [search, setSearch] = useState(false);
+  const [query, setQuery] = useState('');
   const [_, refresh] = useState({});
 
+  // The document range only supplies the trigger-relative prefix (e.g. the second "@" of a block
+  // embed); in search mode the rest of the query comes from the popover's input.
+  const contextRef = useRef<{ view: EditorView; pos: number; text: string; trigger?: string } | null>(null);
+
+  // Monotonic token identifying the latest menu query; bumped per request and on close.
+  const requestRef = useRef(0);
+
   /**
    * Get filtered options.
    */
@@ -73,12 +101,49 @@ export const useEditorMenu = ({
     [getMenu, filter],
   );
 
+  /**
+   * Recompute the menu and preselect the first item.
+   */
+  const updateGroups = useCallback(
+    async ({ view, pos, text, trigger }: { view: EditorView; pos: number; text: string; trigger?: string }) => {
+      const request = ++requestRef.current;
+      const groups = (await getMenuOptions({ state: view.state, pos, text, trigger })) ?? [];
+      // Queries resolve out of order, so a slower earlier one must not overwrite a newer result
+      // (or repopulate the menu after it closed).
+      if (request !== requestRef.current) {
+        return;
+      }
+
+      groupsRef.current = groups;
+      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({});
+    },
+    [getMenuOptions],
+  );
+
   const handleOpenChange = useCallback<NonNullable<UseEditorMenu['onOpenChange']>>(
     async ({ view, open }) => {
       invariant(view);
       setOpen(open);
       if (!open) {
         setCurrentItem(undefined);
+        setSearch(false);
+        setQuery('');
+        contextRef.current = null;
+        // Invalidate in-flight queries so a late response cannot repopulate the closed menu.
+        requestRef.current++;
+        groupsRef.current = [];
+        currentRef.current = null;
         view.dispatch({
           effects: [popoverRangeEffect.of(null)],
         });
@@ -129,7 +194,35 @@ export const useEditorMenu = ({
     }
   }, []);
 
+  const handleQueryChange = useCallback<NonNullable<UseEditorMenu['onQueryChange']>>(
+    (query) => {
+      setQuery(query);
+      const context = contextRef.current;
+      if (context) {
+        void updateGroups({ ...context, text: context.text + query });
+      }
+    },
+    [updateGroups],
+  );
+
+  const handleNavigate = useCallback<NonNullable<UseEditorMenu['onNavigate']>>((direction) => {
+    setCurrentItem((currentItem) => {
+      const next =
+        direction === 'up'
+          ? getPreviousMenuItem(groupsRef.current, currentItem)
+          : getNextMenuItem(groupsRef.current, currentItem);
+      // A query that matches nothing leaves an empty menu; arrow keys then have nowhere to go.
+      if (!next) {
+        return currentItem;
+      }
+
+      currentRef.current = next;
+      return next.id;
+    });
+  }, []);
+
   const serializedTrigger = Array.isArray(trigger) ? trigger.join(',') : trigger;
+  const serializedSearchTriggers = searchTriggers?.join(',');
   const extension = useMemo<Extension>(() => {
     return popover({
       trigger,
@@ -144,46 +237,38 @@ export const useEditorMenu = ({
         }
         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;
-        });
-      },
+      onArrowUp: () => handleNavigate('up'),
+      onArrowDown: () => handleNavigate('down'),
       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({});
+        contextRef.current = { view, pos, text, trigger };
+        // The input is remounted per activation, so the query always starts empty.
+        setSearch(!!trigger && !!searchTriggers?.includes(trigger));
+        setQuery('');
+        await updateGroups({ view, pos, text, trigger });
       },
     });
-  }, [handleOpenChange, getMenuOptions, serializedTrigger, placeholder, activateOnTyping]);
+  }, [
+    handleOpenChange,
+    handleNavigate,
+    updateGroups,
+    serializedTrigger,
+    serializedSearchTriggers,
+    placeholder,
+    activateOnTyping,
+  ]);
 
   return {
     groupsRef,
     extension,
     currentItem,
     open,
+    search,
+    query,
     onOpenChange: handleOpenChange,
     onActivate: handleActivate,
     onSelect: handleSelect,
     onCancel: handleCancel,
+    onQueryChange: handleQueryChange,
+    onNavigate: handleNavigate,
   };
 };

package/src/components/EditorPreviewProvider/EditorPreviewContext.ts

@@ -0,0 +1,21 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { createContext } from '@radix-ui/react-context';
+
+import { type PreviewLinkRef, type PreviewLinkTarget } from '@dxos/ui-types';
+
+// Kept out of `EditorPreviewProvider.tsx`: react-refresh only fast-refreshes a module whose exports are all
+// components, so a context and its hook exported beside them force a full page reload on every edit.
+
+export type EditorPreviewPopoverValue = Partial<{
+  link: PreviewLinkRef;
+  target: PreviewLinkTarget;
+  pending: boolean;
+}>;
+
+export const [EditorPreviewContextProvider, useEditorPreview] = createContext<EditorPreviewPopoverValue>(
+  'PreviewPopover',
+  {},
+);

package/src/components/EditorPreviewProvider/EditorPreviewProvider.tsx

@@ -2,20 +2,13 @@
 // 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-types';
 
-type EditorPreviewPopoverValue = Partial<{
-  link: PreviewLinkRef;
-  target: PreviewLinkTarget;
-  pending: boolean;
-}>;
-
-const [EditorPreviewContextProvider, useEditorPreview] = createContext<EditorPreviewPopoverValue>('PreviewPopover', {});
+import { EditorPreviewContextProvider, type EditorPreviewPopoverValue } from './EditorPreviewContext';
 
 export type EditorPreviewProviderProps = PropsWithChildren<{
   onLookup?: (link: PreviewLinkRef) => Promise<PreviewLinkTarget | null | undefined>;
@@ -76,5 +69,3 @@ export const EditorPreviewProvider = ({ children, onLookup }: EditorPreviewProvi
     </EditorPreviewContextProvider>
   );
 };
-
-export { useEditorPreview };

package/src/components/EditorPreviewProvider/index.ts

@@ -2,4 +2,6 @@
 // Copyright 2025 DXOS.org
 //
 
+export { useEditorPreview } from './EditorPreviewContext';
+
 export * from './EditorPreviewProvider';

package/src/components/EditorToolbar/EditorToolbar.tsx

@@ -3,7 +3,7 @@
 //
 
 import { type EditorView } from '@codemirror/view';
-import { Atom } from '@effect-atom/atom-react';
+import { Atom } from '@effect-atom/atom';
 import React, { memo, useMemo } from 'react';
 
 import { type Node } from '@dxos/app-graph';
@@ -18,7 +18,7 @@ import { addImageUpload } from './image';
 import { addLists } from './lists';
 import { addSearch } from './search';
 import { type EditorToolbarState } from './types';
-import { addViewMode } from './view-mode';
+import { type ViewModeItem, addViewMode } from './view-mode';
 
 // TODO(burdon): Enable toolbar variants (e.g., markdown, code).
 
@@ -35,6 +35,8 @@ export type EditorToolbarFeatureFlags = Partial<{
   // TODO(wittjosiah): Factor out (depends on plugin-level capabilities.)
   onImageUpload: () => void;
   onViewModeChange: (mode: EditorViewMode) => void;
+  /** Override the view-mode dropdown entries (default: the three built-in modes). See {@link ViewModeItem}. */
+  viewModes: ViewModeItem[];
 }>;
 
 export type EditorToolbarActionGraphProps = {
@@ -86,6 +88,7 @@ const useMarkdownMenuActions = ({ state, getView, customActions, ...features }:
       features?.showSearch,
       features?.onImageUpload,
       features?.onViewModeChange,
+      features?.viewModes,
     ],
   );
 
@@ -110,7 +113,7 @@ const createMarkdownActions = ({
       .separator('gap')
       .subgraph(customActions && get(customActions))
       .subgraph(features?.showSearch !== false && addSearch(getView))
-      .subgraph(features?.onViewModeChange && addViewMode(stateSnapshot, features.onViewModeChange))
+      .subgraph(features?.onViewModeChange && addViewMode(stateSnapshot, features.onViewModeChange, features.viewModes))
       .build();
   });
 };

package/src/components/EditorToolbar/index.ts

@@ -5,3 +5,4 @@
 export * from './types';
 
 export * from './EditorToolbar';
+export * from './view-mode';

package/src/components/EditorToolbar/lists.ts

@@ -5,7 +5,7 @@
 import { type EditorView } from '@codemirror/view';
 
 import { type ActionGroupBuilderFn, type ToolbarMenuActionGroupProperties } from '@dxos/react-ui-menu';
-import { List, addList, removeList } from '@dxos/ui-editor';
+import { List, toggleList } from '@dxos/ui-editor';
 
 import { translationKey } from '#translations';
 
@@ -45,11 +45,7 @@ export const addLists =
 
               const listType =
                 listStyle === 'ordered' ? List.Ordered : listStyle === 'bullet' ? List.Bullet : List.Task;
-              if (checked) {
-                removeList(listType)(view);
-              } else {
-                addList(listType)(view);
-              }
+              toggleList(listType)(view);
             },
           );
         }

package/src/components/EditorToolbar/view-mode.ts

@@ -4,20 +4,47 @@
 
 import { type ActionGroupBuilderFn, type ToolbarMenuActionGroupProperties } from '@dxos/react-ui-menu';
 import { type EditorViewMode } from '@dxos/ui-editor/types';
+import { type Label } from '@dxos/ui-types';
 
 import { translationKey } from '#translations';
 
 import { type EditorToolbarState } from './types';
 
-const viewModes = {
-  preview: 'ph--eye--regular',
-  source: 'ph--pencil-simple--regular',
-  readonly: 'ph--pencil-slash--regular',
+/**
+ * One entry in the editor's view-mode dropdown. A built-in entry references an {@link EditorViewMode}
+ * by `id` and relies on the defaults (label `view-mode.<id>.label`, checked when it is the active view
+ * mode, select via `onViewModeChange`). A contributed entry (e.g. a review "Suggesting" mode) supplies
+ * its own `label`, `checked`, and `onSelect` so it can drive state other than the editor view mode.
+ */
+export type ViewModeItem = {
+  id: string;
+  icon: string;
+  label?: Label;
+  checked?: boolean;
+  onSelect?: () => void;
 };
 
-/** Add view mode actions to the builder. */
+/**
+ * The built-in view modes: preview (rendered), source (raw edit), readonly (non-editable source). Typed
+ * so each `id` is an {@link EditorViewMode}, letting callers pass `item.id` to `onViewModeChange` without a cast.
+ */
+export const defaultViewModeItems: Array<ViewModeItem & { id: EditorViewMode }> = [
+  { id: 'preview', icon: 'ph--eye--regular' },
+  { id: 'source', icon: 'ph--pencil-simple--regular' },
+  { id: 'readonly', icon: 'ph--pencil-slash--regular' },
+];
+
+/**
+ * Add view mode actions to the builder. `items` defaults to the three built-in editor view modes;
+ * callers pass an extended list to surface contributed modes (see {@link ViewModeItem}) in the same
+ * single-select dropdown. The trigger tracks the checked item (via the group's `applyActive`).
+ */
 export const addViewMode =
-  (state: EditorToolbarState, onViewModeChange: (mode: EditorViewMode) => void): ActionGroupBuilderFn =>
+  (
+    state: EditorToolbarState,
+    onViewModeChange: (mode: EditorViewMode) => void,
+    items: ViewModeItem[] = defaultViewModeItems,
+  ): ActionGroupBuilderFn =>
   (builder) => {
     const value = state.viewMode ?? 'source';
     builder.group(
@@ -32,16 +59,18 @@ export const addViewMode =
         value,
       } as ToolbarMenuActionGroupProperties,
       (group) => {
-        for (const [viewMode, icon] of Object.entries(viewModes)) {
-          const checked = viewMode === value;
+        for (const item of items) {
+          // A contributed entry may drive non-view-mode state, so honour its explicit `checked`;
+          // a built-in entry is checked when it matches the active editor view mode.
+          const checked = item.checked ?? item.id === value;
           group.action(
-            `view-mode--${viewMode}`,
+            `view-mode--${item.id}`,
             {
-              label: [`view-mode.${viewMode}.label`, { ns: translationKey }],
+              label: item.label ?? [`view-mode.${item.id}.label`, { ns: translationKey }],
               checked,
-              icon,
+              icon: item.icon,
             },
-            () => onViewModeChange(viewMode as EditorViewMode),
+            () => (item.onSelect ? item.onSelect() : onViewModeChange(item.id as EditorViewMode)),
           );
         }
       },

package/src/components/index.ts

@@ -6,3 +6,4 @@ export * from './Editor';
 
 export * from './EditorMenuProvider';
 export * from './EditorPreviewProvider';
+export * from './EditorToolbar/view-mode';

package/src/index.ts

@@ -3,5 +3,4 @@
 //
 
 export * from './components';
-export * from './extensions';
 export * from './hooks';

package/src/{extensions → stories}/Assistant.stories.tsx

@@ -13,13 +13,18 @@ import { AiService } from '@dxos/ai';
 import { AiServiceTestingPreset } from '@dxos/ai/testing';
 import { useThemeContext } from '@dxos/react-ui';
 import { Loading, withLayout, withTheme } from '@dxos/react-ui/testing';
-import { compactSlots, createBasicExtensions, createThemeExtensions } from '@dxos/ui-editor';
+import {
+  type AssistantOptions,
+  assistant,
+  compactSlots,
+  createBasicExtensions,
+  createThemeExtensions,
+} from '@dxos/ui-editor';
 import { trim } from '@dxos/util';
 
 import { translations } from '#translations';
 
 import { Editor, type EditorViewProps } from '../components';
-import { type AssistantOptions, assistant } from './assistant-extension';
 
 // TODO(burdon): Factor out.
 const useTestGenerate = () => {