@prosekit/core 0.8.2 → 0.8.4

package/src/editor/with-priority.ts

@@ -0,0 +1,25 @@
+import type { Extension } from '../types/extension'
+import type { Priority } from '../types/priority'
+
+import { union } from './union'
+
+/**
+ * Return an new extension with the given priority.
+ *
+ * @example
+ * ```ts
+ * import { Priority, withPriority } from 'prosekit/core'
+ *
+ * const extension = withPriority(defineMyExtension(), Priority.high)
+ * ```
+ *
+ * @public
+ */
+export function withPriority<T extends Extension>(
+  extension: T,
+  priority: Priority,
+): T {
+  const result = union(extension)
+  result.priority = priority
+  return result as T
+}

package/src/error.ts

@@ -0,0 +1,28 @@
+/**
+ * Base class for all ProseKit errors.
+ *
+ * @internal
+ */
+export class ProseKitError extends Error {}
+
+/**
+ * @internal
+ */
+export class EditorNotFoundError extends ProseKitError {
+  constructor() {
+    super(
+      'Unable to find editor. Pass it as an argument or call this function inside a ProseKit component.',
+    )
+  }
+}
+
+/**
+ * @internal
+ */
+export class DOMDocumentNotFoundError extends ProseKitError {
+  constructor() {
+    super(
+      'Unable to find browser Document. When not in the browser environment, you need to pass a DOM Document.',
+    )
+  }
+}

package/src/extensions/clipboard-serializer.ts

@@ -0,0 +1,107 @@
+import {
+  DOMSerializer,
+  type DOMOutputSpec,
+  type Mark,
+  type ProseMirrorNode,
+  type Schema,
+} from '@prosekit/pm/model'
+import {
+  PluginKey,
+  ProseMirrorPlugin,
+} from '@prosekit/pm/state'
+
+import { defineFacet } from '../facets/facet'
+import { defineFacetPayload } from '../facets/facet-extension'
+import type { AnyFunction } from '../types/any-function'
+import type { PlainExtension } from '../types/extension'
+import { isNotNullish } from '../utils/type-assertion'
+
+import {
+  pluginFacet,
+  type PluginPayload,
+} from './plugin'
+
+type SerializeFragmentFunction = typeof DOMSerializer.prototype.serializeFragment
+type SerializeNodeFunction = typeof DOMSerializer.prototype.serializeNode
+type NodesFromSchemaFunction = typeof DOMSerializer.nodesFromSchema
+type MarksFromSchemaFunction = typeof DOMSerializer.marksFromSchema
+
+type FunctionWrapper<T extends AnyFunction> = (fn: T) => T
+
+/**
+ * @internal
+ */
+export interface ClipboardSerializerOptions {
+  serializeFragmentWrapper?: FunctionWrapper<SerializeFragmentFunction>
+  serializeNodeWrapper?: FunctionWrapper<SerializeNodeFunction>
+  nodesFromSchemaWrapper?: FunctionWrapper<NodesFromSchemaFunction>
+  marksFromSchemaWrapper?: FunctionWrapper<MarksFromSchemaFunction>
+}
+
+function mergeWrappers<T extends AnyFunction>(wrappers: Array<FunctionWrapper<T> | undefined | null>): FunctionWrapper<T> {
+  return (fn: T) => wrappers.filter(isNotNullish).reduce((fn, wrapper) => wrapper(fn), fn)
+}
+
+function wrapFunction<T extends AnyFunction>(fn: T, wrapper?: FunctionWrapper<T>): T {
+  return wrapper ? wrapper(fn) : fn
+}
+
+class CustomDOMSerializer extends DOMSerializer {
+  constructor(
+    nodes: Record<string, (node: ProseMirrorNode) => DOMOutputSpec>,
+    marks: Record<string, (mark: Mark, inline: boolean) => DOMOutputSpec>,
+    private serializeFragmentWrapper?: FunctionWrapper<SerializeFragmentFunction>,
+    private serializeNodeWrapper?: FunctionWrapper<SerializeNodeFunction>,
+  ) {
+    super(nodes, marks)
+  }
+
+  override serializeFragment(...args: Parameters<SerializeFragmentFunction>): ReturnType<SerializeFragmentFunction> {
+    const fn: SerializeFragmentFunction = (...args) => super.serializeFragment(...args)
+    return wrapFunction(fn, this.serializeFragmentWrapper)(...args)
+  }
+
+  override serializeNode(...args: Parameters<SerializeNodeFunction>): ReturnType<SerializeNodeFunction> {
+    const fn: SerializeNodeFunction = (...args) => super.serializeNode(...args)
+    return wrapFunction(fn, this.serializeNodeWrapper)(...args)
+  }
+}
+
+function createCustomDOMSerializer(schema: Schema, options: ClipboardSerializerOptions) {
+  const nodesFromSchema: NodesFromSchemaFunction = (...args) => DOMSerializer.nodesFromSchema(...args)
+  const marksFromSchema: MarksFromSchemaFunction = (...args) => DOMSerializer.marksFromSchema(...args)
+  const nodes = wrapFunction(nodesFromSchema, options.nodesFromSchemaWrapper)(schema)
+  const marks = wrapFunction(marksFromSchema, options.marksFromSchemaWrapper)(schema)
+  return new CustomDOMSerializer(nodes, marks, options.serializeFragmentWrapper, options.serializeNodeWrapper)
+}
+
+const clipboardSerializerFacet = defineFacet<ClipboardSerializerOptions, PluginPayload>({
+  reducer: (inputs: ClipboardSerializerOptions[]): PluginPayload => {
+    const options: ClipboardSerializerOptions = {
+      serializeFragmentWrapper: mergeWrappers(inputs.map((input) => input.serializeFragmentWrapper)),
+      serializeNodeWrapper: mergeWrappers(inputs.map((input) => input.serializeNodeWrapper)),
+      nodesFromSchemaWrapper: mergeWrappers(inputs.map((input) => input.nodesFromSchemaWrapper)),
+      marksFromSchemaWrapper: mergeWrappers(inputs.map((input) => input.marksFromSchemaWrapper)),
+    }
+
+    return ({ schema }) => {
+      const clipboardSerializer = createCustomDOMSerializer(schema, options)
+
+      return [
+        new ProseMirrorPlugin({
+          key: new PluginKey('prosekit-clipboard-serializer'),
+          props: { clipboardSerializer },
+        }),
+      ]
+    }
+  },
+  singleton: true,
+  parent: pluginFacet,
+})
+
+/**
+ * @internal
+ */
+export function defineClipboardSerializer(options: ClipboardSerializerOptions): PlainExtension {
+  return defineFacetPayload(clipboardSerializerFacet, [options]) as PlainExtension
+}

