@pilotiq/tiptap 3.5.0 → 3.6.0

package/src/react/MarkdownEditor.tsx

@@ -4,6 +4,7 @@ import type { AnyExtension } from '@tiptap/core'
 import StarterKit from '@tiptap/starter-kit'
 import Placeholder from '@tiptap/extension-placeholder'
 import Image from '@tiptap/extension-image'
+import { DOMParser as ProseMirrorDOMParser } from '@tiptap/pm/model'
 // The `tiptap-markdown` chain (incl. CJS-only `markdown-it-task-lists`) is
 // pre-bundled into `dist/markdownExtension.js` at @pilotiq/tiptap build
 // time; importing the wrapper instead of `tiptap-markdown` directly
@@ -17,7 +18,10 @@ import {
   type MarkdownEditorProps,
 } from '@pilotiq/pilotiq/react'
 import { AiSuggestionExtension } from '../extensions/AiSuggestionExtension.js'
+import { AiInlineDiffExtension, aiInlineDiffPluginKey } from '../extensions/AiInlineDiffExtension.js'
 import { useAiSuggestionBridge } from './useAiSuggestionBridge.js'
+import { useAiInlineDiff, useIsAiInlineDiffActive } from './useAiInlineDiff.js'
+import { AiSuggestionBanner } from './AiSuggestionBanner.js'
 
 // Inline lucide.dev SVGs — same posture as `toolbarButtons.tsx` so this
 // package doesn't pull `lucide-react` as a peer dep. Keep stroke / size
@@ -214,12 +218,14 @@ export function MarkdownEditor({
         }),
         Image.configure({ inline: false, allowBase64: false }),
         Placeholder.configure({ placeholder: placeholder ?? 'Write in markdown…' }),
-        // AI suggestions — always-on extension that tracks suggested edits as
-        // inline strikethrough + Approve/Reject chip widgets. Idle until the
-        // host calls `editor.commands.addAiSuggestion(...)` via the bridge below.
-        // Matches the `TiptapEditor` wiring so suggestion mode works uniformly
-        // across RichTextField / MarkdownField / TextField+TextareaField.
+        // AI suggestions — chip widget for surgical (range-anchored) edits.
         AiSuggestionExtension,
+        // AI inline diff — Tiptap-Pro-style visualization for whole-field
+        // suggestions (prosemirror-changeset under the hood). Decorations
+        // show green-background inserts inline + red-strikethrough widgets
+        // for deleted text. Host's `<AiSuggestionBanner>` drives Accept /
+        // Reject via the extension's commands.
+        AiInlineDiffExtension,
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         ...(collabExtensions as any[]),
       ],
