@pilotiq/tiptap 3.10.0 → 3.10.2

package/src/react/TiptapEditor.dom.test.tsx

@@ -0,0 +1,112 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import React from 'react'
+import { render, cleanup, waitFor } from '@testing-library/react'
+
+import { TiptapEditor } from './TiptapEditor.js'
+
+/**
+ * Behavioral coverage for the rich-text field renderer. The matching
+ * pure-data tests under `RichTextField.test.ts` cover `toMeta()` / option
+ * resolution; this file proves the React renderer actually mounts in our
+ * jsdom + RTL environment and produces the FormData wiring downstream
+ * consumers depend on.
+ *
+ * Scope is deliberately narrow — slash menu, floating toolbar, mention
+ * popover, side panel, and AI suggestion bridge all need additional
+ * fixtures (focus traps, document-level key handlers, context providers)
+ * and are covered by the playground + Playwright e2e suite. The asserts
+ * here are the ones that would catch a "renderer crashes at mount" or
+ * "hidden input wire-name drift" regression cheaply.
+ */
+describe('TiptapEditor (DOM)', () => {
+  function renderEditor(opts: {
+    name:          string
+    defaultValue?: unknown
+    placeholder?:  string
+  }) {
+    const { name, defaultValue = '', placeholder = 'Write…' } = opts
+    return render(
+      <TiptapEditor
+        el={{ type: 'field', fieldType: 'richtext', name }}
+        name={name}
+        defaultValue={defaultValue}
+        required={false}
+        disabled={false}
+        placeholder={placeholder}
+      />,
+    )
+  }
+
+  it('mounts the editor on hydration and exposes the hidden FormData input', async () => {
+    const { container } = renderEditor({ name: 'bio' })
+    try {
+      // Initial render is the SSR placeholder gated on `mounted`. After
+      // the mount-effect flips, `ClientEditor` mounts → Tiptap defers
+      // editor construction to its own effect under `immediatelyRender:
+      // false` → the `.ProseMirror` contenteditable lands in the DOM.
+      await waitFor(() => {
+        assert.ok(
+          container.querySelector('.ProseMirror'),
+          'ProseMirror contenteditable mounts after hydration',
+        )
+      })
+      const hidden = container.querySelector<HTMLInputElement>(
+        'input[type="hidden"][name="bio"]',
+      )
+      assert.ok(hidden, 'hidden FormData input present alongside the editor')
+    } finally {
+      cleanup()
+    }
+  })
+
+  it('serializes a JSON `defaultValue` into the hidden input on first paint', async () => {
+    // Tiptap doc shape: paragraph with one text node. The renderer's
+    // `serializeForHidden` round-trips this verbatim under the default
+    // `storage: 'json'` setting, so the hidden input should hold the
+    // JSON string at the very first render (before the editor itself
+    // has even mounted — the SSR placeholder ships the same serialized
+    // value so submit-on-mount works).
+    const defaultValue = {
+      type:    'doc',
+      content: [
+        { type: 'paragraph', content: [{ type: 'text', text: 'hello' }] },
+      ],
+    }
+    const { container } = renderEditor({ name: 'body', defaultValue })
+    try {
+      const hidden = container.querySelector<HTMLInputElement>(
+        'input[type="hidden"][name="body"]',
+      )
+      assert.ok(hidden, 'hidden input present')
+      const parsed = JSON.parse(hidden.value)
+      assert.equal(parsed.type, 'doc', 'value parses to a doc')
+      assert.equal(parsed.content[0].content[0].text, 'hello')
+    } finally {
+      cleanup()
+    }
+  })
+
+  it('uses the field `name` for the hidden input wire-name', async () => {
+    // Pilotiq forms post FormData keyed by field name; renaming the wire
+    // input here would silently drop the field on submit. The non-default
+    // `name` ("article_body" with an underscore) doubles as a regression
+    // guard for any future serializer that tries to clean / normalize
+    // names — the value the host passes in is the value posted back.
+    const { container } = renderEditor({ name: 'article_body' })
+    try {
+      await waitFor(() => {
+        assert.ok(
+          container.querySelector('.ProseMirror'),
+          'editor mounted (post-hydration probe so the test isn\'t racing the SSR branch)',
+        )
+      })
+      const hidden = container.querySelector<HTMLInputElement>(
+        'input[type="hidden"][name="article_body"]',
+      )
+      assert.ok(hidden, 'wire-name matches `name` prop verbatim')
+    } finally {
+      cleanup()
+    }
+  })
+})

