@tiptap/suggestion 3.26.1 → 3.27.0

package/src/helpers.ts

@@ -0,0 +1,129 @@
+import type { Editor, Range } from '@tiptap/core'
+import type { EditorState, PluginKey, Transaction } from '@tiptap/pm/state'
+import type { EditorView } from '@tiptap/pm/view'
+
+import type { SuggestionMatch } from './findSuggestionMatch.js'
+import type { SuggestionOptions, SuggestionPluginState } from './types.js'
+
+/**
+ * Returns true if the transaction inserted any whitespace or newline character.
+ * Used to determine when a dismissed suggestion should become active again.
+ */
+export function hasInsertedWhitespace(transaction: Transaction): boolean {
+  if (!transaction.docChanged) {
+    return false
+  }
+  return transaction.steps.some(step => {
+    const slice = (step as any).slice
+    if (!slice?.content) {
+      return false
+    }
+    // textBetween with '\n' as block separator catches both inline spaces and newlines
+    const inserted = slice.content.textBetween(0, slice.content.size, '\n')
+    return /\s/.test(inserted)
+  })
+}
+
+/**
+ * Gets the DOM rectangle corresponding to the current editor cursor anchor position.
+ * Calculates screen coordinates based on Tiptap's cursor position and converts to a DOMRect object.
+ */
+export function getAnchorClientRect(editor: Editor): () => DOMRect | null {
+  return () => {
+    const pos = editor.state.selection.$anchor.pos
+    const coords = editor.view.coordsAtPos(pos)
+    const { top, right, bottom, left } = coords
+
+    try {
+      return new DOMRect(left, top, right - left, bottom - top)
+    } catch {
+      return null
+    }
+  }
+}
+
+/**
+ * Creates a clientRect callback for a given decoration node.
+ * Returns the anchor rect when no decoration node is present.
+ * Uses the pluginKey's state to resolve the current decoration node on demand.
+ */
+export function clientRectFor(
+  editor: Editor,
+  view: EditorView,
+  decorationNode: Element | null,
+  pluginKey: PluginKey,
+): () => DOMRect | null {
+  if (!decorationNode) {
+    return getAnchorClientRect(editor)
+  }
+
+  return () => {
+    const state: SuggestionPluginState = pluginKey.getState(editor.state) as any
+    const decorationId = state?.decorationId
+    const currentDecorationNode = view.dom.querySelector(`[data-decoration-id="${decorationId}"]`)
+
+    return currentDecorationNode?.getBoundingClientRect() || null
+  }
+}
+
+/**
+ * Determines whether a dismissed suggestion should stay dismissed.
+ * Returns `true` (keep dismissed) or `false` (allow reactivation).
+ */
+export function shouldKeepDismissed({
+  match,
+  dismissedRange,
+  state,
+  transaction,
+  editor,
+  shouldResetDismissed,
+  effectiveAllowSpaces,
+}: {
+  match: Exclude<SuggestionMatch, null>
+  dismissedRange: Range
+  state: EditorState
+  transaction: Transaction
+  editor: Editor
+  shouldResetDismissed?: SuggestionOptions['shouldResetDismissed']
+  effectiveAllowSpaces: boolean
+}): boolean {
+  if (
+    shouldResetDismissed?.({
+      editor,
+      state,
+      range: dismissedRange,
+      match,
+      transaction,
+      allowSpaces: effectiveAllowSpaces,
+    })
+  ) {
+    return false
+  }
+
+  if (effectiveAllowSpaces) {
+    return match.range.from === dismissedRange.from
+  }
+
+  return match.range.from === dismissedRange.from && !hasInsertedWhitespace(transaction)
+}
+
+/**
+ * Dispatch an exit of the suggestion plugin by dispatching a metadata-only
+ * transaction to clear the plugin state. The renderer's onExit hook is NOT
+ * called here — it fires via the plugin view's stopped transition, which
+ * builds SuggestionProps consistently with the normal lifecycle.
+ *
+ * This prevents a double onExit call (one from dispatchExit, one from the
+ * view's update) and keeps exitSuggestion consistent with Escape-triggered
+ * exits.
+ */
+export function dispatchExit({
+  view,
+  pluginKeyRef,
+}: {
+  view: EditorView
+  pluginKeyRef: PluginKey
+}): void {
+  const tr = view.state.tr.setMeta(pluginKeyRef, { exit: true })
+  view.dispatch(tr)
+}

