@prosekit/core 0.8.3 → 0.8.5

package/src/extensions/plugin.spec.ts

@@ -0,0 +1,153 @@
+import {
+  Plugin,
+  PluginKey,
+} from '@prosekit/pm/state'
+import {
+  describe,
+  expect,
+  it,
+  vi,
+} from 'vitest'
+
+import { union } from '../editor/union'
+import { withPriority } from '../editor/with-priority'
+import {
+  defineDoc,
+  defineParagraph,
+  defineText,
+  setupTestFromExtension,
+} from '../testing'
+import { Priority } from '../types/priority'
+
+import { definePlugin } from './plugin'
+
+describe('plugin', () => {
+  it('maintains plugin order in state based on priority', () => {
+    const plugins = {
+      a: new Plugin({ key: new PluginKey('a') }),
+      b: new Plugin({ key: new PluginKey('b') }),
+      c: new Plugin({ key: new PluginKey('c') }),
+      d: new Plugin({ key: new PluginKey('d') }),
+      e: new Plugin({ key: new PluginKey('e') }),
+    }
+
+    const extension1 = definePlugin(() => [plugins.a, plugins.d]) // default priority
+    const extension2 = withPriority(definePlugin(plugins.b), Priority.highest)
+    const extension3 = withPriority(definePlugin([plugins.c]), Priority.lowest)
+    const extension4 = definePlugin(plugins.e) // default priority
+
+    const { editor } = setupTestFromExtension(union(
+      defineDoc(),
+      defineParagraph(),
+      defineText(),
+      extension1,
+      extension2,
+      extension3,
+      extension4,
+    ))
+
+    const pluginKeys = editor.state.plugins.map((plugin) => {
+      for (const [key, value] of Object.entries(plugins)) {
+        if (plugin === value) {
+          return key
+        }
+      }
+      return undefined
+    }).filter(Boolean)
+
+    // The plugins with the highest priority should be listed
+    // first in state. The plugins with the same priority should be listed in
+    // the order of the extensions.
+    expect(pluginKeys).toEqual([
+      // Highest priority
+      'b',
+
+      // Default priority, added in the last extension
+      'e',
+
+      // Default priority, added as the second plugin in the first extension
+      'd',
+
+      // Default priority, added as the first plugin in the first extension
+      'a',
+
+      // Lowest priority
+      'c',
+    ])
+  })
+
+  it('calls handlers in priority order with highest priority first', () => {
+    const callOrder: string[] = []
+
+    const handleKeyDownA = vi.fn(() => {
+      callOrder.push('a')
+      return false
+    })
+    const handleKeyDownB = vi.fn(() => {
+      callOrder.push('b')
+      return false
+    })
+    const handleKeyDownC = vi.fn(() => {
+      callOrder.push('c')
+      return false
+    })
+    const handleKeyDownD = vi.fn(() => {
+      callOrder.push('d')
+      return false
+    })
+    const handleKeyDownE = vi.fn(() => {
+      callOrder.push('e')
+      return false
+    })
+
+    const plugins = {
+      a: new Plugin({ props: { handleKeyDown: handleKeyDownA } }),
+      b: new Plugin({ props: { handleKeyDown: handleKeyDownB } }),
+      c: new Plugin({ props: { handleKeyDown: handleKeyDownC } }),
+      d: new Plugin({ props: { handleKeyDown: handleKeyDownD } }),
+      e: new Plugin({ props: { handleKeyDown: handleKeyDownE } }),
+    }
+
+    const extension1 = definePlugin(() => [plugins.a, plugins.d]) // default priority
+    const extension2 = withPriority(definePlugin(plugins.b), Priority.highest)
+    const extension3 = withPriority(definePlugin([plugins.c]), Priority.lowest)
+    const extension4 = definePlugin(plugins.e) // default priority
+
+    const { editor } = setupTestFromExtension(union(
+      defineDoc(),
+      defineParagraph(),
+      defineText(),
+      extension1,
+      extension2,
+      extension3,
+      extension4,
+    ))
+
+    editor.view.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowUp' }))
+
+    // All handlers should be called since none returns true
+    expect(handleKeyDownA).toHaveBeenCalledTimes(1)
+    expect(handleKeyDownB).toHaveBeenCalledTimes(1)
+    expect(handleKeyDownC).toHaveBeenCalledTimes(1)
+    expect(handleKeyDownD).toHaveBeenCalledTimes(1)
+    expect(handleKeyDownE).toHaveBeenCalledTimes(1)
+
+    // The event handlers of the plugins with the highest priority should be called first
+    expect(callOrder).toEqual([
+      // Highest priority
+      'b',
+
+      // Default priority, added in the last extension
+      'e',
+
+      // Default priority, added as the second plugin in the first extension
+      'd',
+
+      // Default priority, added as the first plugin in the first extension
+      'a',
+
+      // Lowest priority
+      'c',
+    ])
+  })
+})

