inline-editor.tsx

inline-editor.tsxapps/web/src/components/editor/inline-editor.tsxraw ← editor12,298 B← Back to the app
1"use client";
2 
3/**
4 * Inline rich-text editor for text-ish blocks, backed by Tiptap 2.
5 *
6 * Custom nodes from `@factory/editor` (mention, equation, inline code
7 * variants, …) are registered here — the package owns the node definitions,
8 * this app only wires them into the editor. Tiptap owns the ProseMirror
9 * state; the block document is our canonical `Block` JSON (ARCHITECTURE.md
10 * §2), serialized with @factory/editor on blur/save.
11 *
12 * Persistence is delegated: `onChange` is debounced by the caller (the
13 * block renderer queues a batch save), `onBlur` forces the final save.
14 */
15import { useCallback, useEffect, useRef, useState } from "react";
16import { EditorContent, useEditor, type Editor } from "@tiptap/react";
17import StarterKit from "@tiptap/starter-kit";
18import Placeholder from "@tiptap/extension-placeholder";
19import CharacterCount from "@tiptap/extension-character-count";
20import Link from "@tiptap/extension-link";
21import Image from "@tiptap/extension-image";
22import TaskList from "@tiptap/extension-task-list";
23import TaskItem from "@tiptap/extension-task-item";
24// Custom nodes (mention, equation, inline math, toggle-title, …) — owned by
25// packages/editor, consumed here. Import shape is fixed by that package.
26import { atomHtmlToText, atomTextToHtml, factoryEditorExtensions } from "@factory/editor";
27import { cn } from "@/lib/utils";
28import { registerPresenceEditor } from "@/lib/presence-editor-views";
29import { usePresenceCaretStore } from "@/stores/presence-store";
30import { SlashMenu, type SlashCommand } from "./slash-menu";
31 
32export interface InlineEditorProps {
33  blockId: string;
34  /** Canonical block JSON content (the serialized Tiptap doc object). */
35  content: unknown;
36  placeholder?: string;
37  className?: string;
38  /** Called on every doc change (caller debounces persistence). */
39  onChange?: (blockId: string, content: unknown) => void;
40  /** Called when the editor loses focus (final save). */
41  onBlur?: (blockId: string, content: unknown) => void;
42  /** True while the block row is selected (ring highlight). */
43  selected?: boolean;
44  readOnly?: boolean;
45  /** Focus this instance when it becomes true (deep-link / Enter flow). */
46  requestFocus?: boolean;
47  onFocusBlock?: (blockId: string) => void;
48  /**
49   * Block-level keyboard bridge (wired to ProseMirror handleKeyDown):
50   * Enter at the top of the doc → new sibling block; ArrowUp/Down at the
51   * doc boundary → previous/next block. Cmd/Ctrl+Z stays with Tiptap's
52   * history extension.
53   */
54  onEnterKey?: () => void;
55  onNavigate?: (dir: -1 | 1) => void;
56  /**
57   * Slash-menu context: where the editor's block sits, so the parent can
58   * insert the picked command as a sibling after it.
59   */
60  slashContext?: { parentId: string | null; position: string };
61  /**
62   * Invoked when the user types "/" in an otherwise empty block and picks a
63   * command. The typed "/" text is cleared by this editor before the
64   * callback fires.
65   */
66  onSlashPick?: (
67    command: SlashCommand,
68    context: { parentId: string | null; position: string },
69  ) => void;
70}
71 
72/** Escape a stored plain-text value so it is DATA, never markup (untrusted). */
73function escapeHtml(s: string): string {
74  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
75}
76 
77function toHtml(content: unknown): string {
78  if (!content) return "";
79  // Our canonical content is a serialized Tiptap JSON doc. The editor accepts
80  // HTML — convert via a lightweight path: store the doc as HTML on write
81  // (see page-view save path) so round-tripping stays lossless for MVP.
82  if (typeof content === "string") return content;
83  // Object content — the API's canonical `{ text }` shape (blocks created via
84  // the API, import, or the AI apply path — which writes `{ text: newText }`)
85  // — must still render: without this, every non-web-authored block displays
86  // blank (TASK-0123 found the writing e2e hitting exactly this). The stored
87  // text is plain text, so wrap it in a paragraph and escape it (it is
88  // untrusted data, never HTML).
89  const c = content as { text?: unknown; title?: unknown };
90  const raw = typeof c.text === "string" ? c.text : typeof c.title === "string" ? c.title : undefined;
91  if (raw === undefined || raw === "") return "";
92  // T-148: atom tokens (@date/@status/@label) become styled atom nodes; the
93  // bridge escapes all text segments (stored text is untrusted data).
94  return `<p>${atomTextToHtml(raw)}</p>`;
95}
96 
97/**
98 * T-148 save boundary: editor HTML → stored content. Atoms round-trip to
99 * `@kind(value)` tokens in `{ text }` (the API canonical form). Atom-less
100 * HTML is returned untouched — legacy blocks keep their exact content.
101 */
102function saveContent(editor: { getHTML(): string }): unknown {
103  const html = editor.getHTML();
104  const text = atomHtmlToText(html);
105  return text === null ? html : { text };
106}
107 
108export function InlineEditor({
109  blockId,
110  content,
111  placeholder = "Type '/' for commands",
112  className,
113  onChange,
114  onBlur,
115  selected,
116  readOnly,
117  requestFocus,
118  onFocusBlock,
119  onEnterKey,
120  onNavigate,
121  slashContext,
122  onSlashPick,
123}: InlineEditorProps) {
124  const editorRef = useRef<Editor | null>(null);
125  const initialContent = useRef(toHtml(content));
126  const [slash, setSlash] = useState<{
127    query: string;
128    anchor: { top: number; left: number };
129  } | null>(null);
130 
131  // Keep the latest callbacks without re-creating the editor on every render.
132  const handlers = useRef({ onEnterKey, onNavigate, slashContext, onSlashPick });
133  handlers.current = { onEnterKey, onNavigate, slashContext, onSlashPick };
134 
135  const editor = useEditor({
136    extensions: [
137      StarterKit.configure({
138        heading: { levels: [1, 2, 3] },
139        // Lists/todos come from the dedicated extensions below.
140        bulletList: false,
141        orderedList: false,
142        codeBlock: false,
143      }),
144      TaskList,
145      TaskItem.configure({ nested: true }),
146      Placeholder.configure({ placeholder }),
147      CharacterCount,
148      Link.configure({ openOnClick: false, autolink: true }),
149      Image,
150      // @factory/editor custom nodes — kept last so they can override.
151      ...factoryEditorExtensions(),
152    ],
153    content: initialContent.current,
154    editable: !readOnly,
155    immediatelyRender: false,
156    editorProps: {
157      attributes: {
158        class: "editor-content focus:outline-none",
159        "data-block-id": blockId,
160      },
161      handleKeyDown: (_view, event: KeyboardEvent) => {
162        if (!editor) return false;
163        const { $from } = editor.state.selection;
164        // Enter on a top-level paragraph creates a sibling block below.
165        // `$from.depth === 1`: the caret sits inside a top-level text block
166        // (doc > paragraph > text). The old `depth === 0` guard was the DOC
167        // root — unreachable for a text caret — so Enter never reached
168        // onEnterKey (Tiptap split the block in place instead). (The
169        // ArrowUp/Down guards below still check `depth === 0`; they are
170        // equally dead and are left as-is, recorded in the Phase-15 notes.)
171        if (event.key === "Enter" && !event.shiftKey && $from.depth === 1) {
172          event.preventDefault();
173          handlers.current.onEnterKey?.();
174          return true;
175        }
176        if (event.key === "ArrowUp" && $from.depth === 0 && $from.parentOffset === 0) {
177          event.preventDefault();
178          handlers.current.onNavigate?.(-1);
179          return true;
180        }
181        if (
182          event.key === "ArrowDown" &&
183          $from.depth === 0 &&
184          $from.parentOffset >= $from.parent.nodeSize - 2
185        ) {
186          event.preventDefault();
187          handlers.current.onNavigate?.(1);
188          return true;
189        }
190        return false;
191      },
192    },
193    onUpdate: ({ editor }) => {
194      editorRef.current = editor;
195      onChange?.(blockId, saveContent(editor));
196      // Slash trigger: block text starting with "/" (and a short query)
197      // opens the command menu, anchored at the caret.
198      const docText = editor.state.doc.textContent;
199      if (!docText.startsWith("/")) {
200        setSlash(null);
201        return;
202      }
203      const query = docText.slice(1);
204      if (query.trimStart().length > 24) {
205        setSlash(null);
206        return;
207      }
208      const pos = editor.state.selection.from;
209      const rect = editor.view.coordsAtPos(pos);
210      setSlash({ query, anchor: { top: rect.bottom + 4, left: rect.left } });
211    },
212    onBlur: ({ editor }) => {
213      editorRef.current = editor;
214      setSlash(null);
215      onBlur?.(blockId, saveContent(editor));
216      // Presence (TASK-0093): this editor no longer owns the caret. If the
217      // next focused editor is another block it re-asserts its own; if
218      // focus left the page, the caret stays cleared.
219      usePresenceCaretStore.getState().setCaret(null);
220    },
221    onFocus: ({ editor }) => {
222      onFocusBlock?.(blockId);
223      reportPresenceCaret(editor);
224    },
225    onSelectionUpdate: ({ editor }) => {
226      // Presence (TASK-0093): the focused editor reports its caret (the
227      // per-page usePresence hook throttles it into `presence` frames).
228      reportPresenceCaret(editor);
229    },
230  });
231 
232  // Presence (TASK-0093): report this editor's caret to the presence store
233  // (the page's usePresence hook turns it into throttled `presence` frames).
234  // The offset is within THIS block's text (Tiptap doc coords — the page
235  // has no shared document), which is exactly what the wire cursor shape
236  // carries ({blockId, offset, selection?}).
237  const reportPresenceCaret = (ed: Editor): void => {
238    const { from, to, empty, $from } = ed.state.selection;
239    usePresenceCaretStore.getState().setCaret({
240      blockId,
241      offset: from,
242      selection: empty
243        ? undefined
244        : { fromBlockId: blockId, fromOffset: $from.start(0), toBlockId: blockId, toOffset: to },
245    });
246  };
247 
248  // Sync external content (realtime upsert from another user) only when this
249  // editor is NOT focused, to avoid clobbering the local caret.
250  useEffect(() => {
251    if (!editor) return;
252    const next = toHtml(content);
253    if (editor.isFocused) return;
254    const current = editor.getHTML();
255    if (next !== current) {
256      editor.commands.setContent(next, false);
257    }
258  }, [content, editor]);
259 
260  // Presence (TASK-0093): register this block's editor view so the
261  // CursorLayer can resolve a REMOTE cursor's {blockId, offset} → viewport
262  // coordinates (per-block Tiptap — the page has no shared doc). Unregister
263  // on unmount so a deleted block's stale cursor resolves to null (dropped).
264  useEffect(() => {
265    if (!editor) return;
266    return registerPresenceEditor(blockId, editor);
267  }, [blockId, editor]);
268 
269  const focus = useCallback(() => {
270    if (!editor) return;
271    editor.chain().focus("end").run();
272  }, [editor]);
273 
274  // Slash-menu pick: clear the typed "/query" (queues an empty save through
275  // the normal update path), then hand the command to the parent for
276  // sibling insertion.
277  const pickSlash = useCallback((cmd: SlashCommand) => {
278    // Close the menu explicitly: relying on the `setContent("")` update to
279    // clear the slash trigger leaves the portal mounted for at least one
280    // render (a `fixed z-[70]` overlay that intercepts clicks on the dialog
281    // that opens beneath it — the "Slash commands lingers after pick" quirk
282    // noted in the Phase-15 E2E).
283    setSlash(null);
284    const ed = editorRef.current;
285    if (ed) ed.chain().setContent("").focus("start").run();
286    const ctx = handlers.current.slashContext ?? { parentId: null, position: "" };
287    handlers.current.onSlashPick?.(cmd, ctx);
288  }, []);
289 
290  useEffect(() => {
291    if (requestFocus) focus();
292  }, [requestFocus, focus]);
293 
294  if (!editor) {
295    return (
296      <div
297        className={cn("editor-content min-h-[1.5em] text-sm", className)}
298        contentEditable={false}
299        aria-label={placeholder}
300      />
301    );
302  }
303 
304  return (
305    <div className={cn("relative", selected && "rounded-sm", className)}>
306      <EditorContent editor={editor} />
307      {slash ? (
308        <SlashMenu
309          query={slash.query}
310          anchor={slash.anchor}
311          onPick={pickSlash}
312          onClose={() => setSlash(null)}
313        />
314      ) : null}
315    </div>
316  );
317}
318