@dxos/react-ui-editor 0.10.0 → 0.11.0

package/src/stories/Comments.stories.tsx

@@ -2,105 +2,304 @@
 // Copyright 2023 DXOS.org
 //
 
-import { Atom, RegistryContext } from '@effect-atom/atom-react';
+import { Atom, RegistryContext, useAtomValue } from '@effect-atom/atom-react';
 import { type Meta, type StoryObj } from '@storybook/react-vite';
-import React, { type FC, useContext, useMemo } from 'react';
+import React, { useContext, useMemo, useRef, useState } from 'react';
+import { expect, userEvent, waitFor } from 'storybook/test';
 
-import { keySymbols, parseShortcut } from '@dxos/keyboard';
 import { PublicKey } from '@dxos/keys';
 import { log } from '@dxos/log';
+import { random } from '@dxos/random';
+import { IconButton, useThemeContext } from '@dxos/react-ui';
+import { useAttentionAttributes } from '@dxos/react-ui-attention';
+import { withAttention } from '@dxos/react-ui-attention/testing';
+import { Listbox } from '@dxos/react-ui-list';
+import { createMenuAction } from '@dxos/react-ui-menu';
 import { withLayout, withTheme } from '@dxos/react-ui/testing';
-import { withRegistry } from '@dxos/storybook-utils';
-import { annotations, comments, createExternalCommentSync } from '@dxos/ui-editor';
+import {
+  Cursor,
+  EditorView,
+  comments,
+  createBasicExtensions,
+  createComment,
+  createMarkdownExtensions,
+  createThemeExtensions,
+  decorateMarkdown,
+  documentSlots,
+  formattingKeymap,
+  scrollCommentIntoView,
+} from '@dxos/ui-editor';
 import { type Comment } from '@dxos/ui-editor/types';
 
-import { createRenderer, str } from '../util';
-import { EditorStory, content, longText } from './components';
+import { translations } from '#translations';
 
-const meta = {
-  title: 'ui/react-ui-editor/Comments',
-  component: EditorStory,
-  decorators: [withRegistry, withTheme(), withLayout({ layout: 'fullscreen' })],
-  parameters: {
-    layout: 'fullscreen',
-  },
-} satisfies Meta<typeof EditorStory>;
+import { Editor, type EditorController } from '../components';
 
-export default meta;
+random.seed(123);
 
-type Story = StoryObj<typeof meta>;
+const DOCUMENT_ID = 'test';
 
-//
-// Comments
-//
+type StoryArgs = {
+  content?: string;
+  comments?: Comment[];
+};
 
