@pilotiq/tiptap 3.0.0 → 3.1.1

package/dist/react/useAiSuggestionBridge.js

@@ -0,0 +1,110 @@
+import { useEffect, useRef } from 'react';
+import { registerPendingSuggestionApplier, usePendingSuggestionsForField, } 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, fieldName) {
+    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(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 ?? {});
+            const range = meta['editorRange'];
+            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) => 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 = (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]);
+}
+//# sourceMappingURL=useAiSuggestionBridge.js.map

package/dist/react/useAiSuggestionBridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAiSuggestionBridge.js","sourceRoot":"","sources":["../../src/react/useAiSuggestionBridge.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pilotiq/tiptap",
-  "version": "3.0.0",
+  "version": "3.1.1",
   "description": "Tiptap rich-text editor adapter for @pilotiq/pilotiq — slash menu, draggable blocks, custom-block API",
   "license": "MIT",
   "repository": {
@@ -32,6 +32,7 @@
   },
   "dependencies": {},
   "peerDependencies": {
+    "@pilotiq/pilotiq": ">=0.6.0 <1.0.0",
     "@base-ui/react": "^1",
     "@tiptap/core": "^3",
     "@tiptap/pm": "^3",
@@ -51,8 +52,7 @@
     "@tiptap/extension-details": "3.22.4",
     "@tiptap/suggestion": "^3",
     "react": "^18 || ^19",
-    "react-dom": "^18 || ^19",
-    "@pilotiq/pilotiq": "^0.6.0"
+    "react-dom": "^18 || ^19"
   },
   "devDependencies": {
     "@base-ui/react": "^1",
@@ -79,7 +79,7 @@
     "react": "^19",
     "react-dom": "^19",
     "typescript": "^5",
-    "@pilotiq/pilotiq": "^0.6.0"
+    "@pilotiq/pilotiq": "^0.7.0"
   },
   "author": "Suleiman Shahbari",
   "scripts": {

package/src/extensions/AiSuggestionExtension.test.ts

@@ -0,0 +1,141 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import {
+  upsertSuggestion,
+  upsertSuggestions,
+  removeSuggestion,
+  remapSuggestions,
+  sortForApproveAll,
+  clampPos,
+  type AiSuggestion,
+} from './AiSuggestionExtension.js'
+
+const make = (id: string, from: number, to: number, replacement = '…'): AiSuggestion => ({
+  id, from, to, replacement,
+})
+
+describe('upsertSuggestion', () => {
+  it('appends a new suggestion when id is unseen', () => {
+    const list = [make('a', 0, 4)]
+    const out  = upsertSuggestion(list, make('b', 8, 12))
+    assert.equal(out.length, 2)
+    assert.equal(out[1]!.id, 'b')
+  })
+
+  it('replaces in place when id already exists', () => {
+    const list = [make('a', 0, 4, 'old'), make('b', 8, 12, 'old')]
+    const out  = upsertSuggestion(list, make('a', 0, 4, 'new'))
+    assert.equal(out.length, 2)
+    assert.equal(out[0]!.replacement, 'new')
+    assert.equal(out[1]!.id, 'b')
+  })
+
+  it('does not mutate the input array', () => {
+    const list = [make('a', 0, 4)]
+    upsertSuggestion(list, make('b', 8, 12))
+    assert.equal(list.length, 1)
+  })
+})
+
+describe('upsertSuggestions', () => {
+  it('folds multiple inserts and replacements', () => {
+    const list = [make('a', 0, 4, 'old')]
+    const out  = upsertSuggestions(list, [
+      make('a', 0, 4, 'new'),
+      make('b', 8, 12),
+      make('c', 16, 20),
+    ])
+    assert.deepEqual(out.map(s => s.id), ['a', 'b', 'c'])
+    assert.equal(out[0]!.replacement, 'new')
+  })
+})
+
+describe('removeSuggestion', () => {
+  it('drops only the matching id', () => {
+    const list = [make('a', 0, 4), make('b', 8, 12)]
+    const out  = removeSuggestion(list, 'a')
+    assert.deepEqual(out.map(s => s.id), ['b'])
+  })
+
+  it('returns the same shape when id is unseen', () => {
+    const list = [make('a', 0, 4)]
+    const out  = removeSuggestion(list, 'unseen')
+    assert.deepEqual(out, list)
+  })
+})
+
+describe('remapSuggestions', () => {
+  it('shifts ranges through a forward-shift mapping', () => {
+    const list = [make('a', 10, 14)]
+    const out  = remapSuggestions(list, (pos) => pos + 5)
+    assert.equal(out[0]!.from, 15)
+    assert.equal(out[0]!.to,   19)
+  })
+
+  it('drops ranges that collapsed past each other', () => {
+    const list = [make('a', 10, 14), make('b', 20, 24)]
+    // Map collapses everything to position 0 — `to (-1 in mapping bias) < from`.
+    const out  = remapSuggestions(list, (pos, side) => (side === -1 ? pos : 0))
+    assert.equal(out.length, 0)
+  })
+
+  it('keeps a pure-insertion range (`from === to`) when it survives the mapping', () => {
+    const list = [{ ...make('a', 5, 5), replacement: 'inserted' }]
+    const out  = remapSuggestions(list, (pos) => pos + 3)
+    assert.equal(out.length, 1)
+    assert.equal(out[0]!.from, 8)
+    assert.equal(out[0]!.to,   8)
+  })
+
+  it('biases sides — `from` left, `to` right — to keep insertions stable under collapsed text', () => {
+    const list = [make('a', 5, 10)]
+    // A mapping that collapses at exactly `pos = 5` — left bias keeps `from`
+    // anchored at 5; right bias for `to = 10` shifts it to 10. Range survives.
+    const out = remapSuggestions(list, (pos, side) => {
+      if (pos === 5  && side === -1) return 5
+      if (pos === 5  && side ===  1) return 7
+      if (pos === 10 && side === -1) return 7
+      if (pos === 10 && side ===  1) return 10
+      return pos
+    })
+    assert.equal(out.length, 1)
+    assert.equal(out[0]!.from, 5)
+    assert.equal(out[0]!.to,   10)
+  })
+})
+
+describe('sortForApproveAll', () => {
+  it('orders highest-`from` first so earlier positions are stable across replacements', () => {
+    const list = [make('a', 0, 4), make('c', 20, 24), make('b', 10, 14)]
+    const out  = sortForApproveAll(list)
+    assert.deepEqual(out.map(s => s.id), ['c', 'b', 'a'])
+  })
+
+  it('does not mutate the input', () => {
+    const list = [make('a', 0, 4), make('b', 10, 14)]
+    sortForApproveAll(list)
+    assert.deepEqual(list.map(s => s.id), ['a', 'b'])
+  })
+})
+
+describe('clampPos', () => {
+  it('passes through positions within range', () => {
+    assert.equal(clampPos(5, 10), 5)
+    assert.equal(clampPos(0, 10), 0)
+    assert.equal(clampPos(10, 10), 10)
+  })
+
+  it('floors negatives at 0 and ceils overshoots at max', () => {
+    assert.equal(clampPos(-5, 10), 0)
+    assert.equal(clampPos(99, 10), 10)
+  })
+
+  it('returns 0 for non-finite input', () => {
+    assert.equal(clampPos(NaN, 10),      0)
+    assert.equal(clampPos(Infinity, 10), 0)
+  })
+
+  it('truncates fractional positions', () => {
+    assert.equal(clampPos(3.7, 10), 3)
+  })
+})