package/src/extensions/plugin.ts

@@ -0,0 +1,81 @@
+import type { Schema } from '@prosekit/pm/model'
+import {
+  Plugin,
+  type ProseMirrorPlugin,
+} from '@prosekit/pm/state'
+
+import { ProseKitError } from '../error'
+import {
+  defineFacet,
+  type Facet,
+} from '../facets/facet'
+import { defineFacetPayload } from '../facets/facet-extension'
+import {
+  stateFacet,
+  type StatePayload,
+} from '../facets/state'
+import type { PlainExtension } from '../types/extension'
+import { toReversed } from '../utils/array'
+
+/**
+ * Adds a ProseMirror plugin to the editor.
+ *
+ * @param plugin - The ProseMirror plugin to add, or an array of plugins, or a
+ * function that returns one or multiple plugins.
+ *
+ * @public
+ */
+export function definePlugin(
+  plugin:
+    | Plugin
+    | Plugin[]
+    | ((context: { schema: Schema }) => Plugin | Plugin[]),
+): PlainExtension {
+  return definePluginPayload(plugin)
+}
+
+function definePluginPayload(payload: PluginPayload): PlainExtension {
+  return defineFacetPayload(pluginFacet, [payload]) as PlainExtension
+}
+
+/**
+ * @internal
+ */
+export type PluginPayload =
+  | Plugin
+  | Plugin[]
+  | ((context: { schema: Schema }) => Plugin | Plugin[])
+
+/**
+ * @internal
+ */
+export const pluginFacet: Facet<PluginPayload, StatePayload> = defineFacet({
+  reducer: (payloads): StatePayload => {
+    return ({ schema }) => {
+      // An array of plugins from lower to higher priority.
+      const plugins: ProseMirrorPlugin[] = []
+
+      for (const payload of payloads) {
+        if (payload instanceof Plugin) {
+          plugins.push(payload)
+        } else if (
+          Array.isArray(payload)
+          && payload.every((p) => p instanceof Plugin)
+        ) {
+          plugins.push(...payload)
+        } else if (typeof payload === 'function') {
+          plugins.push(...[payload({ schema })].flat())
+        } else {
+          throw new ProseKitError('Invalid plugin')
+        }
+      }
+
+      // An array of plugins from higher to lower priority. This matches the
+      // order of plugins required by ProseMirror.
+      const reversedPlugins = toReversed(plugins)
+
+      return { plugins: reversedPlugins }
+    }
+  },
+  parent: stateFacet,
+})

package/src/extensions/text.ts

