@getguru/slate-yjs-core 1.0.3

package/src/applyToYjs/types.ts

@@ -0,0 +1,12 @@
+import { Node, Operation } from 'slate';
+import * as Y from 'yjs';
+
+export type ApplyFunc<O extends Operation = Operation> = (
+  sharedRoot: Y.XmlText,
+  slateRoot: Node,
+  op: O
+) => void;
+
+export type OpMapper<O extends Operation = Operation> = {
+  [K in O['type']]: O extends { type: K } ? ApplyFunc<O> : never;
+};

package/src/index.ts

@@ -0,0 +1,47 @@
+import { RelativeRange } from './model/types';
+import {
+  CursorEditor,
+  CursorState,
+  CursorStateChangeEvent,
+  RemoteCursorChangeEventListener,
+  withCursors,
+  WithCursorsOptions,
+  withYHistory,
+  WithYHistoryOptions,
+  withYjs,
+  WithYjsOptions,
+  YHistoryEditor,
+  YjsEditor,
+} from './plugins';
+import { slateNodesToInsertDelta, yTextToSlateElement } from './utils/convert';
+import {
+  relativePositionToSlatePoint,
+  relativeRangeToSlateRange,
+  slatePointToRelativePosition,
+  slateRangeToRelativeRange,
+} from './utils/position';
+
+export {
+  withYjs,
+  WithYjsOptions,
+  YjsEditor,
+  // History plugin
+  withYHistory,
+  WithYHistoryOptions,
+  YHistoryEditor,
+  // Base cursor plugin
+  CursorEditor,
+  WithCursorsOptions,
+  withCursors,
+  CursorState,
+  RemoteCursorChangeEventListener,
+  CursorStateChangeEvent,
+  // Utils
+  RelativeRange,
+  yTextToSlateElement,
+  slateNodesToInsertDelta,
+  slateRangeToRelativeRange,
+  relativeRangeToSlateRange,
+  slatePointToRelativePosition,
+  relativePositionToSlatePoint,
+};

package/src/model/types.ts

@@ -0,0 +1,50 @@
+import type { Editor, Element, Node } from 'slate';
+import type Y from 'yjs';
+
+export type DeltaAttributes = {
+  retain: number;
+  attributes: Record<string, unknown>;
+};
+export type DeltaRetain = { retain: number };
+export type DeltaDelete = { delete: number };
+export type DeltaInsert = {
+  insert: string | Y.XmlText;
+  attributes?: Record<string, unknown>;
+};
+
+export type InsertDelta = Array<DeltaInsert>;
+export type Delta = Array<
+  DeltaRetain | DeltaDelete | DeltaInsert | DeltaAttributes
+>;
+
+export type TextRange = { start: number; end: number };
+
+export type HistoryStackItem = {
+  meta: Map<string, unknown>;
+};
+
+export type YTarget = {
+  // TextRange in the yParent mapping to the slateTarget (or position to insert)
+  textRange: TextRange;
+
+  // Y.XmlText containing the slate node
+  yParent: Y.XmlText;
+
+  // Slate element mapping to the yParent
+  slateParent: Element | Editor;
+
+  // If the target points to a slate element, Y.XmlText representing the target.
+  // If it points to a text (or position to insert), this will be undefined.
+  yTarget?: Y.XmlText;
+
+  // Slate node represented by the textRange, won't be set if position is insert.
+  slateTarget?: Node;
+
+  // InsertDelta representing the slateTarget
+  targetDelta: InsertDelta;
+};
+
+export type RelativeRange = {
+  anchor: Y.RelativePosition;
+  focus: Y.RelativePosition;
+};

package/src/plugins/index.ts

@@ -0,0 +1,3 @@
+export * from './withYjs';
+export * from './withYHistory';
+export * from './withCursors';

package/src/plugins/withCursors.ts

