@prosekit/extensions 0.14.1 → 0.15.0

package/src/math/math.ts

@@ -1,9 +1,9 @@
 import { union, type Union } from '@prosekit/core'
 import type { RenderMathBlock, RenderMathInline } from 'prosemirror-math'
 
-import { defineMathBlock, type MathBlockExtension } from './math-block'
-import { defineMathInline, type MathInlineExtension } from './math-inline'
-import { defineMathPlugin } from './math-plugin'
+import { defineMathBlock, type MathBlockExtension } from './math-block.ts'
+import { defineMathInline, type MathInlineExtension } from './math-inline.ts'
+import { defineMathPlugin } from './math-plugin.ts'
 
 /**
  * @public

package/src/page/index.ts

@@ -0,0 +1,5 @@
+export { definePageBreakCommands, insertPageBreak, type PageBreakCommandsExtension } from './page-break-commands.ts'
+export { definePageBreakKeymap, type PageBreakKeymapExtension } from './page-break-keymap.ts'
+export { definePageBreakSpec, type PageBreakSpecExtension } from './page-break-spec.ts'
+export { definePageBreak, type PageBreakExtension } from './page-break.ts'
+export { definePageRendering, type PageRenderingExtension, type PageRenderingOptions } from './page-rendering.ts'

package/src/page/page-break-commands.spec.ts

@@ -0,0 +1,61 @@
+import { union } from '@prosekit/core'
+import { describe, expect, it } from 'vitest'
+
+import { defineDoc } from '../doc/index.ts'
+import { defineHardBreak } from '../hard-break/index.ts'
+import { defineHorizontalRule } from '../horizontal-rule/index.ts'
+import { defineParagraph } from '../paragraph/index.ts'
+import { setupTestFromExtension } from '../testing/index.ts'
+import { defineText } from '../text/index.ts'
+
+import { definePageBreak } from './page-break.ts'
+
+function setup() {
+  const extension = union(
+    defineDoc(),
+    defineText(),
+    defineParagraph(),
+    defineHorizontalRule(),
+    defineHardBreak(),
+    definePageBreak(),
+  )
+  return setupTestFromExtension(extension)
+}
+
+describe('insertPageBreak', () => {
+  it('should insert a page break in an empty paragraph', () => {
+    const { editor, n } = setup()
+    editor.set(n.doc(n.paragraph('<a>')))
+    editor.commands.insertPageBreak()
+    expect(editor.view.state.doc.toJSON()).toEqual(
+      n.doc(n.pageBreak()).toJSON(),
+    )
+  })
+
+  it('should insert a page break after text', () => {
+    const { editor, n } = setup()
+    editor.set(n.doc(n.paragraph('hello<a>')))
+    editor.commands.insertPageBreak()
+    expect(editor.view.state.doc.toJSON()).toEqual(
+      n.doc(n.paragraph('hello'), n.pageBreak()).toJSON(),
+    )
+  })
+
+  it('should insert a page break before text', () => {
+    const { editor, n } = setup()
+    editor.set(n.doc(n.paragraph('<a>hello')))
+    editor.commands.insertPageBreak()
+    expect(editor.view.state.doc.toJSON()).toEqual(
+      n.doc(n.pageBreak(), n.paragraph('hello')).toJSON(),
+    )
+  })
+
+  it('should insert a page break between text', () => {
+    const { editor, n } = setup()
+    editor.set(n.doc(n.paragraph('hel<a>lo')))
+    editor.commands.insertPageBreak()
+    expect(editor.view.state.doc.toJSON()).toEqual(
+      n.doc(n.paragraph('hel'), n.pageBreak(), n.paragraph('lo')).toJSON(),
+    )
+  })
+})

package/src/page/page-break-commands.ts

@@ -0,0 +1,41 @@
+import { defineCommands, getNodeType, type Extension } from '@prosekit/core'
+import { Fragment, Slice } from '@prosekit/pm/model'
+import type { Command } from '@prosekit/pm/state'
+
+/**
+ * @internal
+ */
+export type PageBreakCommandsExtension = Extension<{
+  Commands: {
+    insertPageBreak: []
+  }
+}>
+
+const insertPageBreakCommand: Command = (state, dispatch): boolean => {
+  if (!dispatch) return true
+
+  const { schema, tr } = state
+  const type = getNodeType(schema, 'pageBreak')
+  const node = type.createChecked()
+  const pos = tr.selection.anchor
+  const slice = new Slice(Fragment.from(node), 0, 0)
+  tr.replaceRange(pos, pos, slice).scrollIntoView()
+  dispatch(tr)
+  return true
+}
+
+/**
+ * @internal
+ */
+export function insertPageBreak(): Command {
+  return insertPageBreakCommand
+}
+
+/**
+ * @internal
+ */
+export function definePageBreakCommands(): PageBreakCommandsExtension {
+  return defineCommands({
+    insertPageBreak: insertPageBreak,
+  })
+}

