@prosekit/extensions 0.11.4 → 0.11.6

package/src/paste-rule/paste-rule-plugin.ts

@@ -0,0 +1,53 @@
+import {
+  defineFacet,
+  defineFacetPayload,
+  pluginFacet,
+  type PlainExtension,
+  type PluginPayload,
+} from '@prosekit/core'
+import type { Slice } from '@prosekit/pm/model'
+import {
+  PluginKey,
+  ProseMirrorPlugin,
+} from '@prosekit/pm/state'
+import type { EditorView } from '@prosekit/pm/view'
+
+type PasteRulePayload = (options: { slice: Slice; view: EditorView; plain: boolean }) => Slice
+
+/**
+ * @internal
+ */
+const pasteRuleFacet = defineFacet<PasteRulePayload, PluginPayload>({
+  reduce: () => {
+    let handlers: PasteRulePayload[] = []
+
+    const transformPasted = (slice: Slice, view: EditorView, plain: boolean): Slice => {
+      for (const handler of handlers) {
+        slice = handler({ slice, view, plain })
+      }
+      return slice
+    }
+
+    const plugin = new ProseMirrorPlugin({
+      key: new PluginKey('prosekit-paste-rule'),
+      props: {
+        transformPasted,
+      },
+    })
+
+    return (inputs: PasteRulePayload[]) => {
+      // Last added rule (highest priority) is applied first
+      handlers = [...inputs].reverse()
+      return plugin
+    }
+  },
+  singleton: true,
+  parent: pluginFacet,
+})
+
+/**
+ * @internal
+ */
+export function definePasteRulePlugin(payload: PasteRulePayload): PlainExtension {
+  return defineFacetPayload(pasteRuleFacet, [payload]) as PlainExtension
+}

package/src/paste-rule/paste-rule.spec.ts

@@ -0,0 +1,96 @@
+import {
+  Priority,
+  union,
+  withPriority,
+  type PlainExtension,
+} from '@prosekit/core'
+import type { ProseMirrorNode } from '@prosekit/pm/model'
+import {
+  Fragment,
+  Slice,
+} from '@prosekit/pm/model'
+import {
+  describe,
+  expect,
+  it,
+} from 'vitest'
+
+import {
+  defineTestExtension,
+  setupTestFromExtension,
+} from '../testing'
+
+import { definePasteRule } from './paste-rule'
+
+function replaceTextInSlice(slice: Slice, from: string, to: string): Slice {
+  return new Slice(
+    replaceTextInFragment(slice.content, from, to),
+    slice.openStart,
+    slice.openEnd,
+  )
+}
+
+function replaceTextInFragment(fragment: Fragment, from: string, to: string): Fragment {
+  return Fragment.fromArray(fragment.content.map(node => replaceTextInNode(node, from, to)))
+}
+
+function replaceTextInNode(node: ProseMirrorNode, from: string, to: string): ProseMirrorNode {
+  const text = node.text
+  if (text != null) {
+    return node.type.schema.text(text.replaceAll(from, to))
+  }
+  return node.copy(replaceTextInFragment(node.content, from, to))
+}
+
+function defineTextReplacePasteRule(from: string, to: string): PlainExtension {
+  return definePasteRule({
+    handler: ({ slice }) => {
+      return replaceTextInSlice(slice, from, to)
+    },
+  })
+}
+
+describe('paste rule', () => {
+  it('can transform pasted HTML', () => {
+    const extension = union(
+      defineTestExtension(),
+      defineTextReplacePasteRule('Foo', 'Bar'),
+    )
+    const { editor } = setupTestFromExtension(extension)
+    editor.view.pasteHTML('<div>Foo</div>')
+    expect(editor.getDocHTML()).not.toContain(`Foo`)
+    expect(editor.getDocHTML()).toContain(`Bar`)
+  })
+
+  it('can transform pasted text', () => {
+    const extension = union(
+      defineTestExtension(),
+      defineTextReplacePasteRule('Foo', 'Bar'),
+    )
+    const { editor } = setupTestFromExtension(extension)
+    editor.view.pasteText('Foo')
+    expect(editor.getDocHTML()).not.toContain(`Foo`)
+    expect(editor.getDocHTML()).toContain(`Bar`)
+  })
+
+  it('can order multiple paste rules', () => {
+    const extension = union(
+      defineTestExtension(),
+      withPriority(defineTextReplacePasteRule('Foo', 'Bar'), Priority.high),
+      withPriority(defineTextReplacePasteRule('Foo', 'Baz'), Priority.low),
+    )
+    const { editor } = setupTestFromExtension(extension)
+    editor.view.pasteText('Foo')
+    expect(editor.getDocHTML()).not.toContain(`Foo`)
+    expect(editor.getDocHTML()).toContain(`Bar`)
+    expect(editor.getDocHTML()).not.toContain(`Baz`)
+
+    editor.use(defineTextReplacePasteRule('Bar', 'Qux'))
+    editor.setContent('')
+    editor.view.pasteText('Foo')
+    expect(editor.getDocHTML()).not.toContain(`Foo`)
+    expect(editor.getDocHTML()).not.toContain(`Bar`)
+    expect(editor.getDocHTML()).not.toContain(`Baz`)
+    expect(editor.getDocHTML()).toContain(`Qux`)
+  })
+})

