@dxos/ui-editor 0.0.0

package/src/extensions/automerge/automerge.test.tsx

@@ -0,0 +1,76 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { type DocHandle, Repo } from '@automerge/automerge-repo';
+import { EditorState } from '@codemirror/state';
+import { EditorView } from '@codemirror/view';
+import { render, screen } from '@testing-library/react';
+import React, { type FC, useEffect, useRef, useState } from 'react';
+import { describe, test } from 'vitest';
+
+import { get } from '@dxos/util';
+
+import { automerge } from './automerge';
+
+type TestObject = {
+  text: string;
+};
+
+const path = ['text'];
+
+class Generator {
+  constructor(private readonly _handle: DocHandle<TestObject>) {}
+  update(text: string): void {
+    this._handle.change((doc: TestObject) => {
+      doc.text = text;
+    });
+  }
+}
+
+const Test: FC<{ handle: DocHandle<TestObject>; generator: Generator }> = ({ handle, generator }) => {
+  const ref = useRef<HTMLDivElement>(null);
+  const [view, setView] = useState<EditorView>();
+  useEffect(() => {
+    const extensions = [
+      // TODO(mykola): Fix types.
+      automerge({ handle: handle as any, path }),
+      EditorView.updateListener.of((update) => {
+        if (view.state.doc.toString() === 'hello!') {
+          // Update editor.
+          update.view.dispatch({
+            changes: { from: view.state.doc.length - 1, insert: ' world' },
+          });
+        }
+      }),
+    ];
+
+    const view = new EditorView({
+      state: EditorState.create({ doc: get(handle.doc()!, path), extensions }),
+      parent: ref.current!,
+    });
+
+    setView(view);
+  }, []);
+
+  useEffect(() => {}, [view]);
+
+  return <div ref={ref} data-testid='editor' />;
+};
+
+describe('Automerge', () => {
+  test('basic sync', ({ expect }) => {
+    const repo = new Repo({ network: [] });
+    const handle = repo.create<TestObject>();
+    const generator = new Generator(handle);
+    render(<Test handle={handle} generator={generator} />);
+    const editor = screen.getByTestId('editor');
+    expect(editor.textContent).toBe('');
+
+    generator.update('hello!');
+    expect(editor.textContent).toBe('hello world!');
+  });
+
+  // TODO(burdon): Test history/undo.
+  // TODO(burdon): https://testing-library.com/docs/react-testing-library/example-intro/
+});

package/src/extensions/automerge/automerge.ts

@@ -0,0 +1,105 @@
+//
+// Copyright 2024 DXOS.org
+// Copyright 2024 Automerge
+// Ref: https://github.com/automerge/automerge-codemirror
+//
+
+import { next as A } from '@automerge/automerge';
+import { type Extension, StateField, Transaction } from '@codemirror/state';
+import { EditorView, ViewPlugin } from '@codemirror/view';
+
+import { DocAccessor } from '@dxos/echo-db';
+
+import { Cursor } from '../../util';
+import { initialSync } from '../state';
+
+import { cursorConverter } from './cursor';
+import { type State, isReconcile, updateHeadsEffect } from './defs';
+import { Syncer } from './sync';
+
+export const automerge = (accessor: DocAccessor): Extension => {
+  const syncState = StateField.define<State>({
+    create: () => {
+      return {
+        path: accessor.path.slice(),
+        lastHeads: A.getHeads(accessor.handle.doc()!),
+        unreconciledTransactions: [],
+      };
+    },
+
+    update: (value, tr) => {
+      const result: State = {
+        path: accessor.path.slice(),
+        lastHeads: value.lastHeads,
+        unreconciledTransactions: value.unreconciledTransactions.slice(),
+      };
+
+      let clearUnreconciled = false;
+      for (const effect of tr.effects) {
+        if (effect.is(updateHeadsEffect)) {
+          result.lastHeads = effect.value.newHeads;
+          clearUnreconciled = true;
+        }
+      }
+
+      if (clearUnreconciled) {
+        result.unreconciledTransactions = [];
+      } else {
+        if (!isReconcile(tr)) {
+          result.unreconciledTransactions.push(tr);
+        }
+      }
+
+      return result;
+    },
+  });
+
+  const syncer = new Syncer(accessor.handle, syncState);
+
+  return [
+    Cursor.converter.of(cursorConverter(accessor)),
+
+    // Track heads.
+    syncState,
+
+    // Reconcile external updates.
+    ViewPlugin.fromClass(
+      class {
+        constructor(private readonly _view: EditorView) {
+          accessor.handle.addListener('change', this._handleChange);
+
+          requestAnimationFrame(() => {
+            const value = DocAccessor.getValue<string>(accessor);
+            const current = this._view.state.doc.toString();
+            if (value !== current) {
+              // TODO(burdon): This attempts to set the initial state, but creates problems.
+              // this._view.dispatch({
+              //   changes: { from: 0, to: this._view.state.doc.length, insert: value },
+              //   annotations: initialSync,
+              // });
+            }
+          });
+        }
+
+        destroy() {
+          accessor.handle.removeListener('change', this._handleChange);
+        }
+
+        readonly _handleChange = () => {
+          syncer.reconcile(this._view, false);
+        };
+      },
+    ),
+
+    // Reconcile local updates.
+    EditorView.updateListener.of(({ view, changes, transactions }) => {
+      if (!changes.empty) {
+        // Only reconcile if it's not an initial sync (to avoid loops)
+        const isInitialSync = transactions.some((tr) => tr.annotation(Transaction.userEvent) === initialSync.value);
+        if (!isInitialSync) {
+          syncer.reconcile(view, true);
+        }
+      }
+    }),
+  ];
+};