package/src/react/TiptapEditor.tsx

@@ -18,7 +18,7 @@ import type {
   CollabRoom,
   CollabExtensionFactory,
 } from '@pilotiq/pilotiq/react'
-import { useCollabRoom, getCollabExtensions, onProviderSynced, useRowCoords, parseRowFieldPath } from '@pilotiq/pilotiq/react'
+import { useCollabRoom, getCollabExtensions, useCollabSeed, useRowCoords, parseRowFieldPath } from '@pilotiq/pilotiq/react'
 import { useAiSuggestionBridge } from './useAiSuggestionBridge.js'
 import { useAiInlineDiff, useIsAiInlineDiffActive } from './useAiInlineDiff.js'
 import { AiSuggestionBanner } from './AiSuggestionBanner.js'
@@ -449,47 +449,66 @@ function ClientEditor(props: ClientEditorProps) {
   // scratch on every keystroke.
   useEffect(() => { editorRef.current = editor ?? null }, [editor])
 
-  // First-load seed when collab is active. Collaboration starts the
-  // editor empty regardless of `defaultValue`; once the WebsocketProvider
-  // syncs the room state from the server we check whether the field's
-  // Y.XmlFragment was ever written. Empty + we have an initial value =
-  // first session for this record — push the DB content into the ydoc
-  // exactly once. Non-empty = the room already has authoritative state;
-  // don't overwrite.
+  // Mirror `disabled` onto the live editor at runtime. `useEditor`'s
+  // `editable: !disabled` only fires at construction time, so a parent
+  // flipping read-only after mount (e.g. policy denial mid-edit, form
+  // submitting state) would silently no-op without this effect. Same
+  // shape MarkdownEditor.tsx and CollabTextRenderer.tsx already use.
   useEffect(() => {
-    if (!editor || !collabActive || !room) return
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const provider = room.provider as any
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const ydoc     = room.ydoc as any
-    if (!provider || !ydoc) return
-
-    const trySeed = () => {
-      try {
-        const fragment = ydoc.getXmlFragment(collabName)
-        if (
-          fragment &&
-          fragment.length === 0 &&
-          initialContent !== undefined &&
-          initialContent !== null &&
-          initialContent !== '' &&
-          isTiptapShapedContent(initialContent)
-        ) {
-          // setContent dispatches a Tiptap transaction; the bound
-          // y-prosemirror binding (inside Collaboration) mirrors it
-          // into the fragment so every peer sees the seeded state.
-          // eslint-disable-next-line @typescript-eslint/no-explicit-any
-          editor.commands.setContent(initialContent as any)
-        }
-      } catch { /* ignore — seed is best-effort */ }
-    }
+    if (!editor) return
+    editor.setEditable(!disabled)
+  }, [editor, disabled])
 
-    return onProviderSynced(provider, trySeed)
-    // `initialContent` resolves once per mount (parsed from defaultValue
-    // at the top of this body). The keyed remount above guarantees we
-    // get a fresh closure per collab session.
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [editor, collabActive, room, name])
+  // First-load seed when collab is active. Collaboration starts the
+  // editor empty regardless of `defaultValue`; once the room's first
+  // sync resolves, `useCollabSeed` runs the callback inside
+  // `ydoc.transact(..., 'pilotiq-collab-seed')`. We check whether the
+  // field's `Y.XmlFragment` was ever written — empty + we have an
+  // initial value = first session for this record — push the DB
+  // content into the ydoc exactly once. Non-empty = the room already
+  // has authoritative state; don't overwrite. Gating on `editor` keeps
+  // the effect from firing before Tiptap mounts its
+  // y-prosemirror binding (Tiptap v3 defers editor construction to
+  // first effect under `immediatelyRender: false`).
+  //
+  // Subscribe-after-sync mirror: after the seed branch (or no-op when
+  // the fragment already has content from a remote peer), serialize the
+  // editor's current state into the hidden FormData input. The
+  // debounced `onUpdate` path covers steady-state typing, but in the
+  // cold-mount case (fresh peer joining a populated doc) y-prosemirror's
+  // `ySyncPlugin` view hook may run `_forceRerender` before the React
+  // owner has installed the `update` listener — leaving the hidden
+  // input empty on submit. Idempotent: when `onUpdate` already
+  // propagated, this is a no-op `setSerialized(sameValue)`. Same shape
+  // as `CollabTextRenderer`'s post-sync mirror and
+  // `@pilotiq-pro/collab`'s `rowArrayBinding.subscribeRows` catch-up.
+  useCollabSeed(
+    editor && collabActive ? room : null,
+    collabName,
+    (doc) => {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const fragment = (doc as any).getXmlFragment(collabName)
+      if (
+        fragment &&
+        fragment.length === 0 &&
+        initialContent !== undefined &&
+        initialContent !== null &&
+        initialContent !== '' &&
+        isTiptapShapedContent(initialContent) &&
+        editor
+      ) {
+        // setContent dispatches a Tiptap transaction; the bound
+        // y-prosemirror binding (inside Collaboration) mirrors it
+        // into the fragment so every peer sees the seeded state.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        editor.commands.setContent(initialContent as any)
+      }
+      if (editor) {
+        const value = storage === 'html' ? editor.getHTML() : JSON.stringify(editor.getJSON())
+        setSerialized(value)
+      }
+    },
+  )
 
   // Cross-package suggestion bridge — sync the host's
   // `<PendingSuggestionsContext>` queue with the editor's `AiSuggestion`

