@dxos/ui-editor 0.10.0 → 0.11.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/ui-editor",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "description": "Text editor components.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -16,14 +16,17 @@
     ".": {
       "source": "./src/index.ts",
       "types": "./dist/types/src/index.d.ts",
-      "browser": "./dist/lib/browser/index.mjs",
-      "node": "./dist/lib/node-esm/index.mjs"
+      "import": "./dist/lib/index.mjs"
+    },
+    "./headless": {
+      "source": "./src/headless.ts",
+      "types": "./dist/types/src/headless.d.ts",
+      "import": "./dist/lib/headless.mjs"
     },
     "./types": {
       "source": "./src/types/index.ts",
       "types": "./dist/types/src/types/index.d.ts",
-      "browser": "./dist/lib/browser/types/index.mjs",
-      "node": "./dist/lib/node-esm/types/index.mjs"
+      "import": "./dist/lib/types.mjs"
     }
   },
   "types": "dist/types/src/index.d.ts",
@@ -33,21 +36,22 @@
   ],
   "dependencies": {
     "@automerge/automerge": "3.3.0-fragments.2",
-    "@codemirror/autocomplete": "^6.20.2",
-    "@codemirror/commands": "^6.10.3",
+    "@codemirror/autocomplete": "^6.20.3",
+    "@codemirror/commands": "^6.10.4",
     "@codemirror/lang-html": "^6.4.11",
     "@codemirror/lang-javascript": "^6.2.5",
     "@codemirror/lang-json": "^6.0.2",
-    "@codemirror/lang-markdown": "6.5.0",
+    "@codemirror/lang-markdown": "6.5.1",
     "@codemirror/lang-xml": "^6.1.0",
     "@codemirror/lang-yaml": "^6.1.3",
-    "@codemirror/language": "^6.12.3",
+    "@codemirror/language": "^6.12.4",
     "@codemirror/language-data": "^6.5.2",
     "@codemirror/lint": "6.9.7",
-    "@codemirror/search": "^6.7.0",
-    "@codemirror/state": "^6.6.0",
+    "@codemirror/merge": "^6.12.2",
+    "@codemirror/search": "^6.7.1",
+    "@codemirror/state": "^6.7.1",
     "@codemirror/theme-one-dark": "^6.1.3",
-    "@codemirror/view": "^6.43.0",
+    "@codemirror/view": "^6.43.6",
     "@lezer/common": "^1.5.2",
     "@lezer/generator": "^1.8.0",
     "@lezer/highlight": "^1.2.3",
@@ -57,35 +61,37 @@
     "@uiw/codemirror-theme-vscode": "^4.25.2",
     "ajv": "^8.18.0",
     "codemirror": "^6.0.2",
+    "codemirror-lang-mermaid": "^0.5.0",
+    "diff": "^8.0.3",
     "lib0": "^0.2.65",
     "lodash.defaultsdeep": "^4.6.1",
     "lodash.merge": "^4.6.2",
     "lodash.sortby": "^4.7.0",
     "style-mod": "^4.1.0",
-    "@dxos/async": "0.10.0",
-    "@dxos/app-graph": "0.10.0",
-    "@dxos/client": "0.10.0",
-    "@dxos/context": "0.10.0",
-    "@dxos/debug": "0.10.0",
-    "@dxos/display-name": "0.10.0",
-    "@dxos/echo-doc": "0.10.0",
-    "@dxos/echo-client": "0.10.0",
-    "@dxos/keys": "0.10.0",
-    "@dxos/log": "0.10.0",
-    "@dxos/lit-ui": "0.10.0",
-    "@dxos/invariant": "0.10.0",
-    "@dxos/echo": "0.10.0",
-    "@dxos/nlp": "0.10.0",
-    "@dxos/ui": "0.10.0",
-    "@dxos/protocols": "0.10.0",
-    "@dxos/ui-types": "0.10.0",
-    "@dxos/util": "0.10.0",
-    "@dxos/ui-theme": "0.10.0"
+    "@dxos/app-graph": "0.11.1",
+    "@dxos/async": "0.11.1",
+    "@dxos/client": "0.11.1",
+    "@dxos/context": "0.11.1",
+    "@dxos/debug": "0.11.1",
+    "@dxos/display-name": "0.11.1",
+    "@dxos/echo": "0.11.1",
+    "@dxos/echo-client": "0.11.1",
+    "@dxos/echo-doc": "0.11.1",
+    "@dxos/invariant": "0.11.1",
+    "@dxos/keys": "0.11.1",
+    "@dxos/lit-ui": "0.11.1",
+    "@dxos/log": "0.11.1",
+    "@dxos/nlp": "0.11.1",
+    "@dxos/protocols": "0.11.1",
+    "@dxos/ui": "0.11.1",
+    "@dxos/ui-theme": "0.11.1",
+    "@dxos/ui-types": "0.11.1",
+    "@dxos/util": "0.11.1"
   },
   "devDependencies": {
     "@automerge/automerge": "3.3.0-fragments.2",
-    "@automerge/automerge-repo": "2.6.0-subduction.37",
-    "@automerge/automerge-repo-network-broadcastchannel": "2.6.0-subduction.37",
+    "@automerge/automerge-repo": "2.6.0-subduction.40",
+    "@automerge/automerge-repo-network-broadcastchannel": "2.6.0-subduction.40",
     "@effect/platform": "0.96.2",
     "@types/chai": "^4.2.15",
     "@types/chai-dom": "^1.11.0",
@@ -98,21 +104,21 @@
     "happy-dom": "^20.0.0",
     "jsdom": "^29.1.1",
     "mocha": "^10.6.0",
-    "vite": "^8.0.16",
+    "vite": "^8.1.4",
     "vite-plugin-top-level-await": "^1.6.0",
     "vite-plugin-wasm": "^3.6.0",
-    "@dxos/config": "0.10.0",
-    "@dxos/echo": "0.10.0",
-    "@dxos/keyboard": "0.10.0",
-    "@dxos/random": "0.10.0",
-    "@dxos/ui-theme": "0.10.0",
-    "@dxos/schema": "0.10.0",
-    "@dxos/storybook-utils": "0.10.0"
+    "@dxos/echo": "0.11.1",
+    "@dxos/keyboard": "0.11.1",
+    "@dxos/random": "0.11.1",
+    "@dxos/schema": "0.11.1",
+    "@dxos/storybook-utils": "0.11.1",
+    "@dxos/ui-theme": "0.11.1",
+    "@dxos/config": "0.11.1"
   },
   "peerDependencies": {
     "@effect/platform": "0.96.2",
     "effect": "3.21.4",
-    "@dxos/ui-theme": "0.10.0"
+    "@dxos/ui-theme": "^0.11.1"
   },
   "publishConfig": {
     "access": "public"

package/src/defaults.ts

@@ -30,7 +30,7 @@ export const documentSlots: ThemeExtensionsOptions['slots'] = {
       'dx-inline-size-container',
       // Wider margin for web (vs. mobile).
       'pointer-fine:max-w-[min(50rem,100%-4rem)] pointer-coarse:max-w-[min(50rem,100%-2rem)]',
-      'mx-auto! w-full',
+      'mx-auto! w-full py-3!',
     ),
   },
 };

