@prosekit/extensions 0.11.3 → 0.11.5

package/src/file/file-drop-handler.ts

@@ -0,0 +1,75 @@
+import {
+  defineFacet,
+  defineFacetPayload,
+  editorEventFacet,
+  type DropHandler,
+  type EditorEventPayload,
+  type PlainExtension,
+} from '@prosekit/core'
+import type { EditorView } from '@prosekit/pm/view'
+
+import { handleEvent } from './helpers'
+
+export interface FileDropHandlerOptions {
+  /**
+   * The editor view.
+   */
+  view: EditorView
+
+  /**
+   * The event that triggered the drop.
+   */
+  event: DragEvent
+
+  /**
+   * The file that was dropped.
+   */
+  file: File
+
+  /**
+   * The position of the document where the file was dropped.
+   */
+  pos: number
+}
+
+/**
+ * A function that handles one of the files in a drop event.
+ *
+ * Returns `true` if the file was handled and thus should not be handled by
+ * other handlers.
+ */
+export type FileDropHandler = (
+  options: FileDropHandlerOptions,
+) => boolean | void
+
+export function defineFileDropHandler(
+  handler: FileDropHandler,
+): PlainExtension {
+  return defineFacetPayload(facet, [handler]) as PlainExtension
+}
+
+function getFiles(event: DragEvent) {
+  return Array.from(event.dataTransfer?.files ?? [])
+}
+
+const facet = defineFacet<FileDropHandler, EditorEventPayload>({
+  parent: editorEventFacet,
+  singleton: true,
+  reducer: (handlers: FileDropHandler[]): EditorEventPayload => {
+    const dropHandler: DropHandler = (view, event): boolean => {
+      const position = view.posAtCoords({ left: event.x, top: event.y })
+      if (!position) {
+        return false
+      }
+      const pos = position.inside > 0 ? position.inside : position.pos
+
+      return handleEvent<DragEvent>(
+        view,
+        event,
+        handlers.map((handler) => (options) => handler({ ...options, pos })),
+        getFiles,
+      )
+    }
+    return ['drop', dropHandler]
+  },
+})

package/src/file/file-paste-handler.spec.ts

@@ -0,0 +1,95 @@
+import {
+  Priority,
+  union,
+  withPriority,
+} from '@prosekit/core'
+import {
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+} from 'vitest'
+
+import {
+  defineTestExtension,
+  setupTestFromExtension,
+} from '../testing'
+import { pasteFiles } from '../testing/clipboard'
+
+import { defineFilePasteHandler } from './file-paste-handler'
+
+function definePngPasteHandler(handler: VoidFunction) {
+  const extension = defineFilePasteHandler((options) => {
+    if (options.file.type === 'image/png') {
+      handler()
+      return true
+    }
+  })
+  return withPriority(extension, Priority.high)
+}
+
+function defineImagePasteHandler(handler: VoidFunction) {
+  const extension = defineFilePasteHandler((options) => {
+    if (options.file.type.startsWith('image/')) {
+      handler()
+      return true
+    }
+  })
+  return withPriority(extension, Priority.default)
+}
+
+function defineFallbackPasteHandler(handler: VoidFunction) {
+  const extension = defineFilePasteHandler(() => {
+    handler()
+    return true
+  })
+  return withPriority(extension, Priority.low)
+}
+
+describe('file paste handler', () => {
+  const pngHandler = vi.fn()
+  const imageHandler = vi.fn()
+  const fallbackHandler = vi.fn()
+
+  const extension = union(
+    defineTestExtension(),
+    defineImagePasteHandler(imageHandler),
+    definePngPasteHandler(pngHandler),
+    defineFallbackPasteHandler(fallbackHandler),
+  )
+  const { editor } = setupTestFromExtension(extension)
+  const paste = (files: File[]) => {
+    pasteFiles(editor.view, files)
+  }
+
+  beforeEach(() => {
+    pngHandler.mockClear()
+    imageHandler.mockClear()
+    fallbackHandler.mockClear()
+  })
+
+  it('should handle file pasting', () => {
+    paste([new File([''], 'test.png', { type: 'image/png' })])
+    expect(pngHandler).toHaveBeenCalled()
+    expect(imageHandler).not.toHaveBeenCalled()
+    expect(fallbackHandler).not.toHaveBeenCalled()
+  })
+
+  it('should handle priority', () => {
+    paste([new File([''], 'test.jpg', { type: 'image/jpg' })])
+    expect(pngHandler).not.toHaveBeenCalled()
+    expect(imageHandler).toHaveBeenCalled()
+    expect(fallbackHandler).not.toHaveBeenCalled()
+  })
+
+  it('should handle multiple files', () => {
+    paste([
+      new File([''], 'test.png', { type: 'image/png' }),
+      new File([''], 'test.pdf', { type: 'application/pdf' }),
+    ])
+    expect(pngHandler).toHaveBeenCalled()
+    expect(imageHandler).not.toHaveBeenCalled()
+    expect(fallbackHandler).toHaveBeenCalled()
+  })
+})

