@beyondwork/docx-react-component 1.0.67 → 1.0.70

package/src/shell/use-collab-sync.ts

@@ -0,0 +1,116 @@
+/**
+ * Shell helpers — collab Yjs sync + remote-cursor awareness hooks.
+ *
+ * Two hooks that encapsulate the `WordReviewEditor` collab lifecycle:
+ *
+ * 1. `useRuntimeCollabSync` — while a runtime + Yjs doc are both
+ *    attached, constructs a `RuntimeCollabSync` bridge so local
+ *    document mutations fan out to Yjs CRDT updates and remote
+ *    updates feed back into the runtime's command dispatch.
+ *
+ * 2. `useRemoteCursorPublish` — while a runtime + awareness channel
+ *    are both attached, publishes the local participant's selection
+ *    + identity onto awareness and clears it on teardown.
+ *
+ * Living in `src/shell/` (not `src/ui/`) so the `src/runtime/collab/**`
+ * value imports stay outside the Layer-11 boundary register. The
+ * hooks themselves compose standard React `useEffect`s; no DOM or PM
+ * reads — the only platform dependency is the consumer's `awareness`
+ * / `ydoc` handles.
+ */
+
+import type { MutableRefObject } from "react";
+import { useEffect } from "react";
+
+import { createRuntimeCollabSync } from "../runtime/collab/runtime-collab-sync.ts";
+import {
+  clearLocalCursorState,
+  getCursorColorForUser,
+  setLocalCursorState,
+} from "../runtime/collab/remote-cursor-awareness.ts";
+import type { WordReviewEditorRuntime } from "./session-bootstrap.ts";
+
+// Opaque interop types — we keep them `unknown` + `never`-tolerant so
+// the hook doesn't couple to specific Yjs / awareness-provider versions.
+type YjsDoc = Parameters<typeof createRuntimeCollabSync>[0]["ydoc"];
+type Awareness = Parameters<typeof setLocalCursorState>[0];
+type RuntimeCollabCommandBridge = Parameters<
+  typeof createRuntimeCollabSync
+>[0]["commandAppliedBridge"];
+
+/**
+ * Shipyard the Yjs↔runtime command bridge while both are attached.
+ * Destroys the bridge on teardown. No-op when either is absent.
+ */
+export function useRuntimeCollabSync(input: {
+  ydoc: YjsDoc | null | undefined;
+  runtime: WordReviewEditorRuntime | null | undefined;
+  authorId: string;
+  commandAppliedBridge: RuntimeCollabCommandBridge;
+}): void {
+  const { ydoc, runtime, authorId, commandAppliedBridge } = input;
+  useEffect(() => {
+    if (!ydoc || !runtime) return;
+    const handle = createRuntimeCollabSync({
+      ydoc,
+      runtime,
+      authorId,
+      commandAppliedBridge,
+    });
+    return () => handle.destroy();
+  }, [commandAppliedBridge, authorId, runtime, ydoc]);
+}
+
+/**
+ * Publish the local participant's cursor on awareness while the
+ * runtime + awareness channel are both attached. Clears on teardown
+ * and on runtime detach. `suppressNextPublishRef` lets the caller
+ * skip one publish tick — used to avoid echoing a remote-origin
+ * selection back onto awareness.
+ */
+export function useRemoteCursorPublish(input: {
+  awareness: Awareness | null | undefined;
+  runtime: WordReviewEditorRuntime | null | undefined;
+  currentUser: { userId: string; displayName: string };
+  selection: { anchor: number; head: number };
+  activeStory: Parameters<typeof setLocalCursorState>[1]["storyTarget"];
+  suppressNextPublishRef: MutableRefObject<boolean>;
+}): void {
+  const { awareness, runtime, currentUser, selection, activeStory, suppressNextPublishRef } = input;
+
+  // Teardown — clear cursor on unmount / awareness swap.
+  useEffect(() => {
+    if (!awareness) return;
+    return () => clearLocalCursorState(awareness);
+  }, [awareness]);
+
+  // Publish — write the local cursor each time selection or identity changes.
+  useEffect(() => {
+    if (!awareness) return;
+    if (!runtime) {
+      clearLocalCursorState(awareness);
+      return;
+    }
+    if (suppressNextPublishRef.current) {
+      suppressNextPublishRef.current = false;
+      return;
+    }
+    setLocalCursorState(awareness, {
+      userId: currentUser.userId,
+      displayName: currentUser.displayName,
+      color: getCursorColorForUser(currentUser.userId),
+      anchor: selection.anchor,
+      head: selection.head,
+      storyTarget: activeStory,
+    });
+  }, [
+    awareness,
+    currentUser.displayName,
+    currentUser.userId,
+    runtime,
+    activeStory,
+    selection.anchor,
+    selection.head,
+    suppressNextPublishRef,
+  ]);
+}