@getguru/slate-yjs-react 1.1.1

package/src/hooks/useDecorateRemoteCursors.ts

@@ -0,0 +1,125 @@
+import { CursorState } from '@getguru/slate-yjs-core';
+import { useCallback, useRef } from 'react';
+import { BaseRange, BaseText, NodeEntry, Range } from 'slate';
+import { getCursorRange } from '../utils/getCursorRange';
+import { useRemoteCursorEditor } from './useRemoteCursorEditor';
+import { useRemoteCursorStates } from './useRemoteCursorStates';
+
+export const REMOTE_CURSOR_DECORATION_PREFIX = 'remote-cursor-';
+export const REMOTE_CURSOR_CARET_DECORATION_PREFIX = 'remote-caret-';
+
+export type RemoteCaretDecoration<
+  TCursorData extends Record<string, unknown> = Record<string, unknown>
+> = {
+  [
+    key: `${typeof REMOTE_CURSOR_CARET_DECORATION_PREFIX}${string}`
+  ]: CursorState<TCursorData> & { isBackward: boolean };
+};
+
+export type RemoteCursorDecoration<
+  TCursorData extends Record<string, unknown> = Record<string, unknown>
+> = {
+  [
+    key: `${typeof REMOTE_CURSOR_DECORATION_PREFIX}${string}`
+  ]: CursorState<TCursorData>;
+};
+
+export type RemoteCursorDecoratedRange<
+  TCursorData extends Record<string, unknown> = Record<string, unknown>
+> = BaseRange & RemoteCursorDecoration<TCursorData>;
+
+export type RemoteCaretDecoratedRange<
+  TCursorData extends Record<string, unknown> = Record<string, unknown>
+> = BaseRange & RemoteCaretDecoration<TCursorData>;
+
+export type TextWithRemoteCursors<
+  TCursorData extends Record<string, unknown> = Record<string, unknown>
+> = BaseText &
+  RemoteCursorDecoration<TCursorData> &
+  RemoteCaretDecoration<TCursorData>;
+
+export function getRemoteCursorsOnLeaf<
+  TCursorData extends Record<string, unknown>,
+  TLeaf extends TextWithRemoteCursors<TCursorData>
+>(leaf: TLeaf): CursorState<TCursorData>[] {
+  return Object.entries(leaf)
+    .filter(([key]) => key.startsWith(REMOTE_CURSOR_DECORATION_PREFIX))
+    .map(([, data]) => data);
+}
+
+export function getRemoteCaretsOnLeaf<
+  TCursorData extends Record<string, unknown>,
+  TLeaf extends TextWithRemoteCursors<TCursorData>
+>(leaf: TLeaf): (CursorState<TCursorData> & { isBackward: boolean })[] {
+  return Object.entries(leaf)
+    .filter(([key]) => key.startsWith(REMOTE_CURSOR_CARET_DECORATION_PREFIX))
+    .map(([, data]) => data);
+}
+
+export type UseDecorateRemoteCursorsOptions = {
+  carets?: boolean;
+};
+
+function getDecoration<
+  TCursorData extends Record<string, unknown>,
+  TCaret extends boolean
+>(
+  clientId: string,
+  state: CursorState<TCursorData>,
+  range: BaseRange,
+  caret: TCaret
+): TCaret extends true
+  ? RemoteCursorDecoratedRange<TCursorData>
+  : RemoteCaretDecoratedRange<TCursorData> {
+  if (!caret) {
+    const key = `${REMOTE_CURSOR_DECORATION_PREFIX}${clientId}`;
+    return { ...range, [key]: state };
+  }
+
+  const key = `${REMOTE_CURSOR_CARET_DECORATION_PREFIX}${clientId}`;
+  return {
+    ...range,
+    anchor: range.focus,
+    [key]: state,
+  };
+}
+
+export function useDecorateRemoteCursors<
+  TCursorData extends Record<string, unknown> = Record<string, unknown>
+>({ carets = true }: UseDecorateRemoteCursorsOptions = {}) {
+  const editor = useRemoteCursorEditor<TCursorData>();
+  const cursors = useRemoteCursorStates<TCursorData>();
+
+  const cursorsRef = useRef(cursors);
+  cursorsRef.current = cursors;
+
+  return useCallback(
+    (entry: NodeEntry) => {
+      const [, path] = entry;
+      if (path.length !== 0) {
+        return [];
+      }
+
+      return Object.entries(cursorsRef.current).flatMap(([clientId, state]) => {
+        const range = getCursorRange(editor, state);
+        if (!range) {
+          return [];
+        }
+
+        if (carets && Range.isCollapsed(range)) {
+          return getDecoration(clientId, state, range, true);
+        }
+
+        if (!carets) {
+          return getDecoration(clientId, state, range, false);
+        }
+
+        return [
+          getDecoration(clientId, state, range, false),
+          getDecoration(clientId, state, range, true),
+        ];
+      });
+    },
+    [carets, editor]
+  );
+}

