@pilotiq/tiptap 3.0.0 → 3.1.0

package/src/extensions/AiSuggestionExtension.ts

@@ -0,0 +1,415 @@
+import { Extension, type Editor } from '@tiptap/core'
+import { Plugin, PluginKey, type EditorState, type Transaction } from '@tiptap/pm/state'
+import { Decoration, DecorationSet } from '@tiptap/pm/view'
+
+/**
+ * One AI-suggested replacement of `[from, to)` with `replacement`.
+ *
+ * `from === to` represents a pure insertion at that position. v1 carries
+ * plain-text replacement only — marks and structure round-trip through the
+ * editor as-is when the suggestion is approved (the original range's marks
+ * are preserved on the inserted text node by ProseMirror).
+ */
+export interface AiSuggestion {
+  /** Stable id; consumer-provided. Re-adding with the same id replaces the prior entry. */
+  id:           string
+  /** Inclusive document position the original range starts at. */
+  from:         number
+  /** Exclusive document position the original range ends at. */
+  to:           number
+  /** Plain-text replacement. Empty string = pure deletion. */
+  replacement:  string
+  /** Optional attribution surfaced on the chip widget. */
+  source?: {
+    agentSlug?:  string
+    agentLabel?: string
+  }
+}
+
+export interface AiSuggestionExtensionOptions {
+  /**
+   * Class prefix for both decoration spans and chip widgets. The package
+   * stays CSS-free — consumers ship the matching styles. Default
+   * `'pilotiq-ai-suggestion'` produces classes:
+   *   - `pilotiq-ai-suggestion-original`     (strikethrough on the original range)
+   *   - `pilotiq-ai-suggestion-chip`         (root of the inline widget)
+   *   - `pilotiq-ai-suggestion-replacement`  (the suggested-text preview span)
+   *   - `pilotiq-ai-suggestion-accept`       (Approve button)
+   *   - `pilotiq-ai-suggestion-reject`       (Reject button)
+   */
+  classPrefix: string
+  /**
+   * Fired whenever the suggestion list changes — after `add*`, `approve*`,
+   * `reject*`, `clear*`, or after a doc edit collapses a range. Lets the host
+   * mirror state into a React context (e.g. `PendingSuggestionsApi`).
+   */
+  onChange?: (suggestions: AiSuggestion[]) => void
+}
+
+declare module '@tiptap/core' {
+  interface Commands<ReturnType> {
+    aiSuggestion: {
+      /** Add or replace a suggestion (matched by id). */
+      addAiSuggestion:         (suggestion: AiSuggestion) => ReturnType
+      /** Add or replace many suggestions in one transaction. */
+      addAiSuggestions:        (suggestions: AiSuggestion[]) => ReturnType
+      /** Apply the replacement to the doc and drop the suggestion. */
+      approveAiSuggestion:     (id: string) => ReturnType
+      /** Drop the suggestion without touching the doc. */
+      rejectAiSuggestion:      (id: string) => ReturnType
+      /** Apply every replacement in highest-`from`-first order. */
+      approveAllAiSuggestions: () => ReturnType
+      /** Drop every suggestion. */
+      rejectAllAiSuggestions:  () => ReturnType
+      /** Alias for `rejectAllAiSuggestions`. */
+      clearAiSuggestions:      () => ReturnType
+    }
+  }
+}
+
+interface PluginState {
+  suggestions: readonly AiSuggestion[]
+}
+
+interface SetMeta {
+  type: 'set'
+  next: readonly AiSuggestion[]
+}
+
+export const aiSuggestionPluginKey = new PluginKey<PluginState>('pilotiqAiSuggestion')
+
+/**
+ * Append or replace by id. Pure — exported for tests and so the same dedupe
+ * shape can drive consumer-side mirror state.
+ */
+export function upsertSuggestion(
+  current: readonly AiSuggestion[],
+  next:    AiSuggestion,
+): AiSuggestion[] {
+  const idx = current.findIndex(s => s.id === next.id)
+  if (idx === -1) return [...current, next]
+  const copy = current.slice()
+  copy[idx] = next
+  return copy
+}
+
+/** Append or replace many — semantically equivalent to a fold over `upsertSuggestion`. */
+export function upsertSuggestions(
+  current: readonly AiSuggestion[],
+  nexts:   readonly AiSuggestion[],
+): AiSuggestion[] {
+  let acc: AiSuggestion[] = current.slice()
+  for (const n of nexts) acc = upsertSuggestion(acc, n)
+  return acc
+}
+
+/** Remove by id. */
+export function removeSuggestion(
+  current: readonly AiSuggestion[],
+  id:      string,
+): AiSuggestion[] {
+  return current.filter(s => s.id !== id)
+}
+
+/**
+ * Remap survivors through a PM mapping; drop ranges that collapsed past
+ * each other (`to < from` after remap). Pure — exported for tests.
+ */
+export function remapSuggestions(
+  suggestions: readonly AiSuggestion[],
+  map: (pos: number, side: -1 | 1) => number,
+): AiSuggestion[] {
+  const out: AiSuggestion[] = []
+  for (const s of suggestions) {
+    const from = map(s.from, -1)
+    const to   = map(s.to,   1)
+    if (to < from) continue
+    out.push({ ...s, from, to })
+  }
+  return out
+}
+
+/**
+ * Order suggestions for `approveAll` so the highest-`from` runs first;
+ * earlier-in-doc replacements then can't shift positions of later ones.
+ * Pure — exported for tests.
+ */
+export function sortForApproveAll(
+  suggestions: readonly AiSuggestion[],
+): AiSuggestion[] {
+  return suggestions.slice().sort((a, b) => b.from - a.from)
+}
+
+/**
+ * Editor extension that tracks AI-suggested edits as inline decorations with
+ * per-hunk Approve/Reject chips. The package is CSS-free — consumers wire
+ * styles against the documented class names.
+ *
+ * Usage:
+ * ```ts
+ * editor.commands.addAiSuggestion({
+ *   id:          'seo-1',
+ *   from:        12,
+ *   to:          18,
+ *   replacement: 'better',
+ *   source:      { agentLabel: 'SEO' },
+ * })
+ * // …user clicks ✓ on the chip, or:
+ * editor.commands.approveAiSuggestion('seo-1')
+ * ```
+ *
+ * Mounted by default inside `TiptapEditor`; consumer code reaches it through
+ * the editor's command surface.
+ */
+export const AiSuggestionExtension = Extension.create<AiSuggestionExtensionOptions>({
+  name: 'pilotiqAiSuggestion',
+
+  addOptions() {
+    return {
+      classPrefix: 'pilotiq-ai-suggestion',
+    }
+  },
+
+  addCommands() {
+    return {
+      addAiSuggestion: (suggestion) => ({ tr, state, dispatch }) => {
+        const current = aiSuggestionPluginKey.getState(state)?.suggestions ?? []
+        const next    = upsertSuggestion(current, suggestion)
+        if (dispatch) {
+          tr.setMeta(aiSuggestionPluginKey, { type: 'set', next } satisfies SetMeta)
+          dispatch(tr)
+        }
+        return true
+      },
+
+      addAiSuggestions: (suggestions) => ({ tr, state, dispatch }) => {
+        const current = aiSuggestionPluginKey.getState(state)?.suggestions ?? []
+        const next    = upsertSuggestions(current, suggestions)
+        if (dispatch) {
+          tr.setMeta(aiSuggestionPluginKey, { type: 'set', next } satisfies SetMeta)
+          dispatch(tr)
+        }
+        return true
+      },
+
+      approveAiSuggestion: (id) => ({ tr, state, dispatch }) => {
+        const current = aiSuggestionPluginKey.getState(state)?.suggestions ?? []
+        const target  = current.find(s => s.id === id)
+        if (!target) return false
+        if (dispatch) {
+          applyApprove(tr, state, target)
+          tr.setMeta(aiSuggestionPluginKey, {
+            type: 'set',
+            next: removeSuggestion(current, id),
+          } satisfies SetMeta)
+          dispatch(tr)
+        }
+        return true
+      },
+
+      rejectAiSuggestion: (id) => ({ tr, state, dispatch }) => {
+        const current = aiSuggestionPluginKey.getState(state)?.suggestions ?? []
+        const target  = current.find(s => s.id === id)
+        if (!target) return false
+        if (dispatch) {
+          tr.setMeta(aiSuggestionPluginKey, {
+            type: 'set',
+            next: removeSuggestion(current, id),
+          } satisfies SetMeta)
+          dispatch(tr)
+        }
+        return true
+      },
+
+      approveAllAiSuggestions: () => ({ tr, state, dispatch }) => {
+        const current = aiSuggestionPluginKey.getState(state)?.suggestions ?? []
+        if (current.length === 0) return false
+        if (dispatch) {
+          for (const s of sortForApproveAll(current)) applyApprove(tr, state, s)
+          tr.setMeta(aiSuggestionPluginKey, {
+            type: 'set',
+            next: [],
+          } satisfies SetMeta)
+          dispatch(tr)
+        }
+        return true
+      },
+
+      rejectAllAiSuggestions: () => ({ tr, state, dispatch }) => {
+        const current = aiSuggestionPluginKey.getState(state)?.suggestions ?? []
+        if (current.length === 0) return false
+        if (dispatch) {
+          tr.setMeta(aiSuggestionPluginKey, {
+            type: 'set',
+            next: [],
+          } satisfies SetMeta)
+          dispatch(tr)
+        }
+        return true
+      },
+
+      clearAiSuggestions: () => ({ tr, state, dispatch }) => {
+        const current = aiSuggestionPluginKey.getState(state)?.suggestions ?? []
+        if (current.length === 0) return false
+        if (dispatch) {
+          tr.setMeta(aiSuggestionPluginKey, {
+            type: 'set',
+            next: [],
+          } satisfies SetMeta)
+          dispatch(tr)
+        }
+        return true
+      },
+    }
+  },
+
+  addProseMirrorPlugins() {
+    const ext = this
+    return [
+      new Plugin<PluginState>({
+        key: aiSuggestionPluginKey,
+        state: {
+          init: (): PluginState => ({ suggestions: [] }),
+          apply(tr, prev): PluginState {
+            const meta = tr.getMeta(aiSuggestionPluginKey) as SetMeta | undefined
+            const base = meta?.type === 'set' ? meta.next : prev.suggestions
+            if (!tr.docChanged) return { suggestions: base }
+            return {
+              suggestions: remapSuggestions(base, (pos, side) =>
+                tr.mapping.map(pos, side)),
+            }
+          },
+        },
+        props: {
+          decorations(state) {
+            const ps = aiSuggestionPluginKey.getState(state)
+            if (!ps || ps.suggestions.length === 0) return DecorationSet.empty
+            return buildDecorations(state, ps.suggestions, ext.options.classPrefix, ext.editor)
+          },
+        },
+        view(view) {
+          let last = aiSuggestionPluginKey.getState(view.state)?.suggestions
+          return {
+            update(updated) {
+              const next = aiSuggestionPluginKey.getState(updated.state)?.suggestions
+              if (next === last) return
+              last = next
+              const cb = ext.options.onChange
+              if (cb) cb(next ? [...next] : [])
+            },
+            destroy() {},
+          }
+        },
+      }),
+    ]
+  },
+})
+
+function applyApprove(tr: Transaction, state: EditorState, target: AiSuggestion): void {
+  const docSize = state.doc.content.size
+  const from = clampPos(target.from, docSize)
+  const to   = clampPos(target.to,   docSize)
+  if (from > to) return
+  if (target.replacement.length > 0) {
+    tr.replaceWith(from, to, state.schema.text(target.replacement))
+  } else if (from < to) {
+    tr.delete(from, to)
+  }
+}
+
+function buildDecorations(
+  state:       EditorState,
+  suggestions: readonly AiSuggestion[],
+  prefix:      string,
+  editor:      Editor,
+): DecorationSet {
+  const docSize = state.doc.content.size
+  const decos:  Decoration[] = []
+
+  for (const s of suggestions) {
+    const from = clampPos(s.from, docSize)
+    const to   = clampPos(s.to,   docSize)
+    if (from > to) continue
+
+    if (from < to) {
+      decos.push(
+        Decoration.inline(from, to, {
+          class: `${prefix}-original`,
+          'data-pilotiq-ai-suggestion-id': s.id,
+        }),
+      )
+    }
+
+    decos.push(
+      Decoration.widget(to, () => buildChip(s, prefix, editor), {
+        side: 1,
+        ignoreSelection: true,
+        key: `pilotiq-ai-suggestion:${s.id}`,
+      }),
+    )
+  }
+
+  return DecorationSet.create(state.doc, decos)
+}
+
+/** Bound `pos` into `[0, max]`; non-finite or negative input collapses to 0. */
+export function clampPos(pos: number, max: number): number {
+  if (!Number.isFinite(pos)) return 0
+  if (pos < 0) return 0
+  if (pos > max) return max
+  return Math.trunc(pos)
+}
+
+function buildChip(s: AiSuggestion, prefix: string, editor: Editor): HTMLElement {
+  const root = document.createElement('span')
+  root.className = `${prefix}-chip`
+  root.setAttribute('data-pilotiq-ai-suggestion-id', s.id)
+  root.contentEditable = 'false'
+
+  if (s.replacement.length > 0) {
+    const insert = document.createElement('span')
+    insert.className   = `${prefix}-replacement`
+    insert.textContent = s.replacement
+    root.appendChild(insert)
+  }
+
+  if (s.source?.agentLabel) {
+    root.setAttribute('data-pilotiq-ai-suggestion-source', s.source.agentLabel)
+  }
+  if (s.source?.agentSlug) {
+    root.setAttribute('data-pilotiq-ai-suggestion-source-slug', s.source.agentSlug)
+  }
+
+  root.appendChild(buildButton(prefix, 'accept', '✓', 'Accept suggestion', () => {
+    editor.chain().focus().approveAiSuggestion(s.id).run()
+  }))
+  root.appendChild(buildButton(prefix, 'reject', '✕', 'Reject suggestion', () => {
+    editor.chain().focus().rejectAiSuggestion(s.id).run()
+  }))
+
+  return root
+}
+
+function buildButton(
+  prefix:  string,
+  variant: 'accept' | 'reject',
+  glyph:   string,
+  title:   string,
+  onClick: () => void,
+): HTMLButtonElement {
+  const btn = document.createElement('button')
+  btn.type        = 'button'
+  btn.className   = `${prefix}-${variant}`
+  btn.title       = title
+  btn.textContent = glyph
+  // Don't steal the editor selection on press — the click handler runs on
+  // mouseup, but mousedown is what flips focus to the button. Cancelling it
+  // keeps the cursor in the editor so `editor.chain().focus()` lands cleanly.
+  btn.addEventListener('mousedown', (e) => e.preventDefault())
+  btn.addEventListener('click', (e) => {
+    e.preventDefault()
+    e.stopPropagation()
+    onClick()
+  })
+  return btn
+}