package/src/extensions/automerge/cursor.ts

@@ -0,0 +1,28 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { type DocAccessor, fromCursor, toCursor } from '@dxos/echo-db';
+import { log } from '@dxos/log';
+
+import { type CursorConverter } from '../../util';
+
+export const cursorConverter = (accessor: DocAccessor): CursorConverter => ({
+  toCursor: (pos, assoc) => {
+    try {
+      return toCursor(accessor, pos, assoc);
+    } catch (err) {
+      log.catch(err);
+      return ''; // In case of invalid request (e.g., wrong document).
+    }
+  },
+
+  fromCursor: (cursor) => {
+    try {
+      return fromCursor(accessor, cursor);
+    } catch (err) {
+      log.catch(err);
+      return 0; // In case of invalid request (e.g., wrong document).
+    }
+  },
+});

package/src/extensions/automerge/defs.ts

@@ -0,0 +1,31 @@
+//
+// Copyright 2023 DXOS.org
+// Copyright 2024 Automerge
+// Ref: https://github.com/automerge/automerge-codemirror
+//
+
+import { type Heads, type Prop } from '@automerge/automerge';
+import { Annotation, type EditorState, StateEffect, type StateField, type Transaction } from '@codemirror/state';
+
+export type State = {
+  path: Prop[];
+  lastHeads: Heads;
+  unreconciledTransactions: Transaction[];
+};
+
+export const getPath = (state: EditorState, field: StateField<State>): Prop[] => state.field(field).path;
+export const getLastHeads = (state: EditorState, field: StateField<State>): Heads => state.field(field).lastHeads;
+
+export type UpdateHeads = {
+  newHeads: Heads;
+};
+
+export const updateHeadsEffect = StateEffect.define<UpdateHeads>({});
+
+export const updateHeads = (newHeads: Heads): StateEffect<UpdateHeads> => updateHeadsEffect.of({ newHeads });
+
+export const reconcileAnnotation = Annotation.define<boolean>();
+
+export const isReconcile = (tr: Transaction): boolean => {
+  return !!tr.annotation(reconcileAnnotation);
+};

package/src/extensions/automerge/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+export { automerge } from './automerge';

package/src/extensions/automerge/sync.ts