package/src/paste-rule/paste-rule.ts

@@ -0,0 +1,60 @@
+import type { PlainExtension } from '@prosekit/core'
+import type { Slice } from '@prosekit/pm/model'
+import type { EditorView } from '@prosekit/pm/view'
+
+import { definePasteRulePlugin } from './paste-rule-plugin'
+
+/**
+ * @public
+ *
+ * Options for {@link PasteRuleHandler}.
+ */
+export interface PasteRuleHandlerOptions {
+  /**
+   * The slice to be pasted.
+   */
+  slice: Slice
+
+  /**
+   * The editor view.
+   */
+  view: EditorView
+
+  /**
+   * Whether the pasted content is treated as plain text. This is true when the
+   * `Shift` key is held when pasting.
+   */
+  plain: boolean
+}
+
+/**
+ * @public
+ *
+ * Can be used to transform pasted or dragged-and-dropped content before it is
+ * applied to the document.
+ */
+export type PasteRuleHandler = (options: PasteRuleHandlerOptions) => Slice
+
+/**
+ * Options for {@link definePasteRule}.
+ *
+ * @public
+ */
+export interface PasteRuleOptions {
+  /**
+   * A function to be called when a paste rule is triggered.
+   */
+  handler: PasteRuleHandler
+}
+
+/**
+ * Defines a paste rule. This rule allows you to modify pasted or dragged
+ * content before it is inserted into the document.
+ *
+ * @param options
+ *
+ * @public
+ */
+export function definePasteRule({ handler }: PasteRuleOptions): PlainExtension {
+  return definePasteRulePlugin(handler)
+}

package/src/paste-rule/split-text-by-regex.spec.ts

