@prosekit/extensions 0.11.4 → 0.11.6

package/src/autocomplete/autocomplete-plugin.ts

@@ -0,0 +1,186 @@
+import { OBJECT_REPLACEMENT_CHARACTER } from '@prosekit/core'
+import {
+  Plugin,
+  type EditorState,
+  type Transaction,
+} from '@prosekit/pm/state'
+import {
+  Decoration,
+  DecorationSet,
+} from '@prosekit/pm/view'
+
+import {
+  getPluginState,
+  getTrMeta,
+  pluginKey,
+  setTrMeta,
+  type PredictionPluginMatching,
+  type PredictionPluginState,
+} from './autocomplete-helpers'
+import type { AutocompleteRule } from './autocomplete-rule'
+
+export function createAutocompletePlugin({
+  getRules,
+}: {
+  getRules: () => AutocompleteRule[]
+}): Plugin {
+  return new Plugin<PredictionPluginState>({
+    key: pluginKey,
+
+    state: {
+      init: (): PredictionPluginState => {
+        return { ignores: [], matching: null }
+      },
+      apply: (
+        tr: Transaction,
+        prevValue: PredictionPluginState,
+        oldState: EditorState,
+        newState: EditorState,
+      ): PredictionPluginState => {
+        const meta = getTrMeta(tr)
+
+        // No changes
+        if (
+          !tr.docChanged
+          && oldState.selection.eq(newState.selection)
+          && !meta
+        ) {
+          return prevValue
+        }
+
+        // Receiving a meta means that we are ignoring a match
+        if (meta) {
+          let ignores = prevValue.ignores
+          if (!ignores.includes(meta.ignore)) {
+            ignores = [...ignores, meta.ignore]
+          }
+          return { matching: null, ignores }
+        }
+
+        // Calculate the new ignores
+        const ignoreSet = new Set(prevValue.ignores.map(pos => tr.mapping.map(pos)))
+
+        // Calculate the new matching
+        let matching = calcPluginStateMatching(newState, getRules())
+
+        // Check if the matching should be ignored
+        if (matching && ignoreSet.has(matching.from)) {
+          matching = null
+        }
+
+        // Return the new matching and ignores
+        return { matching, ignores: Array.from(ignoreSet) }
+      },
+    },
+
+    view: () => ({
+      update: (view, prevState) => {
+        const prevValue = getPluginState(prevState)
+        const currValue = getPluginState(view.state)
+
+        if (
+          prevValue?.matching
+          && prevValue.matching.rule !== currValue?.matching?.rule
+        ) {
+          // Deactivate the previous rule
+          prevValue.matching.rule.onLeave?.()
+        }
+
+        if (
+          currValue?.matching
+          && !currValue.ignores.includes(currValue.matching.from)
+        ) {
+          // Activate the current rule
+
+          const { from, to, match, rule } = currValue.matching
+
+          const textContent = view.state.doc.textBetween(
+            from,
+            to,
+            null,
+            OBJECT_REPLACEMENT_CHARACTER,
+          )
+
+          const deleteMatch = () => {
+            if (
+              view.state.doc.textBetween(
+                from,
+                to,
+                null,
+                OBJECT_REPLACEMENT_CHARACTER,
+              ) === textContent
+            ) {
+              view.dispatch(view.state.tr.delete(from, to))
+            }
+          }
+
+          const ignoreMatch = () => {
+            view.dispatch(
+              setTrMeta(view.state.tr, { ignore: from }),
+            )
+          }
+
+          rule.onMatch({
+            state: view.state,
+            match,
+            from,
+            to,
+            deleteMatch,
+            ignoreMatch,
+          })
+        }
+      },
+    }),
+
+    props: {
+      decorations: (state: EditorState) => {
+        const pluginState = getPluginState(state)
+        if (pluginState?.matching) {
+          const { from, to } = pluginState.matching
+          const deco = Decoration.inline(from, to, {
+            class: 'prosemirror-prediction-match',
+          })
+          return DecorationSet.create(state.doc, [deco])
+        }
+        return null
+      },
+    },
+  })
+}
+
+const MAX_MATCH = 200
+
+function calcPluginStateMatching(
+  state: EditorState,
+  rules: AutocompleteRule[],
+): PredictionPluginMatching | null {
+  const $pos = state.selection.$from
+
+  const parentOffset: number = $pos.parentOffset
+
+  const textBefore: string = $pos.parent.textBetween(
+    Math.max(0, parentOffset - MAX_MATCH),
+    parentOffset,
+    null,
+    OBJECT_REPLACEMENT_CHARACTER,
+  )
+
+  for (const rule of rules) {
+    if (!rule.canMatch({ state })) {
+      continue
+    }
+
+    rule.regex.lastIndex = 0
+    const match = rule.regex.exec(textBefore)
+    if (!match) {
+      continue
+    }
+
+    const to = $pos.pos
+    const from = to - textBefore.length + match.index
+
+    return { rule, match, from, to }
+  }
+
+  return null
+}