@@ -0,0 +1,269 @@
+import { Editor, Range } from 'slate';
+import { Awareness } from 'y-protocols/awareness';
+import * as Y from 'yjs';
+import { RelativeRange } from '../model/types';
+import { slateRangeToRelativeRange } from '../utils/position';
+import { YjsEditor } from './withYjs';
+
+export type CursorStateChangeEvent = {
+  added: number[];
+  updated: number[];
+  removed: number[];
+};
+
+export type RemoteCursorChangeEventListener = (
+  event: CursorStateChangeEvent
+) => void;
+
+const CURSOR_CHANGE_EVENT_LISTENERS: WeakMap<
+  Editor,
+  Set<RemoteCursorChangeEventListener>
+> = new WeakMap();
+
+export type CursorState<
+  TCursorData extends Record<string, unknown> = Record<string, unknown>
+> = {
+  relativeSelection: RelativeRange | null;
+  data?: TCursorData;
+  clientId: number;
+};
+
+export type CursorEditor<
+  TCursorData extends Record<string, unknown> = Record<string, unknown>
+> = YjsEditor & {
+  awareness: Awareness;
+
+  cursorDataField: string;
+  selectionStateField: string;
+
+  sendCursorPosition: (range: Range | null) => void;
+  sendCursorData: (data: TCursorData) => void;
+};
+
+export const CursorEditor = {
+  isCursorEditor(value: unknown): value is CursorEditor {
+    return (
+      YjsEditor.isYjsEditor(value) &&
+      (value as CursorEditor).awareness &&
+      typeof (value as CursorEditor).cursorDataField === 'string' &&
+      typeof (value as CursorEditor).selectionStateField === 'string' &&
+      typeof (value as CursorEditor).sendCursorPosition === 'function' &&
+      typeof (value as CursorEditor).sendCursorData === 'function'
+    );
+  },
+
+  sendCursorPosition<TCursorData extends Record<string, unknown>>(
+    editor: CursorEditor<TCursorData>,
+    range: Range | null = editor.selection
+  ) {
+    editor.sendCursorPosition(range);
+  },
+
+  sendCursorData<TCursorData extends Record<string, unknown>>(
+    editor: CursorEditor<TCursorData>,
+    data: TCursorData
+  ) {
+    editor.sendCursorData(data);
+  },
+
+  on<TCursorData extends Record<string, unknown>>(
+    editor: CursorEditor<TCursorData>,
+    event: 'change',
+    handler: RemoteCursorChangeEventListener
+  ) {
+    if (event !== 'change') {
+      return;
+    }
+
+    const listeners = CURSOR_CHANGE_EVENT_LISTENERS.get(editor) ?? new Set();
+    listeners.add(handler);
+    CURSOR_CHANGE_EVENT_LISTENERS.set(editor, listeners);
+  },
+
+  off<TCursorData extends Record<string, unknown>>(
+    editor: CursorEditor<TCursorData>,
+    event: 'change',
+    listener: RemoteCursorChangeEventListener
+  ) {
+    if (event !== 'change') {
+      return;
+    }
+
+    const listeners = CURSOR_CHANGE_EVENT_LISTENERS.get(editor);
+    if (listeners) {
+      listeners.delete(listener);
+    }
+  },
+
+  cursorState<TCursorData extends Record<string, unknown>>(
+    editor: CursorEditor<TCursorData>,
+    clientId: number
+  ): CursorState<TCursorData> | null {
+    if (
+      clientId === editor.awareness.clientID ||
+      !YjsEditor.connected(editor)
+    ) {
+      return null;
+    }
+
+    const state = editor.awareness.getStates().get(clientId);
+    if (!state) {
+      return null;
+    }
+
+    return {
+      relativeSelection: state[editor.selectionStateField] ?? null,
+      data: state[editor.cursorDataField],
+      clientId,
+    };
+  },
+
+  cursorStates<TCursorData extends Record<string, unknown>>(
+    editor: CursorEditor<TCursorData>
+  ): Record<string, CursorState<TCursorData>> {
+    if (!YjsEditor.connected(editor)) {
+      return {};
+    }
+
+    return Object.fromEntries(
+      Array.from(editor.awareness.getStates().entries(), ([id, state]) => {
+        // Ignore own state
+        if (id === editor.awareness.clientID || !state) {
+          return null;
+        }
+
+        return [
+          id,
+          {
+            relativeSelection: state[editor.selectionStateField],
+            data: state[editor.cursorDataField],
+          },
+        ];
+      }).filter(Array.isArray)
+    );
+  },
+};
+
+export type WithCursorsOptions<
+  TCursorData extends Record<string, unknown> = Record<string, unknown>
+> = {
+  // Local state field used to store the user selection
+  cursorStateField?: string;
+
+  // Local state field used to store data attached to the local client
+  cursorDataField?: string;
+
+  data?: TCursorData;
+  autoSend?: boolean;
+};
+
+export function withCursors<
+  TCursorData extends Record<string, unknown>,
+  TEditor extends YjsEditor
+>(
+  editor: TEditor,
+  awareness: Awareness,
+  {
+    cursorStateField: selectionStateField = 'selection',
+    cursorDataField = 'data',
+    autoSend = true,
+    data,
+  }: WithCursorsOptions<TCursorData> = {}
+): TEditor & CursorEditor<TCursorData> {
+  const e = editor as TEditor & CursorEditor<TCursorData>;
+
+  e.awareness = awareness;
+  e.cursorDataField = cursorDataField;
+  e.selectionStateField = selectionStateField;
+
+  e.sendCursorData = (cursorData: TCursorData) => {
+    e.awareness.setLocalStateField(e.cursorDataField, cursorData);
+  };
+
+  e.sendCursorPosition = (range) => {
+    const localState = e.awareness.getLocalState();
+    const currentRange = localState?.[selectionStateField];
+
+    if (!range) {
+      if (currentRange) {
+        e.awareness.setLocalStateField(e.selectionStateField, null);
+      }
+
+      return;
+    }
+
+    const { anchor, focus } = slateRangeToRelativeRange(e.sharedRoot, e, range);
+
+    if (
+      !currentRange ||
+      !Y.compareRelativePositions(anchor, currentRange) ||
+      !Y.compareRelativePositions(focus, currentRange)
+    ) {
+      e.awareness.setLocalStateField(e.selectionStateField, { anchor, focus });
+    }
+  };
+
+  const awarenessChangeListener: RemoteCursorChangeEventListener = (yEvent) => {
+    const listeners = CURSOR_CHANGE_EVENT_LISTENERS.get(e);
+    if (!listeners) {
+      return;
+    }
+
+    const localId = e.awareness.clientID;
+    const event = {
+      added: yEvent.added.filter((id) => id !== localId),
+      removed: yEvent.removed.filter((id) => id !== localId),
+      updated: yEvent.updated.filter((id) => id !== localId),
+    };
+
+    if (
+      event.added.length > 0 ||
+      event.removed.length > 0 ||
+      event.updated.length > 0
+    ) {
+      listeners.forEach((listener) => listener(event));
+    }
+  };
+
+  const { connect, disconnect } = e;
+  e.connect = () => {
+    connect();
+
+    e.awareness.on('change', awarenessChangeListener);
+
+    awarenessChangeListener({
+      removed: [],
+      added: Array.from(e.awareness.getStates().keys()),
+      updated: [],
+    });
+
+    if (autoSend) {
+      if (data) {
+        CursorEditor.sendCursorData(e, data);
+      }
+
+      const { onChange } = e;
+      e.onChange = () => {
+        onChange();
+
+        if (YjsEditor.connected(e)) {
+          CursorEditor.sendCursorPosition(e);
+        }
+      };
+    }
+  };
+
+  e.disconnect = () => {
+    e.awareness.off('change', awarenessChangeListener);
+
+    awarenessChangeListener({
+      removed: Array.from(e.awareness.getStates().keys()),
+      added: [],
+      updated: [],
+    });
+
+    disconnect();
+  };
+
+  return e;
+}