package/src/react/useAiInlineDiff.ts

@@ -37,6 +37,7 @@ import { useEditorState } from '@tiptap/react'
 import {
   registerPendingSuggestionApplier,
   usePendingSuggestionsForField,
+  useFormId,
   type PendingSuggestion,
   type PendingSuggestionApplier,
 } from '@pilotiq/pilotiq/react'
@@ -86,6 +87,15 @@ export function useAiInlineDiff(
   options: UseAiInlineDiffOptions,
 ): void {
   const { list } = usePendingSuggestionsForField(fieldName)
+  // Scope the applier registration by the surrounding form's id so
+  // multi-form pages route suggestions to the editor instance inside the
+  // matching form — without this, two editors on different forms but
+  // sharing a field name (e.g. two "summary" RichTextFields, one in the
+  // main edit form + one in a Replicate modal) would race on
+  // `registerPendingSuggestionApplier(undefined, …)` and the last-mounted
+  // editor would steal every approval. Falls back to wildcard scope
+  // (`undefined`) when no form is up-tree.
+  const formId = useFormId()
 
   const parseRef = useRef(options.parseSuggestion)
   useEffect(() => { parseRef.current = options.parseSuggestion }, [options.parseSuggestion])
@@ -95,6 +105,22 @@ export function useAiInlineDiff(
   // suggestions.
   const startedRef = useRef<Set<string>>(new Set())
 
+  // Re-evaluate the suggestion queue when the editor's doc shape
+  // changes. Specifically guards against the seed race: collab-enabled
+  // markdown/richtext editors mount empty and seed their content
+  // asynchronously after the Yjs provider syncs. A suggestion arriving
+  // during that window (or before the first user keystroke) sees an
+  // empty doc, `planReplaceBlock` returns null for any blockIndex >= 1,
+  // the effect bails — and never re-runs because `list` hasn't changed
+  // and React doesn't track ProseMirror's doc state. Watching
+  // `doc.childCount` flips the diff-start effect from "ran once at
+  // suggestion-push time" to "re-runs when the doc reaches usable
+  // shape," which closes the silent no-preview gap.
+  const childCount = useEditorState({
+    editor,
+    selector: ({ editor: ed }) => ed?.state.doc.childCount ?? 0,
+  }) ?? 0
+
   // Context → editor: start the diff for each new whole-field /
   // surgical-block suggestion. `meta.surgical` (if present) routes to a
   // precise PM transaction; otherwise we treat the suggested value as a
@@ -159,7 +185,7 @@ export function useAiInlineDiff(
     for (const id of Array.from(startedRef.current)) {
       if (!contextIds.has(id)) startedRef.current.delete(id)
     }
-  }, [editor, list])
+  }, [editor, list, childCount])
 
   // Cross-tree applier — two paths:
   //
@@ -192,8 +218,8 @@ export function useAiInlineDiff(
         return true
       })
     }