package/src/extensions/command.ts

@@ -0,0 +1,121 @@
+import {
+  addMark,
+  type AddMarkOptions,
+} from '../commands/add-mark'
+import {
+  insertDefaultBlock,
+  type InsertDefaultBlockOptions,
+} from '../commands/insert-default-block'
+import {
+  insertNode,
+  type InsertNodeOptions,
+} from '../commands/insert-node'
+import {
+  insertText,
+  type InsertTextOptions,
+} from '../commands/insert-text'
+import {
+  removeMark,
+  type RemoveMarkOptions,
+} from '../commands/remove-mark'
+import {
+  removeNode,
+  type RemoveNodeOptions,
+} from '../commands/remove-node'
+import { selectAll } from '../commands/select-all'
+import {
+  setBlockType,
+  type SetBlockTypeOptions,
+} from '../commands/set-block-type'
+import {
+  setNodeAttrs,
+  type SetNodeAttrsOptions,
+} from '../commands/set-node-attrs'
+import {
+  toggleWrap,
+  type ToggleWrapOptions,
+} from '../commands/toggle-wrap'
+import {
+  unsetBlockType,
+  type UnsetBlockTypeOptions,
+} from '../commands/unset-block-type'
+import {
+  unsetMark,
+  type UnsetMarkOptions,
+} from '../commands/unset-mark'
+import {
+  wrap,
+  type WrapOptions,
+} from '../commands/wrap'
+import { commandFacet } from '../facets/command'
+import { defineFacetPayload } from '../facets/facet-extension'
+import type { Extension } from '../types/extension'
+import type { CommandCreator } from '../types/extension-command'
+
+export function defineCommands<
+  T extends Record<string, CommandCreator> = Record<string, CommandCreator>,
+>(
+  commands: T,
+): Extension<{
+  Commands: { [K in keyof T]: Parameters<T[K]> }
+}> {
+  return defineFacetPayload(commandFacet, [commands]) as Extension<{
+    Commands: { [K in keyof T]: Parameters<T[K]> }
+  }>
+}
+
+/**
+ * @internal
+ */
+export type BaseCommandsExtension = Extension<{
+  Commands: {
+    insertText: [options: InsertTextOptions]
+    insertNode: [options: InsertNodeOptions]
+    removeNode: [options: RemoveNodeOptions]
+    wrap: [options: WrapOptions]
+    toggleWrap: [options: ToggleWrapOptions]
+    setBlockType: [options: SetBlockTypeOptions]
+    setNodeAttrs: [options: SetNodeAttrsOptions]
+    insertDefaultBlock: [options?: InsertDefaultBlockOptions]
+    selectAll: []
+    addMark: [options: AddMarkOptions]
+    removeMark: [options: RemoveMarkOptions]
+    unsetBlockType: [options?: UnsetBlockTypeOptions]
+    unsetMark: [options?: UnsetMarkOptions]
+  }
+}>
+
+/**
+ * Add some base commands
+ *
+ * @public
+ */
+export function defineBaseCommands(): BaseCommandsExtension {
+  return defineCommands({
+    insertText,
+
+    insertNode,
+
+    removeNode,
+
+    wrap,
+
+    toggleWrap,
+
+    setBlockType,
+
+    setNodeAttrs,
+
+    insertDefaultBlock,
+
+    selectAll,
+
+    addMark,
+
+    removeMark,
+
+    unsetBlockType,
+
+    unsetMark,
+  })
+}

