@getguru/slate-yjs-core 1.0.3

package/src/plugins/withYjs.ts

@@ -0,0 +1,284 @@
+import { BaseEditor, Descendant, Editor, Operation, Point } from 'slate';
+import * as Y from 'yjs';
+import { applyYjsEvents } from '../applyToSlate';
+import { applySlateOp } from '../applyToYjs';
+import { yTextToSlateElement } from '../utils/convert';
+import {
+  getStoredPosition,
+  getStoredPositions,
+  relativePositionToSlatePoint,
+  removeStoredPosition,
+  setStoredPosition,
+  slatePointToRelativePosition,
+} from '../utils/position';
+import { assertDocumentAttachment } from '../utils/yjs';
+
+type LocalChange = {
+  op: Operation;
+  doc: Descendant[];
+  origin: unknown;
+};
+
+const DEFAULT_LOCAL_ORIGIN = Symbol('slate-yjs-operation');
+const DEFAULT_POSITION_STORAGE_ORIGIN = Symbol('slate-yjs-position-storage');
+
+const ORIGIN: WeakMap<Editor, unknown> = new WeakMap();
+const LOCAL_CHANGES: WeakMap<Editor, LocalChange[]> = new WeakMap();
+const CONNECTED: WeakSet<Editor> = new WeakSet();
+
+export type YjsEditor = BaseEditor & {
+  sharedRoot: Y.XmlText;
+
+  localOrigin: unknown;
+  positionStorageOrigin: unknown;
+
+  applyRemoteEvents: (events: Y.YEvent<Y.XmlText>[], origin: unknown) => void;
+
+  storeLocalChange: (op: Operation) => void;
+  flushLocalChanges: () => void;
+
+  isLocalOrigin: (origin: unknown) => boolean;
+
+  connect: () => void;
+  disconnect: () => void;
+};
+
+export const YjsEditor = {
+  isYjsEditor(value: unknown): value is YjsEditor {
+    return (
+      Editor.isEditor(value) &&
+      (value as YjsEditor).sharedRoot instanceof Y.XmlText &&
+      'localOrigin' in value &&
+      'positionStorageOrigin' in value &&
+      typeof (value as YjsEditor).applyRemoteEvents === 'function' &&
+      typeof (value as YjsEditor).storeLocalChange === 'function' &&
+      typeof (value as YjsEditor).flushLocalChanges === 'function' &&
+      typeof (value as YjsEditor).isLocalOrigin === 'function' &&
+      typeof (value as YjsEditor).connect === 'function' &&
+      typeof (value as YjsEditor).disconnect === 'function'
+    );
+  },
+
+  localChanges(editor: YjsEditor): LocalChange[] {
+    return LOCAL_CHANGES.get(editor) ?? [];
+  },
+
+  applyRemoteEvents(
+    editor: YjsEditor,
+    events: Y.YEvent<Y.XmlText>[],
+    origin: unknown
+  ): void {
+    editor.applyRemoteEvents(events, origin);
+  },
+
+  storeLocalChange(editor: YjsEditor, op: Operation): void {
+    editor.storeLocalChange(op);
+  },
+
+  flushLocalChanges(editor: YjsEditor): void {
+    editor.flushLocalChanges();
+  },
+
+  connected(editor: YjsEditor): boolean {
+    return CONNECTED.has(editor);
+  },
+
+  connect(editor: YjsEditor): void {
+    editor.connect();
+  },
+
+  disconnect(editor: YjsEditor): void {
+    editor.disconnect();
+  },
+
+  isLocal(editor: YjsEditor): boolean {
+    return editor.isLocalOrigin(YjsEditor.origin(editor));
+  },
+
+  origin(editor: YjsEditor): unknown {
+    const origin = ORIGIN.get(editor);
+    return origin !== undefined ? origin : editor.localOrigin;
+  },
+
+  withOrigin(editor: YjsEditor, origin: unknown, fn: () => void): void {
+    const prev = YjsEditor.origin(editor);
+    ORIGIN.set(editor, origin);
+    fn();
+    ORIGIN.set(editor, prev);
+  },
+
+  storePosition(editor: YjsEditor, key: string, point: Point): void {
+    const { sharedRoot, positionStorageOrigin: locationStorageOrigin } = editor;
+    assertDocumentAttachment(sharedRoot);
+
+    const position = slatePointToRelativePosition(sharedRoot, editor, point);
+
+    sharedRoot.doc.transact(() => {
+      setStoredPosition(sharedRoot, key, position);
+    }, locationStorageOrigin);
+  },
+
+  removeStoredPosition(editor: YjsEditor, key: string): void {
+    const { sharedRoot, positionStorageOrigin: locationStorageOrigin } = editor;
+    assertDocumentAttachment(sharedRoot);
+
+    sharedRoot.doc.transact(() => {
+      removeStoredPosition(sharedRoot, key);
+    }, locationStorageOrigin);
+  },
+
+  position(editor: YjsEditor, key: string): Point | null | undefined {
+    const position = getStoredPosition(editor.sharedRoot, key);
+    if (!position) {
+      return undefined;
+    }
+
+    return relativePositionToSlatePoint(editor.sharedRoot, editor, position);
+  },
+
+  storedPositionsRelative(
+    editor: YjsEditor
+  ): Record<string, Y.RelativePosition> {
+    return getStoredPositions(editor.sharedRoot);
+  },
+};
+
+export type WithYjsOptions = {
+  autoConnect?: boolean;
+
+  // Origin used when applying local slate operations to yjs
+  localOrigin?: unknown;
+
+  // Origin used when storing positions
+  positionStorageOrigin?: unknown;
+};
+
+export function withYjs<T extends Editor>(
+  editor: T,
+  sharedRoot: Y.XmlText,
+  {
+    localOrigin,
+    positionStorageOrigin,
+    autoConnect = false,
+  }: WithYjsOptions = {}
+): T & YjsEditor {
+  const e = editor as T & YjsEditor;
+
+  e.sharedRoot = sharedRoot;
+
+  e.localOrigin = localOrigin ?? DEFAULT_LOCAL_ORIGIN;
+  e.positionStorageOrigin =
+    positionStorageOrigin ?? DEFAULT_POSITION_STORAGE_ORIGIN;
+
+  e.applyRemoteEvents = (events, origin) => {
+    YjsEditor.flushLocalChanges(e);
+
+    Editor.withoutNormalizing(e, () => {
+      YjsEditor.withOrigin(e, origin, () => {
+        applyYjsEvents(e.sharedRoot, e, events);
+      });
+    });
+  };
+
+  e.isLocalOrigin = (origin) => origin === e.localOrigin;
+
+  const handleYEvents = (
+    events: Y.YEvent<Y.XmlText>[],
+    transaction: Y.Transaction
+  ) => {
+    if (e.isLocalOrigin(transaction.origin)) {
+      return;
+    }
+
+    YjsEditor.applyRemoteEvents(e, events, transaction.origin);
+  };
+
+  let autoConnectTimeoutId: ReturnType<typeof setTimeout> | null = null;
+  if (autoConnect) {
+    autoConnectTimeoutId = setTimeout(() => {
+      autoConnectTimeoutId = null;
+      YjsEditor.connect(e);
+    });
+  }
+
+  e.connect = () => {
+    if (YjsEditor.connected(e)) {
+      throw new Error('already connected');
+    }
+
+    e.sharedRoot.observeDeep(handleYEvents);
+    const content = yTextToSlateElement(e.sharedRoot);
+    e.children = content.children;
+    CONNECTED.add(e);
+
+    Editor.normalize(editor, { force: true });
+    if (!editor.operations.length) {
+      editor.onChange();
+    }
+  };
+
+  e.disconnect = () => {
+    if (autoConnectTimeoutId) {
+      clearTimeout(autoConnectTimeoutId);
+    }
+
+    YjsEditor.flushLocalChanges(e);
+    e.sharedRoot.unobserveDeep(handleYEvents);
+    CONNECTED.delete(e);
+  };
+
+  e.storeLocalChange = (op) => {
+    LOCAL_CHANGES.set(e, [
+      ...YjsEditor.localChanges(e),
+      { op, doc: editor.children, origin: YjsEditor.origin(e) },
+    ]);
+  };
+
+  e.flushLocalChanges = () => {
+    assertDocumentAttachment(e.sharedRoot);
+    const localChanges = YjsEditor.localChanges(e);
+    LOCAL_CHANGES.delete(e);
+
+    // Group local changes by origin so we can apply them in the correct order
+    // with the correct origin with a minimal amount of transactions.
+    const txGroups: LocalChange[][] = [];
+    localChanges.forEach((change) => {
+      const currentGroup = txGroups[txGroups.length - 1];
+      if (currentGroup && currentGroup[0].origin === change.origin) {
+        return currentGroup.push(change);
+      }
+
+      txGroups.push([change]);
+    });
+
+    txGroups.forEach((txGroup) => {
+      assertDocumentAttachment(e.sharedRoot);
+
+      e.sharedRoot.doc.transact(() => {
+        txGroup.forEach((change) => {
+          assertDocumentAttachment(e.sharedRoot);
+          applySlateOp(e.sharedRoot, { children: change.doc }, change.op);
+        });
+      }, txGroup[0].origin);
+    });
+  };
+
+  const { apply, onChange } = e;
+  e.apply = (op) => {
+    if (YjsEditor.connected(e) && YjsEditor.isLocal(e)) {
+      YjsEditor.storeLocalChange(e, op);
+    }
+
+    apply(op);
+  };
+
+  e.onChange = () => {
+    if (YjsEditor.connected(e)) {
+      YjsEditor.flushLocalChanges(e);
+    }
+
+    onChange();
+  };
+
+  return e;
+}