@@ -0,0 +1,97 @@
+import {
+  describe,
+  expect,
+  it,
+} from 'vitest'
+
+import { splitTextByRegex } from './split-text-by-regex'
+
+describe('splitTextByRegex', () => {
+  it('should return undefined when no matches are found', () => {
+    const result = splitTextByRegex('hello world', /\d+/g)
+    expect(result).toBeUndefined()
+  })
+
+  it('should split text with single match', () => {
+    const result = splitTextByRegex('hello 123 world', /\d+/g)
+    expect(result).toEqual([
+      ['hello ', undefined],
+      ['123', expect.objectContaining({ 0: '123', index: 6 })],
+      [' world', undefined],
+    ])
+  })
+
+  it('should split text with multiple matches', () => {
+    const result = splitTextByRegex('abc 123 def 456 ghi', /\d+/g)
+    expect(result).toEqual([
+      ['abc ', undefined],
+      ['123', expect.objectContaining({ 0: '123', index: 4 })],
+      [' def ', undefined],
+      ['456', expect.objectContaining({ 0: '456', index: 12 })],
+      [' ghi', undefined],
+    ])
+  })
+
+  it('should handle match at the beginning', () => {
+    const result = splitTextByRegex('123 hello', /\d+/g)
+    expect(result).toEqual([
+      ['123', expect.objectContaining({ 0: '123', index: 0 })],
+      [' hello', undefined],
+    ])
+  })
+
+  it('should handle match at the end', () => {
+    const result = splitTextByRegex('hello 123', /\d+/g)
+    expect(result).toEqual([
+      ['hello ', undefined],
+      ['123', expect.objectContaining({ 0: '123', index: 6 })],
+    ])
+  })
+
+  it('should handle consecutive matches', () => {
+    const result = splitTextByRegex('123456', /\d/g)
+    expect(result).toEqual([
+      ['1', expect.objectContaining({ 0: '1', index: 0 })],
+      ['2', expect.objectContaining({ 0: '2', index: 1 })],
+      ['3', expect.objectContaining({ 0: '3', index: 2 })],
+      ['4', expect.objectContaining({ 0: '4', index: 3 })],
+      ['5', expect.objectContaining({ 0: '5', index: 4 })],
+      ['6', expect.objectContaining({ 0: '6', index: 5 })],
+    ])
+  })
+
+  it('should handle entire string match', () => {
+    const result = splitTextByRegex('123', /\d+/g)
+    expect(result).toEqual([
+      ['123', expect.objectContaining({ 0: '123', index: 0 })],
+    ])
+  })
+
+  it('should work with URL regex', () => {
+    const urlRegex = /https?:\/\/\S+/g
+    const result = splitTextByRegex('Visit https://example.com for more info', urlRegex)
+    expect(result).toEqual([
+      ['Visit ', undefined],
+      ['https://example.com', expect.objectContaining({ 0: 'https://example.com', index: 6 })],
+      [' for more info', undefined],
+    ])
+  })
+
+  it('should reset regex lastIndex', () => {
+    const regex = /\d+/g
+    regex.lastIndex = 5 // Set to non-zero
+    const result = splitTextByRegex('123 456', regex)
+    expect(result).toEqual([
+      ['123', expect.objectContaining({ 0: '123', index: 0 })],
+      [' ', undefined],
+      ['456', expect.objectContaining({ 0: '456', index: 4 })],
+    ])
+    expect(regex.lastIndex).toBe(0) // Should be reset
+  })
+
+  it('should return undefined for zero-width matches', () => {
+    const regex = /(?=b)/g
+    const result = splitTextByRegex('abc', regex)
+    expect(result).toBeUndefined()
+  })
+})

package/src/paste-rule/split-text-by-regex.ts

@@ -0,0 +1,44 @@
+/**
+ * Splits text into chunks based on regex matches, preserving both matched and unmatched segments.
+ * Returns an array of tuples where each tuple contains a text segment and either the match data
+ * (for matched segments) or undefined (for unmatched segments).
+ */
+export function splitTextByRegex(
+  text: string,
+  regex: RegExp,
+): Array<[string, RegExpExecArray | undefined]> | undefined {
+  regex.lastIndex = 0
+
+  const chunks: Array<[string, RegExpExecArray | undefined]> = []
+  let lastIndex = 0
+  let match: RegExpExecArray | null
+  let matched = false
+
+  while ((match = regex.exec(text))) {
+    const start = match.index
+    const end = regex.lastIndex
+
+    // Push the unmatched prefix, if any.
+    if (start > lastIndex) {
+      chunks.push([text.slice(lastIndex, start), undefined])
+    }
+
+    // Push the matched segment.
+    chunks.push([text.slice(start, end), match])
+    matched = true
+
+    if (lastIndex === end) {
+      // Safeguard against zero-width matches that would otherwise cause an infinite loop.
+      return
+    }
+    lastIndex = end
+  }
+
+  if (matched && lastIndex < text.length) {
+    chunks.push([text.slice(lastIndex), undefined])
+  }
+
+  regex.lastIndex = 0
+
+  return matched ? chunks : undefined
+}

package/src/placeholder/index.ts