package/src/file/file-paste-handler.ts

@@ -0,0 +1,59 @@
+import {
+  defineFacet,
+  defineFacetPayload,
+  editorEventFacet,
+  type EditorEventPayload,
+  type PasteHandler,
+  type PlainExtension,
+} from '@prosekit/core'
+import type { EditorView } from '@prosekit/pm/view'
+
+import { handleEvent } from './helpers'
+
+export interface FilePasteHandlerOptions {
+  /**
+   * The editor view.
+   */
+  view: EditorView
+
+  /**
+   * The event that triggered the paste.
+   */
+  event: ClipboardEvent
+
+  /**
+   * The file that was pasted.
+   */
+  file: File
+}
+
+/**
+ * A function that handles one of the files in a paste event.
+ *
+ * Returns `true` if the file was handled and thus should not be handled by
+ * other handlers.
+ */
+export type FilePasteHandler = (
+  options: FilePasteHandlerOptions,
+) => boolean | void
+
+export function defineFilePasteHandler(
+  handler: FilePasteHandler,
+): PlainExtension {
+  return defineFacetPayload(facet, [handler]) as PlainExtension
+}
+
+function getFiles(event: ClipboardEvent) {
+  return Array.from(event.clipboardData?.files ?? [])
+}
+
+const facet = defineFacet<FilePasteHandler, EditorEventPayload>({
+  parent: editorEventFacet,
+  singleton: true,
+  reducer: (handlers: FilePasteHandler[]): EditorEventPayload => {
+    const pasteHandler: PasteHandler = (view, event): boolean => {
+      return handleEvent<ClipboardEvent>(view, event, handlers, getFiles)
+    }
+    return ['paste', pasteHandler]
+  },
+})

package/src/file/file-upload.ts

