presence-editor-views.ts

presence-editor-views.tsapps/web/src/lib/presence-editor-views.tsraw ← lib3,328 B← Back to the app
1/**
2 * presence-editor-views (TASK-0093, spec R4) — the browser glue that maps a
3 * remote cursor's `{blockId, offset}` to VIEWPORT coordinates.
4 *
5 * The web editor is per-block Tiptap: each text block owns a ProseMirror
6 * `EditorView`, and a remote offset is only meaningful inside THAT block's
7 * own document. This registry lets the CursorLayer (an overlay sibling of
8 * the block list) resolve a remote point without prop-threading through the
9 * recursive BlockRenderer — the focused/known editors self-register here,
10 * exactly like the presence caret store (stores/presence-store).
11 *
12 * The resolver returns **viewport** coordinates (from a `Range.getBoundingClientRect`
13 * at the block's `domAtPos`). The CursorLayer converts them to its own
14 * container's coordinate space (and re-resolves on scroll/resize). A
15 * `null` return means the block is gone / hidden / the offset is out of
16 * range — the pure resolver (lib/presence-cursor) drops the cursor silently.
17 *
18 * Browser-only (guarded by `document`); the module is imported by
19 * "use client" components only.
20 */
21import type { Editor } from "@tiptap/react";
22import type { BlockOffset } from "./presence-cursor";
23 
24type Resolver = (offset: BlockOffset) => { x: number; y: number } | null;
25 
26const views = new Map<string, Resolver>();
27 
28/** Clamp a doc position into the block's content range. */
29function clampPos(editor: Editor, offset: BlockOffset): number {
30  const size = editor.state.doc.content.size;
31  if (offset === "end") return size;
32  return Math.max(0, Math.min(offset, size));
33}
34 
35/** Viewport point at a block position (caret: the top-left of the caret box). */
36function pointAt(editor: Editor, offset: BlockOffset): { x: number; y: number } | null {
37  if (typeof document === "undefined") return null;
38  const pos = clampPos(editor, offset);
39  const { node, offset: off } = editor.view.domAtPos(pos);
40  const range = document.createRange();
41  try {
42    if (node.nodeType === 3) {
43      range.setStart(node, Math.min(off, (node as CharacterData).length));
44    } else {
45      range.setStart(node, Math.min(off, node.childNodes.length));
46    }
47    range.collapse(true);
48  } catch {
49    return null; // the node detached mid-resolve (concurrent edit) — stale.
50  }
51  const rect = range.getBoundingClientRect();
52  if (rect.width === 0 && rect.height === 0 && rect.left === 0 && rect.top === 0) return null;
53  return { x: rect.left, y: rect.top + rect.height / 2 };
54}
55 
56/**
57 * Register a block's editor for cursor resolution. The resolver closes over
58 * the editor; re-registering (editor recreated) replaces the prior entry.
59 * Returns an unregister fn (call it on unmount / editor destruction).
60 */
61export function registerPresenceEditor(blockId: string, editor: Editor): () => void {
62  views.set(blockId, (offset) => pointAt(editor, offset));
63  return () => {
64    if (views.get(blockId)) views.delete(blockId);
65  };
66}
67 
68/** Resolve a viewport point, or null when the block is unknown/stale. */
69export function resolvePresencePoint(
70  blockId: string,
71  offset: BlockOffset,
72): { x: number; y: number } | null {
73  const resolve = views.get(blockId);
74  return resolve ? resolve(offset) : null;
75}
76 
77/** The block ids currently resolvable (a test/diagnostic view). */
78export function registeredPresenceBlocks(): string[] {
79  return [...views.keys()];
80}
81