@@ -0,0 +1,113 @@
+import {
+  definePlugin,
+  isInCodeBlock,
+  maybeRun,
+  type PlainExtension,
+} from '@prosekit/core'
+import type { ProseMirrorNode } from '@prosekit/pm/model'
+import {
+  Plugin,
+  PluginKey,
+  type EditorState,
+} from '@prosekit/pm/state'
+import {
+  Decoration,
+  DecorationSet,
+} from '@prosekit/pm/view'
+
+import { findTable } from '../table'
+
+export interface PlaceholderOptions {
+  /**
+   * The placeholder to use. It can be a static string or a function that
+   * receives the current editor state and returns a string.
+   */
+  placeholder: string | ((state: EditorState) => string)
+
+  /**
+   * By default, the placeholder text will be shown whenever the current text
+   * cursor is in an empty text node and it's not inside a code block or a
+   * table node.
+   *
+   * If you only want to show the placeholder when the whole doc is empty, you
+   * can set this option to 'doc'.
+   *
+   * You can also pass a function that receives the current editor state and
+   * returns a boolean value to determine whether the placeholder should be
+   * shown.
+   *
+   * @default 'block'
+   */
+  strategy?: 'doc' | 'block' | ((state: EditorState) => boolean)
+}
+
+/**
+ * Add a placeholder text to the editor when the current block or document is
+ * empty.
+ */
+export function definePlaceholder(options: PlaceholderOptions): PlainExtension {
+  return definePlugin(createPlaceholderPlugin(options))
+}
+
+function createPlaceholderPlugin({
+  placeholder,
+  strategy = 'block',
+}: PlaceholderOptions): Plugin {
+  return new Plugin({
+    key: new PluginKey('prosekit-placeholder'),
+    props: {
+      decorations: (state) => {
+        const strategyFn = typeof strategy === 'function'
+          ? strategy
+          : strategy === 'doc'
+          ? docStrategy
+          : defaultStrategy
+
+        if (!strategyFn(state)) {
+          return null
+        }
+
+        const placeholderText: string = maybeRun(placeholder, state)
+        const deco = createPlaceholderDecoration(state, placeholderText)
+        if (!deco) {
+          return null
+        }
+
+        return DecorationSet.create(state.doc, [deco])
+      },
+    },
+  })
+}
+
+function defaultStrategy(state: EditorState): boolean {
+  return !isInCodeBlock(state.selection) && !findTable(state.selection.$from)
+}
+
+function docStrategy(state: EditorState): boolean {
+  return isDocEmpty(state.doc) && defaultStrategy(state)
+}
+
+function isDocEmpty(doc: ProseMirrorNode) {
+  return doc.childCount <= 1 && !doc.firstChild?.content.size
+}
+
+function createPlaceholderDecoration(
+  state: EditorState,
+  placeholderText: string,
+): Decoration | null {
+  if (!placeholderText) return null
+
+  const { selection } = state
+  if (!selection.empty) return null
+
+  const $pos = selection.$anchor
+  const node = $pos.parent
+  if (node.content.size > 0) return null
+
+  const before = $pos.before()
+
+  return Decoration.node(before, before + node.nodeSize, {
+    'class': 'prosekit-placeholder',
+    'data-placeholder': placeholderText,
+  })
+}

package/src/placeholder/style.css

@@ -0,0 +1,7 @@
+.prosekit-placeholder::before {
+  position: absolute;
+  height: 0;
+  content: attr(data-placeholder);
+  opacity: 30%;
+  pointer-events: none;
+}

package/src/readonly/index.ts

@@ -0,0 +1,22 @@
+import {
+  definePlugin,
+  type PlainExtension,
+} from '@prosekit/core'
+import {
+  PluginKey,
+  ProseMirrorPlugin,
+} from '@prosekit/pm/state'
+
+/**
+ * Make the editor read-only.
+ */
+export function defineReadonly(): PlainExtension {
+  return definePlugin(plugin)
+}
+
+const plugin = new ProseMirrorPlugin({
+  key: new PluginKey('prosekey-readonly'),
+  props: {
+    editable: () => false,
+  },
+})

package/src/search/index.ts