@@ -0,0 +1,119 @@
+/**
+ * An interface representing the upload progress.
+ */
+export interface UploadProgress {
+  // A number representing the amount of work already performed by the
+  // underlying process.
+  loaded: number
+  // A number representing the total amount of work that the underlying
+  // process is in the progress of performing.
+  total: number
+}
+
+export interface UploaderOptions {
+  /**
+   * The file to be uploaded.
+   */
+  file: File
+
+  /**
+   * A callback function that should be called with the upload progress updates.
+   */
+  onProgress: (progress: UploadProgress) => void
+}
+
+/**
+ * The implementation of the actual upload function. You need to implement this
+ * function to upload files to your desired destination.
+ */
+export type Uploader<Result> = (options: UploaderOptions) => Promise<Result>
+
+/**
+ * A class that represents a upload task.
+ */
+export class UploadTask<Result> {
+  /**
+   * An [object URL](https://developer.mozilla.org/en-US/docs/Web/API/URL/createObjectURL)
+   * representing the file to be uploaded. This URL will be revoked once the
+   * upload is complete successfully.
+   */
+  readonly objectURL: string
+
+  /**
+   * A boolean indicating whether the upload is complete (either successfully or with an error).
+   */
+  protected done = false
+
+  /**
+   * A promise that fulfills once the upload is complete, or rejects if an error occurs.
+   */
+  readonly finished: Promise<Result>
+
+  private subscribers: ((progress: UploadProgress) => void)[] = []
+
+  /**
+   * Creates a new upload task. You can find the upload task by its object URL
+   * later using `UploadTask.get()`.
+   *
+   * @param options - The options for the upload task.
+   */
+  constructor({ file, uploader }: { file: File; uploader: Uploader<Result> }) {
+    this.objectURL = URL.createObjectURL(file)
+    this.finished = new Promise((resolve, reject) => {
+      const maybePromise = uploader({
+        file,
+        onProgress: (progress) => {
+          for (const subscriber of this.subscribers) {
+            subscriber(progress)
+          }
+        },
+      })
+      Promise.resolve(maybePromise).then(
+        (result) => {
+          this.done = true
+          URL.revokeObjectURL(this.objectURL)
+          resolve(result)
+        },
+        (error) => {
+          this.done = true
+          reject(
+            new Error('[prosekit] Failed to upload file', { cause: error }),
+          )
+        },
+      )
+    })
+    store.set(this.objectURL, this)
+  }
+
+  /**
+   * Subscribes to progress updates. Returns a function to unsubscribe.
+   */
+  public subscribeProgress(
+    callback: (progress: UploadProgress) => void,
+  ): VoidFunction {
+    this.subscribers.push(callback)
+    return () => {
+      this.subscribers = this.subscribers.filter(
+        (subscriber) => subscriber !== callback,
+      )
+    }
+  }
+
+  /**
+   * Finds an upload task by its object URL.
+   */
+  static get<Result = unknown>(
+    objectURL: string,
+  ): UploadTask<Result> | undefined {
+    return store.get(objectURL) as UploadTask<Result> | undefined
+  }
+
+  /**
+   * Deletes an upload task by its object URL.
+   */
+  static delete(objectURL: string): void {
+    store.delete(objectURL)
+  }
+}
+
+const store = new Map<string, UploadTask<unknown>>()

package/src/file/helpers.ts

@@ -0,0 +1,39 @@
+import type { EditorView } from '@prosekit/pm/view'
+
+type FileHandler<E extends Event> = (options: {
+  view: EditorView
+  event: E
+  file: File
+}) => boolean | void
+
+function handleFile<E extends Event>(
+  view: EditorView,
+  event: E,
+  file: File,
+  handlers: FileHandler<E>[],
+) {
+  // The last item in `handlers` should has the highest priority.
+  for (let i = handlers.length - 1; i >= 0; i--) {
+    const handler = handlers[i]
+    if (handler({ view, event, file })) {
+      return true
+    }
+  }
+  return false
+}
+
+export function handleEvent<E extends Event>(
+  view: EditorView,
+  event: E,
+  handlers: FileHandler<E>[],
+  getFiles: (event: E) => File[],
+): boolean {
+  const files = getFiles(event)
+  let handled = false
+  for (const file of files) {
+    if (handleFile(view, event, file, handlers)) {
+      handled = true
+    }
+  }
+  return handled
+}

package/src/file/index.ts

@@ -0,0 +1,16 @@
+export {
+  defineFileDropHandler,
+  type FileDropHandler,
+  type FileDropHandlerOptions,
+} from './file-drop-handler'
+export {
+  defineFilePasteHandler,
+  type FilePasteHandler,
+  type FilePasteHandlerOptions,
+} from './file-paste-handler'
+export {
+  UploadTask,
+  type Uploader,
+  type UploaderOptions,
+  type UploadProgress,
+} from './file-upload'

package/src/gap-cursor/gap-cursor.ts

@@ -0,0 +1,28 @@
+import {
+  definePlugin,
+  type PlainExtension,
+} from '@prosekit/core'
+import { gapCursor } from 'prosemirror-gapcursor'
+
+/**
+ * @internal
+ */
+export type GapCursorExtension = PlainExtension
+
+/**
+ * Capture clicks near and arrow-key-motion past places that don't have a
+ * normally selectable position nearby, and create a gap cursor selection for
+ * them. The cursor is drawn as an element with class `ProseMirror-gapcursor`.
+ *
+ * You can either include `prosekit/extensions/gap-cursor.css` or add your own
+ * styles to make it visible.
+ *
+ * See
+ * [prosemirror-gapcursor](https://github.com/ProseMirror/prosemirror-gapcursor)
+ * for more information.
+ *
+ * @public
+ */
+export function defineGapCursor(): GapCursorExtension {
+  return definePlugin(() => gapCursor())
+}