package/src/autocomplete/autocomplete-rule.ts

@@ -0,0 +1,117 @@
+import type { EditorState } from '@prosekit/pm/state'
+
+import { defaultCanMatch } from './autocomplete-helpers'
+
+/**
+ * Options for the {@link MatchHandler} callback.
+ */
+export interface MatchHandlerOptions {
+  /**
+   * The editor state.
+   */
+  state: EditorState
+
+  /**
+   * The result of `RegExp.exec`.
+   */
+  match: RegExpExecArray
+
+  /**
+   * The start position of the matched text.
+   */
+  from: number
+
+  /**
+   * The end position of the matched text.
+   */
+  to: number
+
+  /**
+   * Call this function to ignore the match. You probably want to call this
+   * function when the user presses the `Escape` key.
+   */
+  ignoreMatch: () => void
+
+  /**
+   * Call this function to delete the matched text. For example, in a slash
+   * menu, you might want to delete the matched text first then do something
+   * else when the user presses the `Enter` key.
+   */
+  deleteMatch: () => void
+}
+
+/**
+ * A callback that is called when the rule starts to match, and also on
+ * subsequent updates while the rule continues to match.
+ */
+export type MatchHandler = (options: MatchHandlerOptions) => void
+
+/**
+ * Options for the {@link CanMatchPredicate} callback.
+ */
+export interface CanMatchOptions {
+  /**
+   * The editor state.
+   */
+  state: EditorState
+}
+
+/**
+ * A predicate to determine if the rule can be applied in the current editor state.
+ */
+export type CanMatchPredicate = (options: CanMatchOptions) => boolean
+
+/**
+ * Options for creating an {@link AutocompleteRule}
+ */
+export interface AutocompleteRuleOptions {
+  /**
+   * The regular expression to match against the text before the cursor. The
+   * last match before the cursor is used.
+   *
+   * For a slash menu, you might use `/(?<!\S)\/(|\S.*)$/u`.
+   * For a mention, you might use `/@\w*$/`
+   */
+  regex: RegExp
+
+  /**
+   * A callback that is called when the rule starts to match, and also on
+   * subsequent updates while the rule continues to match.
+   */
+  onEnter: MatchHandler
+
+  /**
+   * A callback that is called when the rule stops matching.
+   */
+  onLeave?: VoidFunction
+
+  /**
+   * A predicate to determine if the rule can be applied in the current editor
+   * state. If not provided, it defaults to only allowing matches in empty
+   * selections that are not inside a code block or code mark.
+   */
+  canMatch?: CanMatchPredicate
+}
+
+/**
+ * An autocomplete rule that can be used to create an autocomplete extension.
+ *
+ * @public
+ */
+export class AutocompleteRule {
+  /** @internal */
+  readonly regex: RegExp
+  /** @internal */
+  readonly onMatch: MatchHandler
+  /** @internal */
+  readonly onLeave?: VoidFunction
+  /** @internal */
+  readonly canMatch: (options: { state: EditorState }) => boolean
+
+  constructor(options: AutocompleteRuleOptions) {
+    this.regex = options.regex
+    this.onMatch = options.onEnter
+    this.onLeave = options.onLeave
+    this.canMatch = options.canMatch ?? defaultCanMatch
+  }
+}

package/src/autocomplete/autocomplete.spec.ts

