@dxos/react-ui-editor 0.8.4-main.fd6878d → 0.8.4-main.fffef41

package/src/extensions/preview/preview.ts

@@ -2,20 +2,16 @@
 // Copyright 2023 DXOS.org
 //
 
-import '@dxos/lit-ui/dx-ref-tag.pcss';
-
 import { syntaxTree } from '@codemirror/language';
-import {
-  type EditorState,
-  type Extension,
-  type RangeSet,
-  RangeSetBuilder,
-  StateField,
-  type Transaction,
-} from '@codemirror/state';
+import { type EditorState, type Extension, RangeSetBuilder, StateField } from '@codemirror/state';
 import { Decoration, type DecorationSet, EditorView, WidgetType } from '@codemirror/view';
 import { type SyntaxNode } from '@lezer/common';
 
+export type PreviewBlock = {
+  link: PreviewLinkRef;
+  el: HTMLElement;
+};
+
 export type PreviewLinkRef = {
   suggest?: boolean;
   block?: boolean;
@@ -29,13 +25,9 @@ export type PreviewLinkTarget = {
   object?: any;
 };
 
-// TODO(wittjosiah): Remove.
-// TODO(burdon): Handle error.
-export type PreviewLookup = (link: PreviewLinkRef) => Promise<PreviewLinkTarget | null | undefined>;
-
 export type PreviewOptions = {
-  addBlockContainer?: (link: PreviewLinkRef, el: HTMLElement) => void;
-  removeBlockContainer?: (link: PreviewLinkRef) => void;
+  addBlockContainer?: (block: PreviewBlock) => void;
+  removeBlockContainer?: (block: PreviewBlock) => void;
 };
 
 /**
@@ -44,10 +36,16 @@ export type PreviewOptions = {
 export const preview = (options: PreviewOptions = {}): Extension => {
   return [
     // NOTE: Atomic block decorations must be created from a state field, now a widget, otherwise it results in the following error:
-    // "Block decorations may not be specified via plugins"
+    // "Block decorations may not be specified via plugins".
     StateField.define<DecorationSet>({
       create: (state) => buildDecorations(state, options),
-      update: (_: RangeSet<Decoration>, tr: Transaction) => buildDecorations(tr.state, options),
+      update: (decorations, tr) => {
+        if (tr.docChanged) {
+          return buildDecorations(tr.state, options);
+        }
+
+        return decorations.map(tr.changes);
+      },
       provide: (field) => [
         EditorView.decorations.from(field),
         EditorView.atomicRanges.of((view) => view.state.field(field)),
@@ -56,42 +54,19 @@ export const preview = (options: PreviewOptions = {}): Extension => {
   ];
 };
 
-/**
- * Link references.
- *
- *  [Label][dxn:echo:123]    Inline reference
- * ![Label][dxn:echo:123]    Block reference
- * ![Label][?dxn:echo:123]   Suggestion
- */
-export const getLinkRef = (state: EditorState, node: SyntaxNode): PreviewLinkRef | undefined => {
-  const mark = node.getChild('LinkMark');
-  const label = node.getChild('LinkLabel');
-  if (mark && label) {
-    const ref = state.sliceDoc(label.from + 1, label.to - 1);
-    return {
-      suggest: ref.startsWith('?'),
-      block: state.sliceDoc(mark.from, mark.from + 1) === '!',
-      label: state.sliceDoc(mark.to, label.from - 1),
-      ref: ref.startsWith('?') ? ref.slice(1) : ref,
-    };
-  }
-};
-
 /**
  * Echo references are represented as markdown reference links.
  * https://www.markdownguide.org/basic-syntax/#reference-style-links
- * [Label|block][dxn:echo:123]
- * [Label|inline][dxn:echo:123]
  */
-const buildDecorations = (state: EditorState, options: PreviewOptions) => {
+const buildDecorations = (state: EditorState, options: PreviewOptions): DecorationSet => {
   const builder = new RangeSetBuilder<Decoration>();
 
   syntaxTree(state).iterate({
     enter: (node) => {
       switch (node.name) {
         //
-        // Decoration.
-        // [Label][dxn:echo:123]
+        // Inline widget.
+        // [Label](dxn:echo:123)
         //
         case 'Link': {
           const link = getLinkRef(state, node.node);
@@ -101,29 +76,32 @@ const buildDecorations = (state: EditorState, options: PreviewOptions) => {
               node.to,
               Decoration.replace({
                 widget: new PreviewInlineWidget(options, link),
+                side: 1,
               }),
             );
           }
-          break;
+          return false;
         }
+
         //
-        // Block widget.
-        // ![Label][dxn:echo:123]
+        // Block widget (transclusion).
+        // ![Label](dxn:echo:123)
         //
         case 'Image': {
-          const link = getLinkRef(state, node.node);
-          if (options.addBlockContainer && options.removeBlockContainer && link) {
-            builder.add(
-              node.from,
-              node.to,
-              Decoration.replace({
-                block: true,
-                // atomic: true,
-                widget: new PreviewBlockWidget(options, link),
-              }),
-            );
+          if (options.addBlockContainer && options.removeBlockContainer) {
+            const link = getLinkRef(state, node.node);
+            if (link) {
+              builder.add(
+                node.from,
+                node.to,
+                Decoration.replace({
+                  block: true,
+                  widget: new PreviewBlockWidget(options, link),
+                }),
+              );
+            }
           }
-          break;
+          return false;
         }
       }
     },
@@ -132,9 +110,30 @@ const buildDecorations = (state: EditorState, options: PreviewOptions) => {
   return builder.finish();
 };
 
+/**
+ * Link references.
+ *  [Label](dxn:echo:123) Inline reference
+ * ![Label](dxn:echo:123) Block reference
+ */
+export const getLinkRef = (state: EditorState, node: SyntaxNode): PreviewLinkRef | undefined => {
+  const mark = node.getChildren('LinkMark');
+  const urlNode = node.getChild('URL');
+  if (mark && urlNode) {
+    const url = state.sliceDoc(urlNode.from, urlNode.to);
+    if (url.startsWith('dxn:')) {
+      const label = state.sliceDoc(mark[0].to, mark[1].from);
+      return {
+        block: state.sliceDoc(mark[0].from, mark[0].from + 1) === '!',
+        label,
+        ref: url,
+      };
+    }
+  }
+};
+
 /**
  * Inline widget.
- * [Label][dxn:echo:123]
+ *  [Label](dxn:echo:123)
  */
 class PreviewInlineWidget extends WidgetType {
   constructor(
@@ -148,12 +147,13 @@ class PreviewInlineWidget extends WidgetType {
   //   return false;
   // }
 
-  override eq(other: this): boolean {
+  override eq(other: this) {
     return this._link.ref === other._link.ref && this._link.label === other._link.label;
   }
 
-  override toDOM(view: EditorView): HTMLElement {
-    const root = document.createElement('dx-ref-tag');
+  override toDOM(_view: EditorView) {
+    const root = document.createElement('dx-anchor');
+    root.classList.add('dx-tag--anchor');
     root.textContent = this._link.label;
     root.setAttribute('refId', this._link.ref);
     return root;
@@ -161,7 +161,7 @@ class PreviewInlineWidget extends WidgetType {
 }
 
 /**
- * Block widget.
+ * Block widget (e.g., for surfaces).
  * ![Label][dxn:echo:123]
  */
 class PreviewBlockWidget extends WidgetType {
@@ -176,18 +176,18 @@ class PreviewBlockWidget extends WidgetType {
   //   return true;
   // }
 
-  override eq(other: this): boolean {
+  override eq(other: this) {
     return this._link.ref === other._link.ref;
   }
 
-  override toDOM(view: EditorView): HTMLDivElement {
+  override toDOM(_view: EditorView) {
     const root = document.createElement('div');
     root.classList.add('cm-preview-block', 'density-coarse');
-    this._options.addBlockContainer?.(this._link, root);
+    this._options.addBlockContainer?.({ link: this._link, el: root });
     return root;
   }
 
-  override destroy() {
-    this._options.removeBlockContainer?.(this._link);
+  override destroy(root: HTMLDivElement) {
+    this._options.removeBlockContainer?.({ link: this._link, el: root });
   }
 }

package/src/extensions/replacer.test.ts

@@ -0,0 +1,75 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { EditorState } from '@codemirror/state';
+import { EditorView } from '@codemirror/view';
+import { describe, expect, test } from 'vitest';
+
+import { replacer } from './replacer';
+
+describe('replacer extension', () => {
+  test('creates extension with custom replacements and simulates typing', () => {
+    const state = EditorState.create({
+      extensions: [
+        replacer({
+          replacements: [
+            { input: ':)', output: '😊' },
+            { input: ':(', output: '😢' },
+          ],
+        }),
+      ],
+      doc: '',
+    });
+
+    // Create a minimal mock EditorView to test input handler
+    let currentState = state;
+    const mockView = {
+      get state() {
+        return currentState;
+      },
+      dispatch: (transaction: any) => {
+        currentState = transaction.state || currentState.update(transaction).state;
+      },
+    } as any;
+
+    // Get the input handler from the extension
+    const extensions = currentState.facet(EditorView.inputHandler);
+    const inputHandler = extensions[0];
+
+    // Test typing ':' first - should not trigger replacement.
+    let handled = inputHandler(mockView, 0, 0, ':', () =>
+      mockView.state.update({ changes: { from: 0, to: 0, insert: ':' } }),
+    );
+    expect(handled).toBe(false); // Should not handle single ':'
+
+    // Manually insert ':' to simulate first character.
+    mockView.dispatch({
+      changes: { from: 0, to: 0, insert: ':' },
+      selection: { anchor: 1 },
+    });
+    expect(mockView.state.doc.toString()).toBe(':');
+
+    // Test typing ')' which should trigger replacement.
+    // The input handler is called with the position where the character will be inserted.
+    // and it should handle the replacement before the character is actually inserted.
+    handled = inputHandler(mockView, 1, 1, ')', () =>
+      mockView.state.update({ changes: { from: 1, to: 1, insert: ')' } }),
+    );
+    expect(handled).toBe(true); // Should handle and replace ':)'
+    expect(mockView.state.doc.toString()).toBe('😊');
+  });
+
+  test('creates extension with default replacements', () => {
+    const state = EditorState.create({
+      extensions: [replacer()],
+      doc: 'test',
+    });
+
+    expect(state.doc.toString()).toBe('test');
+
+    // Verify the extension is installed.
+    const inputHandlers = state.facet(EditorView.inputHandler);
+    expect(inputHandlers.length).toBeGreaterThan(0);
+  });
+});

package/src/extensions/replacer.ts

@@ -0,0 +1,93 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Extension } from '@codemirror/state';
+import { EditorView } from '@codemirror/view';
+
+type Replacement = {
+  input: string;
+  output: string;
+};
+
+/**
+ * Default character replacements for common typography.
+ */
+export const defaultReplacements: Replacement[] = [
+  { input: '--', output: '—' },
+  { input: '...', output: '…' },
+  { input: '->', output: '→' },
+  { input: '<-', output: '←' },
+  { input: '=>', output: '⇒' },
+  { input: '<=>', output: '⇔' },
+  { input: '+-', output: '±' },
+  { input: '!=', output: '≠' },
+  { input: '<=', output: '≤' },
+  { input: '>=', output: '≥' },
+  { input: '(c)', output: '©' },
+  { input: 'EUR', output: '€' },
+  { input: 'GBP', output: '£' },
+  { input: 'BTC', output: '₿' },
+];
+
+/**
+ * Options for the replacer extension.
+ */
+export interface ReplacerOptions {
+  replacements?: Replacement[];
+}
+
+/**
+ * Creates a CodeMirror extension that automatically replaces typed character sequences.
+ */
+export const replacer = ({ replacements = defaultReplacements }: ReplacerOptions = {}): Extension => {
+  // Sort replacements by input length (longest first) to handle overlapping patterns correctly.
+  const sortedReplacements = [...replacements].sort((a, b) => b.input.length - a.input.length);
+
+  return EditorView.inputHandler.of((view, from, to, insert) => {
+    // Only process single character insertions for performance.
+    if (insert.length !== 1) {
+      return false;
+    }
+
+    const state = view.state;
+    const doc = state.doc;
+
+    // Get the text before the insertion point to check for patterns.
+    const lineStart = doc.lineAt(from).from;
+    const textBefore = doc.sliceString(lineStart, from);
+    const textWithInsert = textBefore + insert;
+
+    // Check each replacement pattern.
+    for (const replacement of sortedReplacements) {
+      if (textWithInsert.endsWith(replacement.input)) {
+        const range = {
+          from: from - replacement.input.length + 1,
+          to: from,
+        };
+
+        // Ensure we don't go before the line start.
+        if (range.from < lineStart) {
+          continue;
+        }
+
+        // Create the replacement transaction.
+        view.dispatch(
+          state.update({
+            changes: {
+              ...range,
+              insert: replacement.output,
+            },
+            selection: {
+              anchor: range.from + replacement.output.length,
+            },
+          }),
+        );
+
+        return true;
+      }
+    }
+
+    return false;
+  });
+};

package/src/extensions/scrolling.ts

@@ -0,0 +1,189 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { StateEffect } from '@codemirror/state';
+import { EditorView, ViewPlugin } from '@codemirror/view';
+
+/**
+ * Configuration options for smooth scrolling behavior.
+ */
+export type SmoothScrollOptions = {
+  /**
+   * Additional offset from the target line in pixels.
+   * Positive values scroll past the line, negative values stop before it.
+   * @default 0
+   */
+  offset?: number;
+  /**
+   * Position of the target line in the viewport.
+   * - 'start': Line appears at the start (top) of the screen
+   * - 'end': Line appears at the end (bottom) of the screen
+   * @default 'start'
+   */
+  position?: 'start' | 'end';
+  /**
+   * Whether to use smooth scrolling.
+   * @default 'smooth'
+   */
+  behavior?: ScrollBehavior;
+};
+
+/**
+ * Parameters for the scroll to line effect.
+ */
+export type ScrollToLineParams = {
+  /**
+   * The line number to scroll to (1-based).
+   */
+  line: number;
+  /**
+   * Optional configuration to override default scroll behavior.
+   */
+  options?: SmoothScrollOptions;
+};
+
+/**
+ * StateEffect for triggering smooth scroll to a specific line.
+ */
+export const scrollToLineEffect = StateEffect.define<ScrollToLineParams>();
+
+/**
+ * Extension that provides smooth scrolling to specific lines in the editor.
+ *
+ * @example
+ * ```typescript
+ * // Add to editor extensions.
+ * const extensions = [
+ *   smoothScroll()
+ * ];
+ *
+ * // Trigger scroll to line 42.
+ * view.dispatch({
+ *   effects: scrollToLineEffect.of({ line: 42 })
+ * });
+ *
+ * // Scroll with custom options.
+ * view.dispatch({
+ *   effects: scrollToLineEffect.of({ line: 100, options: { offset: -50 } })
+ * });
+ *
+ * // Scroll so line appears at end (bottom) of screen.
+ * view.dispatch({
+ *   effects: scrollToLineEffect.of({ line: 50, options: { position: 'end' } })
+ * });
+ * ```
+ */
+export const smoothScroll = ({ offset = 0, position = 'start' }: Partial<SmoothScrollOptions> = {}) => {
+  // ViewPlugin to manage scroll animations.
+  const scrollPlugin = ViewPlugin.fromClass(
+    class SmoothScrollPlugin {
+      constructor(private readonly view: EditorView) {}
+
+      // No-op.
+      destroy() {}
+
+      /**
+       * Perform smooth scroll to the specified line.
+       */
+      scrollToLine(lineNumber: number, options: SmoothScrollOptions) {
+        const { offset: animOffset = 0, position: animPosition, behavior } = options;
+        const doc = this.view.state.doc;
+        const scroller = this.view.scrollDOM;
+
+        // Convert 1-based line number to 0-based.
+        const targetLine = Math.max(0, lineNumber - 1);
+        if (behavior === 'instant') {
+          requestAnimationFrame(() => {
+            this.view.dispatch({
+              selection: { anchor: doc.line(targetLine + 1).from },
+              scrollIntoView: true,
+            });
+          });
+          return;
+        }
+
+        // Get the position of the target line.
+        if (targetLine >= doc.lines) {
+          // Line doesn't exist, scroll to end.
+          const targetScrollTop = scroller.scrollHeight - scroller.clientHeight + (animOffset || 0);
+          this.animateScroll(scroller, targetScrollTop);
+          return;
+        }
+
+        const lineStart = doc.line(targetLine + 1).from;
+        const coords = this.view.coordsAtPos(lineStart);
+        if (!coords) {
+          return;
+        }
+
+        // Calculate target scroll position based on position option.
+        const currentScrollTop = scroller.scrollTop;
+        const scrollerRect = scroller.getBoundingClientRect();
+        const maxScrollTop = scroller.scrollHeight - scroller.clientHeight;
+
+        let targetScrollTop: number;
+        if (animPosition === 'end') {
+          // Position line at end (bottom) of viewport.
+          // Calculate how far down we need to scroll so the line's bottom aligns with viewport bottom.
+          targetScrollTop = currentScrollTop + coords.bottom - scrollerRect.bottom + animOffset;
+        } else {
+          // Default: position line at start (top) of viewport.
+          targetScrollTop = currentScrollTop + coords.top - scrollerRect.top + animOffset;
+        }
+
+        // Clamp to valid scroll range.
+        const clampedScrollTop = Math.max(0, Math.min(targetScrollTop, maxScrollTop));
+        this.animateScroll(scroller, clampedScrollTop);
+      }
+
+      /**
+       * Animate scroll using browser's built-in smooth scrolling.
+       */
+      private animateScroll(element: HTMLElement, targetScrollTop: number) {
+        if (Math.abs(targetScrollTop - element.scrollTop) < 1) {
+          return;
+        }
+
+        // Use browser's built-in smooth scrolling.
+        element.scrollTo({
+          top: targetScrollTop,
+          behavior: 'smooth',
+        });
+      }
+    },
+  );
+
+  return [
+    scrollPlugin,
+
+    // Update listener to handle scroll effects.
+    EditorView.updateListener.of((update) => {
+      update.transactions.forEach((transaction) => {
+        for (const effect of transaction.effects) {
+          if (effect.is(scrollToLineEffect)) {
+            const { line, options = {} } = effect.value;
+            const plugin = update.view.plugin(scrollPlugin);
+            if (plugin) {
+              plugin.scrollToLine(line, { offset, position, ...options });
+            }
+          }
+        }
+      });
+    }),
+  ];
+};
+
+/**
+ * Helper function to scroll to a specific line.
+ * This is a convenience function that can be used directly with an EditorView.
+ *
+ * @param view - The CodeMirror EditorView instance
+ * @param line - The line number to scroll to (1-based)
+ * @param options - Optional scroll configuration
+ */
+export const scrollToLine = (view: EditorView, line: number, options?: SmoothScrollOptions) => {
+  view.dispatch({
+    effects: scrollToLineEffect.of({ line, options }),
+  });
+};

package/src/extensions/selection.ts

@@ -7,7 +7,7 @@ import { EditorView, keymap } from '@codemirror/view';
 
 import { debounce } from '@dxos/async';
 import { invariant } from '@dxos/invariant';
-import { isNotFalsy } from '@dxos/util';
+import { isTruthy } from '@dxos/util';
 
 import { singleValueFacet } from '../util';
 
@@ -86,7 +86,7 @@ export const selectionState = ({ getState, setState }: Partial<EditorStateStore>
     getState &&
       keymap.of([
         {
-          key: 'ctrl-r', // TODO(burdon): Setting to jump back to selection.
+          key: 'Ctrl-r', // TODO(burdon): Setting to jump back to selection.
           run: (view) => {
             const state = getState(view.state.facet(documentId));
             if (state) {
@@ -96,5 +96,5 @@ export const selectionState = ({ getState, setState }: Partial<EditorStateStore>
           },
         },
       ]),
-  ].filter(isNotFalsy);
+  ].filter(isTruthy);
 };

package/src/extensions/state.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Transaction } from '@codemirror/state';
+
+export const initialSync = Transaction.userEvent.of('initial.sync');

package/src/extensions/submit.ts

@@ -0,0 +1,62 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Extension, Prec } from '@codemirror/state';
+import { keymap } from '@codemirror/view';
+
+export type SubmitOptions = {
+  fireIfEmpty?: boolean;
+  onSubmit?: (text: string) => boolean | void;
+};
+
+/**
+ * Handles Enter and Shift-Enter.
+ */
+export const submit = ({ fireIfEmpty = false, onSubmit }: SubmitOptions = {}): Extension => {
+  return [
+    Prec.highest(
+      keymap.of([
+        {
+          key: 'Enter',
+          preventDefault: true,
+          run: (view) => {
+            const text = view.state.doc.toString().trim();
+            if (onSubmit && (fireIfEmpty || text.length > 0)) {
+              const reset = onSubmit(text);
+              if (reset) {
+                // Clear the document after calling onEnter.
+                view.dispatch({
+                  changes: {
+                    from: 0,
+                    to: view.state.doc.length,
+                    insert: '',
+                  },
+                });
+              }
+            }
+
+            return true;
+          },
+        },
+        {
+          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,
+              },
+            });
+            return true;
+          },
+        },
+      ]),
+    ),
+  ];
+};