package/src/extensions/{bookmarks.ts → behavior/bookmarks.ts}

@@ -2,10 +2,8 @@
 // Copyright 2025 DXOS.org
 //
 
-import { type Extension, Prec, StateEffect, StateField } from '@codemirror/state';
-import { keymap } from '@codemirror/view';
-
-import { log } from '@dxos/log';
+import { EditorSelection, type Extension, Prec, StateEffect, StateField } from '@codemirror/state';
+import { type EditorView, keymap } from '@codemirror/view';
 
 type Bookmark = {
   id: string;
@@ -17,6 +15,9 @@ export const addBookmark = StateEffect.define<Bookmark>();
 export const removeBookmark = StateEffect.define<string>();
 export const clearBookmarks = StateEffect.define<void>();
 
+/**
+ * Registers a bookmarks state field and Mod-Arrow navigation keys.
+ */
 export const bookmarks = (): Extension => {
   return [
     bookmarksField,
@@ -24,25 +25,34 @@ export const bookmarks = (): Extension => {
       keymap.of([
         {
           key: 'Mod-ArrowUp',
-          run: (view) => {
-            const bookmarks = view.state.field(bookmarksField);
-            log('up', bookmarks);
-            return true;
-          },
+          run: (view) => navigateBookmark(view, 'up'),
         },
         {
           key: 'Mod-ArrowDown',
-          run: (view) => {
-            const bookmarks = view.state.field(bookmarksField);
-            log('down', bookmarks);
-            return true;
-          },
+          run: (view) => navigateBookmark(view, 'down'),
         },
       ]),
     ),
   ];
 };
 
+// Jump to the nearest bookmark before/after the caret. Declines the key (returns false) when there
+// is none so it falls through to the default behavior rather than being silently swallowed.
+const navigateBookmark = (view: EditorView, direction: 'up' | 'down'): boolean => {
+  const { bookmarks } = view.state.field(bookmarksField);
+  const pos = view.state.selection.main.head;
+  const target =
+    direction === 'up'
+      ? [...bookmarks].reverse().find((bookmark) => bookmark.pos < pos)
+      : bookmarks.find((bookmark) => bookmark.pos > pos);
+  if (!target) {
+    return false;
+  }
+
+  view.dispatch({ selection: EditorSelection.cursor(target.pos), scrollIntoView: true });
+  return true;
+};
+
 type BookmarkFieldState = {
   bookmarks: Bookmark[];
 };

package/src/extensions/behavior/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './bookmarks';
+export * from './dnd';
+export * from './listener';
+export * from './spacing';
+export * from './submit';

package/src/extensions/{listener.ts → behavior/listener.ts}

@@ -7,13 +7,16 @@ import { EditorView } from '@codemirror/view';
 
 import { isNonNullable } from '@dxos/util';
 
-import { documentId } from './selection';
+import { documentId } from '../state/selection';
 
 export type ListenerOptions = {
   onFocus?: (event: { id: string; focusing: boolean }) => void;
   onChange?: (event: { id: string; text: string }) => void;
 };
 
+/**
+ * Fires callbacks on focus change and document change.
+ */
 export const listener = ({ onFocus, onChange }: ListenerOptions): Extension => {
   return [
     onFocus &&

package/src/extensions/{spacing.ts → behavior/spacing.ts}

@@ -5,11 +5,17 @@
 import { Extension } from '@codemirror/state';
 import { EditorView } from '@codemirror/view';
 
+/**
+ * Adds vertical padding to each `.cm-line`.
+ */
 export function lineSpacing(verticalPadding = 2): Extension {
-  return EditorView.theme({
+  return lineSpacingTheme(verticalPadding);
+}
+
+const lineSpacingTheme = (verticalPadding: number): Extension =>
+  EditorView.theme({
     '.cm-line': {
       paddingTop: `${verticalPadding}px`,
       paddingBottom: `${verticalPadding}px`,
     },
   });
-}

package/src/extensions/{submit.ts → behavior/submit.ts}

@@ -43,16 +43,8 @@ export const submit = ({ fireIfEmpty = false, onSubmit }: SubmitOptions = {}): E
           key: 'Shift-Enter',
           preventDefault: true,
           run: (view) => {
-            view.dispatch({
-              changes: {
-                from: view.state.selection.main.head,
-                insert: '\n',
-              },
-              selection: {
-                anchor: view.state.selection.main.head + 1,
-                head: view.state.selection.main.head + 1,
-              },
-            });
+            // Replace the selection (handles ranges and multiple cursors), not just the main head.
+            view.dispatch(view.state.replaceSelection('\n'));
             return true;
           },
         },

package/src/extensions/{automerge → collab/automerge}/automerge.test.tsx

@@ -35,11 +35,11 @@ const Test = ({ accessor }: { accessor: Doc.Accessor<TestType> }) => {
   useEffect(() => {
     const extensions = [
       automerge(accessor),
-      EditorView.updateListener.of(() => {
-        if (view.state.doc.toString() === 'hello!') {
+      EditorView.updateListener.of((update) => {
+        if (update.view.state.doc.toString() === 'hello!') {
           // Update editor.
-          view.dispatch({
-            changes: { from: view.state.doc.length - 1, insert: ' world' },
+          update.view.dispatch({
+            changes: { from: update.view.state.doc.length - 1, insert: ' world' },
           });
         }
       }),

package/src/extensions/{automerge → collab/automerge}/automerge.ts

@@ -10,10 +10,9 @@ import { EditorView, ViewPlugin } from '@codemirror/view';
 
 import { Doc } from '@dxos/echo-doc';
 
-import { Cursor } from '../../util';
-import { initialSync } from '../state';
+import { Cursor } from '../../../util';
 import { cursorConverter } from './cursor';
-import { type State, isReconcile, reconcileAnnotation, updateHeadsEffect } from './defs';
+import { type State, initialSync, isReconcile, reconcileAnnotation, updateHeadsEffect } from './defs';
 import { Syncer } from './sync';
 
 /**
@@ -71,7 +70,11 @@ export const automerge = (accessor: Doc.Accessor): Extension => {
         constructor(private readonly _view: EditorView) {
           accessor.handle.addListener('change', this._handleChange);
 
-          requestAnimationFrame(() => {
+          // Reconcile on attach: a compartment swap hands this extension a view whose content is the
+          // PREVIOUS document's. Deferred by a microtask only to escape the in-progress update cycle;
+          // rAF is not reliable for correctness (hidden/throttled frames never fire it), and until
+          // this replace runs every write maps view coordinates onto the wrong document.
+          queueMicrotask(() => {
             const value = Doc.getValue<string>(accessor);
             const current = this._view.state.doc.toString();
             if (value !== current) {

package/src/extensions/{automerge → collab/automerge}/cursor.ts

@@ -6,7 +6,7 @@ import { fromCursor, toCursor } from '@dxos/echo-client';
 import { Doc } from '@dxos/echo-doc';
 import { log } from '@dxos/log';
 
-import { type CursorConverter } from '../../util';
+import { type CursorConverter } from '../../../util';
 
 /**
  * Maps between editor offsets and stable Automerge cursors for the text the {@link Doc.Accessor}

package/src/extensions/{automerge → collab/automerge}/defs.ts

@@ -5,7 +5,10 @@
 //
 
 import { type Heads, type Prop } from '@automerge/automerge';
-import { Annotation, type EditorState, StateEffect, type StateField, type Transaction } from '@codemirror/state';
+import { Annotation, type EditorState, StateEffect, type StateField, Transaction } from '@codemirror/state';
+
+/** Marks the transaction that performs the initial editor/document reconciliation. */
+export const initialSync = Transaction.userEvent.of('initial.sync');
 
 export type State = {
   path: Prop[];

package/src/extensions/{automerge → collab/automerge}/index.ts

@@ -3,3 +3,4 @@
 //
 
 export { automerge } from './automerge';
+export { initialSync } from './defs';

package/src/extensions/{automerge → collab/automerge}/sync.ts

@@ -21,10 +21,9 @@ import { updateCodeMirror } from './update-codemirror';
 export class Syncer {
   private _pending = false;
 
-  // prettier-ignore
   constructor(
     private readonly _handle: Doc.Handle,
-    private readonly _state: StateField<State>
+    private readonly _state: StateField<State>,
   ) {}
 
   reconcile(view: EditorView, editor: boolean): void {

package/src/extensions/{automerge → collab/automerge}/update-automerge.ts

@@ -11,6 +11,10 @@ import { Doc } from '@dxos/echo-doc';
 
 import { type State } from './defs';
 
+/**
+ * Applies CodeMirror transactions to the Automerge document (via `changeAt` from the last synced
+ * heads) and returns the new heads, or undefined when there are no changes.
+ */
 export const updateAutomerge = (
   field: StateField<State>,
   handle: Doc.Handle,

package/src/extensions/{automerge → collab/automerge}/update-codemirror.ts

@@ -17,6 +17,10 @@ import { type EditorView } from '@codemirror/view';
 
 import { reconcileAnnotation } from './defs';
 
+/**
+ * Applies Automerge patches to the CodeMirror view as changes, keeping the given selection mapped
+ * across them (marked with the reconcile annotation so the sync loop ignores the echoed transaction).
+ */
 export const updateCodeMirror = (view: EditorView, selection: EditorSelection, target: Prop[], patches: Patch[]) => {
   for (const patch of patches) {
     const changeSpec = handlePatch(patch, target, view.state);
@@ -90,7 +94,7 @@ const handlePut = (target: Prop[], patch: PutPatch, state: EditorState): Array<C
     return []; // TODO(dmaretskyi): How to handle non-string values?
   }
 
-  return [{ from: 0, to: length, insert: patch.value as any }];
+  return [{ from: 0, to: length, insert: patch.value }];
 };
 
 // If the path of the patch is of the form [path, <index>] then we know this is a path to a character

package/src/extensions/{awareness → collab/awareness}/awareness-provider.ts

@@ -103,19 +103,18 @@ export class SpaceAwarenessProvider implements AwarenessProvider {
   }
 
   update(position: AwarenessPosition | undefined): void {
-    invariant(this._postTask);
     this._localState = {
       peerId: this._peerId,
       position,
       info: this._info,
     };
 
-    this._postTask.schedule();
+    // Safe no-op if called before open() or during async teardown after close().
+    this._postTask?.schedule();
   }
 
   private _handleQueryMessage(): void {
-    invariant(this._postTask);
-    this._postTask.schedule();
+    this._postTask?.schedule();
   }
 
   private _handlePostMessage(message: ProtocolMessage): void {

package/src/extensions/{awareness → collab/awareness}/awareness.ts

@@ -16,7 +16,7 @@ import {
 import { Event } from '@dxos/async';
 import { Context } from '@dxos/context';
 
-import { Cursor, type CursorConverter, singleValueFacet } from '../../util';
+import { Cursor, type CursorConverter, singleValueFacet } from '../../../util';
 
 export interface AwarenessProvider {
   remoteStateChange: Event<void>;
@@ -28,21 +28,6 @@ export interface AwarenessProvider {
   update(position: AwarenessPosition | undefined): void;
 }
 
-const dummyProvider: AwarenessProvider = {
-  remoteStateChange: new Event(),
-
-  open: () => {},
-  close: () => {},
-
-  getRemoteStates: () => [],
-  update: () => {},
-};
-
-export const awarenessProvider = singleValueFacet<AwarenessProvider>(dummyProvider);
-
-// TODO(dmaretskyi): Specify the users that actually changed. Currently, we recalculate positions for every user.
-const RemoteSelectionChangedAnnotation = Annotation.define();
-
 export type AwarenessPosition = {
   anchor?: string;
   head?: string;
@@ -73,6 +58,24 @@ export const awareness = (provider = dummyProvider): Extension => {
   ];
 };
 
+const dummyProvider: AwarenessProvider = {
+  remoteStateChange: new Event(),
+
+  open: () => {},
+  close: () => {},
+
+  getRemoteStates: () => [],
+  update: () => {},
+};
+
+/**
+ * Single-value facet supplying the AwarenessProvider consumed by the awareness extension.
+ */
+export const awarenessProvider = singleValueFacet<AwarenessProvider>(dummyProvider);
+
+// TODO(dmaretskyi): Specify the users that actually changed. Currently, we recalculate positions for every user.
+const RemoteSelectionChangedAnnotation = Annotation.define();
+
 /**
  * Generates selection decorations from remote peers.
  */

package/src/extensions/collab/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './automerge';
+export * from './awareness';

package/src/extensions/{autocomplete → completion}/autocomplete.ts

@@ -99,11 +99,7 @@ export const autocomplete = ({ onSuggest }: AutocompleteOptions = {}): Extension
 
   return [
     suggest,
-    EditorView.theme({
-      '.cm-inline-suggestion': {
-        opacity: 0.4,
-      },
-    }),
+    styles,
 
     Prec.highest(
       keymap.of([
@@ -149,3 +145,9 @@ class InlineSuggestionWidget extends WidgetType {
     return span;
   }
 }
+
+const styles = EditorView.theme({
+  '.cm-inline-suggestion': {
+    opacity: 0.4,
+  },
+});

package/src/extensions/{autocomplete → completion}/index.ts

@@ -1,8 +1,9 @@
 //
-// Copyright 2023 DXOS.org
+// Copyright 2025 DXOS.org
 //
 
 export * from './autocomplete';
 export * from './match';
+export * from './mention';
 export * from './placeholder';
 export * from './typeahead';

package/src/extensions/{autocomplete → completion}/match.ts

@@ -2,7 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
-export type CompoetionContext = { line: string };
+export type CompletionContext = { line: string };
 
 export type CompletionOptions = {
   default?: string;
@@ -14,7 +14,7 @@ export type CompletionOptions = {
  */
 export const staticCompletion =
   (completions: string[], options: CompletionOptions = {}) =>
-  ({ line }: CompoetionContext) => {
+  ({ line }: CompletionContext) => {
     if (line.length === 0 && options.default) {
       return options.default;
     }

package/src/extensions/{mention.ts → completion/mention.ts}

@@ -13,6 +13,9 @@ export type MentionOptions = {
 };
 
 // TODO(burdon): Can only have a single autocompletion. Merge configuration with autocomplete.
+/**
+ * `@`-mention autocomplete completion source.
+ */
 export const mention = ({ debug, onSearch }: MentionOptions): Extension => {
   return autocompletion({
     // TODO(burdon): Not working.

package/src/extensions/{autocomplete → completion}/placeholder.ts

@@ -7,7 +7,7 @@ import { type Extension } from '@codemirror/state';
 import { Decoration, EditorView, ViewPlugin, type ViewUpdate, WidgetType } from '@codemirror/view';
 
 import { clientRectsFor, flattenRect } from '../../util';
-import { isBusy } from '../busy';
+import { isBusy } from '../state/busy';
 
 type Content = string | HTMLElement | ((view: EditorView) => HTMLElement);