package/src/plugin/async.ts

@@ -0,0 +1,89 @@
+import type { Editor } from '@tiptap/core'
+
+import type { SuggestionOptions } from '../types.js'
+
+export interface CreateSuggestionAsyncRequestManagerOptions<I = any> {
+  editor: Editor
+  items: NonNullable<SuggestionOptions<I>['items']>
+}
+
+type AsyncRequestResult<I> =
+  | { status: 'resolved'; items: I[] }
+  | { status: 'aborted' }
+  | { status: 'error' }
+
+export function createSuggestionAsyncRequestManager<I = any>({
+  editor,
+  items,
+}: CreateSuggestionAsyncRequestManagerOptions<I>) {
+  let abortController: AbortController | null = null
+  let debounceTimer: ReturnType<typeof setTimeout> | null = null
+  let debounceResolve: (() => void) | null = null
+
+  const clearDebounceTimer = () => {
+    if (debounceTimer !== null) {
+      clearTimeout(debounceTimer)
+      debounceTimer = null
+    }
+
+    debounceResolve?.()
+    debounceResolve = null
+  }
+
+  const waitForDebounce = (delay: number) => {
+    return new Promise<void>(resolve => {
+      debounceResolve = resolve
+      debounceTimer = setTimeout(() => {
+        debounceTimer = null
+        const pendingResolve = debounceResolve
+        debounceResolve = null
+        pendingResolve?.()
+      }, delay)
+    })
+  }
+
+  const abort = () => {
+    abortController?.abort()
+    clearDebounceTimer()
+    abortController = null
+  }
+
+  const fetch = async (query: string, debounce: number): Promise<AsyncRequestResult<I>> => {
+    abort()
+    abortController = new AbortController()
+    const controller = abortController
+
+    if (debounce > 0) {
+      await waitForDebounce(debounce)
+    }
+
+    if (abortController !== controller || controller.signal.aborted) {
+      return { status: 'aborted' }
+    }
+
+    try {
+      const result = await items({
+        editor,
+        query,
+        signal: controller.signal,
+      })
+
+      if (abortController !== controller || controller.signal.aborted) {
+        return { status: 'aborted' }
+      }
+
+      return { status: 'resolved', items: result }
+    } catch {
+      if (abortController !== controller || controller.signal.aborted) {
+        return { status: 'aborted' }
+      }
+
+      return { status: 'error' }
+    }
+  }
+
+  return {
+    abort,
+    fetch,
+  }
+}

package/src/plugin/floating-ui.ts