@@ -0,0 +1,132 @@
+import {
+  canUseRegexLookbehind,
+  union,
+} from '@prosekit/core'
+import {
+  describe,
+  expect,
+  it,
+  vi,
+} from 'vitest'
+
+import {
+  defineTestExtension,
+  setupTestFromExtension,
+} from '../testing'
+import {
+  inputText,
+  pressKey,
+} from '../testing/keyboard'
+
+import { defineAutocomplete } from './autocomplete'
+import {
+  AutocompleteRule,
+  type MatchHandler,
+  type MatchHandlerOptions,
+} from './autocomplete-rule'
+
+function setupSlashMenu() {
+  const regex = canUseRegexLookbehind() ? /(?<!\S)\/(|\S.*)$/u : /\/(|\S.*)$/u
+
+  const onEnter = vi.fn<MatchHandler>()
+  const onLeave = vi.fn<VoidFunction>()
+
+  const rule = new AutocompleteRule({ regex, onEnter, onLeave })
+  const extension = union(defineTestExtension(), defineAutocomplete(rule))
+  const { editor, n, m } = setupTestFromExtension(extension)
+
+  const doc = n.doc(n.paragraph('<a>'))
+  editor.set(doc)
+
+  const getOnEnterOptions = (): MatchHandlerOptions => {
+    const parameters = onEnter.mock.calls.at(-1)
+    const options = parameters?.[0]
+    if (!options) {
+      throw new Error('No onEnter options found')
+    }
+    return options
+  }
+
+  return { editor, n, m, onEnter, onLeave, getOnEnterOptions }
+}
+
+describe('defineAutocomplete', () => {
+  it('can trigger onEnter', async () => {
+    const { onEnter, onLeave } = setupSlashMenu()
+
+    expect(onEnter).not.toHaveBeenCalled()
+    expect(onLeave).not.toHaveBeenCalled()
+
+    await inputText('/')
+    expect(onEnter).toHaveBeenCalledTimes(1)
+
+    await inputText('order')
+    expect(onEnter).toHaveBeenCalledTimes(6)
+
+    await inputText(' ')
+    expect(onEnter).toHaveBeenCalledTimes(7)
+
+    await inputText('list')
+    expect(onEnter).toHaveBeenCalledTimes(11)
+  })
+
+  it('can trigger onLeave', async () => {
+    const { onEnter, onLeave } = setupSlashMenu()
+
+    expect(onEnter).not.toHaveBeenCalled()
+    expect(onLeave).not.toHaveBeenCalled()
+
+    // Slash menu should be triggered when typing "/"
+    await inputText('/')
+    expect(onEnter).toHaveBeenCalledTimes(1)
+    expect(onLeave).toHaveBeenCalledTimes(0)
+
+    // Slash menu should not be triggered when typing "/ "
+    await pressKey('Space')
+    expect(onEnter).toHaveBeenCalledTimes(1)
+    expect(onLeave).toHaveBeenCalledTimes(1)
+  })
+
+  it('can delete the matched text', async () => {
+    const { editor, onEnter, getOnEnterOptions } = setupSlashMenu()
+
+    expect(onEnter).not.toHaveBeenCalled()
+
+    await inputText('/')
+    expect(onEnter).toHaveBeenCalledTimes(1)
+
+    const options = getOnEnterOptions()
+    expect(editor.state.doc.textContent).toBe('/')
+    options.deleteMatch()
+    expect(editor.state.doc.textContent).toBe('')
+  })
+
+  it('can ignore the match', async () => {
+    const { editor, onEnter, onLeave, getOnEnterOptions } = setupSlashMenu()
+
+    expect(onEnter).not.toHaveBeenCalled()
+
+    await inputText('/')
+    expect(onEnter).toHaveBeenCalledTimes(1)
+    expect(onLeave).toHaveBeenCalledTimes(0)
+    expect(editor.state.doc.textContent).toBe('/')
+
+    // Typing should trigger autocomplete
+    await inputText('a')
+    expect(onEnter).toHaveBeenCalledTimes(2)
+    expect(onLeave).toHaveBeenCalledTimes(0)
+    expect(editor.state.doc.textContent).toBe('/a')
+
+    // Call `ignoreMatch` to dismiss the match
+    const options = getOnEnterOptions()
+    options.ignoreMatch()
+    expect(onEnter).toHaveBeenCalledTimes(2)
+    expect(onLeave).toHaveBeenCalledTimes(1)
+
+    // Typing should not trigger autocomplete anymore
+    await inputText('a')
+    expect(onEnter).toHaveBeenCalledTimes(2)
+    expect(onLeave).toHaveBeenCalledTimes(1)
+    expect(editor.state.doc.textContent).toBe('/aa')
+  })
+})