@@ -0,0 +1,140 @@
+import {
+  defineCommands,
+  definePlugin,
+  type Extension,
+  type PlainExtension,
+} from '@prosekit/core'
+import type { Command } from '@prosekit/pm/state'
+import type { EditorView } from '@prosekit/pm/view'
+import {
+  findNext,
+  findNextNoWrap,
+  findPrev,
+  findPrevNoWrap,
+  replaceAll,
+  replaceCurrent,
+  replaceNext,
+  replaceNextNoWrap,
+  search,
+  SearchQuery,
+} from 'prosemirror-search'
+
+/**
+ * Options for {@link defineSearchQuery}
+ *
+ * @public
+ */
+export interface SearchQueryOptions {
+  /**
+   * The search string (or regular expression).
+   */
+  search: string
+
+  /**
+   * The replace text.
+   */
+  replace?: string
+
+  /**
+   * Indicates whether the search is case-sensitive
+   *
+   * @default false
+   */
+  caseSensitive?: boolean
+
+  /**
+   * By default, string search will replace `\n`, `\r`, and `\t` in the query
+   * with newline, return, and tab characters. When this is set to true, that
+   * behavior is disabled.
+   *
+   * @default false
+   */
+  literal?: boolean
+
+  /**
+   * When true, the search string is interpreted as a regular expression.
+   *
+   * @default false
+   */
+  regexp?: boolean
+
+  /**
+   * Enable whole-word matching.
+   *
+   * @default false
+   */
+  wholeWord?: boolean
+}
+
+/**
+ * Defines an extension that stores a current search query and replace string.
+ *
+ * @public
+ */
+export function defineSearchQuery(options: SearchQueryOptions): PlainExtension {
+  const query = new SearchQuery(options)
+  return definePlugin(search({ initialQuery: query }))
+}
+
+/**
+ * Scrolls the active search match into view.
+ */
+function scrollActiveIntoView(view: EditorView) {
+  if (view.isDestroyed) return
+  const active = view.dom.querySelector('.ProseMirror-active-search-match')
+  active?.scrollIntoView({
+    block: 'nearest',
+    inline: 'nearest',
+    behavior: 'smooth',
+  })
+}
+
+/**
+ * Wraps a command and scrolls the active search match into view when the command
+ * is applied.
+ */
+function withScrollActiveIntoView(command: Command): Command {
+  return (state, dispatch, view) => {
+    const result = command(state, dispatch, view)
+    if (result && dispatch && view) {
+      // Add a small delay because the command itself will handle scrolling if
+      // the view is focused.
+      setTimeout(() => scrollActiveIntoView(view), 50)
+    }
+    return result
+  }
+}
+
+/**
+ * @internal
+ */
+export type SearchCommandsExtension = Extension<{
+  Commands: {
+    findNext: []
+    findPrev: []
+    findNextNoWrap: []
+    findPrevNoWrap: []
+    replaceNext: []
+    replaceNextNoWrap: []
+    replaceCurrent: []
+    replaceAll: []
+  }
+}>
+
+/**
+ * Defines commands for search and replace.
+ *
+ * @public
+ */
+export function defineSearchCommands(): SearchCommandsExtension {
+  return defineCommands({
+    findNext: () => withScrollActiveIntoView(findNext),
+    findPrev: () => withScrollActiveIntoView(findPrev),
+    findNextNoWrap: () => withScrollActiveIntoView(findNextNoWrap),
+    findPrevNoWrap: () => withScrollActiveIntoView(findPrevNoWrap),
+    replaceNext: () => withScrollActiveIntoView(replaceNext),
+    replaceNextNoWrap: () => withScrollActiveIntoView(replaceNextNoWrap),
+    replaceCurrent: () => withScrollActiveIntoView(replaceCurrent),
+    replaceAll: () => withScrollActiveIntoView(replaceAll),
+  })
+}

package/src/search/style.css

@@ -0,0 +1,13 @@
+.ProseMirror-search-match {
+  border-radius: 2px;
+  background-color: #ffff0054;
+  box-shadow: 0 0 0 2px #ffff0054;
+}
+
+.ProseMirror.ProseMirror-focused .ProseMirror-active-search-match::selection,
+.ProseMirror:not(.ProseMirror-focused) .ProseMirror-active-search-match {
+  border-radius: 2px;
+  background-color: #ff6a0054;
+  box-shadow: 0 0 0 2px #ff6a0054;
+  scroll-margin: 8px;
+}