@prosekit/core 0.8.2 → 0.8.4

package/src/extensions/node-spec.spec.ts

@@ -0,0 +1,224 @@
+import type {
+  DOMOutputSpec,
+  Schema,
+  TagParseRule,
+} from '@prosekit/pm/model'
+import formatHTML from 'diffable-html'
+import {
+  describe,
+  expect,
+  it,
+} from 'vitest'
+
+import { union } from '../editor/union'
+import {
+  defineDoc,
+  defineParagraph,
+  defineText,
+  setupTestFromExtension,
+} from '../testing'
+
+import { defineHistory } from './history'
+import { defineBaseKeymap } from './keymap-base'
+import {
+  defineNodeAttr,
+  defineNodeSpec,
+} from './node-spec'
+
+describe('defineNodeSpec', () => {
+  it('can merge node specs', () => {
+    const toDOM1 = (): DOMOutputSpec => ['p', { 'data-ext1': '' }]
+    const toDOM2 = (): DOMOutputSpec => ['p', { 'data-ext2': '' }]
+    const parseDOM1: TagParseRule = { tag: 'p[data-ext1]' }
+    const parseDOM2: TagParseRule = { tag: 'p[data-ext2]' }
+    const toDebugString2 = () => 'ext2'
+    const leafText1 = () => 'text'
+
+    const ext1 = defineNodeSpec({
+      name: 'paragraph',
+      content: 'text*',
+      leafText: leafText1,
+      parseDOM: [parseDOM1],
+      toDOM: toDOM1,
+      attrs: {
+        foo: { default: undefined },
+        bar: { default: 'bar' },
+        baz: { default: 'baz:1 ' },
+      },
+    })
+    const ext2 = defineNodeSpec({
+      name: 'paragraph',
+      group: 'block',
+      leafText: undefined,
+      parseDOM: [parseDOM2],
+      toDOM: toDOM2,
+      toDebugString: toDebugString2,
+      attrs: {
+        foo: { default: 'foo' },
+        bar: { default: undefined },
+        baz: { default: 'baz:2' },
+      },
+    })
+
+    const extension = union(ext1, ext2, defineDoc(), defineText())
+    const schema = extension.schema
+    expect(schema).toBeTruthy()
+    expect(schema?.spec.nodes.get('paragraph')).toEqual({
+      group: 'block',
+      content: 'text*',
+      leafText: leafText1,
+      parseDOM: [parseDOM1, parseDOM2],
+      toDOM: toDOM2,
+      toDebugString: toDebugString2,
+      attrs: {
+        foo: { default: 'foo' },
+        bar: { default: 'bar' },
+        baz: { default: 'baz:2' },
+      },
+    })
+  })
+
+  it('can reuse schema', () => {
+    const ext1 = union(defineDoc(), defineText(), defineParagraph())
+    const ext2 = union(defineBaseKeymap())
+    const ext3 = union(ext1, ext2)
+
+    const schema1 = ext1.schema
+    const schema2 = ext2.schema
+    const schema3 = ext3.schema
+
+    expect(schema1).toBeTruthy()
+    expect(schema2).toEqual(null)
+    expect(schema3).toBeTruthy()
+
+    expect(schema3 === schema1).toBe(true)
+
+    expect(formatSchema(schema3)).toMatchInlineSnapshot(`
+      {
+        "marks": "",
+        "nodes": "doc, paragraph, text",
+        "topNode": "doc",
+      }
+    `)
+
+    const ext4 = defineCodeBlockSpec()
+    const ext5 = union(ext3, ext4)
+    const schema5 = ext5.schema
+    expect(schema5).toBeTruthy()
+
+    expect(formatSchema(schema5)).toMatchInlineSnapshot(`
+      {
+        "marks": "",
+        "nodes": "codeBlock, doc, paragraph, text",
+        "topNode": "doc",
+      }
+    `)
+
+    expect(schema5 !== schema1).toBe(true)
+
+    const ext6 = union(ext5, defineHistory())
+    const schema6 = ext6.schema
+    expect(schema6).toBeTruthy()
+
+    expect(schema6 === schema5).toBe(true)
+  })
+})
+
+describe('defineNodeAttr', () => {
+  it('can add a new attribute', () => {
+    const textColorExt = defineNodeAttr({
+      type: 'paragraph',
+      attr: 'textColor',
+      default: 'black',
+      toDOM: (value) => ['style', `color: ${value}`],
+      parseDOM: (node: HTMLElement) => node.style.color,
+    })
+    const backgroundColorExt = defineNodeAttr({
+      type: 'paragraph',
+      attr: 'backgroundColor',
+      default: 'white',
+      toDOM: (value) => ['style', `background-color: ${value}`],
+      parseDOM: (node: HTMLElement) => node.style.backgroundColor,
+    })
+    const nodeIdExt = defineNodeAttr<'paragraph', 'nodeId', string | null>({
+      type: 'paragraph',
+      attr: 'nodeId',
+      default: null,
+      toDOM: (value) => (value ? ['data-node-id', value] : null),
+      parseDOM: (node: HTMLElement) => node.dataset.nodeId ?? null,
+    })
+    const extension = union(
+      defineDoc(),
+      defineText(),
+      defineParagraph(),
+      textColorExt,
+      backgroundColorExt,
+      nodeIdExt,
+    )
+    const { editor } = setupTestFromExtension(extension)
+
+    expect(Object.keys(editor.schema.nodes.paragraph.spec.attrs || {}))
+      .toMatchInlineSnapshot(`
+      [
+        "textColor",
+        "backgroundColor",
+        "nodeId",
+      ]
+    `)
+
+    editor.setContent(
+      '<p data-node-id="123" style="background-color:blue;color:red;">Hello</p>',
+    )
+
+    const json1 = editor.getDocJSON()
+    const html1 = editor.getDocHTML()
+    expect(json1).toEqual({
+      type: 'doc',
+      content: [
+        {
+          type: 'paragraph',
+          attrs: { nodeId: '123', textColor: 'red', backgroundColor: 'blue' },
+          content: [{ type: 'text', text: 'Hello' }],
+        },
+      ],
+    })
+    expect(formatHTML(html1)).toMatchInlineSnapshot(`
+      "
+      <div>
+        <p
+          data-node-id="123"
+          style="background-color: blue; color: red;"
+        >
+          Hello
+        </p>
+      </div>
+      "
+    `)
+    editor.setContent(html1)
+    const json2 = editor.getDocJSON()
+    expect(json2).toEqual(json1)
+  })
+})
+
+function defineCodeBlockSpec() {
+  return defineNodeSpec({
+    name: 'codeBlock',
+    content: 'text*',
+    group: 'block',
+    code: true,
+  })
+}
+
+function formatSchema(schema: Schema | null | undefined) {
+  if (!schema) {
+    return null
+  }
+
+  const nodes = Object.keys(schema.spec.nodes.toObject())
+  const marks = Object.keys(schema.spec.marks.toObject())
+  const topNode = schema.spec.topNode
+
+  nodes.sort()
+  marks.sort()
+  return { nodes: nodes.join(', '), marks: marks.join(', '), topNode }
+}