package/src/autocomplete/autocomplete.ts

@@ -0,0 +1,29 @@
+import {
+  defineFacet,
+  defineFacetPayload,
+  pluginFacet,
+  type Extension,
+  type PluginPayload,
+} from '@prosekit/core'
+
+import { createAutocompletePlugin } from './autocomplete-plugin'
+import type { AutocompleteRule } from './autocomplete-rule'
+
+export function defineAutocomplete(rule: AutocompleteRule): Extension {
+  return defineFacetPayload(autocompleteFacet, [rule])
+}
+
+const autocompleteFacet = defineFacet<AutocompleteRule, PluginPayload>({
+  reduce: () => {
+    let rules: AutocompleteRule[] = []
+    const getRules = () => rules
+    const plugin = createAutocompletePlugin({ getRules })
+
+    return function reducer(inputs) {
+      rules = inputs
+      return plugin
+    }
+  },
+  parent: pluginFacet,
+  singleton: true,
+})

package/src/autocomplete/index.ts

@@ -0,0 +1,9 @@
+export { defineAutocomplete } from './autocomplete'
+export {
+  AutocompleteRule,
+  type AutocompleteRuleOptions,
+  type CanMatchOptions,
+  type CanMatchPredicate,
+  type MatchHandler,
+  type MatchHandlerOptions,
+} from './autocomplete-rule'

package/src/blockquote/blockquote-commands.ts

@@ -0,0 +1,32 @@
+import {
+  defineCommands,
+  insertNode,
+  toggleWrap,
+  wrap,
+  type Extension,
+} from '@prosekit/core'
+
+export type BlockquoteCommandsExtension = Extension<{
+  Commands: {
+    setBlockquote: []
+    insertBlockquote: []
+    toggleBlockquote: []
+  }
+}>
+
+/**
+ * @internal
+ */
+export function defineBlockquoteCommands(): BlockquoteCommandsExtension {
+  return defineCommands({
+    setBlockquote: () => {
+      return wrap({ type: 'blockquote' })
+    },
+    insertBlockquote: () => {
+      return insertNode({ type: 'blockquote' })
+    },
+    toggleBlockquote: () => {
+      return toggleWrap({ type: 'blockquote' })
+    },
+  })
+}

package/src/blockquote/blockquote-input-rule.ts

@@ -0,0 +1,14 @@
+import type { PlainExtension } from '@prosekit/core'
+
+import { defineWrappingInputRule } from '../input-rule'
+
+/**
+ * Wraps the text block in a blockquote when `>` is typed at the start of a new
+ * line followed by a space.
+ */
+export function defineBlockquoteInputRule(): PlainExtension {
+  return defineWrappingInputRule({
+    regex: /^>\s/,
+    type: 'blockquote',
+  })
+}

package/src/blockquote/blockquote-keymap.spec.ts

@@ -0,0 +1,45 @@
+import {
+  describe,
+  expect,
+  it,
+} from 'vitest'
+
+import { setupTest } from '../testing'
+import { pressKey } from '../testing/keyboard'
+
+describe('blockquote keymap', () => {
+  it('should wrap paragraph into blockquote with shortcut', async () => {
+    const { editor, n } = setupTest()
+
+    const doc1 = n.doc(n.p('hel<a>lo'))
+    editor.set(doc1)
+
+    await pressKey('mod-shift-b')
+
+    const doc2 = n.doc(n.blockquote(n.p('hello')))
+    expect(editor.state.doc.toJSON()).toEqual(doc2.toJSON())
+  })
+
+  it('should lift blockquote up with shortcut', async () => {
+    const { editor, n } = setupTest()
+    const doc1 = n.doc(n.blockquote(n.p('hello')))
+    editor.set(doc1)
+
+    await pressKey('mod-shift-b')
+
+    const doc2 = n.doc(n.p('hello'))
+    expect(editor.state.doc.toJSON()).toEqual(doc2.toJSON())
+  })
+
+  it('should unset blockquote when press backspace at the beginning of blockquote', async () => {
+    const { editor, n } = setupTest()
+    const doc1 = n.doc(n.blockquote(n.p('<a>hello')))
+
+    editor.set(doc1)
+
+    await pressKey('Backspace')
+
+    const doc2 = n.doc(n.p('hello'))
+    expect(editor.state.doc.toJSON()).toEqual(doc2.toJSON())
+  })
+})

