@tiptap/core 3.0.0-next.4 → 3.0.0-next.6

package/src/types.ts

@@ -1,11 +1,13 @@
 import { Mark as ProseMirrorMark, Node as ProseMirrorNode, ParseOptions, Slice } from '@tiptap/pm/model'
 import { EditorState, Transaction } from '@tiptap/pm/state'
-import { Mappable } from '@tiptap/pm/transform'
+import { Mappable, Transform } from '@tiptap/pm/transform'
 import {
   Decoration,
   DecorationAttrs,
   EditorProps,
   EditorView,
+  MarkView,
+  MarkViewConstructor,
   NodeView,
   NodeViewConstructor,
   ViewMutationRecord,
@@ -37,10 +39,26 @@ export type MaybeThisParameterType<T> =
   Exclude<T, Primitive> extends (...args: any) => any ? ThisParameterType<Exclude<T, Primitive>> : any
 
 export interface EditorEvents {
-  beforeCreate: { editor: Editor }
-  create: { editor: Editor }
+  beforeCreate: {
+    /**
+     * The editor instance
+     */
+    editor: Editor
+  }
+  create: {
+    /**
+     * The editor instance
+     */
+    editor: Editor
+  }
   contentError: {
+    /**
+     * The editor instance
+     */
     editor: Editor
+    /**
+     * The error that occurred while parsing the content
+     */
     error: Error
     /**
      * If called, will re-initialize the editor with the collaboration extension removed.
@@ -48,35 +66,253 @@ export interface EditorEvents {
      */
     disableCollaboration: () => void
   }
-  update: { editor: Editor; transaction: Transaction; appendedTransactions: Transaction[] }
-  selectionUpdate: { editor: Editor; transaction: Transaction }
-  beforeTransaction: { editor: Editor; transaction: Transaction; nextState: EditorState }
-  transaction: { editor: Editor; transaction: Transaction; appendedTransactions: Transaction[] }
-  focus: { editor: Editor; event: FocusEvent; transaction: Transaction }
-  blur: { editor: Editor; event: FocusEvent; transaction: Transaction }
+  update: {
+    /**
+     * The editor instance
+     */
+    editor: Editor
+    /**
+     * The transaction that caused the update
+     */
+    transaction: Transaction
+    /**
+     * Appended transactions that were added to the initial transaction by plugins
+     */
+    appendedTransactions: Transaction[]
+  }
+  selectionUpdate: {
+    /**
+     * The editor instance
+     */
+    editor: Editor
+    /**
+     * The transaction that caused the selection update
+     */
+    transaction: Transaction
+  }
+  beforeTransaction: {
+    /**
+     * The editor instance
+     */
+    editor: Editor
+    /**
+     * The transaction that will be applied
+     */
+    transaction: Transaction
+    /**
+     * The next state of the editor after the transaction is applied
+     */
+    nextState: EditorState
+  }
+  transaction: {
+    /**
+     * The editor instance
+     */
+    editor: Editor
+    /**
+     * The initial transaction
+     */
+    transaction: Transaction
+    /**
+     * Appended transactions that were added to the initial transaction by plugins
+     */
+    appendedTransactions: Transaction[]
+  }
+  focus: {
+    /**
+     * The editor instance
+     */
+    editor: Editor
+    /**
+     * The focus event
+     */
+    event: FocusEvent
+    /**
+     * The transaction that caused the focus
+     */
+    transaction: Transaction
+  }
+  blur: {
+    /**
+     * The editor instance
+     */
+    editor: Editor
+    /**
+     * The focus event
+     */
+    event: FocusEvent
+    /**
+     * The transaction that caused the blur
+     */
+    transaction: Transaction
+  }
   destroy: void
-  paste: { editor: Editor; event: ClipboardEvent; slice: Slice }
-  drop: { editor: Editor; event: DragEvent; slice: Slice; moved: boolean }
+  paste: {
+    /**
+     * The editor instance
+     */
+    editor: Editor
+    /**
+     * The clipboard event
+     */
+    event: ClipboardEvent
+    /**
+     * The slice that was pasted
+     */
+    slice: Slice
+  }
+  drop: {
+    /**
+     * The editor instance
+     */
+    editor: Editor
+    /**
+     * The drag event
+     */
+    event: DragEvent
+    /**
+     * The slice that was dropped
+     */
+    slice: Slice
+    /**
+     * Whether the content was moved (true) or copied (false)
+     */
+    moved: boolean
+  }
+  delete: {
+    /**
+     * The editor instance
+     */
+    editor: Editor
+    /**
+     * The range of the deleted content (before the deletion)
+     */
+    deletedRange: Range
+    /**
+     * The new range of positions of where the deleted content was in the new document (after the deletion)
+     */
+    newRange: Range
+    /**
+     * The transaction that caused the deletion
+     */
+    transaction: Transaction
+    /**
+     * The combined transform (including all appended transactions) that caused the deletion
+     */
+    combinedTransform: Transform
+    /**
+     * Whether the deletion was partial (only a part of this content was deleted)
+     */
+    partial: boolean
+    /**
+     * This is the start position of the mark in the document (before the deletion)
+     */
+    from: number
+    /**
+     * This is the end position of the mark in the document (before the deletion)
+     */
+    to: number
+  } & (
+    | {
+        /**
+         * The content that was deleted
+         */
+        type: 'node'
+        /**
+         * The node which the deletion occurred in
+         * @note This can be a parent node of the deleted content
+         */
+        node: ProseMirrorNode
+        /**
+         * The new start position of the node in the document (after the deletion)
+         */
+        newFrom: number
+        /**
+         * The new end position of the node in the document (after the deletion)
+         */
+        newTo: number
+      }
+    | {
+        /**
+         * The content that was deleted
+         */
+        type: 'mark'
+        /**
+         * The mark that was deleted
+         */
+        mark: ProseMirrorMark
+      }
+  )
 }
 
 export type EnableRules = (AnyExtension | string)[] | boolean
 
 export interface EditorOptions {
-  element: Element
+  /**
+   * The element or selector to bind the editor to
+   * If `null` is passed, the editor will not be mounted automatically
+   * If a function is passed, it will be called with the editor's root element
+   */
+  element: Element | null
+  /**
+   * The content of the editor (HTML, JSON, or a JSON array)
+   */
   content: Content
+  /**
+   * The extensions to use
+   */
   extensions: Extensions
+  /**
+   * Whether to inject base CSS styles
+   */
   injectCSS: boolean
+  /**
+   * A nonce to use for CSP while injecting styles
+   */
   injectNonce: string | undefined
+  /**
+   * The editor's initial focus position
+   */
   autofocus: FocusPosition
+  /**
+   * Whether the editor is editable
+   */
   editable: boolean
+  /**
+   * The editor's props
+   */
   editorProps: EditorProps
+  /**
+   * The editor's content parser options
+   */
   parseOptions: ParseOptions
+  /**
+   * The editor's core extension options
+   */
   coreExtensionOptions?: {
     clipboardTextSerializer?: {
       blockSeparator?: string
     }
+    delete?: {
+      /**
+       * Whether the `delete` extension should be called asynchronously to avoid blocking the editor while processing deletions
+       * @default true deletion events are called asynchronously
+       */
+      async?: boolean
+      /**
+       * Allows filtering the transactions that are processed by the `delete` extension.
+       * If the function returns `true`, the transaction will be ignored.
+       */
+      filterTransaction?: (transaction: Transaction) => boolean
+    }
   }
+  /**
+   * Whether to enable input rules behavior
+   */
   enableInputRules: EnableRules
+  /**
+   * Whether to enable paste rules behavior
+   */
   enablePasteRules: EnableRules
   /**
    * Determines whether core extensions are enabled.
@@ -106,7 +342,8 @@ export interface EditorOptions {
           | 'keymap'
           | 'tabindex'
           | 'drop'
-          | 'paste',
+          | 'paste'
+          | 'delete',
           false
         >
       >
@@ -117,25 +354,65 @@ export interface EditorOptions {
    * @default false
    */
   enableContentCheck: boolean
+  /**
+   * Called before the editor is constructed.
+   */
   onBeforeCreate: (props: EditorEvents['beforeCreate']) => void
+  /**
+   * Called after the editor is constructed.
+   */
   onCreate: (props: EditorEvents['create']) => void
   /**
    * Called when the editor encounters an error while parsing the content.
    * Only enabled if `enableContentCheck` is `true`.
    */
   onContentError: (props: EditorEvents['contentError']) => void
+  /**
+   * Called when the editor's content is updated.
+   */
   onUpdate: (props: EditorEvents['update']) => void
+  /**
+   * Called when the editor's selection is updated.
+   */
   onSelectionUpdate: (props: EditorEvents['selectionUpdate']) => void
+  /**
+   * Called after a transaction is applied to the editor.
+   */
   onTransaction: (props: EditorEvents['transaction']) => void
+  /**
+   * Called on focus events.
+   */
   onFocus: (props: EditorEvents['focus']) => void
+  /**
+   * Called on blur events.
+   */
   onBlur: (props: EditorEvents['blur']) => void
+  /**
+   * Called when the editor is destroyed.
+   */
   onDestroy: (props: EditorEvents['destroy']) => void
+  /**
+   * Called when content is pasted into the editor.
+   */
   onPaste: (e: ClipboardEvent, slice: Slice) => void
+  /**
+   * Called when content is dropped into the editor.
+   */
   onDrop: (e: DragEvent, slice: Slice, moved: boolean) => void
+  /**
+   * Called when content is deleted from the editor.
+   */
+  onDelete: (props: EditorEvents['delete']) => void
 }
 
+/**
+ * The editor's content as HTML
+ */
 export type HTMLContent = string
 
+/**
+ * Loosely describes a JSON representation of a Prosemirror document or node
+ */
 export type JSONContent = {
   type?: string
   attrs?: Record<string, any>
@@ -154,10 +431,10 @@ export type JSONContent = {
  */
 export type MarkType<
   Type extends string | { name: string } = any,
-  Attributes extends undefined | Record<string, any> = any,
+  TAttributes extends undefined | Record<string, any> = any,
 > = {
   type: Type
-  attrs: Attributes
+  attrs: TAttributes
 }
 
 /**
@@ -165,13 +442,13 @@ export type MarkType<
  */
 export type NodeType<
   Type extends string | { name: string } = any,
-  Attributes extends undefined | Record<string, any> = any,
+  TAttributes extends undefined | Record<string, any> = any,
   NodeMarkType extends MarkType = any,
-  Content extends (NodeType | TextType)[] = any,
+  TContent extends (NodeType | TextType)[] = any,
 > = {
   type: Type
-  attrs: Attributes
-  content?: Content
+  attrs: TAttributes
+  content?: TContent
   marks?: NodeMarkType[]
 }
 
@@ -346,6 +623,44 @@ export interface NodeViewRendererProps {
 
 export type NodeViewRenderer = (props: NodeViewRendererProps) => NodeView
 
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface MarkViewProps extends MarkViewRendererProps {}
+
+export interface MarkViewRendererProps {
+  // pass-through from prosemirror
+  /**
+   * The node that is being rendered.
+   */
+  mark: Parameters<MarkViewConstructor>[0]
+  /**
+   * The editor's view.
+   */
+  view: Parameters<MarkViewConstructor>[1]
+  /**
+   * indicates whether the mark's content is inline
+   */
+  inline: Parameters<MarkViewConstructor>[2]
+  // tiptap-specific
+  /**
+   * The editor instance.
+   */
+  editor: Editor
+  /**
+   * The extension that is responsible for the mark.
+   */
+  extension: Mark
+  /**
+   * The HTML attributes that should be added to the mark's DOM element.
+   */
+  HTMLAttributes: Record<string, any>
+}
+
+export type MarkViewRenderer = (props: MarkViewRendererProps) => MarkView
+
+export interface MarkViewRendererOptions {
+  ignoreMutation: ((props: { mutation: ViewMutationRecord }) => boolean) | null
+}
+
 export type AnyCommands = Record<string, (...args: any[]) => Command>
 
 export type UnionCommands<T = Command> = UnionToIntersection<

package/src/utilities/elementFromString.ts

@@ -15,6 +15,9 @@ const removeWhitespaces = (node: HTMLElement) => {
 }
 
 export function elementFromString(value: string): HTMLElement {
+  if (typeof window === 'undefined') {
+    throw new Error('[tiptap error]: there is no window object available, so this function cannot be used')
+  }
   // add a wrapper to preserve leading and trailing whitespace
   const wrappedValue = `<body>${value}</body>`
 

package/src/utilities/index.ts

@@ -5,6 +5,7 @@ export * from './elementFromString.js'
 export * from './escapeForRegEx.js'
 export * from './findDuplicates.js'
 export * from './fromString.js'
+export * from './isAndroid.js'
 export * from './isEmptyObject.js'
 export * from './isFunction.js'
 export * from './isiOS.js'

package/src/utilities/mergeAttributes.ts

@@ -14,7 +14,7 @@ export function mergeAttributes(...objects: Record<string, any>[]): Record<strin
         }
 
         if (key === 'class') {
-          const valueClasses: string[] = value ? value.split(' ') : []
+          const valueClasses: string[] = value ? String(value).split(' ') : []
           const existingClasses: string[] = mergedAttributes[key] ? mergedAttributes[key].split(' ') : []
 
           const insertClasses = valueClasses.filter(valueClass => !existingClasses.includes(valueClass))