package/src/gap-cursor/index.ts

@@ -0,0 +1,4 @@
+export {
+  defineGapCursor,
+  type GapCursorExtension,
+} from './gap-cursor'

package/src/gap-cursor/style.css

@@ -0,0 +1,25 @@
+.ProseMirror-gapcursor {
+  display: none;
+  position: relative;
+  pointer-events: none;
+}
+
+.ProseMirror-gapcursor:after {
+  display: block;
+  position: absolute;
+  top: -2px;
+  width: 20px;
+  border-top: 1px solid currentColor;
+  content: "";
+  animation: ProseMirror-cursor-blink 1.1s steps(2, start) infinite;
+}
+
+@keyframes ProseMirror-cursor-blink {
+  to {
+    visibility: hidden;
+  }
+}
+
+.ProseMirror-focused .ProseMirror-gapcursor {
+  display: block;
+}

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

@@ -0,0 +1,31 @@
+import {
+  defineCommands,
+  insertNode,
+  type Extension,
+} from '@prosekit/core'
+import type { Command } from '@prosekit/pm/state'
+
+/**
+ * @internal
+ */
+export type HardBreakCommandsExtension = Extension<{
+  Commands: {
+    insertHardBreak: []
+  }
+}>
+
+/**
+ * @internal
+ */
+export function insertHardBreak(): Command {
+  return insertNode({ type: 'hardBreak' })
+}
+
+/**
+ * @internal
+ */
+export function defineHardBreakCommands(): HardBreakCommandsExtension {
+  return defineCommands({
+    insertHardBreak: insertHardBreak,
+  })
+}

package/src/hard-break/hard-break-keymap.spec.ts

@@ -0,0 +1,45 @@
+import {
+  describe,
+  expect,
+  it,
+} from 'vitest'
+
+import { setupTest } from '../testing'
+import {
+  inputText,
+  pressKey,
+} from '../testing/keyboard'
+
+describe('defineHardBreakKeymap', () => {
+  it('should insert hard break', async () => {
+    const { editor, n } = setupTest()
+
+    const doc1 = n.doc(n.p('foo<a>bar'))
+    const doc2 = n.doc(n.p('foo', n.hardBreak(), 'bar'))
+
+    editor.set(doc1)
+    expect(editor.state.doc.toJSON()).toEqual(doc1.toJSON())
+    await pressKey('Shift-Enter')
+    expect(editor.state.doc.toJSON()).toEqual(doc2.toJSON())
+
+    editor.set(doc1)
+    expect(editor.state.doc.toJSON()).toEqual(doc1.toJSON())
+    await pressKey('Mod-Enter')
+    expect(editor.state.doc.toJSON()).toEqual(doc2.toJSON())
+  })
+
+  it('can continue to type after a hard break', async () => {
+    const { editor, n } = setupTest()
+
+    const doc1 = n.doc(n.p('foo<a>bar'))
+    const doc2 = n.doc(n.p('foo', n.hardBreak(), 'bar'))
+    const doc3 = n.doc(n.p('foo', n.hardBreak(), 'bazbar'))
+
+    editor.set(doc1)
+    expect(editor.state.doc.toJSON()).toEqual(doc1.toJSON())
+    await pressKey('Shift-Enter')
+    expect(editor.state.doc.toJSON()).toEqual(doc2.toJSON())
+    await inputText('baz')
+    expect(editor.state.doc.toJSON()).toEqual(doc3.toJSON())
+  })
+})

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

@@ -0,0 +1,16 @@
+import {
+  defineKeymap,
+  type PlainExtension,
+} from '@prosekit/core'
+
+import { insertHardBreak } from './hard-break-commands'
+
+/**
+ * @internal
+ */
+export function defineHardBreakKeymap(): PlainExtension {
+  return defineKeymap({
+    'Mod-Enter': insertHardBreak(),
+    'Shift-Enter': insertHardBreak(),
+  })
+}

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