package/src/page/page-break-keymap.ts

@@ -0,0 +1,17 @@
+import { defineKeymap, type PlainExtension } from '@prosekit/core'
+
+import { insertPageBreak } from './page-break-commands.ts'
+
+/**
+ * @internal
+ */
+export type PageBreakKeymapExtension = PlainExtension
+
+/**
+ * @internal
+ */
+export function definePageBreakKeymap(): PageBreakKeymapExtension {
+  return defineKeymap({
+    'Mod-Enter': insertPageBreak(),
+  })
+}

package/src/page/page-break-spec.ts

@@ -0,0 +1,33 @@
+import { defineNodeSpec, type Extension } from '@prosekit/core'
+import type { Attrs } from '@prosekit/pm/model'
+
+/**
+ * @internal
+ */
+export type PageBreakSpecExtension = Extension<{
+  Nodes: {
+    pageBreak: Attrs
+  }
+}>
+
+/**
+ * @internal
+ */
+export function definePageBreakSpec(): PageBreakSpecExtension {
+  return defineNodeSpec({
+    name: 'pageBreak',
+    group: 'block',
+    selectable: true,
+    parseDOM: [{ tag: 'div.prosekit-page-break' }],
+    toDOM() {
+      return ['div', { class: 'prosekit-horizontal-rule prosekit-page-break' }, ['hr']]
+    },
+    pageBreak: true,
+  })
+}
+
+declare module '@prosekit/pm/model' {
+  interface NodeSpec {
+    pageBreak?: boolean | undefined
+  }
+}

package/src/page/page-break.ts

@@ -0,0 +1,23 @@
+import { union, type Union } from '@prosekit/core'
+
+import { definePageBreakCommands, type PageBreakCommandsExtension } from './page-break-commands.ts'
+import { definePageBreakKeymap, type PageBreakKeymapExtension } from './page-break-keymap.ts'
+import { definePageBreakSpec, type PageBreakSpecExtension } from './page-break-spec.ts'
+
+/**
+ * @internal
+ */
+export type PageBreakExtension = Union<
+  [PageBreakSpecExtension, PageBreakCommandsExtension, PageBreakKeymapExtension]
+>
+
+/**
+ * @public
+ */
+export function definePageBreak(): PageBreakExtension {
+  return union(
+    definePageBreakSpec(),
+    definePageBreakCommands(),
+    definePageBreakKeymap(),
+  )
+}

package/src/page/page-element.ts