@@ -0,0 +1,204 @@
+import type { Middleware, VirtualElement } from '@floating-ui/dom'
+import {
+  autoUpdate,
+  computePosition,
+  flip as floatingUiFlip,
+  offset as floatingUiOffset,
+} from '@floating-ui/dom'
+
+import type {
+  SuggestionFloatingUiConfig,
+  SuggestionFloatingUiOptions,
+  SuggestionMount,
+  SuggestionPlacement,
+} from '../types.js'
+
+export interface CreateSuggestionFloatingUiConfigOptions {
+  placement: SuggestionPlacement
+  offset: { mainAxis?: number; crossAxis?: number }
+  flip: boolean
+  floatingUi?: SuggestionFloatingUiOptions
+}
+
+export function createSuggestionFloatingUiConfig({
+  placement,
+  offset,
+  flip,
+  floatingUi,
+}: CreateSuggestionFloatingUiConfigOptions): SuggestionFloatingUiConfig {
+  const middleware: Middleware[] = [
+    floatingUiOffset({
+      mainAxis: offset.mainAxis ?? 4,
+      crossAxis: offset.crossAxis ?? 0,
+    }),
+  ]
+
+  if (flip) {
+    middleware.push(floatingUiFlip())
+  }
+
+  if (floatingUi?.middleware?.length) {
+    middleware.push(...floatingUi.middleware)
+  }
+
+  return {
+    placement,
+    strategy: floatingUi?.strategy ?? 'absolute',
+    middleware,
+  }
+}
+
+export interface CreateMountOptions {
+  /** Returns the current cursor/anchor rect the popup should track. */
+  getReferenceRect: () => DOMRect | null
+  /**
+   * An element inside the editor's layout/scroll context. Floating UI walks up
+   * from here to discover the scroll ancestors (and the window) to observe, so
+   * the scroll container does not need to be configured manually.
+   */
+  contextElement: Element
+  /** Resolved Floating UI config (placement, strategy, middleware). */
+  config: SuggestionFloatingUiConfig
+  /**
+   * CSS selector or element the popup should be mounted into. Defaults to
+   * `document.body`. Used to portal the popup inside dialogs/modals so it
+   * renders on top of (and clips within) the right context.
+   */
+  container?: string | HTMLElement
+  /**
+   * When `true`, a pointerdown outside both the popup and the editor dismisses
+   * the suggestion. Wired up and torn down alongside the mounted element.
+   */
+  dismissOnOutsideClick: boolean
+  /** Dismisses the active suggestion (used by outside-click handling). */
+  dismiss: () => void
+}
+
+/**
+ * Resolves a container option (selector or element) to a mount target,
+ * falling back to `document.body` when it can't be resolved.
+ */
+function resolveContainer(container?: string | HTMLElement): HTMLElement {
+  if (container instanceof HTMLElement) {
+    return container
+  }
+
+  if (typeof container === 'string') {
+    try {
+      // `container` is consumer-provided; an invalid selector throws a
+      // DOMException, so fall back to document.body instead of crashing.
+      const found = document.querySelector<HTMLElement>(container)
+
+      if (found) {
+        return found
+      }
+    } catch {
+      return document.body
+    }
+  }
+
+  return document.body
+}
+
+/**
+ * Builds the `mount` function handed to the renderer on `SuggestionProps`.
+ *
+ * Mounts the popup into the container, then wires Floating UI's `autoUpdate`
+ * against a virtual reference that re-reads the live cursor rect, so the popup
+ * stays anchored across scroll, resize, and layout shifts without the consumer
+ * attaching any listeners. The returned `unmount` tears all of that down.
+ */
+export function createMount({
+  getReferenceRect,
+  contextElement,
+  config,
+  container,
+  dismissOnOutsideClick,
+  dismiss,
+}: CreateMountOptions): SuggestionMount {
+  return (element, options = {}) => {
+    const reference: VirtualElement = {
+      getBoundingClientRect: () => getReferenceRect() ?? new DOMRect(),
+      contextElement,
+    }
+
+    let positioned = false
+
+    // Mount the popup into the container (default `document.body`) unless the
+    // consumer already placed it in the DOM themselves — in which case we leave
+    // mounting (and unmounting) to them.
+    const mountedByUs = !element.isConnected
+
+    if (mountedByUs) {
+      resolveContainer(container).appendChild(element)
+    }
+
+    // Hide the element until the first measurement resolves so it doesn't flash
+    // at its initial coordinates. Skipped when the consumer owns applying the
+    // position via `onPosition`.
+    if (!options.onPosition) {
+      element.style.visibility = 'hidden'
+      element.style.width = 'max-content'
+    }
+
+    const update = () => {
+      computePosition(reference, element, {
+        placement: config.placement,
+        strategy: config.strategy,
+        middleware: config.middleware,
+      }).then(({ x, y, placement, strategy }) => {
+        if (options.onPosition) {
+          options.onPosition({ x, y, placement: placement as SuggestionPlacement, strategy })
+          return
+        }
+
+        Object.assign(element.style, {
+          position: strategy,
+          left: `${x}px`,
+          top: `${y}px`,
+        })
+
+        if (!positioned) {
+          positioned = true
+          element.style.visibility = ''
+        }
+      })
+    }
+
+    const cleanupAutoUpdate = autoUpdate(reference, element, update, options.autoUpdate)
+
+    // Dismiss when the user interacts outside both the popup and the editor.
+    // Capture phase so a parent that stops propagation can't swallow it.
+    let onOutsidePointerDown: ((event: PointerEvent) => void) | undefined
+
+    if (dismissOnOutsideClick) {
+      onOutsidePointerDown = event => {
+        const target = event.target
+
+        if (
+          !(target instanceof Node) ||
+          element.contains(target) ||
+          contextElement.contains(target)
+        ) {
+          return
+        }
+
+        dismiss()
+      }
+
+      document.addEventListener('pointerdown', onOutsidePointerDown, true)
+    }
+
+    return () => {
+      cleanupAutoUpdate()
+
+      if (onOutsidePointerDown) {
+        document.removeEventListener('pointerdown', onOutsidePointerDown, true)
+      }
+
+      if (mountedByUs) {
+        element.remove()
+      }
+    }
+  }
+}