package/src/plugins/withYHistory.ts

@@ -0,0 +1,183 @@
+import { Editor, Transforms } from 'slate';
+import * as Y from 'yjs';
+import { HistoryStackItem, RelativeRange } from '../model/types';
+import {
+  relativeRangeToSlateRange,
+  slateRangeToRelativeRange,
+} from '../utils/position';
+import { YjsEditor } from './withYjs';
+
+const LAST_SELECTION: WeakMap<Editor, RelativeRange | null> = new WeakMap();
+const DEFAULT_WITHOUT_SAVING_ORIGIN = Symbol(
+  'slate-yjs-history-without-saving'
+);
+
+export type YHistoryEditor = YjsEditor & {
+  undoManager: Y.UndoManager;
+
+  withoutSavingOrigin: unknown;
+
+  undo: () => void;
+  redo: () => void;
+};
+
+export const YHistoryEditor = {
+  isYHistoryEditor(value: unknown): value is YHistoryEditor {
+    return (
+      YjsEditor.isYjsEditor(value) &&
+      (value as YHistoryEditor).undoManager instanceof Y.UndoManager &&
+      typeof (value as YHistoryEditor).undo === 'function' &&
+      typeof (value as YHistoryEditor).redo === 'function' &&
+      'withoutSavingOrigin' in value
+    );
+  },
+
+  canUndo(editor: YHistoryEditor) {
+    return editor.undoManager.undoStack.length > 0;
+  },
+
+  canRedo(editor: YHistoryEditor) {
+    return editor.undoManager.redoStack.length > 0;
+  },
+
+  isSaving(editor: YHistoryEditor): boolean {
+    return editor.undoManager.trackedOrigins.has(YjsEditor.origin(editor));
+  },
+
+  withoutSaving(editor: YHistoryEditor, fn: () => void) {
+    YjsEditor.withOrigin(editor, editor.withoutSavingOrigin, fn);
+  },
+};
+
+export type WithYHistoryOptions = NonNullable<
+  ConstructorParameters<typeof Y.UndoManager>[1]
+> & {
+  withoutSavingOrigin?: unknown;
+};
+
+export function withYHistory<T extends YjsEditor>(
+  editor: T,
+  {
+    withoutSavingOrigin = DEFAULT_WITHOUT_SAVING_ORIGIN,
+    trackedOrigins = new Set([editor.localOrigin]),
+    ...options
+  }: WithYHistoryOptions = {}
+): T & YHistoryEditor {
+  const e = editor as T & YHistoryEditor;
+
+  const undoManager = new Y.UndoManager(e.sharedRoot, {
+    trackedOrigins,
+    ...options,
+  });
+
+  e.undoManager = undoManager;
+  e.withoutSavingOrigin = withoutSavingOrigin;
+
+  const { onChange, isLocalOrigin } = e;
+  e.onChange = () => {
+    onChange();
+
+    LAST_SELECTION.set(
+      e,
+      e.selection && slateRangeToRelativeRange(e.sharedRoot, e, e.selection)
+    );
+  };
+
+  e.isLocalOrigin = (origin) =>
+    origin === e.withoutSavingOrigin || isLocalOrigin(origin);
+
+  const handleStackItemAdded = ({
+    stackItem,
+  }: {
+    stackItem: HistoryStackItem;
+    type: 'redo' | 'undo';
+  }) => {
+    stackItem.meta.set(
+      'selection',
+      e.selection && slateRangeToRelativeRange(e.sharedRoot, e, e.selection)
+    );
+    stackItem.meta.set('selectionBefore', LAST_SELECTION.get(e));
+  };
+
+  const handleStackItemUpdated = ({
+    stackItem,
+  }: {
+    stackItem: HistoryStackItem;
+    type: 'redo' | 'undo';
+  }) => {
+    stackItem.meta.set(
+      'selection',
+      e.selection && slateRangeToRelativeRange(e.sharedRoot, e, e.selection)
+    );
+  };
+
+  const handleStackItemPopped = ({
+    stackItem,
+    type,
+  }: {
+    stackItem: HistoryStackItem;
+    type: 'redo' | 'undo';
+  }) => {
+    // TODO: Change once https://github.com/yjs/yjs/issues/353 is resolved
+    const inverseStack =
+      type === 'undo' ? e.undoManager.redoStack : e.undoManager.undoStack;
+    const inverseItem = inverseStack[inverseStack.length - 1];
+    if (inverseItem) {
+      inverseItem.meta.set('selection', stackItem.meta.get('selectionBefore'));
+      inverseItem.meta.set('selectionBefore', stackItem.meta.get('selection'));
+    }
+
+    const relativeSelection = stackItem.meta.get(
+      'selectionBefore'
+    ) as RelativeRange | null;
+
+    if (!relativeSelection) {
+      return;
+    }
+
+    const selection = relativeRangeToSlateRange(
+      e.sharedRoot,
+      e,
+      relativeSelection
+    );
+
+    if (!selection) {
+      return;
+    }
+
+    Transforms.select(e, selection);
+  };
+
+  const { connect, disconnect } = e;
+  e.connect = () => {
+    connect();
+
+    e.undoManager.on('stack-item-added', handleStackItemAdded);
+    e.undoManager.on('stack-item-popped', handleStackItemPopped);
+    e.undoManager.on('stack-item-updated', handleStackItemUpdated);
+  };
+
+  e.disconnect = () => {
+    e.undoManager.off('stack-item-added', handleStackItemAdded);
+    e.undoManager.off('stack-item-popped', handleStackItemPopped);
+    e.undoManager.off('stack-item-updated', handleStackItemUpdated);
+
+    disconnect();
+  };
+
+  e.undo = () => {
+    if (YjsEditor.connected(e)) {
+      YjsEditor.flushLocalChanges(e);
+      e.undoManager.undo();
+    }
+  };
+
+  e.redo = () => {
+    if (YjsEditor.connected(e)) {
+      YjsEditor.flushLocalChanges(e);
+      e.undoManager.redo();
+    }
+  };
+
+  return e;
+}