@@ -0,0 +1,34 @@
+import type { Attrs } from '@prosekit/pm/model'
+
+import type { Extension } from '../types/extension'
+
+import { defineNodeSpec } from './node-spec'
+
+/**
+ * @internal
+ */
+export type TextExtension = Extension<{
+  Nodes: {
+    text: Attrs
+  }
+}>
+
+/**
+ * @public
+ *
+ * @deprecated Use the following import instead:
+ *
+ * ```ts
+ * import { defineText } from 'prosekit/extensions/text'
+ * ```
+ */
+export function defineText(): TextExtension {
+  console.warn(
+    '[prosekit] The `defineText` function from `prosekit/core` is deprecated. Use the following import instead: `import { defineText } from "prosekit/extensions/text"`.',
+  )
+
+  return defineNodeSpec({
+    name: 'text',
+    group: 'inline',
+  })
+}

package/src/facets/base-extension.ts

@@ -0,0 +1,54 @@
+import type { Schema } from '@prosekit/pm/model'
+
+import type {
+  Extension,
+  ExtensionTyping,
+} from '../types/extension'
+import { Priority } from '../types/priority'
+
+import type { Facet } from './facet'
+import type { FacetNode } from './facet-node'
+import type { Tuple5 } from './facet-types'
+import { schemaFacet } from './schema'
+
+/**
+ * @internal
+ */
+export abstract class BaseExtension<T extends ExtensionTyping = ExtensionTyping> implements Extension<T> {
+  abstract extension: Extension | Extension[]
+  priority?: Priority
+  _type?: T
+
+  private trees: Tuple5<FacetNode | null> = [null, null, null, null, null]
+
+  /**
+   * @internal
+   */
+  abstract createTree(priority: Priority): FacetNode
+
+  /**
+   * @internal
+   */
+  getTree(priority?: Priority): FacetNode {
+    const pri = priority ?? this.priority ?? Priority.default
+    return (this.trees[pri] ||= this.createTree(pri))
+  }
+
+  /**
+   * @internal
+   */
+  findFacetOutput<I, O>(facet: Facet<I, O>): Tuple5<O | null> | null {
+    let node: FacetNode | undefined = this.getTree()
+
+    for (const index of facet.path) {
+      node = node?.children.get(index)
+    }
+
+    return node?.getOutput() ?? null
+  }
+
+  get schema(): Schema | null {
+    const output = this.findFacetOutput(schemaFacet)
+    return output?.find(Boolean)?.schema ?? null
+  }
+}

package/src/facets/command.ts

@@ -0,0 +1,21 @@
+import type { CommandCreators } from '../types/extension-command'
+
+import {
+  defineFacet,
+  type Facet,
+} from './facet'
+import {
+  rootFacet,
+  type RootPayload,
+} from './root'
+
+type CommandPayload = CommandCreators
+
+export const commandFacet: Facet<CommandPayload, RootPayload> = defineFacet({
+  reducer: (inputs) => {
+    const commands = Object.assign({}, ...inputs) as CommandPayload
+    return { commands }
+  },
+  parent: rootFacet,
+  singleton: true,
+})

package/src/facets/facet-extension.spec.ts