@@ -248,23 +254,46 @@ export function MarkdownEditor({
   // `<PendingSuggestionsContext>` queue with the editor's `AiSuggestion`
   // extension. No-op when no provider is mounted (default no-op context).
   //
-  // Whole-field handling for chat-driven suggestions (e.g.
-  // `update_form_state`). The chip widget renders inline for visualization
-  // (synthesized range over the whole doc), but Approve routes through
-  // `onApplyWholeField` so the new markdown source parses correctly via
-  // the Markdown extension — the chip's plain-text replace would lose
-  // headings, lists, formatting.
+  // Whole-field handling: NO chip widget here. The chip's `textContent`
+  // renderer surfaces raw markdown (`## Heading\n- item`) as literal text
+  // inside the green pill — visually unparseable for multi-paragraph
+  // rewrites. Instead, `<AiSuggestionBanner>` mounts above the editor
+  // (see render below). Producer-supplied range suggestions still ride
+  // the inline chip path — those have a precise anchor worth showing
+  // in context.
+  const applyWholeField = (value: string): void => {
+    if (!editor || editor.isDestroyed) return
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ;(editor.commands as any).setContent(value)
+  }
   useAiSuggestionBridge(editor ?? null, name, {
-    synthesizeWholeFieldRange: (ed) => ({
-      from: 0,
-      to:   ed.state.doc.content.size,
-    }),
-    onApplyWholeField: (value) => {
-      if (!editor || editor.isDestroyed) return
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      ;(editor.commands as any).setContent(value)
+    onApplyWholeField: applyWholeField,
+  })
+
+  // Inline diff for whole-field suggestions — replaces the editor doc with
+  // the proposed markdown so the user sees the structural diff (inserted
+  // headings / list items / etc.) before approving. Pipeline:
+  //   1. tiptap-markdown's parser turns the source into HTML
+  //      (`editor.storage.markdown.parser.parse(value)` returns a string).
+  //   2. ProseMirror's `DOMParser.fromSchema(schema).parseSlice(...)` turns
+  //      that HTML into a Slice against THIS editor's schema — same path
+  //      the editor's own clipboard-paste uses, so the slice is guaranteed
+  //      schema-valid.
+  useAiInlineDiff(editor ?? null, name, {
+    parseSuggestion: (ed, value) => {
+      try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const parser = (ed.storage as any).markdown?.parser
+        if (!parser || typeof parser.parse !== 'function') return null
+        const html = parser.parse(value)
+        if (typeof html !== 'string') return null
+        const container = document.createElement('div')
+        container.innerHTML = html
+        return ProseMirrorDOMParser.fromSchema(ed.schema).parseSlice(container)
+      } catch { return null }
     },
   })
+  const isDiffActive = useIsAiInlineDiffActive(editor ?? null)
 
   // First-load seed for collab. Collaboration starts the editor empty
   // regardless of `content`; once the provider syncs from the server we
@@ -434,6 +463,16 @@ export function MarkdownEditor({
 
   return (
     <div className="flex flex-col rounded-md border bg-background">
+      <AiSuggestionBanner
+        fieldName={name}
+        onApplyWholeField={applyWholeField}
+        {...(isDiffActive && editor
+          ? {
+              onAcceptViaEditor: () => editor.commands.acceptAiInlineDiff(),
+              onRejectViaEditor: () => editor.commands.rejectAiInlineDiff(),
+            }
+          : {})}
+      />
       {canAttach && (
         <input
           ref={fileInputRef}

package/src/react/TiptapEditor.tsx

@@ -20,6 +20,9 @@ import type {
 } from '@pilotiq/pilotiq/react'
 import { useCollabRoom, getCollabExtensions, onProviderSynced } from '@pilotiq/pilotiq/react'
 import { useAiSuggestionBridge } from './useAiSuggestionBridge.js'
+import { useAiInlineDiff, useIsAiInlineDiffActive } from './useAiInlineDiff.js'
+import { AiSuggestionBanner } from './AiSuggestionBanner.js'
+import { DOMParser as ProseMirrorDOMParser } from '@tiptap/pm/model'
 import type { BlockMeta } from '../Block.js'
 import type { ToolbarGroups, RichTextStorage, ColorSwatch } from '../RichTextField.js'
 import { BlockNodeExtension } from '../extensions/BlockNodeExtension.js'
@@ -31,6 +34,7 @@ import { DragHandleExtension } from '../extensions/DragHandleExtension.js'
 import { MergeTagExtension } from '../extensions/MergeTagExtension.js'
 import { LeadMarkExtension, SmallMarkExtension } from '../extensions/TextSizeMarks.js'
 import { AiSuggestionExtension } from '../extensions/AiSuggestionExtension.js'
+import { AiInlineDiffExtension } from '../extensions/AiInlineDiffExtension.js'
 import {
   MentionExtension,
   type MentionState,
@@ -315,10 +319,11 @@ function ClientEditor(props: ClientEditorProps) {
         fieldName:     name,
       })] : [MentionExtension]),
       DragHandleExtension,
-      // AI suggestions — always-on extension that tracks suggested edits as
-      // inline strikethrough + Approve/Reject chip widgets. Idle until the
-      // host calls `editor.commands.addAiSuggestion(...)`.
+      // AI suggestions — chip widget for surgical (range-anchored) edits.
       AiSuggestionExtension,
+      // AI inline diff — Tiptap-Pro-style visualization for whole-field
+      // suggestions via prosemirror-changeset. See AiInlineDiffExtension.
+      AiInlineDiffExtension,
       // Realtime-collab extensions (Yjs `Collaboration` + cursor) — empty
       // when no `<RecordCollabRoom>` is mounted up-tree, or when no plugin
       // registered a factory via `registerCollabExtensions`.
@@ -464,22 +469,35 @@ function ClientEditor(props: ClientEditorProps) {
   // `<PendingSuggestionsContext>` queue with the editor's `AiSuggestion`
   // extension. No-op when no provider is mounted (default no-op context).
   //
-  // Whole-field handling: rare for RichTextField (chat-driven flows usually
-  // emit range-anchored suggestions for richtext), but `update_form_state`
-  // can still arrive with `set_value` on a rich field. The chip widget
-  // renders over the whole doc for visualization; Approve routes through
-  // `onApplyWholeField` so `setContent` parses the new HTML / JSON
-  // correctly — the chip's plain-text replace would lose all formatting.
+  // Whole-field handling: NO chip widget here. The chip's `textContent`
+  // renderer would surface raw HTML tags as literal text inside the
+  // green pill — unparseable on multi-paragraph rewrites. Instead,
+  // `<AiSuggestionBanner>` mounts above the editor (see render below).
+  // Producer-supplied range suggestions still ride the inline chip —
+  // those have a precise anchor worth visualizing in context.
+  const applyWholeField = (value: string): void => {
+    if (!editor || editor.isDestroyed) return
+    editor.commands.setContent(value)
+  }
   useAiSuggestionBridge(editor ?? null, name, {
-    synthesizeWholeFieldRange: (ed) => ({
-      from: 0,
-      to:   ed.state.doc.content.size,
-    }),
-    onApplyWholeField: (value) => {
-      if (!editor || editor.isDestroyed) return
-      editor.commands.setContent(value)
+    onApplyWholeField: applyWholeField,
+  })
+
+  // Inline diff for whole-field suggestions. Pipeline mirrors MarkdownEditor:
+  // HTML → ProseMirror Slice via the schema's DOMParser. Suggested values
+  // on a RichTextField are typically HTML (or marked-up JSON that the
+  // schema's DOMParser also handles via its serialized round-trip). For
+  // JSON suggestions, the schema may reject — falls back to banner-only.
+  useAiInlineDiff(editor ?? null, name, {
+    parseSuggestion: (ed, value) => {
+      try {
+        const container = document.createElement('div')
+        container.innerHTML = value
+        return ProseMirrorDOMParser.fromSchema(ed.schema).parseSlice(container)
+      } catch { return null }
     },
   })
+  const isDiffActive = useIsAiInlineDiffActive(editor ?? null)
 
   // Re-render the toolbar when the selection / marks change so active-state
   // booleans stay fresh.
@@ -488,6 +506,16 @@ function ClientEditor(props: ClientEditorProps) {
   return (
     <div className="relative flex flex-col">
       <input type="hidden" name={name} value={serialized} />
+      <AiSuggestionBanner
+        fieldName={name}
+        onApplyWholeField={applyWholeField}
+        {...(isDiffActive && editor
+          ? {
+              onAcceptViaEditor: () => editor.commands.acceptAiInlineDiff(),
+              onRejectViaEditor: () => editor.commands.rejectAiInlineDiff(),
+            }
+          : {})}
+      />
       {editor && toolbarGroups && toolbarGroups.length > 0 && (
         <Toolbar
           editor={editor}

package/src/react/useAiInlineDiff.ts

@@ -0,0 +1,146 @@
+/**
+ * Bridge between the host's `<PendingSuggestionsContext>` queue and the
+ * editor's `AiInlineDiffExtension`. When a whole-field suggestion arrives
+ * for the field, the hook:
+ *
+ *   1. Parses the suggested value into a ProseMirror `Slice` via the
+ *      renderer-supplied parser. Each Tiptap surface owns its own
+ *      content shape — markdown source for `MarkdownEditor`, HTML / JSON
+ *      for `TiptapEditor`, plain text for `CollabTextRenderer`.
+ *   2. Calls `editor.commands.startAiInlineDiff(id, slice)` — the
+ *      extension snapshots the current doc as the baseline, replaces
+ *      the doc content with the proposed slice, and starts a
+ *      `prosemirror-changeset` tracking the diff.
+ *   3. Registers an applier on the cross-tree pending-suggestion
+ *      registry so the host's `<AiSuggestionBanner>` Accept button (and
+ *      any other surface calling `pendingSuggestions.approve(id)`) runs
+ *      `acceptAiInlineDiff()` instead of the legacy `onApplyWholeField`
+ *      callback. The current doc IS the accepted state — no extra
+ *      content swap needed.
+ *
+ * Reject handling: not registered on the applier (the registry only
+ * tracks Approve). Renderers wire Reject through the banner's
+ * `onRejectWithEditor` prop, which calls `rejectAiInlineDiff()` to revert
+ * the doc to the baseline before dismissing the suggestion.
+ *
+ * Defensive: only one inline diff active at a time per editor. If a new
+ * synthesized suggestion arrives while one is still pending review, the
+ * hook drops it (the producer should have waited). This matches
+ * `AiSuggestionExtension`'s chip path which also allows only one
+ * suggestion at a time per id.
+ */
+
+import { useEffect, useRef } from 'react'
+import type { Editor } from '@tiptap/core'
+import type { Slice } from '@tiptap/pm/model'
+import {
+  registerPendingSuggestionApplier,
+  usePendingSuggestionsForField,
+  type PendingSuggestion,
+  type PendingSuggestionApplier,
+} from '@pilotiq/pilotiq/react'
+import { aiInlineDiffPluginKey } from '../extensions/AiInlineDiffExtension.js'
+
+export interface UseAiInlineDiffOptions {
+  /**
+   * Parse the suggested string value into a ProseMirror Slice that's
+   * compatible with this editor's schema. Returns `null` to skip (e.g.
+   * malformed content, unsupported markup) — the suggestion stays in
+   * the queue but no diff renders, and the host's fallback path (banner
+   * with `onApplyWholeField`) takes over.
+   *
+   * Renderers implement this per content shape:
+   *   - plain text → wrap each line in a `paragraph` node
+   *   - markdown   → run through the Markdown extension's parseMarkdown
+   *   - HTML       → DOMParser + ProseMirror's DOMParser.parse
+   */
+  parseSuggestion: (editor: Editor, value: string) => Slice | null
+}
+
+/**
+ * Returns whether a diff is currently active in the editor. Hosts use
+ * this to gate the banner's UI between the legacy `onApplyWholeField`
+ * mode and the diff-aware mode (Reject routes through
+ * `rejectAiInlineDiff` to revert the doc).
+ */
+export function useIsAiInlineDiffActive(editor: Editor | null): boolean {
+  // Re-render on every editor transaction so the hook tracks state
+  // changes (start / accept / reject). useEditorState would be the
+  // idiomatic way; we read directly here to keep the dep surface tiny.
+  const [, force] = useReducerForceUpdate()
+  useEffect(() => {
+    if (!editor) return
+    const handler = () => force()
+    editor.on('transaction', handler)
+    return () => { editor.off('transaction', handler) }
+  }, [editor, force])
+  if (!editor) return false
+  return aiInlineDiffPluginKey.getState(editor.state) !== null
+}
+
+export function useAiInlineDiff(
+  editor: Editor | null,
+  fieldName: string,
+  options: UseAiInlineDiffOptions,
+): void {
+  const { list } = usePendingSuggestionsForField(fieldName)
+
+  const parseRef = useRef(options.parseSuggestion)
+  useEffect(() => { parseRef.current = options.parseSuggestion }, [options.parseSuggestion])
+
+  // Track which ids we've handed off to the editor's diff extension
+  // so we don't re-start the diff every render or for already-active
+  // suggestions.
+  const startedRef = useRef<Set<string>>(new Set())
+
+  // Context → editor: start the diff for each new whole-field suggestion.
+  useEffect(() => {
+    if (!editor) return
+    const wholeField = list.filter(s => !hasEditorRange(s))
+    for (const s of wholeField) {
+      if (startedRef.current.has(s.id)) continue
+      if (typeof s.suggestedValue !== 'string') continue
+      // Bail when a different diff is already showing — one at a time.
+      // Producer should serialize calls; if not, the second suggestion
+      // sits in the queue until the first is approved/rejected.
+      if (aiInlineDiffPluginKey.getState(editor.state) !== null) continue
+      const slice = parseRef.current(editor, s.suggestedValue)
+      if (!slice) continue
+      editor.commands.startAiInlineDiff(s.id, slice)
+      startedRef.current.add(s.id)
+    }
+    // Cleanup: when a suggestion leaves the context AND we previously
+    // started a diff for it, the editor should drop the diff state too.
+    // Approve dismisses via context → here we drop from startedRef.
+    const contextIds = new Set(list.map(s => s.id))
+    for (const id of Array.from(startedRef.current)) {
+      if (!contextIds.has(id)) startedRef.current.delete(id)
+    }
+  }, [editor, list])
+
+  // Cross-tree applier — when the banner / chat-sidebar pill calls
+  // `pendingSuggestions.approve(id)` for one of our tracked suggestions,
+  // accept the diff. Editor is the source of truth for the new doc.
+  useEffect(() => {
+    if (!editor) return
+    const applier: PendingSuggestionApplier = (suggestion) => {
+      if (!startedRef.current.has(suggestion.id)) return
+      editor.commands.acceptAiInlineDiff()
+    }
+    return registerPendingSuggestionApplier(undefined, fieldName, applier)
+  }, [editor, fieldName])
+}
+
+function hasEditorRange(s: PendingSuggestion): boolean {
+  const meta = (s.meta ?? {}) as Record<string, unknown>
+  const range = meta['editorRange'] as { from?: unknown; to?: unknown } | undefined
+  return !!(range && typeof range.from === 'number' && typeof range.to === 'number')
+}
+
+// useReducer + dispatch is the smallest-API force-update primitive React
+// ships. Hoisted into a helper so the call site stays one line.
+import { useReducer } from 'react'
+function useReducerForceUpdate(): [number, () => void] {
+  const [n, inc] = useReducer((x: number) => (x + 1) | 0, 0)
+  return [n, () => inc()]
+}