package/src/extensions/node-spec.ts

@@ -0,0 +1,199 @@
+import type {
+  AttributeSpec,
+  NodeSpec,
+  SchemaSpec,
+} from '@prosekit/pm/model'
+import clone from 'just-clone'
+import OrderedMap from 'orderedmap'
+
+import { defineFacet } from '../facets/facet'
+import { defineFacetPayload } from '../facets/facet-extension'
+import { schemaSpecFacet } from '../facets/schema-spec'
+import type {
+  AnyAttrs,
+  AttrSpec,
+} from '../types/attrs'
+import type { Extension } from '../types/extension'
+import { groupBy } from '../utils/array-grouping'
+import { assert } from '../utils/assert'
+import { mergeSpecs } from '../utils/merge-specs'
+import {
+  wrapOutputSpecAttrs,
+  wrapTagParseRuleAttrs,
+} from '../utils/output-spec'
+import { isNotNullish } from '../utils/type-assertion'
+
+/**
+ * @public
+ */
+export interface NodeSpecOptions<
+  NodeName extends string = string,
+  Attrs extends AnyAttrs = AnyAttrs,
+> extends NodeSpec {
+  /**
+   * The name of the node type.
+   */
+  name: NodeName
+
+  /**
+   * Whether this is the top-level node type. Only one node type can be the
+   * top-level node type in a schema.
+   */
+  topNode?: boolean
+
+  /**
+   * The attributes that nodes of this type get.
+   */
+  attrs?: {
+    [key in keyof Attrs]: AttrSpec<Attrs[key]>
+  }
+}
+
+/**
+ * @public
+ */
+export interface NodeAttrOptions<
+  NodeName extends string = string,
+  AttrName extends string = string,
+  AttrType = any,
+> extends AttrSpec<AttrType> {
+  /**
+   * The name of the node type.
+   */
+  type: NodeName
+
+  /**
+   * The name of the attribute.
+   */
+  attr: AttrName
+
+  /**
+   * Whether the attribute should be kept when the node is split. Set it to
+   * `true` if you want to inherit the attribute from the previous node when
+   * splitting the node by pressing `Enter`.
+   *
+   * @default undefined
+   */
+  splittable?: boolean
+
+  /**
+   * Returns the attribute key and value to be set on the HTML element.
+   *
+   * If the returned `key` is `"style"`, the value is a string of CSS properties and will
+   * be prepended to the existing `style` attribute on the DOM node.
+   *
+   * @param value - The value of the attribute of current ProseMirror node.
+   */
+  toDOM?: (value: AttrType) => [key: string, value: string] | null | undefined
+
+  /**
+   * Parses the attribute value from the DOM.
+   */
+  parseDOM?: (node: HTMLElement) => AttrType
+}
+
+/**
+ * Defines a node type.
+ *
+ * @public
+ */
+export function defineNodeSpec<
+  Node extends string,
+  Attrs extends AnyAttrs = AnyAttrs,
+>(
+  options: NodeSpecOptions<Node, Attrs>,
+): Extension<{
+  Nodes: { [K in Node]: Attrs }
+}> {
+  const payload: NodeSpecPayload = [options, undefined]
+  return defineFacetPayload(nodeSpecFacet, [payload]) as Extension<{
+    Nodes: any
+  }>
+}
+
+/**
+ * Defines an attribute for a node type.
+ *
+ * @public
+ */
+export function defineNodeAttr<
+  NodeType extends string = string,
+  AttrName extends string = string,
+  AttrType = any,
+>(
+  options: NodeAttrOptions<NodeType, AttrName, AttrType>,
+): Extension<{
+  Nodes: { [K in NodeType]: { [K in AttrName]: AttrType } }
+}> {
+  const payload: NodeSpecPayload = [undefined, options]
+  return defineFacetPayload(nodeSpecFacet, [payload]) as Extension<{
+    Nodes: any
+  }>
+}
+
+type NodeSpecPayload = [
+  NodeSpecOptions | undefined,
+  NodeAttrOptions | undefined,
+]
+
+const nodeSpecFacet = defineFacet<NodeSpecPayload, SchemaSpec>({
+  reducer: (payloads: NodeSpecPayload[]): SchemaSpec => {
+    let specs = OrderedMap.from<NodeSpec>({})
+    let topNodeName: string | undefined = undefined
+
+    const specPayloads = payloads.map((input) => input[0]).filter(isNotNullish)
+    const attrPayloads = payloads.map((input) => input[1]).filter(isNotNullish)
+
+    for (const { name, topNode, ...spec } of specPayloads) {
+      if (topNode) {
+        topNodeName = name
+      }
+
+      const prevSpec = specs.get(name)
+      if (prevSpec) {
+        specs = specs.update(name, mergeSpecs(prevSpec, spec))
+      } else {
+        // The latest spec has the highest priority, so we put it at the start
+        // of the map.
+        specs = specs.addToStart(name, spec)
+      }
+    }
+
+    const groupedAttrs = groupBy(attrPayloads, (payload) => payload.type)
+
+    for (const [type, attrs] of Object.entries(groupedAttrs)) {
+      if (!attrs) continue
+
+      const maybeSpec = specs.get(type)
+      assert(maybeSpec, `Node type ${type} must be defined`)
+
+      const spec = clone(maybeSpec)
+
+      if (!spec.attrs) {
+        spec.attrs = {}
+      }
+
+      for (const attr of attrs) {
+        spec.attrs[attr.attr] = {
+          default: attr.default as unknown,
+          validate: attr.validate,
+          splittable: attr.splittable,
+        } as AttributeSpec
+      }
+
+      if (spec.toDOM) {
+        spec.toDOM = wrapOutputSpecAttrs(spec.toDOM, attrs)
+      }
+
+      if (spec.parseDOM) {
+        spec.parseDOM = spec.parseDOM.map((rule) => wrapTagParseRuleAttrs(rule, attrs))
+      }
+
+      specs = specs.update(type, spec)
+    }
+
+    return { nodes: specs, topNode: topNodeName }
+  },
+  parent: schemaSpecFacet,
+  singleton: true,
+})