@@ -0,0 +1,173 @@
+import {
+  describe,
+  expect,
+  it,
+  vi,
+} from 'vitest'
+
+import { Priority } from '../types/priority'
+import { isNotNullish } from '../utils/type-assertion'
+
+import {
+  defineFacet,
+  Facet,
+} from './facet'
+import { FacetExtensionImpl } from './facet-extension'
+import {
+  subtractFacetNode,
+  unionFacetNode,
+} from './facet-node'
+import type { FacetReducer } from './facet-types'
+import { UnionExtensionImpl } from './union-extension'
+
+describe('facet extension', () => {
+  type FooHandler = (foo: string) => void
+  type BarHandler = (bar: string) => void
+
+  interface RootInput {
+    onFoo?: FooHandler
+    onBar?: BarHandler
+  }
+
+  interface RootOutput {
+    fooHandlers: FooHandler[]
+    barHandlers: BarHandler[]
+  }
+
+  type FooInput = FooHandler
+  type BarInput = BarHandler
+
+  const rootReducerImpl: FacetReducer<RootInput, RootOutput> = (input) => {
+    const fooHandlers = input.map((i) => i.onFoo).filter(isNotNullish)
+    const barHandlers = input.map((i) => i.onBar).filter(isNotNullish)
+    return { fooHandlers, barHandlers }
+  }
+  const rootReducer = vi.fn(rootReducerImpl)
+  const rootFacet = new Facet(null, true, rootReducer)
+
+  // Foo facet uses `reduce` closure to return the same `onFoo` function every time.
+  const fooReduce: () => FacetReducer<FooInput, RootInput> = () => {
+    let fooHandlers: FooHandler[] | undefined
+
+    const onFoo = (value: string): void => {
+      fooHandlers?.forEach((handler) => handler(value))
+    }
+
+    return (input) => {
+      fooHandlers = input
+      return { onFoo }
+    }
+  }
+  const fooFacet = defineFacet<FooInput, RootInput>({
+    parent: rootFacet,
+    reduce: fooReduce,
+  })
+
+  // Bar facet uses `reducer` directly thus the `onBar` function is a different instance every time.
+  const barReducer: FacetReducer<BarInput, RootInput> = (input) => {
+    return {
+      onBar: (value: string) => {
+        input.forEach((handler) => handler(value))
+      },
+    }
+  }
+  const barFacet = defineFacet<BarInput, RootInput>({
+    parent: rootFacet,
+    reducer: barReducer,
+  })
+
+  it('can merge payloads', () => {
+    const fooHandler1: FooHandler = vi.fn()
+    const fooExtension1 = new FacetExtensionImpl(fooFacet, [fooHandler1])
+
+    const fooHandler2: FooHandler = vi.fn()
+    const fooExtension2 = new FacetExtensionImpl(fooFacet, [fooHandler2])
+
+    const barHandler1: BarHandler = vi.fn()
+    const barExtension1 = new FacetExtensionImpl(barFacet, [barHandler1])
+
+    const extension1 = new UnionExtensionImpl([
+      fooExtension1,
+      fooExtension2,
+      barExtension1,
+    ])
+
+    const tree = extension1.createTree(Priority.default)
+    const rootOutput = tree.getSingletonOutput() as RootOutput
+    expect(rootOutput.fooHandlers).toHaveLength(1)
+    expect(rootOutput.barHandlers).toHaveLength(1)
+
+    expect(fooHandler1).toHaveBeenCalledTimes(0)
+    expect(fooHandler2).toHaveBeenCalledTimes(0)
+    expect(barHandler1).toHaveBeenCalledTimes(0)
+
+    rootOutput.fooHandlers.forEach((handler) => handler('a'))
+    expect(fooHandler1).toHaveBeenCalledWith('a')
+    expect(fooHandler1).toHaveBeenCalledTimes(1)
+    expect(fooHandler2).toHaveBeenCalledWith('a')
+    expect(fooHandler2).toHaveBeenCalledTimes(1)
+
+    rootOutput.barHandlers.forEach((handler) => handler('b'))
+    expect(barHandler1).toHaveBeenCalledWith('b')
+    expect(barHandler1).toHaveBeenCalledTimes(1)
+  })
+
+  it('can skip unnecessary update', () => {
+    const fooHandler1: FooHandler = vi.fn()
+    const fooExtension1 = new FacetExtensionImpl(fooFacet, [fooHandler1])
+
+    const fooHandler2: FooHandler = vi.fn()
+    const fooExtension2 = new FacetExtensionImpl(fooFacet, [fooHandler2])
+
+    const barHandler1: BarHandler = vi.fn()
+    const barExtension1 = new FacetExtensionImpl(barFacet, [barHandler1])
+
+    const barHandler2: BarHandler = vi.fn()
+    const barExtension2 = new FacetExtensionImpl(barFacet, [barHandler2])
+
+    // Initial the root output with fooExtension1 and barExtension1.
+    const rootExtension = new UnionExtensionImpl([fooExtension1, barExtension1])
+    let tree = rootExtension.createTree(Priority.default)
+    let rootOutput = tree.getSingletonOutput() as RootOutput
+
+    // Save the initial root output.
+    const rootFooHandlers1 = [...rootOutput.fooHandlers]
+    const rootBarHandlers1 = [...rootOutput.barHandlers]
+
+    // Add fooExtension2.
+    // This should not trigger any updates to the root output.
+    tree = unionFacetNode(tree, fooExtension2.getTree())
+    rootOutput = tree.getSingletonOutput() as RootOutput
+    const rootFooHandlers2 = [...rootOutput.fooHandlers]
+    const rootBarHandlers2 = [...rootOutput.barHandlers]
+    expect(rootFooHandlers2).toEqual(rootFooHandlers1)
+    expect(rootBarHandlers2).toEqual(rootBarHandlers1)
+
+    // Add barExtension2.
+    // This should change rootOutput.barHandlers
+    tree = unionFacetNode(tree, barExtension2.getTree())
+    rootOutput = tree.getSingletonOutput() as RootOutput
+    const rootFooHandlers3 = [...rootOutput.fooHandlers]
+    const rootBarHandlers3 = [...rootOutput.barHandlers]
+    expect(rootFooHandlers3).toEqual(rootFooHandlers2)
+    expect(rootBarHandlers3).not.toEqual(rootBarHandlers2)
+
+    // Remove fooExtension1
+    // This should not trigger any updates to the root output.
+    tree = subtractFacetNode(tree, fooExtension1.getTree())
+    rootOutput = tree.getSingletonOutput() as RootOutput
+    const rootFooHandlers4 = [...rootOutput.fooHandlers]
+    const rootBarHandlers4 = [...rootOutput.barHandlers]
+    expect(rootFooHandlers4).toEqual(rootFooHandlers3)
+    expect(rootBarHandlers4).toEqual(rootBarHandlers3)
+
+    // Remove barExtension2
+    // This should change rootOutput.barHandlers
+    tree = subtractFacetNode(tree, barExtension2.getTree())
+    rootOutput = tree.getSingletonOutput() as RootOutput
+    const rootFooHandlers5 = [...rootOutput.fooHandlers]
+    const rootBarHandlers5 = [...rootOutput.barHandlers]
+    expect(rootFooHandlers5).toEqual(rootFooHandlers4)
+    expect(rootBarHandlers5).not.toEqual(rootBarHandlers4)
+  })
+})