package/src/hooks/useRemoteCursorEditor.ts

@@ -0,0 +1,15 @@
+import { CursorEditor } from '@getguru/slate-yjs-core';
+import { ReactEditor, useSlateStatic } from 'slate-react';
+
+export function useRemoteCursorEditor<
+  TCursorData extends Record<string, unknown> = Record<string, unknown>
+>(): CursorEditor<TCursorData> & ReactEditor {
+  const editor = useSlateStatic();
+  if (!CursorEditor.isCursorEditor(editor)) {
+    throw new Error(
+      'Cannot use useSyncExternalStore outside the context of a RemoteCursorEditor'
+    );
+  }
+
+  return editor as CursorEditor & ReactEditor;
+}

package/src/hooks/useRemoteCursorOverlayPositions.tsx

@@ -0,0 +1,144 @@
+import { CursorState } from '@getguru/slate-yjs-core';
+import {
+  RefObject,
+  useCallback,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import { BaseRange, NodeMatch, Text } from 'slate';
+import { getCursorRange } from '../utils/getCursorRange';
+import {
+  CaretPosition,
+  getOverlayPosition,
+  OverlayPosition,
+  SelectionRect,
+} from '../utils/getOverlayPosition';
+import { useRemoteCursorEditor } from './useRemoteCursorEditor';
+import { useRemoteCursorStates } from './useRemoteCursorStates';
+import { useOnResize, useRequestRerender } from './utils';
+
+const FROZEN_EMPTY_ARRAY = Object.freeze([]);
+
+export type UseRemoteCursorOverlayPositionsOptions<T extends HTMLElement> = {
+  shouldGenerateOverlay?: NodeMatch<Text>;
+} & (
+  | {
+      // Container the overlay will be rendered in. If set, all returned overlay positions
+      // will be relative to this container and the cursor positions will be automatically
+      // updated on container resize.
+      containerRef?: undefined;
+    }
+  | {
+      containerRef: RefObject<T>;
+
+      // Whether to refresh the cursor overlay positions on container resize. Defaults
+      // to true. If set to 'debounced', the remote cursor positions will be updated
+      // each animation frame.
+      refreshOnResize?: boolean | 'debounced';
+    }
+);
+
+export type CursorOverlayData<TCursorData extends Record<string, unknown>> =
+  CursorState<TCursorData> & {
+    range: BaseRange | null;
+    caretPosition: CaretPosition | null;
+    selectionRects: SelectionRect[];
+  };
+
+export function useRemoteCursorOverlayPositions<
+  TCursorData extends Record<string, unknown>,
+  TContainer extends HTMLElement = HTMLDivElement
+>({
+  containerRef,
+  shouldGenerateOverlay,
+  ...opts
+}: UseRemoteCursorOverlayPositionsOptions<TContainer> = {}) {
+  const editor = useRemoteCursorEditor<TCursorData>();
+  const cursorStates = useRemoteCursorStates<TCursorData>();
+  const requestRerender = useRequestRerender();
+
+  const overlayPositionCache = useRef(
+    new WeakMap<BaseRange, OverlayPosition>()
+  );
+  const [overlayPositions, setOverlayPositions] = useState<
+    Record<string, OverlayPosition>
+  >({});
+
+  const refreshOnResize =
+    'refreshOnResize' in opts ? opts.refreshOnResize ?? true : true;
+
+  useOnResize(refreshOnResize ? containerRef : undefined, () => {
+    overlayPositionCache.current = new WeakMap();
+    requestRerender(refreshOnResize !== 'debounced');
+  });
+
+  // Update selection rects after paint
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  useLayoutEffect(() => {
+    // We have a container ref but the ref is null => container
+    // isn't mounted to we can't calculate the selection rects.
+    if (containerRef && !containerRef.current) {
+      return;
+    }
+
+    const containerRect = containerRef?.current?.getBoundingClientRect();
+    const xOffset = containerRect?.x ?? 0;
+    const yOffset = containerRect?.y ?? 0;
+
+    let overlayPositionsChanged =
+      Object.keys(overlayPositions).length !== Object.keys(cursorStates).length;
+
+    const updated = Object.fromEntries(
+      Object.entries(cursorStates).map(([key, state]) => {
+        const range = state.relativeSelection && getCursorRange(editor, state);
+
+        if (!range) {
+          return [key, FROZEN_EMPTY_ARRAY];
+        }
+
+        const cached = overlayPositionCache.current.get(range);
+        if (cached) {
+          return [key, cached];
+        }
+
+        const overlayPosition = getOverlayPosition(editor, range, {
+          xOffset,
+          yOffset,
+          shouldGenerateOverlay,
+        });
+        overlayPositionsChanged = true;
+        overlayPositionCache.current.set(range, overlayPosition);
+        return [key, overlayPosition];
+      })
+    );
+
+    if (overlayPositionsChanged) {
+      setOverlayPositions(updated);
+    }
+  });
+
+  const overlayData = useMemo<CursorOverlayData<TCursorData>[]>(
+    () =>
+      Object.entries(cursorStates).map(([clientId, state]) => {
+        const range = state.relativeSelection && getCursorRange(editor, state);
+        const overlayPosition = overlayPositions[clientId];
+
+        return {
+          ...state,
+          range,
+          caretPosition: overlayPosition?.caretPosition ?? null,
+          selectionRects: overlayPosition?.selectionRects ?? FROZEN_EMPTY_ARRAY,
+        };
+      }),
+    [cursorStates, editor, overlayPositions]
+  );
+
+  const refresh = useCallback(() => {
+    overlayPositionCache.current = new WeakMap();
+    requestRerender(true);
+  }, [requestRerender]);
+
+  return [overlayData, refresh] as const;
+}

package/src/hooks/useRemoteCursorStateStore.ts

@@ -0,0 +1,89 @@
+import {
+  CursorEditor,
+  CursorState,
+  RemoteCursorChangeEventListener,
+} from '@getguru/slate-yjs-core';
+import { BaseEditor } from 'slate';
+import { Store } from '../types';
+import { useRemoteCursorEditor } from './useRemoteCursorEditor';
+
+export type CursorStore<
+  TCursorData extends Record<string, unknown> = Record<string, unknown>
+> = Store<Record<string, CursorState<TCursorData>>>;
+
+const EDITOR_TO_CURSOR_STORE: WeakMap<BaseEditor, CursorStore> = new WeakMap();
+
+function createRemoteCursorStateStore<
+  TCursorData extends Record<string, unknown>
+>(editor: CursorEditor<TCursorData>): CursorStore<TCursorData> {
+  let cursors: Record<string, CursorState<TCursorData>> = {};
+
+  const changed = new Set<number>();
+  const addChanged = changed.add.bind(changed);
+  const onStoreChangeListeners: Set<() => void> = new Set();
+
+  let changeHandler: RemoteCursorChangeEventListener | null = null;
+
+  const subscribe = (onStoreChange: () => void) => {
+    onStoreChangeListeners.add(onStoreChange);
+    if (!changeHandler) {
+      changeHandler = (event) => {
+        event.added.forEach(addChanged);
+        event.removed.forEach(addChanged);
+        event.updated.forEach(addChanged);
+        onStoreChangeListeners.forEach((listener) => listener());
+      };
+      CursorEditor.on(editor, 'change', changeHandler);
+    }
+
+    return () => {
+      onStoreChangeListeners.delete(onStoreChange);
+      if (changeHandler && onStoreChangeListeners.size === 0) {
+        CursorEditor.off(editor, 'change', changeHandler);
+        changeHandler = null;
+      }
+    };
+  };
+
+  const getSnapshot = () => {
+    if (changed.size === 0) {
+      return cursors;
+    }
+
+    changed.forEach((clientId) => {
+      const state = CursorEditor.cursorState(editor, clientId);
+      if (state === null) {
+        delete cursors[clientId.toString()];
+        return;
+      }
+
+      cursors[clientId] = state;
+    });
+
+    changed.clear();
+    cursors = { ...cursors };
+    return cursors;
+  };
+
+  return [subscribe, getSnapshot];
+}
+
+function getCursorStateStore<TCursorData extends Record<string, unknown>>(
+  editor: CursorEditor<TCursorData>
+): CursorStore<TCursorData> {
+  const existing = EDITOR_TO_CURSOR_STORE.get(editor);
+  if (existing) {
+    return existing as CursorStore<TCursorData>;
+  }
+
+  const store = createRemoteCursorStateStore(editor);
+  EDITOR_TO_CURSOR_STORE.set(editor, store);
+  return store;
+}
+
+export function useRemoteCursorStateStore<
+  TCursorData extends Record<string, unknown> = Record<string, unknown>
+>() {
+  const editor = useRemoteCursorEditor<TCursorData>();
+  return getCursorStateStore(editor);
+}

package/src/hooks/useRemoteCursorStates.ts

@@ -0,0 +1,28 @@
+import { CursorState } from '@getguru/slate-yjs-core';
+import { useSyncExternalStore } from 'use-sync-external-store/shim';
+import { useSyncExternalStoreWithSelector } from 'use-sync-external-store/shim/with-selector';
+import { useRemoteCursorStateStore } from './useRemoteCursorStateStore';
+
+export function useRemoteCursorStates<
+  TCursorData extends Record<string, unknown> = Record<string, unknown>
+>() {
+  const [subscribe, getSnapshot] = useRemoteCursorStateStore<TCursorData>();
+  return useSyncExternalStore(subscribe, getSnapshot);
+}
+
+export function useRemoteCursorStatesSelector<
+  TCursorData extends Record<string, unknown> = Record<string, unknown>,
+  TSelection = unknown
+>(
+  selector: (cursors: Record<string, CursorState<TCursorData>>) => TSelection,
+  isEqual?: (a: TSelection, b: TSelection) => boolean
+): TSelection {
+  const [subscribe, getSnapshot] = useRemoteCursorStateStore<TCursorData>();
+  return useSyncExternalStoreWithSelector(
+    subscribe,
+    getSnapshot,
+    null,
+    selector,
+    isEqual
+  );
+}

package/src/hooks/useUnsetCursorPositionOnBlur.ts

@@ -0,0 +1,48 @@
+import { CursorEditor } from '@getguru/slate-yjs-core';
+import { useCallback, useEffect } from 'react';
+import { useFocused } from 'slate-react';
+import { useRemoteCursorEditor } from './useRemoteCursorEditor';
+
+export function useUnsetCursorPositionOnBlur() {
+  const editor = useRemoteCursorEditor();
+  const isSlateFocused = useFocused();
+
+  const sendCursorPosition = useCallback(
+    (isFocused?: boolean) => {
+      if (isFocused && editor.selection) {
+        CursorEditor.sendCursorPosition(editor, editor.selection);
+        return;
+      }
+
+      if (!isFocused) {
+        CursorEditor.sendCursorPosition(editor, null);
+      }
+    },
+    [editor]
+  );
+
+  useEffect(() => {
+    const handleWindowBlur = () => {
+      if (isSlateFocused) {
+        sendCursorPosition(false);
+      }
+    };
+
+    const handleWindowFocus = () => {
+      if (isSlateFocused) {
+        sendCursorPosition(true);
+      }
+    };
+
+    window.addEventListener('blur', handleWindowBlur);
+    window.addEventListener('focus', handleWindowFocus);
+    return () => {
+      window.removeEventListener('blur', handleWindowBlur);
+      window.removeEventListener('focus', handleWindowFocus);
+    };
+  }, [isSlateFocused, sendCursorPosition]);
+
+  useEffect(() => {
+    sendCursorPosition(isSlateFocused);
+  }, [editor, isSlateFocused, sendCursorPosition]);
+}

package/src/hooks/utils.ts

@@ -0,0 +1,61 @@
+import {
+  RefObject,
+  useCallback,
+  useEffect,
+  useReducer,
+  useRef,
+  useState,
+} from 'react';
+
+export function useRequestRerender() {
+  const [, rerender] = useReducer((s) => s + 1, 0);
+  const animationFrameIdRef = useRef<number | null>(null);
+
+  const clearAnimationFrame = () => {
+    if (animationFrameIdRef.current) {
+      cancelAnimationFrame(animationFrameIdRef.current);
+      animationFrameIdRef.current = 0;
+    }
+  };
+
+  useEffect(clearAnimationFrame);
+  useEffect(() => clearAnimationFrame, []);
+
+  return useCallback((immediately = false) => {
+    if (immediately) {
+      rerender();
+      return;
+    }
+
+    if (animationFrameIdRef.current) {
+      return;
+    }
+
+    animationFrameIdRef.current = requestAnimationFrame(rerender);
+  }, []);
+}
+
+export function useOnResize<T extends HTMLElement>(
+  ref: RefObject<T> | undefined,
+  onResize: () => void
+) {
+  const onResizeRef = useRef(onResize);
+  onResizeRef.current = onResize;
+
+  const [observer] = useState(
+    () =>
+      new ResizeObserver(() => {
+        onResizeRef.current();
+      })
+  );
+
+  useEffect(() => {
+    if (!ref?.current) {
+      return;
+    }
+
+    const { current: element } = ref;
+    observer.observe(element);
+    return () => observer.unobserve(element);
+  }, [observer, ref]);
+}

package/src/index.ts

@@ -0,0 +1,26 @@
+export {
+  RemoteCursorDecoration,
+  RemoteCursorDecoratedRange,
+  RemoteCaretDecoration,
+  RemoteCaretDecoratedRange,
+  TextWithRemoteCursors,
+  UseDecorateRemoteCursorsOptions,
+  getRemoteCursorsOnLeaf,
+  getRemoteCaretsOnLeaf,
+  useDecorateRemoteCursors,
+} from './hooks/useDecorateRemoteCursors';
+
+export {
+  useRemoteCursorStatesSelector,
+  useRemoteCursorStates,
+} from './hooks/useRemoteCursorStates';
+
+export { useUnsetCursorPositionOnBlur } from './hooks/useUnsetCursorPositionOnBlur';
+
+export { getCursorRange } from './utils/getCursorRange';
+
+export {
+  CursorOverlayData,
+  UseRemoteCursorOverlayPositionsOptions,
+  useRemoteCursorOverlayPositions,
+} from './hooks/useRemoteCursorOverlayPositions';

package/src/types.ts

@@ -0,0 +1,4 @@
+export type Store<T> = readonly [
+  (onStoreChange: () => void) => () => void,
+  () => T
+];

package/src/utils/getCursorRange.ts

@@ -0,0 +1,45 @@
+import {
+  CursorEditor,
+  CursorState,
+  relativeRangeToSlateRange,
+} from '@getguru/slate-yjs-core';
+import { BaseRange, Descendant, Range } from 'slate';
+
+const CHILDREN_TO_CURSOR_STATE_TO_RANGE: WeakMap<
+  Descendant[],
+  WeakMap<CursorState, Range | null>
+> = new WeakMap();
+
+export function getCursorRange<
+  TCursorData extends Record<string, unknown> = Record<string, unknown>
+>(
+  editor: CursorEditor<TCursorData>,
+  cursorState: CursorState<TCursorData>
+): BaseRange | null {
+  if (!cursorState.relativeSelection) {
+    return null;
+  }
+
+  let cursorStates = CHILDREN_TO_CURSOR_STATE_TO_RANGE.get(editor.children);
+  if (!cursorStates) {
+    cursorStates = new WeakMap();
+    CHILDREN_TO_CURSOR_STATE_TO_RANGE.set(editor.children, cursorStates);
+  }
+
+  let range = cursorStates.get(cursorState);
+  if (range === undefined) {
+    try {
+      range = relativeRangeToSlateRange(
+        editor.sharedRoot,
+        editor,
+        cursorState.relativeSelection
+      );
+
+      cursorStates.set(cursorState, range);
+    } catch (e) {
+      return null;
+    }
+  }
+
+  return range;
+}

package/src/utils/getOverlayPosition.ts

@@ -0,0 +1,111 @@
+import { BaseRange, Editor, Path, Range, Text } from 'slate';
+import { ReactEditor } from 'slate-react';
+import { reactEditorToDomRangeSafe } from './react-editor-to-dom-range-safe';
+
+export type SelectionRect = {
+  width: number;
+  height: number;
+  top: number;
+  left: number;
+};
+
+export type CaretPosition = {
+  height: number;
+  top: number;
+  left: number;
+};
+
+export type OverlayPosition = {
+  caretPosition: CaretPosition | null;
+  selectionRects: SelectionRect[];
+};
+
+export type GetSelectionRectsOptions = {
+  xOffset: number;
+  yOffset: number;
+  shouldGenerateOverlay?: (node: Text, path: Path) => boolean;
+};
+
+export function getOverlayPosition(
+  editor: ReactEditor,
+  range: BaseRange,
+  { yOffset, xOffset, shouldGenerateOverlay }: GetSelectionRectsOptions
+): OverlayPosition {
+  const [start, end] = Range.edges(range);
+  const domRange = reactEditorToDomRangeSafe(editor, range);
+  if (!domRange) {
+    return {
+      caretPosition: null,
+      selectionRects: [],
+    };
+  }
+
+  const selectionRects: SelectionRect[] = [];
+  const nodeIterator = Editor.nodes(editor, {
+    at: range,
+    match: (n, p) =>
+      Text.isText(n) && (!shouldGenerateOverlay || shouldGenerateOverlay(n, p)),
+  });
+
+  let caretPosition: CaretPosition | null = null;
+  const isBackward = Range.isBackward(range);
+  for (const [node, path] of nodeIterator) {
+    const domNode = ReactEditor.toDOMNode(editor, node);
+
+    const isStartNode = Path.equals(path, start.path);
+    const isEndNode = Path.equals(path, end.path);
+
+    let clientRects: DOMRectList | null = null;
+    if (isStartNode || isEndNode) {
+      const nodeRange = document.createRange();
+      nodeRange.selectNode(domNode);
+
+      if (isStartNode) {
+        nodeRange.setStart(domRange.startContainer, domRange.startOffset);
+      }
+      if (isEndNode) {
+        nodeRange.setEnd(domRange.endContainer, domRange.endOffset);
+      }
+
+      clientRects = nodeRange.getClientRects();
+    } else {
+      clientRects = domNode.getClientRects();
+    }
+
+    const isCaret = isBackward ? isStartNode : isEndNode;
+    for (let i = 0; i < clientRects.length; i++) {
+      const clientRect = clientRects.item(i);
+      if (!clientRect) {
+        continue;
+      }
+
+      const isCaretRect =
+        isCaret && (isBackward ? i === 0 : i === clientRects.length - 1);
+
+      const top = clientRect.top - yOffset;
+      const left = clientRect.left - xOffset;
+
+      if (isCaretRect) {
+        caretPosition = {
+          height: clientRect.height,
+          top,
+          left:
+            left +
+            (isBackward || Range.isCollapsed(range) ? 0 : clientRect.width),
+        };
+      }
+
+      selectionRects.push({
+        width: clientRect.width,
+        height: clientRect.height,
+        top,
+        left,
+      });
+    }
+  }
+
+  return {
+    selectionRects,
+    caretPosition,
+  };
+}