package/src/extensions/default-state.spec.ts

@@ -0,0 +1,60 @@
+import {
+  describe,
+  expect,
+  it,
+} from 'vitest'
+
+import { createEditor } from '../editor/editor'
+import { defineTestExtension } from '../testing'
+
+import type { DefaultStateOptions } from './default-state'
+
+describe('defineDefaultState', () => {
+  const docJSON = {
+    type: 'doc',
+    content: [
+      { type: 'paragraph', content: [{ type: 'text', text: 'docJSON' }] },
+    ],
+  }
+  const docHTMLString = '<p>docHTMLString</p>'
+  const docHTMLElement = document.createElement('p')
+  docHTMLElement.innerHTML = 'docHTMLElement'
+
+  it('can set the default document', () => {
+    const run = (options: DefaultStateOptions): string => {
+      const extension = defineTestExtension()
+      const editor = createEditor({ extension, ...options })
+      return editor.state.doc.toString()
+    }
+
+    expect(run({ defaultDoc: docJSON })).toContain('docJSON')
+    expect(run({ defaultHTML: docHTMLString })).toContain('docHTMLString')
+    expect(run({ defaultHTML: docHTMLElement })).toContain('docHTMLElement')
+
+    expect(run({ defaultContent: docJSON })).toContain('docJSON')
+    expect(run({ defaultContent: docHTMLString })).toContain('docHTMLString')
+    expect(run({ defaultContent: docHTMLElement })).toContain('docHTMLElement')
+  })
+
+  it('can set the default selection', () => {
+    const extension = defineTestExtension()
+    const editor = createEditor({
+      extension,
+      defaultContent: docJSON,
+      defaultSelection: {
+        anchor: 4,
+        head: 1,
+        type: 'text',
+      },
+    })
+
+    expect(editor.state.selection.toJSON()).toEqual({
+      anchor: 4,
+      head: 1,
+      type: 'text',
+    })
+    expect(editor.state.selection.content().content.toString()).toEqual(
+      '<paragraph("doc")>',
+    )
+  })
+})

package/src/extensions/default-state.ts

@@ -0,0 +1,76 @@
+import {
+  Selection,
+  type EditorStateConfig,
+} from '@prosekit/pm/state'
+
+import { defineFacetPayload } from '../facets/facet-extension'
+import { stateFacet } from '../facets/state'
+import type { PlainExtension } from '../types/extension'
+import type {
+  NodeJSON,
+  SelectionJSON,
+} from '../types/model'
+import { getEditorContentJSON } from '../utils/editor-content'
+
+/**
+ * @public
+ */
+export interface DefaultStateOptions {
+  /**
+   * The starting document to use when creating the editor. It can be a
+   * ProseMirror node JSON object, a HTML string, or a HTML element instance.
+   */
+  defaultContent?: NodeJSON | string | HTMLElement
+
+  /**
+   * A JSON object representing the starting document to use when creating the
+   * editor.
+   *
+   * @deprecated Use `defaultContent` instead.
+   */
+  defaultDoc?: NodeJSON
+
+  /**
+   * A HTML element or a HTML string representing the starting document to use
+   * when creating the editor.
+   *
+   * @deprecated Use `defaultContent` instead.
+   */
+  defaultHTML?: string | HTMLElement
+
+  /**
+   * A JSON object representing the starting selection to use when creating the
+   * editor. It's only used when `defaultContent` is also provided.
+   */
+  defaultSelection?: SelectionJSON
+}
+
+/**
+ * Define a default state for the editor.
+ *
+ * @param options
+ *
+ * @public
+ */
+export function defineDefaultState({
+  defaultSelection,
+  defaultContent,
+  defaultDoc,
+  defaultHTML,
+}: DefaultStateOptions): PlainExtension {
+  const defaultDocContent = defaultContent || defaultDoc || defaultHTML
+
+  return defineFacetPayload(stateFacet, [
+    ({ schema }) => {
+      const config: EditorStateConfig = {}
+      if (defaultDocContent) {
+        const json = getEditorContentJSON(schema, defaultDocContent)
+        config.doc = schema.nodeFromJSON(json)
+        if (defaultSelection) {
+          config.selection = Selection.fromJSON(config.doc, defaultSelection)
+        }
+      }
+      return config
+    },
+  ]) as PlainExtension
+}

