wrapping and custom mention tokenizers + * natively, eliminating the need for the HTML detour. + * + * 3. PREPROCESSING is minimal: only legacy mention shortcode migration and + * URL linkification (preprocessMarkdown). No HTML conversion. + * + * Tech: Tiptap v3.22.1 (ProseMirror wrapper), @tiptap/markdown for + * bidirectional Markdown ↔ ProseMirror JSON conversion. + */ + import { forwardRef, useEffect, diff --git a/apps/web/features/editor/extensions/index.ts b/apps/web/features/editor/extensions/index.ts index b901b452..c182dd8a 100644 --- a/apps/web/features/editor/extensions/index.ts +++ b/apps/web/features/editor/extensions/index.ts @@ -1,3 +1,24 @@ +/** + * Shared extension factory for ContentEditor. + * + * One function builds the extension array for BOTH edit and readonly modes. + * This ensures visual consistency — the same extensions parse and render + * content identically regardless of mode. + * + * Split: + * - Both modes: StarterKit, CodeBlock, Link, Image, Table, Markdown, Mention + * - Edit only: Typography, Placeholder, markdownPaste, submitShortcut, + * fileUpload, Mention suggestion popup + * + * Link config differs: edit mode has autolink (detects URLs while typing), + * readonly does not (prevents false positives on display). + * + * Mention suggestion is only attached in edit mode — readonly doesn't need + * the autocomplete popup. + * + * All link styling is controlled by content-editor.css (var(--brand) color), + * not Tailwind HTMLAttributes, to keep a single source of truth. + */ import type { RefObject } from "react"; import StarterKit from "@tiptap/starter-kit"; import CodeBlockLowlight from "@tiptap/extension-code-block-lowlight"; diff --git a/apps/web/features/editor/extensions/markdown-paste.ts b/apps/web/features/editor/extensions/markdown-paste.ts index 7dde1fb9..00132ce2 100644 --- a/apps/web/features/editor/extensions/markdown-paste.ts +++ b/apps/web/features/editor/extensions/markdown-paste.ts @@ -1,3 +1,27 @@ +/** + * Markdown paste extension — ensures pasted text is parsed as Markdown. + * + * Problem: The browser clipboard can contain BOTH text/plain and text/html. + * ProseMirror always prefers text/html when present (hardcoded in + * parseFromClipboard: `let asText = !html`). When copying from VS Code, + * text editors, or .md files, the OS wraps text in
/HTML tags. + * ProseMirror parses these as code blocks — wrong. + * + * Solution: Use `handlePaste` (the only ProseMirror prop that runs for ALL + * paste events and has access to raw ClipboardEvent). We check for + * `data-pm-slice` in the HTML — this attribute is added by ProseMirror's + * own clipboard serializer. If present, the source is another ProseMirror + * editor and its HTML is structurally correct — let ProseMirror handle it. + * Otherwise, ignore the HTML and parse text/plain as Markdown. + * + * Why not clipboardTextParser? It only runs when there's NO text/html on + * the clipboard (ProseMirror source: `let asText = !!text && !html`). + * + * Why not heuristic detection (looksLikeMarkdown / hasRichHtml)? Unreliable. + * VS Code's HTML containstags that fool rich-content detectors. + * Markdown pattern matching has too many edge cases. The data-pm-slice + * check is deterministic — no false positives. + */ import { Extension } from "@tiptap/core"; import { Plugin, PluginKey } from "@tiptap/pm/state"; import { Slice } from "@tiptap/pm/model"; diff --git a/apps/web/features/editor/extensions/mention-view.tsx b/apps/web/features/editor/extensions/mention-view.tsx index b721140a..0f62158d 100644 --- a/apps/web/features/editor/extensions/mention-view.tsx +++ b/apps/web/features/editor/extensions/mention-view.tsx @@ -1,5 +1,23 @@ "use client"; +/** + * MentionView — NodeView for rendering @mentions inline in the editor. + * + * Member/agent mentions: plain "@Name" text with .mention class styling. + * Issue mentions: inline card with StatusIcon + identifier + title. + * + * Issue card sizing: must fit within the paragraph line box (14px * 1.625 + * = 22.75px). Card uses text-xs (12px) + py-0.5 + border ≈ 22px total. + * vertical-align: middle is set on the [data-node-view-wrapper] in CSS + * (not on the tag) because the wrapper is the outermost inline element + * that participates in line box calculation. Setting it on the inner + * had no effect since the wrapper was already positioned. + * + * Fallback: when issue is not in the Zustand store (deleted or other + * workspace), the same card style is used with just the identifier from + * fallbackLabel — no visual degradation to a plain text link. + */ + import { NodeViewWrapper } from "@tiptap/react"; import type { NodeViewProps } from "@tiptap/react"; import { useIssueStore } from "@/features/issues/store"; diff --git a/apps/web/features/editor/utils/preprocess.ts b/apps/web/features/editor/utils/preprocess.ts index d820b79a..ffb4d259 100644 --- a/apps/web/features/editor/utils/preprocess.ts +++ b/apps/web/features/editor/utils/preprocess.ts @@ -4,9 +4,17 @@ import { preprocessMentionShortcodes } from "@/components/markdown/mentions"; /** * Preprocess a markdown string before loading into Tiptap via contentType: 'markdown'. * - * Two string→string transforms: + * This is the ONLY transform applied before @tiptap/markdown parses the content. + * It does NOT convert to HTML — that was the old markdownToHtml.ts pipeline which + * was deleted in the April 2026 refactor. + * + * Two string→string transforms on raw Markdown: * 1. Legacy mention shortcodes [@ id="..." label="..."] → [@Label](mention://member/id) - * 2. Raw URLs → markdown links (so they render as clickable Link nodes) + * (old serialization format in database, migrated on read) + * 2. Raw URLs → markdown links via linkify-it (so they render as clickable Link nodes) + * + * After this, @tiptap/markdown's parse() handles everything else: headings, lists, + * tables, code blocks, and our custom mention tokenizer ([@Name](mention://type/id)). */ export function preprocessMarkdown(markdown: string): string { if (!markdown) return "";