@tiptap/extension-find-and-replace 3.29.0

package/src/plugin/plugin-state.ts

@@ -0,0 +1,27 @@
+import type { DecorationSet } from '@tiptap/pm/view'
+
+import type { SearchResult } from '../search/search.js'
+
+export interface FindAndReplacePluginState {
+  searchTerm: string
+  replaceTerm: string
+  caseSensitive: boolean
+  useRegex: boolean
+  wholeWord: boolean
+  results: SearchResult[]
+  currentIndex: number | null
+  decorations: DecorationSet
+}
+
+/**
+ * Transaction meta to patch the plugin state. Setting `searchTerm`,
+ * `caseSensitive`, `useRegex` or `wholeWord` re-runs the search.
+ */
+export interface FindAndReplaceMeta {
+  searchTerm?: string
+  replaceTerm?: string
+  caseSensitive?: boolean
+  useRegex?: boolean
+  wholeWord?: boolean
+  currentIndex?: number | null
+}

package/src/plugin/plugin.ts

@@ -0,0 +1,60 @@
+import { Plugin, PluginKey } from '@tiptap/pm/state'
+
+import { currentResultClass, resultClass } from '../constants/constants.js'
+import { createStyleTag } from '../style/create-style-tag.js'
+import type { FindAndReplaceMeta, FindAndReplacePluginState } from './plugin-state.js'
+import { style } from '../style/style.js'
+import type { FindAndReplaceOptions } from '../types.js'
+import { createState, updateState } from '../utils/index.js'
+
+export { currentResultClass, resultClass }
+export type { FindAndReplaceMeta, FindAndReplacePluginState }
+
+export const FindAndReplacePluginKey = new PluginKey<FindAndReplacePluginState>('findAndReplace')
+
+export const FindAndReplacePlugin = (
+  options: FindAndReplaceOptions,
+  onCreate: (pluginState: FindAndReplacePluginState) => void,
+) => {
+  return new Plugin<FindAndReplacePluginState>({
+    key: FindAndReplacePluginKey,
+
+    state: {
+      init: (_config, state) => {
+        if (options.injectCSS && typeof document !== 'undefined') {
+          createStyleTag(style, options.injectNonce)
+        }
+
+        const pluginState = createState(state.doc, options)
+        onCreate(pluginState)
+
+        return pluginState
+      },
+
+      apply: (tr, state, _oldState, newState) => {
+        const meta = tr.getMeta(FindAndReplacePluginKey) as FindAndReplaceMeta | undefined
+
+        if (!meta && !tr.docChanged) {
+          return state
+        }
+
+        return updateState(
+          state,
+          { ...state, ...meta },
+          newState.doc,
+          meta,
+          tr.docChanged,
+          tr.mapping,
+        )
+      },
+    },
+
+    props: {
+      decorations(state) {
+        return FindAndReplacePluginKey.getState(state)?.decorations
+      },
+    },
+  })
+}
+
+export default FindAndReplacePlugin

package/src/search/matches.ts

@@ -0,0 +1,26 @@
+import { RE2JS } from 're2js'
+
+import type { SearchRegex } from './regex.js'
+
+interface TextMatch {
+  index: number
+  value: string
+}
+
+function* findNativeMatches(regex: RegExp, text: string): Generator<TextMatch> {
+  for (const match of text.matchAll(regex)) {
+    yield { index: match.index, value: match[0] }
+  }
+}
+
+function* findSafeMatches(regex: RE2JS, text: string): Generator<TextMatch> {
+  const matcher = regex.matcher(text)
+
+  while (matcher.find()) {
+    yield { index: matcher.start(), value: matcher.group() ?? '' }
+  }
+}
+
+export function findMatches(regex: SearchRegex, text: string): Generator<TextMatch> {
+  return regex instanceof RegExp ? findNativeMatches(regex, text) : findSafeMatches(regex, text)
+}

package/src/search/regex.ts