@@ -0,0 +1,79 @@
+//
+// Copyright 2023 DXOS.org
+// Copyright 2024 Automerge
+// Ref: https://github.com/automerge/automerge-codemirror
+//
+
+import { next as A } from '@automerge/automerge';
+import { type StateField } from '@codemirror/state';
+import { type EditorView } from '@codemirror/view';
+
+import { type IDocHandle } from '@dxos/echo-db';
+import { log } from '@dxos/log';
+
+import { type State, getLastHeads, getPath, isReconcile, reconcileAnnotation, updateHeads } from './defs';
+import { updateAutomerge } from './update-automerge';
+import { updateCodeMirror } from './update-codemirror';
+
+/**
+ * Implements three-way merge (on each mutation).
+ */
+export class Syncer {
+  private _pending = false;
+
+  // prettier-ignore
+  constructor(
+    private readonly _handle: IDocHandle,
+    private readonly _state: StateField<State>
+  ) {}
+
+  reconcile(view: EditorView, editor: boolean): void {
+    if (this._pending) {
+      return;
+    }
+
+    this._pending = true;
+    if (editor) {
+      this.onEditorChange(view);
+    } else {
+      this.onAutomergeChange(view);
+    }
+    this._pending = false;
+  }
+
+  private onEditorChange(view: EditorView): void {
+    log('onEditorChange');
+
+    // Apply the unreconciled transactions to the document.
+    const transactions = view.state.field(this._state).unreconciledTransactions.filter((tx) => !isReconcile(tx));
+    const newHeads = updateAutomerge(this._state, this._handle, transactions, view.state);
+
+    if (newHeads) {
+      view.dispatch({
+        effects: updateHeads(newHeads),
+        annotations: reconcileAnnotation.of(false),
+      });
+    }
+  }
+
+  private onAutomergeChange(view: EditorView): void {
+    log('onAutomergeChange');
+
+    // Get the diff between the updated state of the document and the heads and apply that to the codemirror doc.
+    const oldHeads = getLastHeads(view.state, this._state);
+    const newHeads = A.getHeads(this._handle.doc()!);
+    const diff = A.equals(oldHeads, newHeads) ? [] : A.diff(this._handle.doc()!, oldHeads, newHeads);
+
+    const selection = view.state.selection;
+    const path = getPath(view.state, this._state);
+    updateCodeMirror(view, selection, path, diff);
+
+    // TODO(burdon): Test conflicts?
+    // A.getConflicts(this._handle.doc()!, path[0]);
+
+    view.dispatch({
+      effects: updateHeads(newHeads),
+      annotations: reconcileAnnotation.of(false),
+    });
+  }
+}

package/src/extensions/automerge/update-automerge.ts

@@ -0,0 +1,50 @@
+//
+// Copyright 2023 DXOS.org
+// Copyright 2024 Automerge
+// Ref: https://github.com/automerge/automerge-codemirror
+//
+
+import { next as A, type Heads } from '@automerge/automerge';
+import { type EditorState, type StateField, type Text, type Transaction } from '@codemirror/state';
+
+import { type IDocHandle } from '@dxos/echo-db';
+
+import { type State } from './defs';
+
+export const updateAutomerge = (
+  field: StateField<State>,
+  handle: IDocHandle,
+  transactions: Transaction[],
+  state: EditorState, // TODO(burdon): Just pass in the state field value?
+): Heads | undefined => {
+  const { lastHeads, path } = state.field(field);
+
+  // We don't want to call `automerge.updateAt` if there are no changes.
+  // Otherwise, later on `automerge.diff` will return empty patches that result in a no-op but still mess up the selection.
+  let hasChanges = false;
+  for (const tr of transactions) {
+    tr.changes.iterChanges(() => {
+      hasChanges = true;
+    });
+  }
+
+  if (!hasChanges) {
+    return undefined;
+  }
+
+  const newHeads = handle.changeAt(lastHeads, (doc: A.Doc<unknown>) => {
+    const invertedTransactions: { from: number; del: number; insert: Text }[] = [];
+    for (const tr of transactions) {
+      tr.changes.iterChanges((fromA, toA, _fromB, _toB, insert) => {
+        invertedTransactions.push({ from: fromA, del: toA - fromA, insert });
+      });
+    }
+
+    // TODO(burdon): Hack to apply in reverse order to properly apply range.
+    invertedTransactions.reverse().forEach(({ from, del, insert }) => {
+      A.splice(doc, path.slice(), from, del, insert.toString());
+    });
+  });
+
+  return newHeads ?? undefined;
+};

package/src/extensions/automerge/update-codemirror.ts