-const CommentsStory = () => {
+const DefaultStory = ({ content, comments: commentsProp = [] }: StoryArgs) => {
+  const { themeMode } = useThemeContext();
   const registry = useContext(RegistryContext);
-  const commentsAtom = useMemo(() => Atom.make<Comment[]>([]), []);
+  const editorRef = useRef<EditorController>(null);
+  const attentionAttrs = useAttentionAttributes(DOCUMENT_ID);
+  const commentsAtom = useMemo(() => Atom.make<Comment[]>(commentsProp), []);
+  const [activeComment, setActiveComment] = useState<string>();
+  // Bumped on every document edit so the comments list re-resolves each thread's range.
+  const [, setDocVersion] = useState(0);
 
-  return (
-    <EditorStory
-      text={str('# Comments', '', content.paragraphs, content.footer)}
-      extensions={[
-        createExternalCommentSync(
-          'test',
-          (sink) => registry.subscribe(commentsAtom, () => sink()),
-          () => registry.get(commentsAtom),
-        ),
-        comments({
-          id: 'test',
-          renderTooltip: createRenderer(CommentTooltip),
-          onCreate: ({ cursor }) => {
-            const id = PublicKey.random().toHex();
-            const current = registry.get(commentsAtom);
-            registry.set(commentsAtom, [...current, { id, cursor }]);
-            return id;
-          },
-          onSelect: (state) => {
-            const debug = false;
-            if (debug) {
-              log.info('update', {
-                comments: state.comments.length,
-                active: state.selection.current?.slice(0, 8),
-                closest: state.selection.closest?.slice(0, 8),
-              });
+  const extensions = useMemo(
+    () => [
+      createBasicExtensions({ placeholder: 'Type here...', lineWrapping: true, search: true }),
+      createThemeExtensions({ themeMode, syntaxHighlighting: true, slots: documentSlots }),
+      createMarkdownExtensions(),
+      decorateMarkdown(),
+      formattingKeymap(),
+      EditorView.updateListener.of((update) => {
+        if (update.docChanged) {
+          setDocVersion((version) => version + 1);
+        }
+      }),
+      comments({
+        id: DOCUMENT_ID,
+        // Append the new thread to the atom; the extension re-reads it via `getComments`/`subscribe`.
+        onCreate: ({ cursor }) => {
+          registry.set(commentsAtom, [...registry.get(commentsAtom), { id: PublicKey.random().toHex(), cursor }]);
+        },
+        onSelect: ({ comments, selection }) => {
+          // Reflect the editor's current thread in the list selection.
+          setActiveComment(selection.current);
+          log.info('update', {
+            comments: comments.length,
+            active: selection.current?.slice(0, 8),
+            closest: selection.closest?.slice(0, 8),
+          });
+        },
+        // A deliberate click selects the thread in the editor (handled internally); reflect it in the
+        // list immediately (mirrors plugin-review revealing the companion on click).
+        onActivate: (id) => setActiveComment(id),
+        getComments: () => registry.get(commentsAtom),
+        subscribe: (sink) => {
+          sink();
+          return registry.subscribe(commentsAtom, () => sink());
+        },
+      }),
+    ],
+    [themeMode, registry, commentsAtom],
+  );
+
+  // Toolbar action that creates a comment on the current selection (mirrors the `meta-'` shortcut).
+  const customActions = useMemo(
+    () =>
+      Atom.make(() => {
+        const action = createMenuAction(
+          'comment',
+          () => {
+            const view = editorRef.current?.view;
+            if (view) {
+              createComment(view);
             }
           },
-        }),
-      ]}
-    />
+          {
+            label: 'Add comment',
+            icon: 'ph--chat-text--regular',
+            iconOnly: true,
+          },
+        );
+
+        return {
+          nodes: [action],
+          edges: [{ source: 'root', target: action.id, relation: 'child' as const }],
+        };
+      }),
+    [],
   );
-};
 
-export const Comments: Story = {
-  render: () => <CommentsStory />,
+  return (
+    <Editor.Root ref={editorRef} extensions={extensions}>
+      <Editor.Content>
+        <Editor.Toolbar classNames='dx-document' attendableId={DOCUMENT_ID} customActions={customActions} />
+        <div className='dx-container dx-document dx-base-surface' {...attentionAttrs}>
+          <Editor.View initialValue={content} selectionEnd />
+        </div>
+        <CommentsList
+          commentsAtom={commentsAtom}
+          getView={() => editorRef.current?.view}
+          activeId={activeComment}
+          onActivate={setActiveComment}
+        />
+      </Editor.Content>
+    </Editor.Root>
+  );
 };
 
-const Key: FC<{ char: string }> = ({ char }) => (
-  <span className='flex justify-center items-center w-[24px] h-[24px] rounded-sm text-xs bg-neutral-200 text-black'>
-    {char}
-  </span>
-);
+/**
+ * Renders the current comments (reactively from the atom), labelling each with the text it anchors to
+ * (resolved from its relative cursor against the live editor state). Selecting a row scrolls to and
+ * activates that thread in the editor; the delete button removes it.
+ */
+const CommentsList = ({
+  commentsAtom,
+  getView,
+  activeId,
+  onActivate,
+}: {
+  commentsAtom: Atom.Writable<Comment[]>;
+  getView: () => EditorController['view'] | undefined;
+  activeId?: string;
+  onActivate: (id: string) => void;
+}) => {
+  const registry = useContext(RegistryContext);
+  const items = useAtomValue(commentsAtom);
+
+  const view = getView();
+  // Resolve each comment's range once, then sort by document position (unresolved ranges sort last).
+  const resolved = items
+    .map((comment) => ({
+      comment,
+      range: view && comment.cursor ? Cursor.getRangeFromCursor(view.state, comment.cursor) : undefined,
+    }))
+    .sort((a, b) => (a.range?.from ?? Infinity) - (b.range?.from ?? Infinity));
+
+  const handleSelect = (id: string) => {
+    // Update the list selection directly: activating a thread in the editor doesn't re-fire `onSelect`
+    // (the effect already set it current), so the round-trip wouldn't move the list selection.
+    onActivate(id);
+    if (view) {
+      scrollCommentIntoView(view, id);
+      view.focus();
+    }
+  };
+
+  const handleDelete = (id: string) => {
+    registry.set(
+      commentsAtom,
+      registry.get(commentsAtom).filter((comment) => comment.id !== id),
+    );
+  };
 
-const CommentTooltip: FC<{ shortcut: string }> = ({ shortcut }) => {
   return (
-    <div className='flex items-center gap-2 px-2 py-2 bg-neutral-700 text-white text-xs rounded-sm'>
-      <div>Create comment</div>
-      <div className='flex gap-1'>
-        {keySymbols(parseShortcut(shortcut)).map((char) => (
-          <Key key={char} char={char} />
-        ))}
-      </div>
+    <div className='border-bs border-subdued-separator overflow-y-auto max-h-48'>
+      <Listbox.Root value={activeId} onValueChange={handleSelect}>
+        <Listbox.Content aria-label='Comments' classNames='p-1'>
+          {resolved.map(({ comment, range }) => (
+            <Listbox.Item key={comment.id} id={comment.id} classNames='flex items-center gap-2'>
+              <Listbox.ItemContent
+                classNames='grow'
+                title={(range && view?.state.doc.sliceString(range.from, range.to)) || comment.cursor || comment.id}
+                description={range ? `${range.from}–${range.to}` : comment.cursor}
+              />
+              <IconButton
+                variant='ghost'
+                iconOnly
+                icon='ph--x--regular'
+                label='Delete comment'
+                onClick={(event) => {
+                  // Keep the row from selecting when the delete button is pressed.
+                  event.stopPropagation();
+                  handleDelete(comment.id);
+                }}
+              />
+            </Listbox.Item>
+          ))}
+        </Listbox.Content>
+      </Listbox.Root>
     </div>
   );
 };
 
-//
-// Annotations
-//
+const meta = {
+  title: 'ui/react-ui-editor/Comments',
+  render: (args) => <DefaultStory {...args} />,
+  decorators: [withAttention(DOCUMENT_ID), withTheme(), withLayout({ layout: 'column' })],
+  parameters: {
+    layout: 'fullscreen',
+    translations,
+  },
+} satisfies Meta<typeof DefaultStory>;
+
+export default meta;
 
-export const Annotations: Story = {
-  render: () => (
-    <EditorStory text={str('# Annotations', '', longText)} extensions={[annotations({ match: /volup/gi })]} />
-  ),
+type Story = StoryObj<StoryArgs>;
+
+export const Default: Story = {
+  args: {
+    content: Array.from({ length: 3 })
+      .map(() => random.lorem.paragraph(3))
+      .join('\n\n'),
+    comments: [
+      { id: PublicKey.random().toHex(), cursor: '16:197' },
+      { id: PublicKey.random().toHex(), cursor: '402:420' },
+    ],
+  },
+};
+
+/**
+ * Regression: clicking INSIDE a comment must be detected. The highlight-layer rectangles are drawn over
+ * the comment text; if they intercept the click (no `pointer-events: none`), it never reaches
+ * `handleCommentClick` and the thread isn't selected. Asserts the clicked comment becomes current.
+ */
+export const ClickSelectsComment: Story = {
+  args: {
+    content: 'The quick brown fox jumps over the lazy dog.',
+    comments: [{ id: PublicKey.random().toHex(), cursor: '4:19' }], // "quick brown fox"
+  },
+  play: async ({ canvasElement }) => {
+    await waitFor(() => expect(canvasElement.querySelector('.cm-comment')).not.toBeNull(), { timeout: 15_000 });
+    const comment = canvasElement.querySelector<HTMLElement>('.cm-comment');
+    if (!comment) {
+      throw new Error('comment mark not rendered');
+    }
+
+    // Click inside the comment: must reach handleCommentClick and select the thread (data-current="1").
+    await userEvent.click(comment);
+    await waitFor(() => expect(canvasElement.querySelector('.cm-comment[data-current="1"]')).not.toBeNull(), {
+      timeout: 5_000,
+    });
+  },
+};
+
+/**
+ * Regression (app repro): a click on a comment often lands on the `.cm-line` (an ANCESTOR of the
+ * `.cm-comment` span), because the highlight-layer rectangles sit over the text with
+ * `pointer-events: none` and pass the click through to the line. An upward DOM-target walk never finds
+ * the span's `data-comment-id`, so `handleCommentClick` must fall back to a `posAtCoords` hit-test.
+ * Dispatches the click ON the line element (target = line) at the comment's coordinates and asserts the
+ * thread is still selected — this is exactly the "first click ignored" case seen in the app.
+ */
+export const ClickThroughLineSelectsComment: Story = {
+  args: {
+    content: 'The quick brown fox jumps over the lazy dog.',
+    comments: [{ id: PublicKey.random().toHex(), cursor: '4:19' }], // "quick brown fox"
+  },
+  play: async ({ canvasElement }) => {
+    await waitFor(() => expect(canvasElement.querySelector('.cm-comment')).not.toBeNull(), { timeout: 15_000 });
+    const comment = canvasElement.querySelector<HTMLElement>('.cm-comment');
+    const line = comment?.closest<HTMLElement>('.cm-line');
+    if (!comment || !line) {
+      throw new Error('comment mark or line not rendered');
+    }
+
+    // Dispatch the click on the LINE (not the span) at the comment's centre — reproduces the highlight
+    // rect passing the click through to `.cm-line`, which the old target-walk missed.
+    const rect = comment.getBoundingClientRect();
+    line.dispatchEvent(
+      new MouseEvent('click', {
+        bubbles: true,
+        cancelable: true,
+        view: window,
+        clientX: rect.left + rect.width / 2,
+        clientY: rect.top + rect.height / 2,
+      }),
+    );
+    await waitFor(() => expect(canvasElement.querySelector('.cm-comment[data-current="1"]')).not.toBeNull(), {
+      timeout: 5_000,
+    });
+  },
 };

package/src/stories/Diff.stories.tsx

@@ -0,0 +1,48 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React from 'react';
+
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+import { diffView } from '@dxos/ui-editor';
+
+import { EditorStory } from './components';
+
+// Two versions of a markdown document. The editor shows `modified` with insertions and deletions
+// marked relative to `original` — exactly what the branch compare view renders (current branch vs
+// another branch).
+const original = ['# Release notes', '', '- Fixed a crash on startup.', '- Improved sync performance.', ''].join('\n');
+
+const modified = [
+  '# Release notes',
+  '',
+  '- Fixed a crash on startup and on resume.',
+  '- Improved sync performance.',
+  '- Added dark mode.',
+  '',
+].join('\n');
+
+const meta = {
+  title: 'ui/react-ui-editor/Diff',
+  component: EditorStory,
+  decorators: [withTheme(), withLayout({ layout: 'fullscreen' })],
+  parameters: {
+    layout: 'fullscreen',
+    controls: { disable: true },
+  },
+} satisfies Meta<typeof EditorStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/**
+ * Inline (unified) diff of two markdown versions — what the branch compare view renders. The editor
+ * stays editable: typing updates the diff against `original` live (you edit the current branch while
+ * viewing the diff to another branch).
+ */
+export const Markdown: Story = {
+  render: () => <EditorStory text={modified} extensions={diffView({ original })} />,
+};

package/src/stories/EditorToolbar.stories.tsx

@@ -52,7 +52,7 @@ const DefaultStory = ({ autoFocus, initialValue, placeholder, viewMode = 'source
     <Editor.Root extensions={extensions} viewMode={viewMode}>
       <Editor.Content>
         <Editor.Toolbar classNames='dx-document' />
-        <div className='dx-container dx-document bg-base-surface'>
+        <div className='dx-container dx-document dx-base-surface'>
           <Editor.View autoFocus={autoFocus} initialValue={initialValue} selectionEnd />
         </div>
       </Editor.Content>
@@ -63,7 +63,7 @@ const DefaultStory = ({ autoFocus, initialValue, placeholder, viewMode = 'source
 const meta = {
   title: 'ui/react-ui-editor/EditorToolbar',
   render: DefaultStory,
-  decorators: [withRegistry, withTheme(), withLayout({ layout: 'fullscreen', classNames: 'bg-sidebar-surface' })],
+  decorators: [withRegistry, withTheme(), withLayout({ layout: 'column' })],
   parameters: {
     layout: 'fullscreen',
     translations,

package/src/stories/Experimental.stories.tsx

@@ -9,9 +9,10 @@ import React from 'react';
 import { log } from '@dxos/log';
 import { random } from '@dxos/random';
 import { withLayout, withTheme } from '@dxos/react-ui/testing';
-import { blast, defaultOptions, dropFile, join, snippets } from '@dxos/ui-editor';
+import { annotations, blast, defaultOptions, dropFile, join, snippets } from '@dxos/ui-editor';
 
-import { EditorStory, content } from './components';
+import { str } from '../util';
+import { EditorStory, content, longText } from './components';
 
 const meta = {
   title: 'ui/react-ui-editor/Experimental',
@@ -86,3 +87,13 @@ export const DND: Story = {
     />
   ),
 };
+
+//
+// Annotations
+//
+
+export const Annotations: Story = {
+  render: () => (
+    <EditorStory text={str('# Annotations', '', longText)} extensions={[annotations({ match: /volup/gi })]} />
+  ),
+};

package/src/stories/Folding.stories.tsx

@@ -0,0 +1,120 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+/**
+ * Stories for turn folding: a chat transcript is treated as a sequence of turns, and each turn's
+ * response is a foldable region built on CodeMirror's native folding. The fold ranges are supplied
+ * by the story via a `TurnSource` — here, one that scans `<prompt>` boundaries (a user turn is a
+ * `<prompt>` element; the response is everything up to the next prompt).
+ */
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { useMemo, useState } from 'react';
+
+import { random } from '@dxos/random';
+import { Panel, SystemIconButton, Toolbar, useThemeContext } from '@dxos/react-ui';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+import {
+  PROMPT_ELEMENT,
+  createBasicExtensions,
+  createThemeExtensions,
+  createTurnSource,
+  decorateMarkdown,
+  documentSlots,
+  extendedMarkdown,
+  foldTurns,
+  turnFolding,
+  unfoldTurns,
+  xmlBlockDecoration,
+  xmlFormatting,
+} from '@dxos/ui-editor';
+
+import { useTextEditor } from '../hooks';
+
+const source = createTurnSource(PROMPT_ELEMENT);
+
+/** Extensions shared by the stories: markdown + prompt bubbles + turn folding. */
+const chatExtensions = (themeMode: 'dark' | 'light') => [
+  createThemeExtensions({ themeMode, slots: documentSlots }),
+  createBasicExtensions({ readOnly: true, lineWrapping: true }),
+  decorateMarkdown(),
+  extendedMarkdown({ registry: {} }),
+  xmlFormatting({ skip: ['prompt'] }),
+  xmlBlockDecoration({
+    tag: 'prompt',
+    contentClass: 'bg-green-600 text-black p-1',
+    hideTags: true,
+  }),
+  turnFolding({ source }),
+];
+
+const PROMPTS = [
+  'Hello',
+  'What is ECHO and how does it relate to spaces?',
+  'Show me how queries and replication work together.',
+  'Summarize the tradeoffs of a local-first architecture.',
+  'What comes next on the roadmap?',
+];
+
+/** Builds a large, deterministic transcript: each prompt followed by several lorem paragraphs. */
+const buildSampleText = (): string => {
+  random.seed(1234);
+  return PROMPTS.map((prompt) => {
+    const body = Array.from({ length: 4 }, () => random.lorem.paragraphs()).join('\n\n');
+    return [`<prompt>${prompt}</prompt>`, '', body].join('\n');
+  }).join('\n\n');
+};
+
+const sampleText = buildSampleText();
+
+type StoryProps = { text: string };
+
+const DefaultStory = ({ text }: StoryProps) => {
+  const { themeMode } = useThemeContext();
+  const [collapsed, setCollapsed] = useState(false);
+  const extensions = useMemo(() => chatExtensions(themeMode), [themeMode]);
+  const { parentRef, view } = useTextEditor({ initialValue: text, extensions });
+
+  return (
+    <Panel.Root>
+      <Panel.Toolbar>
+        <Toolbar.Root classNames='dx-document'>
+          <SystemIconButton.Expander
+            active={!collapsed}
+            label={collapsed ? 'Expand all' : 'Collapse all'}
+            onClick={() => {
+              if (!view) {
+                return;
+              }
+              const next = !collapsed;
+              setCollapsed(next);
+              if (next) {
+                foldTurns(view, source);
+              } else {
+                unfoldTurns(view, source);
+              }
+            }}
+          />
+        </Toolbar.Root>
+      </Panel.Toolbar>
+      <Panel.Content classNames='grid overflow-hidden'>
+        <div ref={parentRef} className='dx-expander' />
+      </Panel.Content>
+    </Panel.Root>
+  );
+};
+
+const meta = {
+  title: 'ui/react-ui-editor/Folding',
+  decorators: [withTheme(), withLayout({ layout: 'fullscreen' })],
+  parameters: { layout: 'fullscreen' },
+} satisfies Meta;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => <DefaultStory text={sampleText} />,
+};

package/src/stories/Markdown.stories.tsx

@@ -48,7 +48,7 @@ export const Headings: Story = {
 
 export const Links: Story = {
   render: () => (
-    <EditorStory text={join(content.links, content.footer)} extensions={[linkTooltip(renderLinkTooltip)]} />
+    <EditorStory text={join(content.links, content.footer)} extensions={[linkTooltip({ render: renderLinkTooltip })]} />
   ),
 };
 

package/src/stories/Outliner.stories.tsx

@@ -5,18 +5,17 @@
 import { type Meta, type StoryObj } from '@storybook/react-vite';
 import React, { useCallback, useMemo, useState } from 'react';
 
+import { random } from '@dxos/random';
 import { withAttention } from '@dxos/react-ui-attention/testing';
 import { withLayout, withTheme } from '@dxos/react-ui/testing';
 import { deleteItem, hashtag, join, listItemToString, outliner, treeFacet } from '@dxos/ui-editor';
 
 import { type EditorController, type EditorMenuGroup, EditorMenuProvider } from '../components';
-import { EditorStory } from './components';
+import { EditorStory, EditorStoryProps, generateList } from './components';
 
-type StoryArgs = {
-  text?: string;
-};
+type StoryArgs = EditorStoryProps;
 
-const DefaultStory = ({ text }: StoryArgs) => {
+const DefaultStory = (props: StoryArgs) => {
   const [controller, setController] = useState<EditorController | null>(null);
 
   const extensions = useMemo(() => [outliner(), hashtag()], []);
@@ -37,6 +36,7 @@ const DefaultStory = ({ text }: StoryArgs) => {
     ],
     [],
   );
+
   const getView = useCallback(() => controller?.view ?? null, [controller]);
 
   return (
@@ -51,9 +51,8 @@ const DefaultStory = ({ text }: StoryArgs) => {
     >
       <EditorStory
         ref={setController}
-        text={text}
+        {...props}
         extensions={extensions}
-        debug='raw+tree'
         debugCustom={(view) => {
           const tree = view.state.facet(treeFacet);
           const lines: string[] = [];
@@ -82,8 +81,19 @@ export const Empty: Story = {
   args: {},
 };
 
+export const Paragraphs: Story = {
+  args: {
+    text: generateList({
+      depth: 3,
+      children: [2, 3],
+      content: () => random.lorem.paragraph(),
+    }),
+  },
+};
+
 export const Basic: Story = {
   args: {
+    debug: 'raw+tree',
     text: join(
       //
       '- [ ] A',
@@ -99,6 +109,7 @@ export const Basic: Story = {
 
 export const Nested: Story = {
   args: {
+    // debug: 'raw+tree',
     text: join(
       //
       '- [ ] A',