package/src/plugin/props.ts

@@ -0,0 +1,94 @@
+import type { EditorState, PluginKey } from '@tiptap/pm/state'
+import type { EditorView } from '@tiptap/pm/view'
+import { Decoration, DecorationSet } from '@tiptap/pm/view'
+
+import type { SuggestionKeyDownProps, SuggestionPluginState } from '../types.js'
+
+/**
+ * Creates the `props` object for the suggestion ProseMirror plugin.
+ * Contains `handleKeyDown` for keyboard handling and `decorations`
+ * for rendering the suggestion highlight.
+ */
+export interface CreateSuggestionPropsOptions {
+  pluginKey: PluginKey
+  decorationTag: string
+  decorationClass: string
+  decorationContent: string
+  decorationEmptyClass: string
+  renderer: { onKeyDown?: (props: SuggestionKeyDownProps) => boolean } | undefined
+  dispatchExit: (view: EditorView) => void
+}
+
+/**
+ * Creates the `props` object for the suggestion ProseMirror plugin.
+ * Contains `handleKeyDown` for keyboard handling and `decorations`
+ * for rendering the suggestion highlight.
+ */
+export function createSuggestionProps({
+  pluginKey,
+  decorationTag,
+  decorationClass,
+  decorationContent,
+  decorationEmptyClass,
+  renderer,
+  dispatchExit,
+}: CreateSuggestionPropsOptions) {
+  return {
+    /**
+     * Call the keydown hook if suggestion is active.
+     */
+    handleKeyDown(view: EditorView, event: KeyboardEvent) {
+      const state: SuggestionPluginState = pluginKey.getState(view.state) as any
+
+      if (!state.active) {
+        return false
+      }
+
+      // If Escape is pressed, call onKeyDown and dispatch a metadata-only
+      // transaction to unset the suggestion state. This provides a safe
+      // and deterministic way to exit the suggestion without altering the
+      // document (avoids transaction mapping/mismatch issues).
+      if (event.key === 'Escape' || event.key === 'Esc') {
+        // Allow the consumer to react to Escape, but always clear the
+        // suggestion state afterward so the decoration is removed too.
+        renderer?.onKeyDown?.({ view, event, range: state.range })
+
+        // dispatch metadata-only transaction to unset the plugin state
+        dispatchExit(view)
+
+        return true
+      }
+
+      const handled = renderer?.onKeyDown?.({ view, event, range: state.range }) || false
+      return handled
+    },
+
+    /**
+     * Setup decorator on the currently active suggestion.
+     */
+    decorations(state: EditorState) {
+      const pluginState: SuggestionPluginState = pluginKey.getState(state) as any
+      const { active, range, decorationId, query } = pluginState
+
+      if (!active) {
+        return null
+      }
+
+      const isEmpty = !query?.length
+      const classNames = [decorationClass]
+
+      if (isEmpty) {
+        classNames.push(decorationEmptyClass)
+      }
+
+      return DecorationSet.create(state.doc, [
+        Decoration.inline(range.from, range.to, {
+          nodeName: decorationTag,
+          class: classNames.join(' '),
+          'data-decoration-id': decorationId || undefined,
+          'data-decoration-content': decorationContent,
+        }),
+      ])
+    },
+  }
+}

package/src/plugin/state.ts