package/src/facets/facet-extension.ts

@@ -0,0 +1,53 @@
+import type { Extension } from '../types/extension'
+import type { Priority } from '../types/priority'
+
+import { BaseExtension } from './base-extension'
+import type { Facet } from './facet'
+import { FacetNode } from './facet-node'
+import type { Tuple5 } from './facet-types'
+
+/**
+ * @internal
+ */
+export class FacetExtensionImpl<Input, Output> extends BaseExtension {
+  declare extension: Extension
+
+  /**
+   * @internal
+   */
+  constructor(
+    readonly facet: Facet<Input, Output>,
+    readonly payloads: Input[],
+  ) {
+    super()
+  }
+
+  /**
+   * @internal
+   */
+  createTree(priority: Priority): FacetNode {
+    const pri = this.priority ?? priority
+
+    const inputs: Tuple5<Input[] | null> = [null, null, null, null, null]
+    inputs[pri] = [...this.payloads]
+
+    let node: FacetNode = new FacetNode(this.facet, inputs)
+
+    while (node.facet.parent) {
+      const children = new Map([[node.facet.index, node]])
+      node = new FacetNode(node.facet.parent, undefined, children)
+    }
+
+    return node
+  }
+}
+
+/**
+ * @internal
+ */
+export function defineFacetPayload<Input>(
+  facet: Facet<Input, any>,
+  payloads: Input[],
+): Extension {
+  return new FacetExtensionImpl(facet, payloads)
+}