@dxos/react-ui-editor 0.10.0 → 0.11.0

package/src/stories/Popover.stories.tsx

@@ -18,6 +18,7 @@ import {
   type EditorMenuGroup,
   type EditorMenuItem,
   EditorMenuProvider,
+  type EditorMenuProviderProps,
   type UseEditorMenuProps,
   createMenuGroup,
   filterMenuGroups,
@@ -43,15 +44,21 @@ const placeholder = (trigger: string[]) => {
   return Domino.of('div').append(pressEl, ...triggerEls, forCommandsEl).root;
 };
 
-type StoryArgs = Omit<UseEditorMenuProps, 'viewRef'> & { text: string };
+type StoryArgs = Omit<UseEditorMenuProps, 'viewRef'> &
+  Pick<EditorMenuProviderProps, 'searchPlaceholder'> & { text: string };
 
-const DefaultStory = ({ text, ...props }: StoryArgs) => {
+const DefaultStory = ({ text, searchPlaceholder, ...props }: StoryArgs) => {
   const [controller, setController] = useState<EditorController | null>(null);
   const { groupsRef, extension, ...menuProps } = useEditorMenu(props);
   const getView = useCallback(() => controller?.view ?? null, [controller]);
 
   return (
-    <EditorMenuProvider getView={getView} groups={groupsRef.current} {...menuProps}>
+    <EditorMenuProvider
+      getView={getView}
+      groups={groupsRef.current}
+      searchPlaceholder={searchPlaceholder}
+      {...menuProps}
+    >
       <EditorStory ref={setController} text={text} extensions={extension} />
     </EditorMenuProvider>
   );
@@ -76,6 +83,7 @@ const LinkStory = (args: StoryArgs) => {
       const result = await space?.db.query(Query.type(TestSchema.Person)).run();
       const items = result
         .filter((object) => object.name.toLowerCase().includes(name))
+        .sort((a, b) => a.name.localeCompare(b.name))
         .map(
           (object): EditorMenuItem => ({
             id: object.id,
@@ -92,7 +100,18 @@ const LinkStory = (args: StoryArgs) => {
           }),
         );
 
-      return [{ id: 'test', items }];
+      // Mirrors the plugin's picker, where this opens the app's create-object dialog.
+      const createItem: EditorMenuItem = {
+        id: 'create-object',
+        label: 'Add object',
+        icon: 'ph--plus--regular',
+        onSelect: ({ view, head }) => insertAtCursor(view, head, `[${name || 'New object'}](dxn:echo:@:new) `),
+      };
+
+      return [
+        { id: 'create', items: [createItem] },
+        { id: 'test', items },
+      ];
     },
     [space],
   );
@@ -143,7 +162,7 @@ export const Link: Story = {
       },
       onCreateSpace: async ({ space }) => {
         const createObjects = createObjectFactory(space.db, generator);
-        await createObjects([{ type: TestSchema.Person, count: 10 }]);
+        await createObjects([{ type: TestSchema.Person, count: 50 }]);
         await space.db.flush({ indexes: true });
       },
     }),
@@ -151,6 +170,9 @@ export const Link: Story = {
   args: {
     text: join('# Links', '', ''),
     trigger: ['/', '@'],
+    // The "@" picker is a combobox: the query is typed into the popover, not the document.
+    searchTriggers: ['@'],
+    searchPlaceholder: 'Search or create…',
     placeholder: {
       content: () => placeholder(['/', '@']),
     },

package/src/stories/Suggest.stories.tsx

@@ -0,0 +1,199 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { useMemo } from 'react';
+import { expect, userEvent, waitFor } from 'storybook/test';
+
+import { createObject } from '@dxos/echo-client';
+import { Doc } from '@dxos/echo-doc';
+import { useThemeContext } from '@dxos/react-ui';
+import { withAttention } from '@dxos/react-ui-attention/testing';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+import { Text } from '@dxos/schema';
+import {
+  automerge,
+  createBasicExtensions,
+  createMarkdownExtensions,
+  createThemeExtensions,
+  suggestChanges,
+  suggestions,
+} from '@dxos/ui-editor';
+
+import { Editor, type EditorViewProps } from '../components';
+
+// The parent (main) content and a branch proposal that rewrites three words — three independent,
+// reviewable changes (like a branch's edits against a style guide).
+const ORIGINAL = 'The quick brown fox jumps over the lazy dog.';
+const PROPOSAL = 'The fast brown fox leaps over the sleepy dog.';
+
+/**
+ * Simulate hovering a change to surface its tooltip-layer controls. CodeMirror's `hoverTooltip` reads
+ * pointer coordinates from a bubbling `mousemove`, which `userEvent.hover` does not reliably provide, so
+ * dispatch one at the element's centre.
+ */
+const hoverChange = (element: HTMLElement): void => {
+  const rect = element.getBoundingClientRect();
+  element.dispatchEvent(
+    new MouseEvent('mousemove', {
+      bubbles: true,
+      clientX: rect.left + rect.width / 2,
+      clientY: rect.top + rect.height / 2,
+    }),
+  );
+};
+
+/** The document text (struck-through deletions included), excluding the proposal preview widgets. */
+const documentText = (canvasElement: HTMLElement): string => {
+  const content = canvasElement.querySelector('.cm-content');
+  if (!content) {
+    return '';
+  }
+  const clone = content.cloneNode(true) as HTMLElement;
+  clone.querySelectorAll('.cm-suggest-actions').forEach((node) => node.remove());
+  return clone.textContent ?? '';
+};
+
+const Render = (args: EditorViewProps) => {
+  const { themeMode } = useThemeContext();
+  const extensions = useMemo(
+    () => [
+      createBasicExtensions(),
+      createThemeExtensions({ themeMode }),
+      createMarkdownExtensions(),
+      // The editor is bound to the parent (ORIGINAL); the branch is the proposal.
+      automerge(Doc.createAccessor(createObject(Text.make({ content: ORIGINAL })), ['content'])),
+      suggestChanges({ proposal: PROPOSAL }),
+    ],
+    [themeMode],
+  );
+
+  return (
+    <Editor.Root>
+      <Editor.View {...args} extensions={extensions} />
+    </Editor.Root>
+  );
+};
+
+// Two reviewers proposing over the same base: Alice and Bob both rewrite "quick" (an overlap), and
+// each has one further, non-overlapping change — a multi-author suggestion overlay.
+const ALICE = 'The fast brown fox jumps over the sleepy dog.';
+const BOB = 'The swift brown fox leaps over the lazy dog.';
+
+const MultiAuthorRender = (args: EditorViewProps) => {
+  const { themeMode } = useThemeContext();
+  const extensions = useMemo(
+    () => [
+      createBasicExtensions(),
+      createThemeExtensions({ themeMode }),
+      createMarkdownExtensions(),
+      automerge(Doc.createAccessor(createObject(Text.make({ content: ORIGINAL })), ['content'])),
+      // Author colours come from the shared hue palette (the same `--color-<hue>-text` tokens used
+      // for a user's avatar/tag), so a suggestion reads with its author's consistent colour.
+      suggestions({
+        sources: [
+          { author: 'did:alice', colour: 'var(--color-lime-text)', content: ALICE },
+          { author: 'did:bob', colour: 'var(--color-violet-text)', content: BOB },
+        ],
+      }),
+    ],
+    [themeMode],
+  );
+
+  return (
+    <Editor.Root>
+      <Editor.View {...args} extensions={extensions} />
+    </Editor.Root>
+  );
+};
+
+const meta = {
+  title: 'ui/react-ui-editor/Suggest',
+  render: Render,
+  decorators: [withTheme(), withLayout({ layout: 'column' }), withAttention()],
+  parameters: {
+    layout: 'fullscreen',
+  },
+} satisfies Meta<typeof Render>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/** The branch's changes rendered over the parent as accept/reject suggestions. */
+export const Default: Story = {};
+
+/**
+ * Accept applies a change to the document (merging it into the parent); Reject hides a change without
+ * altering the document. Deterministic — no AI, so it runs in CI.
+ */
+export const AcceptReject: Story = {
+  play: async ({ canvasElement }) => {
+    // Each change carries a strikethrough of the replaced word; its accept/reject controls live in the
+    // (non-clipped) tooltip layer and surface on hover.
+    const deletes = () => Array.from(canvasElement.querySelectorAll<HTMLElement>('.cm-suggest-delete'));
+    const inserts = () => canvasElement.querySelectorAll<HTMLElement>('.cm-suggest-insert');
+    const acceptButton = () => canvasElement.querySelector<HTMLElement>('.cm-tooltip .cm-suggest-accept');
+    const rejectButton = () => canvasElement.querySelector<HTMLElement>('.cm-tooltip .cm-suggest-reject');
+
+    // Three suggestions (quick→fast, jumps→leaps, lazy→sleepy) over the original document.
+    await waitFor(() => expect(documentText(canvasElement)).toContain('quick'), { timeout: 15_000 });
+    await waitFor(() => expect(inserts()).toHaveLength(3));
+
+    // Hover the first change: its controls mount in the tooltip layer (a `.cm-tooltip`, not clipped by
+    // the scroller). Accept applies that change to the document.
+    hoverChange(deletes()[0]);
+    await waitFor(() => expect(acceptButton()).not.toBeNull());
+    await userEvent.click(acceptButton()!);
+    await waitFor(() => expect(documentText(canvasElement)).toContain('fast'));
+    await waitFor(() => expect(documentText(canvasElement)).not.toContain('quick'));
+    await waitFor(() => expect(inserts()).toHaveLength(2));
+
+    // Reject the next change: the suggestion disappears, but the document keeps the original.
+    const before = documentText(canvasElement);
+    hoverChange(deletes()[0]);
+    await waitFor(() => expect(rejectButton()).not.toBeNull());
+    await userEvent.click(rejectButton()!);
+    await waitFor(() => expect(inserts()).toHaveLength(1));
+    await waitFor(() => expect(documentText(canvasElement)).toBe(before));
+  },
+};
+
+/**
+ * Two authors reviewing the same base, overlapping on one word. Each change is independently
+ * attributable and accepting one re-diffs the rest (the overlapping author's change persists).
+ * Deterministic — no AI, so it runs in CI.
+ */
+export const MultipleAuthors: Story = {
+  render: MultiAuthorRender,
+  play: async ({ canvasElement }) => {
+    const deletes = () => Array.from(canvasElement.querySelectorAll<HTMLElement>('.cm-suggest-delete'));
+    const acceptButton = () => canvasElement.querySelector<HTMLElement>('.cm-tooltip .cm-suggest-accept');
+    const insertText = () =>
+      Array.from(canvasElement.querySelectorAll<HTMLElement>('.cm-suggest-insert')).map((node) => node.textContent);
+
+    const insertColours = () =>
+      Array.from(canvasElement.querySelectorAll<HTMLElement>('.cm-suggest-insert')).map((node) => node.style.color);
+
+    // Four suggestions total: Alice{fast, sleepy} + Bob{swift, leaps}; "fast"/"swift" overlap on "quick".
+    await waitFor(() => expect(documentText(canvasElement)).toContain('quick'), { timeout: 15_000 });
+    await waitFor(() => expect(insertText()).toEqual(expect.arrayContaining(['fast', 'swift', 'sleepy', 'leaps'])));
+
+    // Each author's inline markers carry that author's palette colour (Alice lime, Bob violet).
+    await waitFor(() => expect(insertColours().some((colour) => colour.includes('lime'))).toBe(true));
+    await waitFor(() => expect(insertColours().some((colour) => colour.includes('violet'))).toBe(true));
+
+    // Hover the overlapping "quick" change; offset-then-author order surfaces Alice's "quick"→"fast"
+    // first. Accepting it makes the base take "fast"; Bob's "quick"→"swift" re-diffs and remains.
+    const quick = deletes().find((node) => node.textContent?.includes('quick'));
+    void expect(quick).toBeDefined();
+    hoverChange(quick!);
+    await waitFor(() => expect(acceptButton()).not.toBeNull());
+    await userEvent.click(acceptButton()!);
+    await waitFor(() => expect(documentText(canvasElement)).toContain('fast'));
+    await waitFor(() => expect(documentText(canvasElement)).not.toContain('quick'));
+    await waitFor(() => expect(insertText()).toEqual(expect.arrayContaining(['swift'])));
+    await waitFor(() => expect(insertText()).toHaveLength(3));
+  },
+};

package/src/stories/TrackChanges.stories.tsx

@@ -0,0 +1,226 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { useMemo } from 'react';
+import { expect, userEvent, waitFor } from 'storybook/test';
+
+import { useThemeContext } from '@dxos/react-ui';
+import { withAttention } from '@dxos/react-ui-attention/testing';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+import {
+  createBasicExtensions,
+  createMarkdownExtensions,
+  createThemeExtensions,
+  documentSlots,
+  suggestions,
+  trackChanges,
+} from '@dxos/ui-editor';
+
+import { Editor, type EditorViewProps } from '../components';
+
+// The accepted base (main). The editor is bound to a *branch* whose live edits are tracked against it.
+const MAIN = 'The quick brown fox jumps over the lazy dog.';
+
+// A second author's proposal against main ("lazy" -> "sleepy"). Milestone B decouples the diff base
+// from the editor document, so this overlay is diffed vs MAIN and rebased into the (diverged) branch's
+// coordinates — it no longer strikes the tester's own new text (the collision the old overlay had).
+const BOB = 'The quick brown fox jumps over the sleepy dog.';
+
+const SELF_COLOUR = 'var(--color-cyan-text)';
+const BOB_COLOUR = 'var(--color-violet-text)';
+
+/** The document text with phantom deletions folded in, excluding the foreign overlay's controls. */
+const documentText = (canvasElement: HTMLElement): string => {
+  const content = canvasElement.querySelector('.cm-content');
+  if (!content) {
+    return '';
+  }
+  const clone = content.cloneNode(true) as HTMLElement;
+  clone.querySelectorAll('.cm-suggest-actions').forEach((node) => node.remove());
+  return clone.textContent ?? '';
+};
+
+type RenderProps = EditorViewProps & { branch: string };
+
+const Render = ({ branch, ...args }: RenderProps) => {
+  const { themeMode } = useThemeContext();
+  const extensions = useMemo(
+    () => [
+      createBasicExtensions(),
+      createThemeExtensions({ themeMode, slots: documentSlots }),
+      createMarkdownExtensions(),
+      // The branch's own edits, diffed against MAIN and shown as tracked changes (self only).
+      trackChanges({ main: MAIN, colour: SELF_COLOUR }),
+    ],
+    [themeMode],
+  );
+
+  return (
+    <Editor.Root>
+      <Editor.View {...args} value={branch} extensions={extensions} />
+    </Editor.Root>
+  );
+};
+
+/**
+ * The tester's own live edits (self, via {@link trackChanges}) composed with a foreign author's
+ * proposal (via {@link suggestions} with an explicit `base`). Because the foreign overlay is diffed
+ * against MAIN — not the editor document — the tester's own typing is never mistaken for text the
+ * foreign author would remove.
+ */
+const ForeignAuthorRender = ({ branch, ...args }: RenderProps) => {
+  const { themeMode } = useThemeContext();
+  const extensions = useMemo(
+    () => [
+      createBasicExtensions(),
+      createThemeExtensions({ themeMode, slots: documentSlots }),
+      createMarkdownExtensions(),
+      trackChanges({ main: MAIN, colour: SELF_COLOUR }),
+      // The foreign author is diffed against MAIN and rebased into the branch's coordinates.
+      suggestions({ base: MAIN, sources: [{ author: 'did:bob', colour: BOB_COLOUR, content: BOB }] }),
+    ],
+    [themeMode],
+  );
+
+  return (
+    <Editor.Root>
+      <Editor.View {...args} value={branch} extensions={extensions} />
+    </Editor.Root>
+  );
+};
+
+const meta = {
+  title: 'ui/react-ui-editor/TrackChanges',
+  render: Render,
+  decorators: [withTheme(), withLayout({ layout: 'column', classNames: 'py-8' }), withAttention()],
+  parameters: {
+    layout: 'fullscreen',
+  },
+} satisfies Meta<typeof Render>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/**
+ * Interactive "Suggesting mode" (bind-to-branch): the editor is bound to a branch that starts equal to
+ * MAIN, so it opens clean. Type to feel the tracked-change ergonomics:
+ *
+ * - Type — the added characters appear as an underlined, cyan insertion (character-level, so editing
+ *   inside a word marks only the changed characters, not the whole word).
+ * - Select text and delete it — the removed characters stay visible as a struck-through phantom
+ *   (`~~old~~`), because they are absent from the branch but present in main.
+ * - Replace text — you get both at once, `~~old~~new`, at character granularity.
+ * - Move the caret across a phantom with the arrow keys — it is stepped over as one unit.
+ * - Press Backspace with the caret just after a phantom — the real branch text behind it is protected
+ *   (the keystroke is swallowed rather than eating the hidden character).
+ */
+export const Default: Story = {
+  args: { branch: MAIN },
+};
+
+/**
+ * A branch that has already diverged from main, so tracked changes render on mount without typing:
+ * `swiftly ` inserted after "jumps" and `lazy ` deleted — both clean whole-word edits so the
+ * character-level diff yields contiguous hunks. Deterministic — used for the render smoke test.
+ */
+export const Divergent: Story = {
+  args: { branch: 'The quick brown fox jumps swiftly over the dog.' },
+  play: async ({ canvasElement }) => {
+    await waitFor(() => expect(canvasElement.querySelector('.cm-content')).not.toBeNull(), { timeout: 15_000 });
+
+    // Insertion mark: the branch's added text.
+    const inserts = () => Array.from(canvasElement.querySelectorAll<HTMLElement>('.cm-track-insert'));
+    await waitFor(() =>
+      expect(
+        inserts()
+          .map((node) => node.textContent)
+          .join(''),
+      ).toContain('swiftly'),
+    );
+
+    // Phantom deletion: base text absent from the branch, still visible struck through.
+    const deletes = () => Array.from(canvasElement.querySelectorAll<HTMLElement>('.cm-track-delete'));
+    await waitFor(() => expect(deletes().length).toBeGreaterThan(0));
+    const deletedText = () =>
+      deletes()
+        .map((node) => node.textContent)
+        .join('');
+    await waitFor(() => expect(deletedText()).toContain('lazy'));
+
+    // The phantom text is not part of the document (it is a widget, not doc content).
+    await waitFor(() => expect(documentText(canvasElement)).toContain('swiftly'));
+  },
+};
+
+/**
+ * A foreign author's proposal (Bob: "lazy"→"sleepy") layered over the tester's own live edits. The
+ * overlay is diffed against MAIN (not the branch), so after the tester types, their new text is tracked
+ * as a self-insertion and is NOT struck by Bob's overlay, while Bob's change still renders. This is the
+ * multi-author case the old (diff-vs-document) overlay could not support. Deterministic — runs in CI.
+ */
+export const WithForeignAuthor: Story = {
+  render: ForeignAuthorRender,
+  args: { branch: MAIN },
+  play: async ({ canvasElement }) => {
+    const content = await waitFor(
+      () => {
+        const node = canvasElement.querySelector<HTMLElement>('.cm-content');
+        void expect(node).not.toBeNull();
+        return node!;
+      },
+      { timeout: 15_000 },
+    );
+
+    // Bob's proposal renders on mount: "lazy" struck through, "sleepy" previewed.
+    const suggestDeletes = () => Array.from(canvasElement.querySelectorAll<HTMLElement>('.cm-suggest-delete'));
+    const suggestInserts = () => Array.from(canvasElement.querySelectorAll<HTMLElement>('.cm-suggest-insert'));
+    await waitFor(() =>
+      expect(
+        suggestDeletes()
+          .map((node) => node.textContent)
+          .join(' '),
+      ).toContain('lazy'),
+    );
+    await waitFor(() =>
+      expect(
+        suggestInserts()
+          .map((node) => node.textContent)
+          .join(' '),
+      ).toContain('sleepy'),
+    );
+
+    // The tester types at the start of the branch (a region Bob did not touch).
+    content.focus();
+    await userEvent.keyboard('really ');
+
+    // The typed text is tracked as the tester's own insertion (self overlay), not attributed to Bob.
+    const trackInserts = () => Array.from(canvasElement.querySelectorAll<HTMLElement>('.cm-track-insert'));
+    await waitFor(() =>
+      expect(
+        trackInserts()
+          .map((node) => node.textContent)
+          .join(''),
+      ).toContain('really'),
+    );
+
+    // Critically, Bob's overlay does NOT strike the tester's new text — only "lazy" stays struck.
+    await waitFor(() => {
+      const struck = suggestDeletes()
+        .map((node) => node.textContent)
+        .join(' ');
+      void expect(struck).toContain('lazy');
+      void expect(struck).not.toContain('really');
+    });
+    // And Bob's proposal still renders after the divergence.
+    await waitFor(() =>
+      expect(
+        suggestInserts()
+          .map((node) => node.textContent)
+          .join(' '),
+      ).toContain('sleepy'),
+    );
+  },
+};