@@ -0,0 +1,31 @@
+import {
+  defineNodeSpec,
+  type Extension,
+} from '@prosekit/core'
+import type { Attrs } from '@prosekit/pm/model'
+
+/**
+ * @internal
+ */
+export type HardBreakSpecExtension = Extension<{
+  Nodes: {
+    hardBreak: Attrs
+  }
+}>
+
+/**
+ * @internal
+ */
+export function defineHardBreakSpec(): HardBreakSpecExtension {
+  return defineNodeSpec({
+    name: 'hardBreak',
+    inline: true,
+    selectable: false,
+    leafText: () => '\n',
+    group: 'inline',
+    parseDOM: [{ tag: 'br' }],
+    toDOM() {
+      return ['br']
+    },
+  })
+}

package/src/hard-break/hard-break.ts

@@ -0,0 +1,32 @@
+import {
+  union,
+  type Union,
+} from '@prosekit/core'
+
+import {
+  defineHardBreakCommands,
+  type HardBreakCommandsExtension,
+} from './hard-break-commands'
+import { defineHardBreakKeymap } from './hard-break-keymap'
+import {
+  defineHardBreakSpec,
+  type HardBreakSpecExtension,
+} from './hard-break-spec'
+
+/**
+ * @internal
+ */
+export type HardBreakExtension = Union<
+  [HardBreakSpecExtension, HardBreakCommandsExtension]
+>
+
+/**
+ * @public
+ */
+export function defineHardBreak(): HardBreakExtension {
+  return union(
+    defineHardBreakSpec(),
+    defineHardBreakKeymap(),
+    defineHardBreakCommands(),
+  )
+}

package/src/hard-break/index.ts

@@ -0,0 +1,13 @@
+export {
+  defineHardBreak,
+  type HardBreakExtension,
+} from './hard-break'
+export {
+  defineHardBreakCommands,
+  type HardBreakCommandsExtension,
+} from './hard-break-commands'
+export { defineHardBreakKeymap } from './hard-break-keymap'
+export {
+  defineHardBreakSpec,
+  type HardBreakSpecExtension,
+} from './hard-break-spec'

package/src/heading/heading-commands.ts

@@ -0,0 +1,37 @@
+import {
+  defineCommands,
+  insertNode,
+  setBlockType,
+  toggleNode,
+  type Extension,
+} from '@prosekit/core'
+
+import type { HeadingAttrs } from './heading-types'
+
+/**
+ * @internal
+ */
+export type HeadingCommandsExtension = Extension<{
+  Commands: {
+    setHeading: [attrs?: HeadingAttrs | undefined]
+    insertHeading: [attrs?: HeadingAttrs | undefined]
+    toggleHeading: [attrs?: HeadingAttrs | undefined]
+  }
+}>
+
+/**
+ * @internal
+ */
+export function defineHeadingCommands(): HeadingCommandsExtension {
+  return defineCommands({
+    setHeading: (attrs?: HeadingAttrs) => {
+      return setBlockType({ type: 'heading', attrs })
+    },
+    insertHeading: (attrs?: HeadingAttrs) => {
+      return insertNode({ type: 'heading', attrs })
+    },
+    toggleHeading: (attrs?: HeadingAttrs) => {
+      return toggleNode({ type: 'heading', attrs })
+    },
+  })
+}

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

@@ -0,0 +1,22 @@
+import type { PlainExtension } from '@prosekit/core'
+
+import { defineTextBlockInputRule } from '../input-rule'
+
+import type { HeadingAttrs } from './heading-types'
+
+/**
+ * Converts the text block to a heading when `#` is typed at the start of a new
+ * line followed by a space.
+ *
+ * @internal
+ */
+export function defineHeadingInputRule(): PlainExtension {
+  return defineTextBlockInputRule({
+    regex: /^(#{1,6})\s$/,
+    type: 'heading',
+    attrs: (match) => {
+      const level: number = match[1]?.length ?? 1
+      return { level } satisfies HeadingAttrs
+    },
+  })
+}