@@ -0,0 +1,115 @@
+//
+// Copyright 2023 DXOS.org
+// Copyright 2024 Automerge
+// Ref: https://github.com/automerge/automerge-codemirror
+//
+
+import {
+  type DelPatch,
+  type InsertPatch,
+  type Patch,
+  type Prop,
+  type PutPatch,
+  type SpliceTextPatch,
+} from '@automerge/automerge';
+import { ChangeSet, type ChangeSpec, type EditorSelection, type EditorState } from '@codemirror/state';
+import { type EditorView } from '@codemirror/view';
+
+import { reconcileAnnotation } from './defs';
+
+export const updateCodeMirror = (view: EditorView, selection: EditorSelection, target: Prop[], patches: Patch[]) => {
+  for (const patch of patches) {
+    const changeSpec = handlePatch(patch, target, view.state);
+    if (changeSpec != null) {
+      const changeSet = ChangeSet.of(changeSpec, view.state.doc.length, '\n');
+      selection = selection.map(changeSet, 1);
+      view.dispatch({
+        changes: changeSet,
+        annotations: reconcileAnnotation.of(false),
+      });
+    }
+  }
+
+  view.dispatch({
+    selection,
+    annotations: reconcileAnnotation.of(false),
+  });
+};
+
+const handlePatch = (patch: Patch, target: Prop[], state: EditorState): ChangeSpec | null => {
+  if (patch.action === 'insert') {
+    return handleInsert(target, patch);
+  } else if (patch.action === 'splice') {
+    return handleSplice(target, patch);
+  } else if (patch.action === 'del') {
+    return handleDel(target, patch);
+  } else if (patch.action === 'put') {
+    return handlePut(target, patch, state);
+  } else {
+    return null;
+  }
+};
+
+const handleInsert = (target: Prop[], patch: InsertPatch): Array<ChangeSpec> => {
+  const index = charPath(target, patch.path);
+  if (index == null) {
+    return [];
+  }
+
+  const text = patch.values.map((value) => (value ? value.toString() : '')).join('');
+  return [{ from: index, to: index, insert: text }];
+};
+
+const handleSplice = (target: Prop[], patch: SpliceTextPatch): Array<ChangeSpec> => {
+  const index = charPath(target, patch.path);
+  if (index == null) {
+    return [];
+  }
+
+  return [{ from: index, insert: patch.value }];
+};
+
+const handleDel = (target: Prop[], patch: DelPatch): Array<ChangeSpec> => {
+  const index = charPath(target, patch.path);
+  if (index == null) {
+    return [];
+  }
+
+  const length = patch.length || 1;
+  return [{ from: index, to: index + length }];
+};
+
+const handlePut = (target: Prop[], patch: PutPatch, state: EditorState): Array<ChangeSpec> => {
+  const index = charPath(target, [...patch.path, 0]);
+  if (index == null) {
+    return [];
+  }
+
+  const length = state.doc.length;
+  if (typeof patch.value !== 'string') {
+    return []; // TODO(dmaretskyi): How to handle non-string values?
+  }
+
+  return [{ from: 0, to: length, insert: patch.value as any }];
+};
+
+// If the path of the patch is of the form [path, <index>] then we know this is a path to a character
+// within the sequence given by path.
+const charPath = (textPath: Prop[], candidatePath: Prop[]): number | null => {
+  if (candidatePath.length !== textPath.length + 1) {
+    return null;
+  }
+
+  for (let i = 0; i < textPath.length; i++) {
+    if (textPath[i] !== candidatePath[i]) {
+      return null;
+    }
+  }
+
+  const index = candidatePath[candidatePath.length - 1];
+  if (typeof index === 'number') {
+    return index;
+  }
+
+  return null;
+};

package/src/extensions/autoscroll.ts