package/src/index.ts

@@ -19,6 +19,19 @@ export {
 export { registerTiptap } from './register.js'
 export { tiptap } from './plugin.js'
 export { TiptapEditor } from './react/TiptapEditor.js'
+export {
+  AiSuggestionExtension,
+  aiSuggestionPluginKey,
+  upsertSuggestion,
+  upsertSuggestions,
+  removeSuggestion,
+  remapSuggestions,
+  sortForApproveAll,
+  clampPos,
+  type AiSuggestion,
+  type AiSuggestionExtensionOptions,
+} from './extensions/AiSuggestionExtension.js'
+export { useAiSuggestionBridge } from './react/useAiSuggestionBridge.js'
 export {
   renderRichTextToHtml,
   isRichTextValue,

package/src/react/TiptapEditor.tsx

@@ -14,6 +14,7 @@ import { Details, DetailsSummary, DetailsContent } from '@tiptap/extension-detai
 import { Grid, GridColumn } from '../extensions/GridExtension.js'
 import { Popover } from '@base-ui/react/popover'
 import type { FieldRendererProps } from '@pilotiq/pilotiq/react'
+import { useAiSuggestionBridge } from './useAiSuggestionBridge.js'
 import type { BlockMeta } from '../Block.js'
 import type { ToolbarGroups, RichTextStorage, ColorSwatch } from '../RichTextField.js'
 import { BlockNodeExtension } from '../extensions/BlockNodeExtension.js'
@@ -24,6 +25,7 @@ import {
 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 {
   MentionExtension,
   type MentionState,
@@ -246,6 +248,10 @@ function ClientEditor(props: FieldRendererProps) {
         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(...)`.
+      AiSuggestionExtension,
     ],
     content: initialContent ?? '',
     onUpdate: ({ editor: ed }) => {
@@ -332,6 +338,11 @@ function ClientEditor(props: FieldRendererProps) {
   // scratch on every keystroke.
   useEffect(() => { editorRef.current = editor ?? null }, [editor])
 
+  // Cross-package suggestion bridge — sync the host's
+  // `<PendingSuggestionsContext>` queue with the editor's `AiSuggestion`
+  // extension. No-op when no provider is mounted (default no-op context).
+  useAiSuggestionBridge(editor ?? null, name)
+
   // Re-render the toolbar when the selection / marks change so active-state
   // booleans stay fresh.
   const tick = useEditorTick(editor)

package/src/react/useAiSuggestionBridge.ts

@@ -0,0 +1,119 @@
+import { useEffect, useRef } from 'react'
+import type { Editor } from '@tiptap/core'
+import {
+  registerPendingSuggestionApplier,
+  usePendingSuggestionsForField,
+  type PendingSuggestion,
+  type PendingSuggestionApplier,
+} from '@pilotiq/pilotiq/react'
+import { aiSuggestionPluginKey } from '../extensions/AiSuggestionExtension.js'
+
+/**
+ * Two-way sync between the cross-package `<PendingSuggestionsContext>`
+ * queue and this editor's `AiSuggestionExtension` state.
+ *
+ *   - **Context → editor**: every entry whose `meta.editorRange = { from, to }`
+ *     is present and whose `suggestedValue` is a string gets pushed into the
+ *     editor as an inline-diff hunk via `addAiSuggestion`. Entries leaving the
+ *     queue are removed from the editor via `rejectAiSuggestion` (no doc edit).
+ *
+ *   - **Editor → context**: when a chip's Approve / Reject button removes a
+ *     hunk from the editor's plugin state, the matching id is dismissed from
+ *     the queue (`dismiss(id)`) so other surfaces (e.g. the chat-sidebar pill,
+ *     a future FieldShell overlay) clear in lock-step. The doc mutation
+ *     itself happens inside the editor — context is just a notification.
+ *
+ * Cycle protection: the hook tracks which ids it has personally pushed to
+ * the editor (`pushed`). The Context→editor pass never re-pushes an id that's
+ * already there, and the Editor→context pass only dismisses ids that this
+ * hook had previously pushed (so an id added directly by host code via
+ * `editor.commands.addAiSuggestion(...)` doesn't get reflected back through
+ * a context that never knew about it).
+ */
+export function useAiSuggestionBridge(editor: Editor | null, fieldName: string): void {
+  const { list, dismiss } = usePendingSuggestionsForField(fieldName)
+
+  // Hold the latest `dismiss` in a ref so the editor-side listener — which
+  // installs once per editor — always reaches the up-to-date context API.
+  const dismissRef = useRef(dismiss)
+  useEffect(() => { dismissRef.current = dismiss }, [dismiss])
+
+  // Set of ids this hook pushed; used by both directions for cycle control.
+  const pushedRef = useRef<Set<string>>(new Set())
+
+  // Context → editor.
+  useEffect(() => {
+    if (!editor) return
+    const contextIds = new Set(list.map(s => s.id))
+
+    for (const s of list) {
+      if (pushedRef.current.has(s.id)) continue
+      const meta = (s.meta ?? {}) as Record<string, unknown>
+      const range = meta['editorRange'] as { from?: unknown; to?: unknown } | undefined
+      if (!range || typeof range.from !== 'number' || typeof range.to !== 'number') continue
+      const replacement = typeof s.suggestedValue === 'string' ? s.suggestedValue : ''
+      editor.commands.addAiSuggestion({
+        id:          s.id,
+        from:        range.from,
+        to:          range.to,
+        replacement,
+        ...(s.source ? { source: s.source } : {}),
+      })
+      pushedRef.current.add(s.id)
+    }
+
+    for (const id of Array.from(pushedRef.current)) {
+      if (contextIds.has(id)) continue
+      // Context dropped the suggestion — remove from editor without
+      // mutating the doc (rejectAiSuggestion drops state only).
+      editor.commands.rejectAiSuggestion(id)
+      pushedRef.current.delete(id)
+    }
+  }, [editor, list])
+
+  // Editor → context.
+  useEffect(() => {
+    if (!editor) return
+    const handler = () => {
+      const ps = aiSuggestionPluginKey.getState(editor.state)
+      if (!ps) return
+      const editorIds = new Set(ps.suggestions.map((s: { id: string }) => s.id))
+      for (const id of Array.from(pushedRef.current)) {
+        if (editorIds.has(id)) continue
+        // Chip removed the suggestion (Approve mutated the doc, Reject did
+        // not — either way it's gone from editor state). Mirror to context.
+        pushedRef.current.delete(id)
+        dismissRef.current(id)
+      }
+    }
+    editor.on('transaction', handler)
+    return () => { editor.off('transaction', handler) }
+  }, [editor])
+
+  // Cross-tree applier (Phase 8.5). When an aggregate consumer (e.g. a
+  // chat-sidebar pending-pill) calls `pendingSuggestions.approve(id)`,
+  // the pro provider looks up the applier registered for this
+  // `(formId, fieldName)` and invokes it. We translate that into the
+  // editor's own approve command — same path the inline chip click takes.
+  useEffect(() => {
+    if (!editor) return
+    const applier: PendingSuggestionApplier = (suggestion) => {
+      // Bail when the suggestion isn't one of ours (no editor range or
+      // bridge-pushed entry). Pro provider falls back to plain dismiss.
+      if (!pushedRef.current.has(suggestion.id)) return
+      editor.chain().focus().approveAiSuggestion(suggestion.id).run()
+      // The transaction listener above sees the editor state drop the id
+      // and calls `dismiss(id)` on its own — no manual mirror needed.
+    }
+    // Editor renderers don't currently have access to a `formId` here;
+    // pass `undefined` so the wildcard form scope resolves. Phase 8.5+
+    // can thread `formId` via the bridge call site if a future multi-
+    // form richtext consumer needs it.
+    return registerPendingSuggestionApplier(undefined, fieldName, applier)
+  }, [editor, fieldName])
+}
+
+// Re-export the pending-suggestion type for consumers that import the hook
+// from this module directly — saves them a separate `@pilotiq/pilotiq/react`
+// import when wiring an external producer.
+export type { PendingSuggestion }