@@ -0,0 +1,246 @@
+import { once } from '@ocavue/utils'
+import { customElements, HTMLElement } from 'server-dom-shim'
+
+/**
+ * @internal
+ */
+export const PAGE_CHUNK_TAG_NAME = 'pm-page-chunk'
+
+/**
+ * @internal
+ */
+export const registerPageChunkElement: VoidFunction = /* @__PURE__ */ once(() => {
+  if (typeof window === 'undefined' || customElements.get(PAGE_CHUNK_TAG_NAME)) return
+  customElements.define(PAGE_CHUNK_TAG_NAME, PageChunkElement)
+})
+
+class PageChunkElement extends HTMLElement {
+  static observedAttributes = [
+    'data-group',
+    'data-break',
+    'data-h',
+    'data-mt',
+    'data-mb',
+
+    // Only the first chunk of the whole document has this attribute.
+    'data-size',
+  ]
+
+  // Data attributes set by external code
+  #group: string = ''
+  #forceNextBreak: boolean = false
+  #pageHeight: number = 0
+  #pageMarginTop: number = 0
+  #pageMarginBottom: number = 0
+  #size: number | undefined = undefined
+
+  // Internal states
+  #updateRequested: boolean = false
+  #contentBoxHeight: number = 0
+
+  // Rendering states
+  #isHead: boolean = false
+  #isTail: boolean = false
+  #paddingTop: number = 0
+  #paddingBottom: number = 0
+
+  // Pending rendering states
+  #isHeadPending: boolean = false
+  #isTailPending: boolean = false
+  #paddingTopPending: number = 0
+  #paddingBottomPending: number = 0
+
+  connectedCallback() {
+    this.#parseDataAttributes()
+
+    if (this.#isLeader()) {
+      this.#isHeadPending = true
+    }
+
+    this.#render()
+
+    // Get the initial content box height when the resize observer is not started yet. Notice that
+    // `this.clientHeight` is an integer while the content box height can be a float, so this is not
+    // accurate but should be good enough for the first render.
+    this.#contentBoxHeight = this.clientHeight - this.#paddingTop - this.#paddingBottom
+
+    observeElement(this)
+
+    this.#requestUpdate()
+  }
+
+  disconnectedCallback() {
+    unobserveElement(this)
+  }
+
+  attributeChangedCallback(_: string, oldValue: string | null, newValue: string | null) {
+    if (oldValue === newValue) return
+    this.#parseDataAttributes()
+    this.#requestUpdate()
+  }
+
+  #parseDataAttributes() {
+    this.#group = this.getAttribute('data-group') || ''
+    this.#forceNextBreak = this.hasAttribute('data-break')
+    this.#pageHeight = this.#parseFloatAttribute('data-h')
+    this.#pageMarginTop = this.#parseFloatAttribute('data-mt')
+    this.#pageMarginBottom = this.#parseFloatAttribute('data-mb')
+
+    const sizeAttr = this.getAttribute('data-size')
+    this.#size = sizeAttr ? Number.parseInt(sizeAttr, 10) : undefined
+  }
+
+  #parseFloatAttribute(name: string): number {
+    const value = this.getAttribute(name)
+    return value != null ? Number.parseFloat(value) : 0
+  }
+
+  #isLeader() {
+    return this.#size != null
+  }
+
+  #render() {
+    if (this.#paddingTop !== this.#paddingTopPending || this.#paddingBottom !== this.#paddingBottomPending) {
+      Object.assign(this.style, {
+        paddingTop: `${this.#paddingTop = this.#paddingTopPending}px`,
+        paddingBottom: `${this.#paddingBottom = this.#paddingBottomPending}px`,
+      })
+    }
+    if (this.#isHead !== this.#isHeadPending) {
+      this.toggleAttribute('data-page-head', this.#isHead = this.#isHeadPending)
+    }
+    if (this.#isTail !== this.#isTailPending) {
+      this.toggleAttribute('data-page-tail', this.#isTail = this.#isTailPending)
+    }
+  }
+
+  setHeight(height: number) {
+    // Avoid potential float number precision issues
+    if (Math.abs(this.#contentBoxHeight - height) < 0.1) {
+      return
+    }
+    this.#contentBoxHeight = height
+    this.#requestUpdate()
+  }
+
+  /**
+   * Schedules a batched page layout recalculation.
+   *
+   * Any chunk can call this method, but the actual layout work (#updateAll)
+   * always runs on the leader chunk, because it needs to iterate over every
+   * chunk in order to compute page breaks.
+   *
+   * Two nested microtasks are used to batch updates:
+   *
+   *   Microtask 1 – Delegation: non-leader chunks forward the request to the
+   *   leader chunk, so multiple chunks changing in the same tick only trigger
+   *   one layout pass.
+   *
+   *   Microtask 2 – Execution: the leader chunk defers #updateAll to a second
+   *   microtask so that any other attribute / resize changes that were queued
+   *   in the same tick (and forwarded during microtask 1) are already reflected
+   *   before the layout is recalculated.
+   *
+   * The #updateRequested flag acts as a deduplication guard so that rapid
+   * successive calls (e.g. multiple attributes changing at once) result in at
+   * most one scheduled pass per chunk.
+   */
+  #requestUpdate() {
+    if (this.#updateRequested) {
+      return
+    }
+
+    this.#updateRequested = true
+    queueMicrotask(() => {
+      if (!this.#isLeader()) {
+        this.#updateRequested = false
+        const leader = findLeaderChunk(this, this.#group)
+        if (!leader) return
+        leader.#requestUpdate()
+        return
+      }
+      queueMicrotask(() => {
+        this.#updateRequested = false
+        this.#updateAll()
+      })
+    })
+  }
+
+  #updateAll() {
+    if (!this.isConnected) {
+      return
+    }
+
+    const elements = findAllChunks(this, this.#group)
+    const count = elements.length
+    if (count === 0) return
+
+    const pageHeight = this.#pageHeight
+    const pageMarginTop = this.#pageMarginTop
+    const maxContentHeight = pageHeight - pageMarginTop - this.#pageMarginBottom
+
+    let currentContentHeight = 0
+    let forceNextBreak = false
+
+    for (let i = 0; i < count; i++) {
+      const element = elements[i]
+      const h = element.#contentBoxHeight
+      const isHead = forceNextBreak || i === 0 || (currentContentHeight + h > maxContentHeight)
+
+      forceNextBreak = element.#forceNextBreak
+
+      if (isHead && i > 0) {
+        const prev = elements[i - 1]
+        prev.#paddingBottomPending = Math.max(0, pageHeight - pageMarginTop - currentContentHeight)
+        prev.#isTailPending = true
+        currentContentHeight = h
+      } else {
+        currentContentHeight += h
+      }
+
+      element.#paddingTopPending = isHead ? pageMarginTop : 0
+      element.#paddingBottomPending = 0
+      element.#isTailPending = false
+      element.#isHeadPending = isHead
+    }
+
+    const last = elements[count - 1]
+    last.#paddingBottomPending = Math.max(0, pageHeight - pageMarginTop - currentContentHeight)
+    last.#isTailPending = true
+
+    for (const element of elements) {
+      element.#render()
+    }
+  }
+}
+
+function handleResize(entries: ResizeObserverEntry[]) {
+  for (const entry of entries) {
+    const contentBoxHeight = entry.contentBoxSize?.[0]?.blockSize ?? entry.contentRect.height
+    const element = entry.target as PageChunkElement
+    element.setHeight(contentBoxHeight)
+  }
+}
+
+const getResizeObserver = /* @__PURE__ */ once(() => {
+  return new ResizeObserver(handleResize)
+})
+
+function observeElement(element: PageChunkElement) {
+  getResizeObserver().observe(element)
+}
+
+function unobserveElement(element: PageChunkElement) {
+  getResizeObserver().unobserve(element)
+}
+
+function findLeaderChunk(element: HTMLElement, group: string): PageChunkElement | null | undefined {
+  const root = element.closest('.ProseMirror')
+  return root?.querySelector<PageChunkElement>(`${PAGE_CHUNK_TAG_NAME}[data-group="${group}"][data-size]`)
+}
+
+function findAllChunks(element: HTMLElement, group: string): PageChunkElement[] {
+  const root = element.closest('.ProseMirror')
+  const elements = root?.querySelectorAll<PageChunkElement>(`${PAGE_CHUNK_TAG_NAME}[data-group="${group}"]`)
+  return Array.from(elements || [])
+}

package/src/page/page-rendering.ts

@@ -0,0 +1,164 @@
+import { getId } from '@ocavue/utils'
+import { definePlugin, type Extension } from '@prosekit/core'
+import type { Node } from '@prosekit/pm/model'
+import { Plugin, PluginKey } from '@prosekit/pm/state'
+import { Decoration, DecorationSet } from '@prosekit/pm/view'
+
+import { PAGE_CHUNK_TAG_NAME, registerPageChunkElement } from './page-element.ts'
+
+/**
+ * @public
+ */
+export interface PageRenderingOptions {
+  /**
+   * The width of the page in px.
+   *
+   * @default 794 (Portrait A4 paper size in 96 DPI)
+   */
+  pageWidth?: number
+
+  /**
+   * The height of the page in px.
+   *
+   * @default 1123 (Portrait A4 paper size in 96 DPI)
+   */
+  pageHeight?: number
+
+  /**
+   * The top margin of the page in px.
+   *
+   * @default 70
+   */
+  marginTop?: number
+
+  /**
+   * The right margin of the page in px.
+   *
+   * @default 70
+   */
+  marginRight?: number
+
+  /**
+   * The bottom margin of the page in px.
+   *
+   * @default 70
+   */
+  marginBottom?: number
+
+  /**
+   * The left margin of the page in px.
+   *
+   * @default 70
+   */
+  marginLeft?: number
+}
+
+/**
+ * @public
+ */
+export function definePageRendering(options: PageRenderingOptions = {}): PageRenderingExtension {
+  return definePlugin(
+    createPageRenderingPlugin(options),
+  )
+}
+
+/**
+ * @internal
+ */
+export type PageRenderingExtension = Extension
+
+function createPageRenderingPlugin(options: PageRenderingOptions): Plugin {
+  const {
+    pageWidth = 794,
+    pageHeight = 1123,
+    marginTop = 70,
+    marginRight = 70,
+    marginBottom = 70,
+    marginLeft = 70,
+  } = options
+
+  type PluginState = [group: string, decoration: DecorationSet]
+
+  const key = new PluginKey<PluginState>('prosekit-page-render')
+
+  function createDecorationSet(doc: Node, group: string): DecorationSet {
+    const decorations: Decoration[] = []
+    const totalCount = doc.childCount
+
+    doc.forEach((node, pos, index) => {
+      const isPageBreak: boolean | undefined = node.type.spec.pageBreak
+
+      decorations.push(Decoration.node(pos, pos + node.nodeSize, {
+        'nodeName': PAGE_CHUNK_TAG_NAME,
+        'data-group': group,
+        'data-break': isPageBreak ? 'true' : undefined,
+        'data-h': String(pageHeight),
+        'data-mt': String(marginTop),
+        'data-mb': String(marginBottom),
+        'data-size': index === 0 ? String(totalCount) : undefined,
+      }))
+    })
+
+    return DecorationSet.create(doc, decorations)
+  }
+
+  return new Plugin<PluginState>({
+    key,
+    view: () => {
+      registerPageChunkElement()
+      return {}
+    },
+    state: {
+      init: (_config, state): PluginState => {
+        const group = `page-group-${getId()}`
+        const decoration = createDecorationSet(state.doc, group)
+        return [group, decoration]
+      },
+      apply: (tr, value, oldState, newState): PluginState => {
+        if (!tr.docChanged) return value
+
+        const [group, decoration] = value
+
+        let needRecreate = oldState.doc.childCount !== newState.doc.childCount
+
+        if (!needRecreate) {
+          const count = oldState.doc.childCount
+          for (let i = 0; i < count; i++) {
+            const oldNode = oldState.doc.child(i)
+            const newNode = newState.doc.child(i)
+            if (oldNode.type !== newNode.type) {
+              needRecreate = true
+              break
+            }
+          }
+        }
+
+        if (!needRecreate) {
+          const mapped = decoration.map(tr.mapping, tr.doc, {
+            onRemove: () => {
+              needRecreate = true
+            },
+          })
+          if (!needRecreate) {
+            return [group, mapped]
+          }
+        }
+
+        return [group, createDecorationSet(newState.doc, group)]
+      },
+    },
+    props: {
+      decorations: (state) => {
+        return key.getState(state)?.[1]
+      },
+      attributes: {
+        style: [
+          `--page-margin-right:${marginRight}px;`,
+          `--page-margin-left:${marginLeft}px;`,
+          `--page-width:${pageWidth}px;`,
+          `--page-height:${pageHeight}px;`,
+        ].join(''),
+      },
+    },
+  })
+}

package/src/page/style.css

@@ -0,0 +1,43 @@
+.ProseMirror pm-page-chunk {
+  box-sizing: border-box;
+  display: flow-root;
+  position: relative;
+  width: var(--page-width, 100%);
+  margin: 0;
+  padding-top: 0;
+  padding-right: var(--page-margin-right, 0);
+  padding-bottom: 0;
+  padding-left: var(--page-margin-left, 0);
+}
+
+.ProseMirror pm-page-chunk ~ pm-page-chunk[data-page-head] {
+  margin-top: 50px;
+}
+
+@media print {
+  .ProseMirror pm-page-chunk ~ pm-page-chunk[data-page-head] {
+    margin-top: 0;
+  }
+}
+
+.ProseMirror pm-page-chunk[data-page-head]::before {
+  box-sizing: border-box;
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: var(--page-height);
+  outline: 1px solid CanvasText;
+  content: "";
+  pointer-events: none;
+}
+
+@media print {
+  .ProseMirror pm-page-chunk[data-page-head]::before {
+    outline-color: transparent;
+  }
+}
+
+.ProseMirror pm-page-chunk[data-page-tail] {
+  break-after: page;
+}

package/src/paragraph/index.ts

@@ -1,7 +1,7 @@
-export { defineParagraph } from './paragraph'
-export type { ParagraphExtension } from './paragraph'
-export { defineParagraphCommands } from './paragraph-commands'
-export type { ParagraphCommandsExtension } from './paragraph-commands'
-export { defineParagraphKeymap } from './paragraph-keymap'
-export { defineParagraphSpec } from './paragraph-spec'
-export type { ParagraphSpecExtension } from './paragraph-spec'
+export { defineParagraphCommands } from './paragraph-commands.ts'
+export type { ParagraphCommandsExtension } from './paragraph-commands.ts'
+export { defineParagraphKeymap } from './paragraph-keymap.ts'
+export { defineParagraphSpec } from './paragraph-spec.ts'
+export type { ParagraphSpecExtension } from './paragraph-spec.ts'
+export { defineParagraph } from './paragraph.ts'
+export type { ParagraphExtension } from './paragraph.ts'

package/src/paragraph/paragraph-keymap.ts

@@ -1,6 +1,6 @@
 import { defineKeymap, type PlainExtension } from '@prosekit/core'
 
-import { setParagraph } from './paragraph-commands'
+import { setParagraph } from './paragraph-commands.ts'
 
 /**
  * @internal