package/src/extensions/doc.ts

@@ -0,0 +1,31 @@
+import type { Attrs } from '@prosekit/pm/model'
+
+import type { Extension } from '../types/extension'
+
+import { defineNodeSpec } from './node-spec'
+
+/**
+ * @internal
+ */
+export type DocExtension = Extension<{ Nodes: { doc: Attrs } }>
+
+/**
+ * @public
+ *
+ * @deprecated Use the following import instead:
+ *
+ * ```ts
+ * import { defineDoc } from 'prosekit/extensions/doc'
+ * ```
+ */
+export function defineDoc(): DocExtension {
+  console.warn(
+    '[prosekit] The `defineDoc` function from `prosekit/core` is deprecated. Use the following import instead: `import { defineDoc } from "prosekit/extensions/doc"`.',
+  )
+
+  return defineNodeSpec({
+    name: 'doc',
+    content: 'block+',
+    topNode: true,
+  })
+}

package/src/extensions/events/doc-change.ts

@@ -0,0 +1,34 @@
+import type { EditorState } from '@prosekit/pm/state'
+import type { EditorView } from '@prosekit/pm/view'
+
+import type { PlainExtension } from '../../types/extension'
+
+import { defineUpdateHandler } from './plugin-view'
+
+/**
+ * A function that is called when the editor document is changed.
+ *
+ * @param view - The editor view.
+ * @param prevState - The previous editor state.
+ *
+ * @public
+ */
+export type DocChangeHandler = (
+  view: EditorView,
+  prevState: EditorState,
+) => void
+
+/**
+ * Registers a event handler that is called when the editor document is changed.
+ *
+ * @public
+ */
+export function defineDocChangeHandler(
+  handler: DocChangeHandler,
+): PlainExtension {
+  return defineUpdateHandler((view, prevState) => {
+    if (!view.state.doc.eq(prevState.doc)) {
+      handler(view, prevState)
+    }
+  })
+}

package/src/extensions/events/dom-event.spec.ts

@@ -0,0 +1,70 @@
+import {
+  describe,
+  expect,
+  it,
+  vi,
+} from 'vitest'
+
+import { createEditor } from '../../editor/editor'
+import { defineTestExtension } from '../../testing'
+
+import { defineDOMEventHandler } from './dom-event'
+
+describe('defineDOMEventHandler', () => {
+  it('should register and unregister event handlers dynamically', () => {
+    const div = document.body.appendChild(document.createElement('div'))
+    const handleFocus = vi.fn()
+    const handleBlur = vi.fn()
+
+    const extension = defineTestExtension()
+    const editor = createEditor({ extension })
+    editor.mount(div)
+
+    expect(handleFocus).toHaveBeenCalledTimes(0)
+    expect(handleBlur).toHaveBeenCalledTimes(0)
+
+    const disposeFocus = editor.use(defineFocusEventHandler(handleFocus))
+    const disposeBlur = editor.use(defineBlurEventHandler(handleBlur))
+    expect(handleFocus).toHaveBeenCalledTimes(0)
+    expect(handleBlur).toHaveBeenCalledTimes(0)
+
+    editor.focus()
+    expect(handleFocus).toHaveBeenCalledTimes(1)
+    expect(handleBlur).toHaveBeenCalledTimes(0)
+
+    editor.blur()
+    expect(handleFocus).toHaveBeenCalledTimes(1)
+    expect(handleBlur).toHaveBeenCalledTimes(1)
+
+    disposeFocus()
+    expect(handleFocus).toHaveBeenCalledTimes(1)
+    expect(handleBlur).toHaveBeenCalledTimes(1)
+
+    editor.focus()
+    expect(handleFocus).toHaveBeenCalledTimes(1)
+    expect(handleBlur).toHaveBeenCalledTimes(1)
+
+    editor.blur()
+    expect(handleFocus).toHaveBeenCalledTimes(1)
+    expect(handleBlur).toHaveBeenCalledTimes(2)
+
+    disposeBlur()
+    expect(handleFocus).toHaveBeenCalledTimes(1)
+    expect(handleBlur).toHaveBeenCalledTimes(2)
+
+    editor.focus()
+    editor.blur()
+    editor.focus()
+    editor.blur()
+    expect(handleFocus).toHaveBeenCalledTimes(1)
+    expect(handleBlur).toHaveBeenCalledTimes(2)
+  })
+})
+
+function defineFocusEventHandler(handler: VoidFunction) {
+  return defineDOMEventHandler('focus', handler)
+}
+
+function defineBlurEventHandler(handler: VoidFunction) {
+  return defineDOMEventHandler('blur', handler)
+}