@@ -0,0 +1,182 @@
+import type { Editor, Range } from '@tiptap/core'
+import type { EditorState, PluginKey, Transaction } from '@tiptap/pm/state'
+
+import type {
+  findSuggestionMatch as defaultFindSuggestionMatch,
+  SuggestionMatch,
+} from '../findSuggestionMatch.js'
+import type { SuggestionOptions, SuggestionPluginState } from '../types.js'
+
+export interface CreateSuggestionStateOptions {
+  editor: Editor
+  char: string
+  effectiveAllowSpaces: boolean
+  allowToIncludeChar: boolean
+  allowedPrefixes: string[] | null
+  startOfLine: boolean
+  findSuggestionMatch: typeof defaultFindSuggestionMatch
+  allow: Exclude<SuggestionOptions['allow'], undefined>
+  shouldShow?: SuggestionOptions['shouldShow']
+  shouldKeepDismissed: (props: {
+    match: Exclude<SuggestionMatch, null>
+    dismissedRange: Range
+    state: EditorState
+    transaction: Transaction
+  }) => boolean
+  pluginKey: PluginKey
+}
+
+/**
+ * Creates the `state` object for the suggestion ProseMirror plugin.
+ * Contains `init()` and `apply()` for managing the plugin's internal state
+ * across transactions.
+ */
+export function createSuggestionState({
+  editor,
+  char,
+  effectiveAllowSpaces,
+  allowToIncludeChar,
+  allowedPrefixes,
+  startOfLine,
+  findSuggestionMatch,
+  allow,
+  shouldShow,
+  shouldKeepDismissed,
+  pluginKey,
+}: CreateSuggestionStateOptions) {
+  return {
+    /**
+     * Initialize the plugin's internal state.
+     */
+    init(): SuggestionPluginState {
+      return {
+        active: false,
+        range: { from: 0, to: 0 },
+        query: null,
+        text: null,
+        composing: false,
+        dismissedRange: null,
+      }
+    },
+
+    /**
+     * Apply changes to the plugin state from a view transaction.
+     */
+    apply(
+      transaction: Transaction,
+      prev: SuggestionPluginState,
+      _oldState: EditorState,
+      state: EditorState,
+    ): SuggestionPluginState {
+      const { isEditable } = editor
+      const { composing } = editor.view
+      const { selection } = transaction
+      const { empty, from } = selection
+      const next = { ...prev }
+
+      // If a transaction carries the exit meta for this plugin, immediately
+      // deactivate the suggestion. This allows metadata-only transactions
+      // (dispatched by escape or programmatic exit) to deterministically
+      // clear decorations without changing the document.
+      const meta = transaction.getMeta(pluginKey)
+      if (meta && meta.exit) {
+        next.active = false
+        next.decorationId = null
+        next.range = { from: 0, to: 0 }
+        next.query = null
+        next.text = null
+        next.dismissedRange = prev.active ? { ...prev.range } : prev.dismissedRange
+
+        return next
+      }
+
+      next.composing = composing
+
+      if (transaction.docChanged && next.dismissedRange !== null) {
+        next.dismissedRange = {
+          from: transaction.mapping.map(next.dismissedRange.from),
+          to: transaction.mapping.map(next.dismissedRange.to),
+        }
+      }
+
+      // We can only be suggesting if the view is editable, and:
+      //   * there is no selection, or
+      //   * a composition is active (see: https://github.com/ueberdosis/tiptap/issues/1449)
+      if (isEditable && (empty || editor.view.composing)) {
+        // Reset active state if we just left the previous suggestion range
+        if ((from < prev.range.from || from > prev.range.to) && !composing && !prev.composing) {
+          next.active = false
+        }
+
+        // Try to match against where our cursor currently is
+        const match = findSuggestionMatch({
+          char,
+          allowSpaces: effectiveAllowSpaces,
+          allowToIncludeChar,
+          allowedPrefixes,
+          startOfLine,
+          $position: selection.$from,
+        })
+        const decorationId = `id_${Math.floor(Math.random() * 0xffffffff)}`
+
+        // If we found a match, update the current state to show it
+        if (
+          match &&
+          allow({
+            editor,
+            state,
+            range: match.range,
+            isActive: prev.active,
+          }) &&
+          (!shouldShow ||
+            shouldShow({
+              editor,
+              range: match.range,
+              query: match.query,
+              text: match.text,
+              transaction,
+            }))
+        ) {
+          if (
+            next.dismissedRange !== null &&
+            !shouldKeepDismissed({
+              match,
+              dismissedRange: next.dismissedRange,
+              state,
+              transaction,
+            })
+          ) {
+            next.dismissedRange = null
+          }
+
+          if (next.dismissedRange === null) {
+            next.active = true
+            next.decorationId = prev.decorationId || decorationId
+            next.range = match.range
+            next.query = match.query
+            next.text = match.text
+          } else {
+            next.active = false
+          }
+        } else {
+          if (!match) {
+            next.dismissedRange = null
+          }
+          next.active = false
+        }
+      } else {
+        next.active = false
+      }
+
+      // Make sure to empty the range if suggestion is inactive
+      if (!next.active) {
+        next.decorationId = null
+        next.range = { from: 0, to: 0 }
+        next.query = null
+        next.text = null
+      }
+
+      return next
+    },
+  }
+}