package/src/extensions/node-view-effect.ts

@@ -0,0 +1,85 @@
+import {
+  PluginKey,
+  ProseMirrorPlugin,
+} from '@prosekit/pm/state'
+import type { NodeViewConstructor } from '@prosekit/pm/view'
+
+import { defineFacet } from '../facets/facet'
+import { defineFacetPayload } from '../facets/facet-extension'
+import type { Extension } from '../types/extension'
+import { isNotNullish } from '../utils/type-assertion'
+
+import {
+  pluginFacet,
+  type PluginPayload,
+} from './plugin'
+
+/**
+ * @internal
+ */
+export type NodeViewFactoryOptions<T> = {
+  group: string
+  factory: (args: T) => NodeViewConstructor
+}
+
+/**
+ * @internal
+ */
+export type NodeViewComponentOptions<T> = {
+  group: string
+  name: string
+  args: T
+}
+
+type NodeViewFactoryInput = [
+  NodeViewFactoryOptions<any> | null,
+  NodeViewComponentOptions<any> | null,
+]
+
+/**
+ * @internal
+ */
+export function defineNodeViewFactory<T>(
+  options: NodeViewFactoryOptions<T>,
+): Extension {
+  const input: NodeViewFactoryInput = [options, null]
+  return defineFacetPayload(nodeViewFactoryFacet, [input])
+}
+
+/**
+ * @internal
+ */
+export function defineNodeViewComponent<T>(
+  options: NodeViewComponentOptions<T>,
+): Extension {
+  const input: NodeViewFactoryInput = [null, options]
+  return defineFacetPayload(nodeViewFactoryFacet, [input])
+}
+
+const isServer = typeof window === 'undefined'
+
+const nodeViewFactoryFacet = defineFacet<NodeViewFactoryInput, PluginPayload>({
+  reducer: (inputs: NodeViewFactoryInput[]): PluginPayload => {
+    // Don't register node views on the server
+    if (isServer) return []
+
+    const nodeViews: { [nodeName: string]: NodeViewConstructor } = {}
+
+    const factories = inputs.map((x) => x[0]).filter(isNotNullish)
+    const options = inputs.map((x) => x[1]).filter(isNotNullish)
+
+    for (const { group, name, args } of options) {
+      const factory = factories.find((factory) => factory.group === group)
+      if (!factory) continue
+      nodeViews[name] = factory.factory(args)
+    }
+
+    return () => [
+      new ProseMirrorPlugin({
+        key: new PluginKey('prosekit-node-view-effect'),
+        props: { nodeViews },
+      }),
+    ]
+  },
+  parent: pluginFacet,
+})