package/src/blockquote/blockquote-keymap.ts

@@ -0,0 +1,31 @@
+import {
+  defineKeymap,
+  isAtBlockStart,
+  toggleWrap,
+  type PlainExtension,
+} from '@prosekit/core'
+import { joinBackward } from '@prosekit/pm/commands'
+import type { Command } from '@prosekit/pm/state'
+
+function toggleBlockquoteKeybinding(): Command {
+  return toggleWrap({ type: 'blockquote' })
+}
+
+function backspaceUnsetBlockquote(): Command {
+  return (state, dispatch, view) => {
+    const $pos = isAtBlockStart(state, view)
+    if ($pos?.node(-1).type.name === 'blockquote') {
+      return joinBackward(state, dispatch, view)
+    }
+    return false
+  }
+}
+/**
+ * @internal
+ */
+export function defineBlockquoteKeymap(): PlainExtension {
+  return defineKeymap({
+    'mod-shift-b': toggleBlockquoteKeybinding(),
+    'Backspace': backspaceUnsetBlockquote(),
+  })
+}

package/src/blockquote/blockquote-spec.ts

@@ -0,0 +1,24 @@
+import {
+  defineNodeSpec,
+  type Extension,
+} from '@prosekit/core'
+import type { Attrs } from '@prosekit/pm/model'
+
+export type BlockquoteSpecExtension = Extension<{
+  Nodes: {
+    blockquote: Attrs
+  }
+}>
+
+export function defineBlockquoteSpec(): BlockquoteSpecExtension {
+  return defineNodeSpec({
+    name: 'blockquote',
+    content: 'block+',
+    group: 'block',
+    defining: true,
+    parseDOM: [{ tag: 'blockquote' }],
+    toDOM() {
+      return ['blockquote', 0]
+    },
+  })
+}

package/src/blockquote/blockquote.ts

@@ -0,0 +1,34 @@
+import {
+  union,
+  type Union,
+} from '@prosekit/core'
+
+import {
+  defineBlockquoteCommands,
+  type BlockquoteCommandsExtension,
+} from './blockquote-commands'
+import { defineBlockquoteInputRule } from './blockquote-input-rule'
+import { defineBlockquoteKeymap } from './blockquote-keymap'
+import {
+  defineBlockquoteSpec,
+  type BlockquoteSpecExtension,
+} from './blockquote-spec'
+
+/**
+ * @internal
+ */
+export type BlockquoteExtension = Union<
+  [BlockquoteSpecExtension, BlockquoteCommandsExtension]
+>
+
+/**
+ * @public
+ */
+export function defineBlockquote(): BlockquoteExtension {
+  return union(
+    defineBlockquoteSpec(),
+    defineBlockquoteInputRule(),
+    defineBlockquoteCommands(),
+    defineBlockquoteKeymap(),
+  )
+}

package/src/blockquote/index.ts

@@ -0,0 +1,14 @@
+export {
+  defineBlockquote,
+  type BlockquoteExtension,
+} from './blockquote'
+export {
+  defineBlockquoteCommands,
+  type BlockquoteCommandsExtension,
+} from './blockquote-commands'
+export { defineBlockquoteInputRule } from './blockquote-input-rule'
+export { defineBlockquoteKeymap } from './blockquote-keymap'
+export {
+  defineBlockquoteSpec,
+  type BlockquoteSpecExtension,
+} from './blockquote-spec'

package/src/bold/bold-commands.ts

@@ -0,0 +1,23 @@
+import {
+  defineCommands,
+  toggleMark,
+  type Extension,
+} from '@prosekit/core'
+
+/**
+ * @internal
+ */
+export type BoldCommandsExtension = Extension<{
+  Commands: {
+    toggleBold: []
+  }
+}>
+
+/**
+ * @internal
+ */
+export function defineBoldCommands(): BoldCommandsExtension {
+  return defineCommands({
+    toggleBold: () => toggleMark({ type: 'bold' }),
+  })
+}