-    return registerPendingSuggestionApplier(undefined, fieldName, applier)
-  }, [editor, fieldName])
+    return registerPendingSuggestionApplier(formId, fieldName, applier)
+  }, [editor, fieldName, formId])
 }
 
 function hasEditorRange(s: PendingSuggestion): boolean {

package/src/react/useAiSuggestionBridge.ts

@@ -3,6 +3,7 @@ import type { Editor } from '@tiptap/core'
 import {
   registerPendingSuggestionApplier,
   usePendingSuggestionsForField,
+  useFormId,
   type PendingSuggestion,
   type PendingSuggestionApplier,
 } from '@pilotiq/pilotiq/react'
@@ -74,6 +75,12 @@ export function useAiSuggestionBridge(
   options: UseAiSuggestionBridgeOptions = {},
 ): void {
   const { list, dismiss } = usePendingSuggestionsForField(fieldName)
+  // Scope the applier under the surrounding form's id — same reasoning
+  // as `useAiInlineDiff`: two editors with the same field name across
+  // different forms (main edit form vs. a Replicate modal, say) would
+  // otherwise race on `registerPendingSuggestionApplier(undefined, …)`
+  // and the last-mounted editor would steal every approval.
+  const formId = useFormId()
 
   // 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.
@@ -201,12 +208,13 @@ export function useAiSuggestionBridge(
         apply(suggestion.suggestedValue)
       }
     }
-    // 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])
+    // formId comes from `useFormId()` on the form-context side — scopes
+    // the registration per-form so multi-form pages route approvals to
+    // the matching editor. Falls back to wildcard (`undefined`) when no
+    // FormRenderer is up-tree (modal action schemas, action-modal forms
+    // mounted outside the main page form).
+    return registerPendingSuggestionApplier(formId, fieldName, applier)
+  }, [editor, fieldName, formId])
 }
 
 // Re-export the pending-suggestion type for consumers that import the hook

package/src/test/setup.ts

@@ -0,0 +1,64 @@
+/**
+ * Phase 6e test setup — boots jsdom into globalThis so React Testing
+ * Library + Tiptap render against a real-ish DOM. Loaded via the test
+ * script's `--import` flag *before* any test file is imported, so React
+ * sees the DOM globals at module-load time (RTL's `cleanup()` and
+ * `render()` both expect `document` + `window` to exist as globals).
+ *
+ * We register a minimal subset of DOM globals: the rest hang off
+ * `window`, which is how the browser code under test reaches them. The
+ * `assign` helper preserves `globalThis`'s native bindings (e.g. Node's
+ * `URL`) when jsdom exports a shadowing constructor that breaks
+ * downstream code (Tiptap uses `URL` in extension-link's autolink
+ * heuristic).
+ */
+import { JSDOM } from 'jsdom'
+
+const dom = new JSDOM('<!DOCTYPE html><html><body></body></html>', {
+  url:               'http://localhost/',
+  pretendToBeVisual: true,
+})
+
+const window = dom.window as unknown as Window & typeof globalThis
+
+// Properties that Tiptap, React 19, and RTL touch directly via the
+// global namespace (rather than via the captured `window` reference).
+// Keep this list tight — every override is a place where jsdom and Node
+// can diverge subtly.
+const globals: Record<string, unknown> = {
+  window,
+  document:           window.document,
+  navigator:          window.navigator,
+  HTMLElement:        window.HTMLElement,
+  HTMLInputElement:   window.HTMLInputElement,
+  HTMLTextAreaElement: window.HTMLTextAreaElement,
+  HTMLAnchorElement:  window.HTMLAnchorElement,
+  HTMLDivElement:     window.HTMLDivElement,
+  HTMLSpanElement:    window.HTMLSpanElement,
+  Element:            window.Element,
+  Node:               window.Node,
+  Text:               window.Text,
+  Event:              window.Event,
+  MouseEvent:         window.MouseEvent,
+  KeyboardEvent:      window.KeyboardEvent,
+  CustomEvent:        window.CustomEvent,
+  DocumentFragment:   window.DocumentFragment,
+  Range:              window.Range,
+  Selection:          window.Selection,
+  MutationObserver:   window.MutationObserver,
+  IntersectionObserver: window.IntersectionObserver,
+  ResizeObserver:     window.ResizeObserver ?? class { observe() {} unobserve() {} disconnect() {} },
+  DOMRect:            window.DOMRect,
+  getComputedStyle:   window.getComputedStyle.bind(window),
+  requestAnimationFrame: (cb: FrameRequestCallback) => setTimeout(() => cb(performance.now()), 16) as unknown as number,
+  cancelAnimationFrame:  (id: number) => clearTimeout(id),
+}
+
+for (const [k, v] of Object.entries(globals)) {
+  Object.defineProperty(globalThis, k, { value: v, writable: true, configurable: true })
+}
+
+// React 19 + RTL require `IS_REACT_ACT_ENVIRONMENT` so `act()` warnings
+// don't fire on every render. Without it, Tiptap's mount cascade
+// produces dozens of warnings that swamp real test failures.
+;(globalThis as Record<string, unknown>)['IS_REACT_ACT_ENVIRONMENT'] = true