package/src/extensions/events/dom-event.ts

@@ -0,0 +1,117 @@
+import {
+  PluginKey,
+  ProseMirrorPlugin,
+} from '@prosekit/pm/state'
+import type {
+  DOMEventMap,
+  EditorView,
+} from '@prosekit/pm/view'
+
+import {
+  defineFacet,
+  type Facet,
+} from '../../facets/facet'
+import { defineFacetPayload } from '../../facets/facet-extension'
+import type { PlainExtension } from '../../types/extension'
+import type { Setter } from '../../types/setter'
+import { groupEntries } from '../../utils/array-grouping'
+import { combineEventHandlers } from '../../utils/combine-event-handlers'
+import {
+  pluginFacet,
+  type PluginPayload,
+} from '../plugin'
+
+/**
+ * A function to handle the events fired on the editable DOM element. Returns
+ * `true` to indicate that it handled the given event. When returning `true`,
+ * you are responsible for calling `event.preventDefault()` yourself (or not, if
+ * you want to allow the default behavior).
+ *
+ * @public
+ */
+export type DOMEventHandler<Event extends keyof DOMEventMap = string> = (
+  view: EditorView,
+  event: DOMEventMap[Event],
+) => boolean | void
+
+/**
+ * @internal
+ */
+export function defineDomEventFacetPayload(
+  ...payloads: DOMEventPayload[]
+): PlainExtension {
+  return defineFacetPayload<DOMEventPayload>(
+    domEventFacet,
+    payloads,
+  ) as PlainExtension
+}
+
+/**
+ * Register a new event handler for the given event type.
+ *
+ * @public
+ */
+export function defineDOMEventHandler<Event extends keyof DOMEventMap = string>(
+  event: Event,
+  handler: DOMEventHandler<Event>,
+): PlainExtension {
+  return defineDomEventFacetPayload([
+    event as string,
+    handler as DOMEventHandler,
+  ])
+}
+
+/**
+ * @internal
+ */
+type DOMEventPayload = [event: string, handler: DOMEventHandler]
+
+/**
+ * @internal
+ */
+const domEventFacet: Facet<DOMEventPayload, PluginPayload> = defineFacet(
+  {
+    reduce: () => {
+      const setHandlersMap: Record<string, Setter<DOMEventHandler[]>> = {}
+      const combinedHandlerMap: Record<string, DOMEventHandler> = {}
+
+      let plugin: ProseMirrorPlugin | undefined
+
+      const update = (payloads: DOMEventPayload[]): void => {
+        let hasNewEvent = false
+
+        for (const [event] of payloads) {
+          if (!setHandlersMap[event]) {
+            hasNewEvent = true
+            const [setHandlers, combinedHandler] = combineEventHandlers<DOMEventHandler>()
+            setHandlersMap[event] = setHandlers
+            const e: DOMEventHandler = (view, eventObject) => {
+              return combinedHandler(view, eventObject)
+            }
+            combinedHandlerMap[event] = e
+          }
+        }
+
+        const map: Record<string, DOMEventHandler[] | undefined> = groupEntries<DOMEventMap>(payloads)
+        for (const [event, setHandlers] of Object.entries(setHandlersMap)) {
+          const handlers = map[event] ?? []
+          setHandlers(handlers)
+        }
+
+        if (hasNewEvent) {
+          plugin = new ProseMirrorPlugin({
+            key: new PluginKey('prosekit-dom-event-handler'),
+            props: { handleDOMEvents: combinedHandlerMap },
+          })
+        }
+      }
+
+      return function reducer(inputs) {
+        update(inputs)
+        return plugin ?? []
+      }
+    },
+    parent: pluginFacet,
+    singleton: true,
+  },
+)