package/src/extensions/node-view.ts

@@ -0,0 +1,43 @@
+import {
+  PluginKey,
+  ProseMirrorPlugin,
+} from '@prosekit/pm/state'
+import type { NodeViewConstructor } from '@prosekit/pm/view'
+
+import { defineFacet } from '../facets/facet'
+import { defineFacetPayload } from '../facets/facet-extension'
+import type { Extension } from '../types/extension'
+
+import {
+  pluginFacet,
+  type PluginPayload,
+} from './plugin'
+
+export interface NodeViewOptions {
+  name: string
+  constructor: NodeViewConstructor
+}
+
+export function defineNodeView(options: NodeViewOptions): Extension {
+  return defineFacetPayload(nodeViewFacet, [options])
+}
+
+const nodeViewFacet = defineFacet<NodeViewOptions, PluginPayload>({
+  reducer: (inputs: NodeViewOptions[]): PluginPayload => {
+    const nodeViews: { [nodeName: string]: NodeViewConstructor } = {}
+
+    for (const input of inputs) {
+      if (!nodeViews[input.name]) {
+        nodeViews[input.name] = input.constructor
+      }
+    }
+
+    return () => [
+      new ProseMirrorPlugin({
+        key: new PluginKey('prosekit-node-view'),
+        props: { nodeViews },
+      }),
+    ]
+  },
+  parent: pluginFacet,
+})