package/src/utils/clone.ts

@@ -0,0 +1,29 @@
+import * as Y from 'yjs';
+import { InsertDelta } from '../model/types';
+import { yTextToInsertDelta } from './delta';
+
+export function cloneInsertDeltaDeep(delta: InsertDelta): InsertDelta {
+  return delta.map((element) => {
+    if (typeof element.insert === 'string') {
+      return element;
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-use-before-define
+    return { ...element, insert: cloneDeep(element.insert) };
+  });
+}
+
+export function cloneDeep(yText: Y.XmlText): Y.XmlText {
+  const clone = new Y.XmlText();
+
+  const attributes = yText.getAttributes();
+  Object.entries(attributes).forEach(([key, value]) => {
+    clone.setAttribute(key, value);
+  });
+
+  clone.applyDelta(cloneInsertDeltaDeep(yTextToInsertDelta(yText)), {
+    sanitize: false,
+  });
+
+  return clone;
+}

package/src/utils/convert.ts

@@ -0,0 +1,48 @@
+import { Element, Node, Text } from 'slate';
+import * as Y from 'yjs';
+import { DeltaInsert, InsertDelta } from '../model/types';
+import { yTextToInsertDelta } from './delta';
+import { getProperties } from './slate';
+
+export function yTextToSlateElement(yText: Y.XmlText): Element {
+  const delta = yTextToInsertDelta(yText);
+
+  const children =
+    // eslint-disable-next-line @typescript-eslint/no-use-before-define
+    delta.length > 0 ? delta.map(deltaInsertToSlateNode) : [{ text: '' }];
+
+  return { ...yText.getAttributes(), children };
+}
+
+export function deltaInsertToSlateNode(insert: DeltaInsert): Node {
+  if (typeof insert.insert === 'string') {
+    return { ...insert.attributes, text: insert.insert };
+  }
+
+  return yTextToSlateElement(insert.insert);
+}
+
+export function slateNodesToInsertDelta(nodes: Node[]): InsertDelta {
+  return nodes.map((node) => {
+    if (Text.isText(node)) {
+      return { insert: node.text, attributes: getProperties(node) };
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-use-before-define
+    return { insert: slateElementToYText(node) };
+  });
+}
+
+export function slateElementToYText({
+  children,
+  ...attributes
+}: Element): Y.XmlText {
+  const yElement = new Y.XmlText();
+
+  Object.entries(attributes).forEach(([key, value]) => {
+    yElement.setAttribute(key, value);
+  });
+
+  yElement.applyDelta(slateNodesToInsertDelta(children), { sanitize: false });
+  return yElement;
+}

package/src/utils/delta.ts

@@ -0,0 +1,97 @@
+import * as Y from 'yjs';
+import { DeltaInsert, InsertDelta } from '../model/types';
+import { deepEquals } from './object';
+
+export function normalizeInsertDelta(delta: InsertDelta): InsertDelta {
+  const normalized: InsertDelta = [];
+
+  for (const element of delta) {
+    if (typeof element.insert === 'string' && element.insert.length === 0) {
+      continue;
+    }
+
+    const prev = normalized[normalized.length - 1];
+    if (
+      !prev ||
+      typeof prev.insert !== 'string' ||
+      typeof element.insert !== 'string'
+    ) {
+      normalized.push(element);
+      continue;
+    }
+
+    const merge =
+      prev.attributes === element.attributes ||
+      (!prev.attributes === !element.attributes &&
+        deepEquals(prev.attributes ?? {}, element.attributes ?? {}));
+
+    if (merge) {
+      prev.insert += element.insert;
+      continue;
+    }
+
+    normalized.push(element);
+  }
+
+  return normalized;
+}
+
+export function yTextToInsertDelta(yText: Y.XmlText): InsertDelta {
+  return normalizeInsertDelta(yText.toDelta());
+}
+
+export function getInsertLength({ insert }: DeltaInsert): number {
+  return typeof insert === 'string' ? insert.length : 1;
+}
+
+export function getInsertDeltaLength(delta: InsertDelta): number {
+  return delta.reduce((curr, element) => curr + getInsertLength(element), 0);
+}
+
+export function sliceInsertDelta(
+  delta: InsertDelta,
+  start: number,
+  length: number
+): InsertDelta {
+  if (length < 1) {
+    return [];
+  }
+
+  let currentOffset = 0;
+  const sliced: InsertDelta = [];
+  const end = start + length;
+
+  for (let i = 0; i < delta.length; i++) {
+    if (currentOffset >= end) {
+      break;
+    }
+
+    const element = delta[i];
+    const elementLength = getInsertLength(element);
+
+    if (currentOffset + elementLength <= start) {
+      currentOffset += elementLength;
+      continue;
+    }
+
+    if (typeof element.insert !== 'string') {
+      currentOffset += elementLength;
+      sliced.push(element);
+      continue;
+    }
+
+    const startOffset = Math.max(0, start - currentOffset);
+    const endOffset = Math.min(
+      elementLength,
+      elementLength - (currentOffset + elementLength - end)
+    );
+
+    sliced.push({
+      ...element,
+      insert: element.insert.slice(startOffset, endOffset),
+    });
+    currentOffset += elementLength;
+  }
+
+  return sliced;
+}

package/src/utils/errors.ts

@@ -0,0 +1,20 @@
+const SYNC_SKEW_ERROR_PATTERNS = [
+  'Cannot find a descendant at path',
+  'yOffset out of bounds',
+  'Cannot descent into slate text',
+  "yText isn't a descendant of root element",
+  "Path doesn't match yText",
+  'Unexpected y parent type',
+  'Path has to a have a length >= 1',
+  'yTarget spans multiple nodes',
+];
+
+export function isSyncSkewError(error: unknown): boolean {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+
+  return SYNC_SKEW_ERROR_PATTERNS.some((pattern) =>
+    error.message.includes(pattern)
+  );
+}

package/src/utils/location.ts

@@ -0,0 +1,157 @@
+import { Element, Node, Path, Text } from 'slate';
+import * as Y from 'yjs';
+import { YTarget } from '../model/types';
+import { sliceInsertDelta, yTextToInsertDelta } from './delta';
+
+export function getSlateNodeYLength(node: Node | undefined): number {
+  if (!node) {
+    return 0;
+  }
+
+  return Text.isText(node) ? node.text.length : 1;
+}
+
+export function slatePathOffsetToYOffset(element: Element, pathOffset: number) {
+  return element.children
+    .slice(0, pathOffset)
+    .reduce((yOffset, node) => yOffset + getSlateNodeYLength(node), 0);
+}
+
+export function getYTarget(
+  yRoot: Y.XmlText,
+  slateRoot: Node,
+  path: Path
+): YTarget {
+  if (path.length === 0) {
+    throw new Error('Path has to a have a length >= 1');
+  }
+
+  if (Text.isText(slateRoot)) {
+    throw new Error('Cannot descent into slate text');
+  }
+
+  const [pathOffset, ...childPath] = path;
+
+  const yOffset = slatePathOffsetToYOffset(slateRoot, pathOffset);
+  const targetNode = slateRoot.children[pathOffset];
+
+  const delta = yTextToInsertDelta(yRoot);
+  const targetLength = getSlateNodeYLength(targetNode);
+
+  const targetDelta = sliceInsertDelta(delta, yOffset, targetLength);
+  if (targetDelta.length > 1) {
+    throw new Error("Path doesn't match yText, yTarget spans multiple nodes");
+  }
+
+  const yTarget = targetDelta[0]?.insert;
+  if (childPath.length > 0) {
+    if (!(yTarget instanceof Y.XmlText)) {
+      throw new Error(
+        "Path doesn't match yText, cannot descent into non-yText"
+      );
+    }
+
+    return getYTarget(yTarget, targetNode, childPath);
+  }
+
+  return {
+    yParent: yRoot,
+    textRange: { start: yOffset, end: yOffset + targetLength },
+    yTarget: yTarget instanceof Y.XmlText ? yTarget : undefined,
+    slateParent: slateRoot,
+    slateTarget: targetNode,
+    targetDelta,
+  };
+}
+
+export function yOffsetToSlateOffsets(
+  parent: Element,
+  yOffset: number,
+  opts: { assoc?: number; insert?: boolean } = {}
+): [number, number] {
+  const { assoc = 0, insert = false } = opts;
+
+  let currentOffset = 0;
+  let lastNonEmptyPathOffset = 0;
+  for (let pathOffset = 0; pathOffset < parent.children.length; pathOffset++) {
+    const child = parent.children[pathOffset];
+    const nodeLength = Text.isText(child) ? child.text.length : 1;
+
+    if (nodeLength > 0) {
+      lastNonEmptyPathOffset = pathOffset;
+    }
+
+    const endOffset = currentOffset + nodeLength;
+    if (
+      nodeLength > 0 &&
+      (assoc >= 0 ? endOffset > yOffset : endOffset >= yOffset)
+    ) {
+      return [pathOffset, yOffset - currentOffset];
+    }
+
+    currentOffset += nodeLength;
+  }
+
+  if (yOffset > currentOffset + (insert ? 1 : 0)) {
+    throw new Error('yOffset out of bounds');
+  }
+
+  if (insert) {
+    return [parent.children.length, 0];
+  }
+
+  const child = parent.children[lastNonEmptyPathOffset];
+  const textOffset = Text.isText(child) ? child.text.length : 1;
+  return [lastNonEmptyPathOffset, textOffset];
+}
+
+export function getSlatePath(
+  sharedRoot: Y.XmlText,
+  slateRoot: Node,
+  yText: Y.XmlText
+): Path {
+  const yNodePath = [yText];
+  while (yNodePath[0] !== sharedRoot) {
+    const { parent: yParent } = yNodePath[0];
+
+    if (!yParent) {
+      throw new Error("yText isn't a descendant of root element");
+    }
+
+    if (!(yParent instanceof Y.XmlText)) {
+      throw new Error('Unexpected y parent type');
+    }
+
+    yNodePath.unshift(yParent);
+  }
+
+  if (yNodePath.length < 2) {
+    return [];
+  }
+
+  let slateParent = slateRoot;
+  return yNodePath.reduce<Path>((path, yParent, idx) => {
+    const yChild = yNodePath[idx + 1];
+    if (!yChild) {
+      return path;
+    }
+
+    let yOffset = 0;
+    const currentDelta = yTextToInsertDelta(yParent);
+    for (const element of currentDelta) {
+      if (element.insert === yChild) {
+        break;
+      }
+
+      yOffset += typeof element.insert === 'string' ? element.insert.length : 1;
+    }
+
+    if (Text.isText(slateParent)) {
+      throw new Error('Cannot descent into slate text');
+    }
+
+    const [pathOffset] = yOffsetToSlateOffsets(slateParent, yOffset);
+    slateParent = slateParent.children[pathOffset];
+    return path.concat(pathOffset);
+  }, []);
+}