@@ -0,0 +1,165 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { StateEffect } from '@codemirror/state';
+import { EditorView, ViewPlugin } from '@codemirror/view';
+
+import { debounce } from '@dxos/async';
+import { Domino } from '@dxos/ui';
+
+import { scrollToLineEffect } from './scrolling';
+
+// TODO(burdon): Reconcile with scrollToLineEffect (scrolling).
+export const scrollToBottomEffect = StateEffect.define<ScrollBehavior | undefined>();
+
+export type AutoScrollOptions = {
+  /** Auto-scroll when reaches the bottom. */
+  autoScroll?: boolean;
+  /** Threshold in px to trigger scroll from bottom. */
+  threshold?: number;
+  /** Throttle time in ms. */
+  throttleDelay?: number;
+  /** Callback when auto-scrolling. */
+  onAutoScroll?: (props: { view: EditorView; distanceFromBottom: number }) => boolean | void;
+};
+
+/**
+ * Extension that supports pinning the scroll position and automatically scrolls to the bottom when content is added.
+ */
+// TODO(burdon): Reconcile with transcript-extension.
+export const autoScroll = ({
+  autoScroll = true,
+  threshold = 100,
+  throttleDelay = 1_000,
+  onAutoScroll,
+}: Partial<AutoScrollOptions> = {}) => {
+  let buttonContainer: HTMLDivElement | undefined;
+  let hideTimeout: NodeJS.Timeout | undefined;
+  let lastScrollTop = 0;
+  let isPinned = true;
+
+  const setPinned = (pin: boolean) => {
+    isPinned = pin;
+    buttonContainer?.classList.toggle('opacity-0', pin);
+  };
+
+  // Temporarily hide the scrollbar while auto-scrolling.
+  const hideScrollbar = (view: EditorView) => {
+    view.scrollDOM.classList.add('cm-hide-scrollbar');
+    clearTimeout(hideTimeout);
+    hideTimeout = setTimeout(() => {
+      view.scrollDOM.classList.remove('cm-hide-scrollbar');
+    }, 1_000);
+  };
+
+  // Throttled scroll to bottom.
+  const scrollToBottom = (view: EditorView, behavior?: ScrollBehavior) => {
+    setPinned(true);
+    hideScrollbar(view);
+    const line = view.state.doc.lineAt(view.state.doc.length);
+    view.dispatch({
+      selection: { anchor: line.to, head: line.to },
+      effects: scrollToLineEffect.of({
+        line: line.number,
+        options: { position: 'end', offset: threshold, behavior },
+      }),
+    });
+  };
+
+  // Throttled check for distance from bottom (for downward scrolls only).
+  const checkDistance = debounce((view: EditorView) => {
+    const scrollerRect = view.scrollDOM.getBoundingClientRect();
+    const coords = view.coordsAtPos(view.state.doc.length);
+    const distanceFromBottom = coords ? coords.bottom - scrollerRect.bottom : 0;
+    setPinned(distanceFromBottom < 0);
+  }, 1_000);
+
+  // Debounce scroll updates so rapid edits don't cause clunky scrolling.
+  const triggerUpdate = debounce((view: EditorView) => scrollToBottom(view), throttleDelay);
+
+  return [
+    // Update listener for logging when scrolling is needed.
+    EditorView.updateListener.of(({ view, transactions, heightChanged }) => {
+      // TODO(burdon): Remove and use scrollToLineEffect instead.
+      transactions.forEach((transaction) => {
+        for (const effect of transaction.effects) {
+          if (effect.is(scrollToBottomEffect)) {
+            scrollToBottom(view, effect.value);
+          }
+        }
+      });
+
+      // Maybe scroll if doc changed and pinned.
+      // NOTE: Geometry changed is triggered when widgets change height (e.g., toggle tool block).
+      if (heightChanged && isPinned) {
+        const coords = view.coordsAtPos(view.state.doc.length);
+        const scrollerRect = view.scrollDOM.getBoundingClientRect();
+        const distanceFromBottom = coords ? scrollerRect.bottom - coords.bottom : 0;
+        if (autoScroll && distanceFromBottom < threshold) {
+          const shouldScroll = onAutoScroll?.({ view, distanceFromBottom }) ?? true;
+          if (shouldScroll) {
+            triggerUpdate(view);
+          }
+        } else if (distanceFromBottom < 0) {
+          setPinned(false);
+        }
+      }
+    }),
+
+    // Detect user scroll.
+    EditorView.domEventHandlers({
+      scroll: (event, view) => {
+        const currentScrollTop = view.scrollDOM.scrollTop;
+        const scrollingUp = currentScrollTop < lastScrollTop;
+        lastScrollTop = currentScrollTop;
+
+        // If user scrolls up, immediately unpin auto-scroll.
+        if (scrollingUp) {
+          setPinned(false);
+        } else {
+          checkDistance(view);
+        }
+      },
+    }),
+
+    // Scroll button.
+    ViewPlugin.fromClass(
+      class {
+        constructor(view: EditorView) {
+          const icon = Domino.of('dx-icon' as any).attributes({ icon: 'ph--arrow-down--regular' });
+          const button = Domino.of('button')
+            .classNames('dx-button bg-accentSurface')
+            .attributes({ 'data-density': 'fine' })
+            .children(icon)
+            .on('click', () => {
+              scrollToBottom(view);
+            });
+          buttonContainer = Domino.of('div')
+            .classNames('cm-scroll-button transition-opacity duration-300 opacity-0')
+            .children(button).root as HTMLDivElement;
+
+          view.scrollDOM.parentElement!.appendChild(buttonContainer);
+        }
+      },
+    ),
+
+    // Styles.
+    EditorView.theme({
+      '.cm-scroller': {
+        scrollbarWidth: 'thin',
+      },
+      '.cm-scroller.cm-hide-scrollbar': {
+        scrollbarWidth: 'none',
+      },
+      '.cm-scroller.cm-hide-scrollbar::-webkit-scrollbar': {
+        display: 'none',
+      },
+      '.cm-scroll-button': {
+        position: 'absolute',
+        bottom: '0.5rem',
+        right: '1rem',
+      },
+    }),
+  ];
+};