@prosekit/extensions 0.11.4 → 0.11.6

package/src/enter-rule/index.ts

@@ -0,0 +1,241 @@
+import {
+  defineFacet,
+  defineFacetPayload,
+  getNodeType,
+  isTextSelection,
+  maybeRun,
+  OBJECT_REPLACEMENT_CHARACTER,
+  pluginFacet,
+  type PlainExtension,
+  type PluginPayload,
+} from '@prosekit/core'
+import { keydownHandler } from '@prosekit/pm/keymap'
+import type {
+  Attrs,
+  NodeType,
+} from '@prosekit/pm/model'
+import {
+  PluginKey,
+  ProseMirrorPlugin,
+  type Command,
+  type EditorState,
+  type Transaction,
+} from '@prosekit/pm/state'
+import type { EditorView } from '@prosekit/pm/view'
+
+/**
+ * @public
+ *
+ * Options for {@link EnterRuleHandler}.
+ */
+export interface EnterRuleHandlerOptions {
+  /**
+   * The current editor state.
+   */
+  state: EditorState
+
+  /**
+   * The start position of the matched text.
+   */
+  from: number
+
+  /**
+   * The end position of the matched text.
+   */
+  to: number
+
+  /**
+   * The matched result from the regular expression.
+   */
+  match: RegExpExecArray
+}
+
+/**
+ * @public
+ */
+export type EnterRuleHandler = (options: EnterRuleHandlerOptions) => Transaction | null
+
+/**
+ * Options for {@link defineEnterRule}.
+ *
+ * @public
+ */
+export type EnterRuleOptions = {
+  /**
+   * The regular expression to match against. It should end with `$`.
+   */
+  regex: RegExp
+
+  /**
+   * A function to be called when an enter rule is triggered.
+   */
+  handler: EnterRuleHandler
+
+  /**
+   * Whether to stop further handlers from being called if this rule is triggered.
+   *
+   * @default false
+   */
+  stop?: boolean
+}
+
+/**
+ * Options for {@link defineTextBlockEnterRule}.
+ *
+ * @public
+ */
+export interface TextBlockEnterRuleOptions {
+  /**
+   * The regular expression to match against. It should end with `$`.
+   */
+  regex: RegExp
+
+  /**
+   * The node type to replace the matched text with.
+   */
+  type: string | NodeType
+
+  /**
+   * Attributes to set on the node. If a function is provided, it will be called
+   * with the matched result from the regular expression.
+   */
+  attrs?: Attrs | null | ((match: RegExpMatchArray) => Attrs | null)
+
+  /**
+   * Whether to stop further handlers from being called if this rule is triggered.
+   *
+   * @default true
+   */
+  stop?: boolean
+}
+
+/**
+ * Defines an enter rule. An enter rule applies when the text directly in front of
+ * the cursor matches `regex` and user presses Enter. The `regex` should end
+ * with `$`.
+ *
+ * @param options
+ *
+ * @public
+ */
+export function defineEnterRule({
+  regex,
+  handler,
+  stop = false,
+}: EnterRuleOptions): PlainExtension {
+  const rule: EnterRule = new EnterRule(regex, handler, stop)
+  return defineFacetPayload(enterRule, [rule]) as PlainExtension
+}
+
+/**
+ * Defines an enter rule that replaces the matched text with a block node.
+ *
+ * See also {@link defineEnterRule}.
+ *
+ * @param options
+ *
+ * @public
+ */
+export function defineTextBlockEnterRule({
+  regex,
+  type,
+  attrs,
+  stop = true,
+}: TextBlockEnterRuleOptions): PlainExtension {
+  return defineEnterRule({
+    regex,
+    handler: ({ state, from, to, match }) => {
+      const nodeType = getNodeType(state.schema, type)
+      const $start = state.doc.resolve(from)
+
+      if (
+        !$start
+          .node(-1)
+          .canReplaceWith($start.index(-1), $start.indexAfter(-1), nodeType)
+      ) {
+        return null
+      }
+
+      const nodeAttrs = maybeRun(attrs, match)
+      return state.tr
+        .delete(from, to)
+        .setBlockType(from, from, nodeType, nodeAttrs)
+    },
+    stop,
+  })
+}
+
+/**
+ * @internal
+ */
+class EnterRule {
+  constructor(
+    readonly regex: RegExp,
+    readonly handler: EnterRuleHandler,
+    readonly stop: boolean,
+  ) {}
+}
+
+const enterRule = defineFacet<EnterRule, PluginPayload>({
+  reduce: () => {
+    let rules: EnterRule[] = []
+
+    const command: Command = (state, dispatch, view) => {
+      if (!view) return false
+      return execRules(view, rules, dispatch)
+    }
+    const handler = keydownHandler({ Enter: command })
+    const plugin = new ProseMirrorPlugin({
+      key: new PluginKey('prosekit-enter-rule'),
+      props: { handleKeyDown: handler },
+    })
+
+    return function reducer(inputs) {
+      rules = inputs
+      return plugin
+    }
+  },
+
+  parent: pluginFacet,
+})
+
+function execRules(
+  view: EditorView,
+  rules: readonly EnterRule[],
+  dispatch?: (tr: Transaction) => void,
+): boolean {
+  if (view.composing) return false
+  const state = view.state
+  const selection = state.selection
+  if (!isTextSelection(selection)) return false
+  const $cursor = selection.$cursor
+  if (!$cursor || $cursor.parent.type.spec.code) return false
+
+  const textBefore = $cursor.parent.textBetween(
+    Math.max(0, $cursor.parentOffset - MAX_MATCH),
+    $cursor.parentOffset,
+    null,
+    OBJECT_REPLACEMENT_CHARACTER,
+  )
+
+  for (const rule of rules) {
+    rule.regex.lastIndex = 0
+    const match = rule.regex.exec(textBefore)
+    const tr = match
+      && rule.handler({
+        state,
+        from: $cursor.pos - match[0].length,
+        to: $cursor.pos,
+        match,
+      })
+    if (!tr) continue
+    dispatch?.(tr)
+
+    if (rule.stop) {
+      return true
+    }
+  }
+  return false
+}
+
+const MAX_MATCH = 200

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,140 @@
+import { ProseKitError } from '@prosekit/core'
+
+/**
+ * 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
+
+  /**
+   * If the upload is complete successfully, this will be the result of the upload.
+   */
+  protected result: Result | undefined
+
+  /**
+   * If the upload is complete with an error, this will be the error that occurred.
+   */
+  protected error: Error | undefined
+
+  /**
+   * 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) => {
+          if (typeof progress.total !== 'number') {
+            throw new TypeError('total must be a number')
+          }
+          if (typeof progress.loaded !== 'number') {
+            throw new TypeError('loaded must be a number')
+          }
+          if (progress.loaded > 0) {
+            for (const subscriber of this.subscribers) {
+              subscriber(progress)
+            }
+          }
+        },
+      })
+      Promise.resolve(maybePromise).then(
+        (result) => {
+          this.done = true
+          URL.revokeObjectURL(this.objectURL)
+          this.result = result
+          resolve(result)
+        },
+        (err) => {
+          this.done = true
+          const error = new ProseKitError('[prosekit] Failed to upload file', { cause: err })
+          this.error = error
+          reject(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 from the global store 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 from the global store 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'