@@ -0,0 +1,67 @@
+import { RE2JS } from 're2js'
+
+import type { SearchOptions } from './types.js'
+
+export type SearchRegex = RegExp | RE2JS
+
+const escapeRegExp = (value: string): string => {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/** Unicode word characters like letters, accents, numbers, and underscore-like punctuation. */
+const unicodeWordCharacter = '[\\p{L}\\p{M}\\p{N}\\p{Pc}]'
+
+function compileNativeRegex(source: string, caseSensitive: boolean): RegExp | null {
+  try {
+    return new RegExp(source, caseSensitive ? 'gu' : 'giu')
+  } catch {
+    return null
+  }
+}
+
+function compileSafeRegex(source: string, caseSensitive: boolean): RE2JS | null {
+  try {
+    const flags = caseSensitive ? 0 : RE2JS.CASE_INSENSITIVE
+
+    return RE2JS.compile(source, flags)
+  } catch {
+    return null
+  }
+}
+
+function compileRegex(
+  source: string,
+  options: Pick<SearchOptions, 'caseSensitive' | 'useRegex'>,
+): SearchRegex | null {
+  return options.useRegex
+    ? compileSafeRegex(source, options.caseSensitive)
+    : compileNativeRegex(source, options.caseSensitive)
+}
+
+/**
+ * Creates a search matcher for a term.
+ * Regex mode uses RE2-compatible syntax to avoid catastrophic backtracking.
+ * @param term The search term, treated as regex source when `useRegex` is enabled.
+ * @param options Case sensitivity, regex mode, and whole word matching.
+ * @returns A compiled matcher, or `null` when the term is invalid or unsupported.
+ */
+export function createSearchRegex(term: string, options: SearchOptions): SearchRegex | null {
+  if (!term) {
+    return null
+  }
+
+  let source: string
+
+  if (options.useRegex) {
+    source = term
+  } else {
+    const escaped = escapeRegExp(term)
+
+    // Whole-word searches reject terms next to another Unicode word character.
+    source = options.wholeWord
+      ? `(?<!${unicodeWordCharacter})${escaped}(?!${unicodeWordCharacter})`
+      : escaped
+  }
+
+  return compileRegex(source, options)
+}

package/src/search/search.ts

@@ -0,0 +1,70 @@
+import type { Node } from '@tiptap/pm/model'
+
+import { createSearchRegex } from './regex.js'
+import { searchTextblock } from './textblock-search.js'
+import type { SearchOptions, SearchResult, TextblockSearchTarget } from './types.js'
+
+export type { SearchOptions, SearchResult, TextblockSearchTarget } from './types.js'
+export { createSearchRegex } from './regex.js'
+
+/**
+ * Searches textblocks for a term and returns their matched ranges.
+ * @param textblocks The textblocks and their document positions.
+ * @param term The search term, treated as regex source when `useRegex` is enabled.
+ * @param options Case sensitivity, regex mode, and whole word matching.
+ * @returns The list of matched ranges in textblock order.
+ */
+export function searchTextblocks(
+  textblocks: readonly TextblockSearchTarget[],
+  term: string,
+  options: SearchOptions,
+): SearchResult[] {
+  const regex = createSearchRegex(term, options)
+
+  if (!regex) {
+    return []
+  }
+
+  return textblocks.flatMap(({ node, pos }) => searchTextblock(regex, node, pos))
+}
+
+/**
+ * Searches all textblocks of a document for a term and returns the matched ranges.
+ * Matches may span multiple text nodes (e.g. across marks), but never leave a textblock.
+ * @param doc The document to search in.
+ * @param term The search term, treated as regex source when `useRegex` is enabled.
+ * @param options Case sensitivity, regex mode, and whole word matching.
+ * @returns The list of matched ranges in document order.
+ */
+export function searchDocument(doc: Node, term: string, options: SearchOptions): SearchResult[] {
+  const textblocks: TextblockSearchTarget[] = []
+
+  doc.descendants((node, pos) => {
+    if (!node.isTextblock) {
+      return true
+    }
+
+    textblocks.push({ node, pos })
+
+    return false
+  })
+
+  return searchTextblocks(textblocks, term, options)
+}
+
+/**
+ * Finds the index of the first result at or after a position, wrapping around
+ * to the first result when the position is behind the last result.
+ * @param results The current search results.
+ * @param from The position to search from.
+ * @returns The result index, or `null` when there are no results.
+ */
+export function findNextIndex(results: SearchResult[], from: number): number | null {
+  if (results.length === 0) {
+    return null
+  }
+
+  const index = results.findIndex(result => result.from >= from)
+
+  return index === -1 ? 0 : index
+}

package/src/search/text-segments.ts

@@ -0,0 +1,63 @@
+import type { Node } from '@tiptap/pm/model'
+
+interface TextSegment {
+  isText: boolean
+  pos: number
+  length: number
+  text: string
+  textOffset: number
+}
+
+// Non-text inline nodes (hard break, mention, ...) contribute a placeholder
+// so matches never silently span across them.
+export function getTextSegments(textblock: Node, pos: number): TextSegment[] {
+  const segments: TextSegment[] = []
+  let textOffset = 0
+
+  textblock.forEach((child, offset) => {
+    const text = child.isText ? (child.text ?? '') : '\n'
+
+    segments.push({
+      isText: child.isText,
+      pos: pos + 1 + offset,
+      length: child.nodeSize,
+      text,
+      textOffset,
+    })
+    textOffset += text.length
+  })
+
+  return segments
+}
+
+function findOffsetSegment(segments: TextSegment[], offset: number): TextSegment | undefined {
+  let low = 0
+  let high = segments.length
+
+  while (low < high) {
+    const middle = Math.floor((low + high) / 2)
+    const segment = segments[middle]
+    const segmentEnd = segment.textOffset + segment.text.length
+
+    if (offset < segmentEnd) {
+      high = middle
+    } else {
+      low = middle + 1
+    }
+  }
+
+  return segments[low] ?? segments.at(-1)
+}
+
+export function offsetToPos(segments: TextSegment[], offset: number): number {
+  const segment = findOffsetSegment(segments, offset)
+
+  return segment ? segment.pos + Math.min(offset - segment.textOffset, segment.length) : 0
+}
+
+export function overlapsNonTextSegment(segments: TextSegment[], from: number, to: number): boolean {
+  return segments.some(
+    segment =>
+      !segment.isText && from < segment.textOffset + segment.text.length && to > segment.textOffset,
+  )
+}

package/src/search/textblock-search.ts

@@ -0,0 +1,31 @@
+import type { Node } from '@tiptap/pm/model'
+
+import { findMatches } from './matches.js'
+import type { SearchRegex } from './regex.js'
+import { getTextSegments, offsetToPos, overlapsNonTextSegment } from './text-segments.js'
+import type { SearchResult } from './types.js'
+
+export function searchTextblock(regex: SearchRegex, textblock: Node, pos: number): SearchResult[] {
+  const segments = getTextSegments(textblock, pos)
+  const text = segments.map(segment => segment.text).join('')
+  const results: SearchResult[] = []
+
+  for (const match of findMatches(regex, text)) {
+    if (match.value.length === 0) {
+      continue
+    }
+
+    const matchEnd = match.index + match.value.length
+
+    if (overlapsNonTextSegment(segments, match.index, matchEnd)) {
+      continue
+    }
+
+    results.push({
+      from: offsetToPos(segments, match.index),
+      to: offsetToPos(segments, matchEnd),
+    })
+  }
+
+  return results
+}

package/src/search/types.ts

@@ -0,0 +1,17 @@
+import type { Node } from '@tiptap/pm/model'
+
+export interface SearchResult {
+  from: number
+  to: number
+}
+
+export interface TextblockSearchTarget {
+  node: Node
+  pos: number
+}
+
+export interface SearchOptions {
+  caseSensitive: boolean
+  useRegex: boolean
+  wholeWord: boolean
+}

package/src/state/debounced-search-state.ts

@@ -0,0 +1,39 @@
+import type { Editor } from '@tiptap/core'
+
+export interface DebouncedSearchState {
+  timeout: ReturnType<typeof setTimeout> | null
+  pendingTerm: string | null
+}
+
+const debouncedSearchState = new WeakMap<Editor, DebouncedSearchState>()
+
+export function getDebouncedSearchState(editor: Editor): DebouncedSearchState {
+  const existingState = debouncedSearchState.get(editor)
+
+  if (existingState) {
+    return existingState
+  }
+
+  const nextState: DebouncedSearchState = {
+    timeout: null,
+    pendingTerm: null,
+  }
+
+  debouncedSearchState.set(editor, nextState)
+
+  return nextState
+}
+
+export function clearDebouncedSearchState(editor: Editor): void {
+  const state = debouncedSearchState.get(editor)
+
+  if (!state) {
+    return
+  }
+
+  if (state.timeout !== null) {
+    clearTimeout(state.timeout)
+  }
+
+  debouncedSearchState.delete(editor)
+}

package/src/style/create-style-tag.ts

@@ -0,0 +1,23 @@
+export const createStyleTag = (style: string, nonce?: string): HTMLStyleElement => {
+  const existing = document.querySelector<HTMLStyleElement>(
+    'style[data-tiptap-extension-find-and-replace-style]',
+  )
+
+  if (existing !== null) {
+    return existing
+  }
+
+  const styleNode = document.createElement('style')
+
+  if (nonce) {
+    styleNode.setAttribute('nonce', nonce)
+  }
+
+  styleNode.setAttribute('data-tiptap-extension-find-and-replace-style', '')
+  styleNode.textContent = style
+  document.getElementsByTagName('head')[0].appendChild(styleNode)
+
+  return styleNode
+}
+
+export default createStyleTag

package/src/style/style.ts

@@ -0,0 +1,10 @@
+export const style = `.find-and-replace-result {
+  background-color: rgb(255 225 0 / 0.4);
+}
+
+.find-and-replace-result-current {
+  background-color: rgb(255 165 0 / 0.55);
+}
+`
+
+export default style

package/src/types.ts

@@ -0,0 +1,96 @@
+import type { SearchResult } from './search/search.js'
+
+export interface FindAndReplaceOptions {
+  /**
+   * The initial search term.
+   * @default ''
+   */
+  searchTerm: string
+
+  /**
+   * The initial replace term.
+   * @default ''
+   */
+  replaceTerm: string
+
+  /**
+   * Whether the search is case sensitive.
+   * @default false
+   */
+  caseSensitive: boolean
+
+  /**
+   * Whether the search term is treated as an RE2-compatible regular expression.
+   * Lookarounds and backreferences are not supported.
+   * @default false
+   */
+  useRegex: boolean
+
+  /**
+   * Whether to match whole words only. Ignored when `useRegex` is enabled.
+   * @default false
+   */
+  wholeWord: boolean
+
+  /**
+   * Debounce delay in milliseconds applied to `setSearchTerm`.
+   * Set to `0` to disable debouncing.
+   * @default 250
+   */
+  searchDebounceMs: number
+
+  /**
+   * Whether the default result highlight styles are injected.
+   * @default true
+   */
+  injectCSS: boolean
+
+  /**
+   * A nonce for the injected style tag, needed for strict CSP setups.
+   * @default undefined
+   */
+  injectNonce: string | undefined
+}
+
+export interface FindAndReplaceStorage {
+  /**
+   * The current search term.
+   */
+  searchTerm: string
+
+  /**
+   * The current replace term.
+   */
+  replaceTerm: string
+
+  /**
+   * Whether the search is case sensitive.
+   */
+  caseSensitive: boolean
+
+  /**
+   * Whether the search term is treated as an RE2-compatible regular expression.
+   */
+  useRegex: boolean
+
+  /**
+   * Whether to match whole words only. Ignored when `useRegex` is enabled.
+   */
+  wholeWord: boolean
+
+  /**
+   * The current search results in document order.
+   */
+  results: SearchResult[]
+
+  /**
+   * The index of the current result, or `null` when no result is selected.
+   */
+  currentIndex: number | null
+}
+
+declare module '@tiptap/core' {
+  interface Storage {
+    findAndReplace: FindAndReplaceStorage
+  }
+}

package/src/utils/createDecoration.ts

@@ -0,0 +1,14 @@
+import { Decoration } from '@tiptap/pm/view'
+
+import { currentResultClass, resultClass } from '../constants/constants.js'
+import type { SearchResult } from '../search/search.js'
+
+export function createDecoration(
+  result: SearchResult,
+  currentIndex: number | null,
+  index: number,
+): Decoration {
+  const className = index === currentIndex ? `${resultClass} ${currentResultClass}` : resultClass
+
+  return Decoration.inline(result.from, result.to, { class: className })
+}

package/src/utils/createDecorations.ts

@@ -0,0 +1,16 @@
+import type { Node } from '@tiptap/pm/model'
+import { DecorationSet } from '@tiptap/pm/view'
+
+import type { SearchResult } from '../search/search.js'
+
+import { createDecoration } from './createDecoration.js'
+
+export function createDecorations(
+  doc: Node,
+  results: SearchResult[],
+  currentIndex: number | null,
+): DecorationSet {
+  const decorations = results.map((result, index) => createDecoration(result, currentIndex, index))
+
+  return DecorationSet.create(doc, decorations)
+}

package/src/utils/createState.ts

@@ -0,0 +1,23 @@
+import type { Node } from '@tiptap/pm/model'
+
+import type { FindAndReplaceOptions } from '../types.js'
+import type { FindAndReplacePluginState } from '../plugin/plugin-state.js'
+import { searchDocument } from '../search/search.js'
+
+import { createDecorations } from './createDecorations.js'
+
+export function createState(doc: Node, options: FindAndReplaceOptions): FindAndReplacePluginState {
+  const results = searchDocument(doc, options.searchTerm, options)
+  const currentIndex = results.length > 0 ? 0 : null
+
+  return {
+    searchTerm: options.searchTerm,
+    replaceTerm: options.replaceTerm,
+    caseSensitive: options.caseSensitive,
+    useRegex: options.useRegex,
+    wholeWord: options.wholeWord,
+    results,
+    currentIndex,
+    decorations: createDecorations(doc, results, currentIndex),
+  }
+}

package/src/utils/findDecorations.ts

@@ -0,0 +1,27 @@
+import { Decoration, DecorationSet } from '@tiptap/pm/view'
+
+import type { SearchResult } from '../search/search.js'
+
+import type { TextblockRange } from './types.js'
+
+export function findDecorations(
+  decorations: DecorationSet,
+  results: readonly SearchResult[],
+  textblocks: readonly TextblockRange[],
+): Decoration[] {
+  const found = new Set<Decoration>()
+
+  textblocks.forEach(textblock => {
+    decorations.find(textblock.from, textblock.to).forEach(decoration => found.add(decoration))
+  })
+
+  results.forEach(result => {
+    decorations
+      .find(result.from, result.to, decoration => {
+        return decoration.from === result.from && decoration.to === result.to
+      })
+      .forEach(decoration => found.add(decoration))
+  })
+
+  return [...found]
+}

package/src/utils/getChangedTextblocks.ts

@@ -0,0 +1,29 @@
+import type { Node } from '@tiptap/pm/model'
+import type { Mapping } from '@tiptap/pm/transform'
+
+import type { TextblockRange } from './types.js'
+
+export function getChangedTextblocks(doc: Node, mapping: Mapping): TextblockRange[] {
+  const textblocks = new Map<number, TextblockRange>()
+
+  mapping.maps.forEach((stepMap, index) => {
+    const remaining = mapping.slice(index + 1)
+
+    stepMap.forEach((_oldStart, _oldEnd, newStart, newEnd) => {
+      const from = Math.max(0, remaining.map(newStart, -1) - 1)
+      const to = Math.min(doc.content.size, remaining.map(newEnd, 1) + 1)
+
+      doc.nodesBetween(from, to, (node, pos) => {
+        if (!node.isTextblock) {
+          return true
+        }
+
+        textblocks.set(pos, { node, pos, from: pos, to: pos + node.nodeSize })
+
+        return false
+      })
+    })
+  })
+
+  return [...textblocks.values()].sort((first, second) => first.pos - second.pos)
+}

package/src/utils/getFallbackCurrentIndex.ts

@@ -0,0 +1,8 @@
+import type { FindAndReplacePluginState } from '../plugin/plugin-state.js'
+
+export function getFallbackCurrentIndex(
+  previousState: FindAndReplacePluginState,
+  length: number,
+): number {
+  return previousState.currentIndex === null ? 0 : Math.min(previousState.currentIndex, length - 1)
+}