package/src/extensions/paragraph.ts

@@ -0,0 +1,61 @@
+import type { Attrs } from '@prosekit/pm/model'
+
+import { withPriority } from '../editor/with-priority'
+import type { Extension } from '../types/extension'
+import { Priority } from '../types/priority'
+
+import { defineNodeSpec } from './node-spec'
+
+/**
+ * @internal
+ */
+type ParagraphSpecExtension = Extension<{
+  Nodes: {
+    paragraph: Attrs
+  }
+}>
+
+/**
+ * Defines a paragraph node spec.
+ */
+function defineParagraphSpec(): ParagraphSpecExtension {
+  return defineNodeSpec({
+    name: 'paragraph',
+    content: 'inline*',
+    group: 'block',
+    parseDOM: [{ tag: 'p' }],
+    toDOM() {
+      return ['p', 0]
+    },
+  })
+}
+
+/**
+ * @internal
+ *
+ * @deprecated Use the following import instead:
+ *
+ * ```ts
+ * import type { ParagraphExtension } from 'prosekit/extensions/paragraph'
+ * ```
+ */
+export type ParagraphExtension = ParagraphSpecExtension
+
+/**
+ * @public
+ *
+ * Defines a paragraph node spec as the highest priority, because it should be the default block node for most cases.
+ *
+ * @deprecated Use the following import instead:
+ *
+ * ```ts
+ * import { defineParagraph } from 'prosekit/extensions/paragraph'
+ * ```
+ */
+export function defineParagraph(): ParagraphExtension {
+  console.warn(
+    '[prosekit] The `defineParagraph` function from `prosekit/core` is deprecated. Use the following import instead: `import { defineParagraph } from "prosekit/extensions/paragraph"`.',
+  )
+
+  return withPriority(defineParagraphSpec(), Priority.highest)
+}

package/src/extensions/plugin.ts

@@ -0,0 +1,91 @@
+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'
+
+/**
+ * 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 {
+  if (
+    plugin instanceof Plugin
+    || (Array.isArray(plugin) && plugin.every((p) => p instanceof Plugin))
+  ) {
+    return definePluginPayload(() => plugin)
+  }
+
+  if (typeof plugin === 'function') {
+    return definePluginPayload(plugin)
+  }
+
+  throw new TypeError('Invalid 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 }) => {
+      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')
+        }
+      }
+
+      // In ProseMirror, the plugins at the beginning have a higher priority.
+      // However, in ProseKit, the extensions at the end have a higher priority
+      // because we want to easily override the default behaviors by appending
+      // new extensions. Therefore, we need to reverse plugins here.
+      plugins.reverse()
+      return { plugins }
+    }
+  },
+  parent: stateFacet,
+})