@tiptap/extension-list 3.0.0-beta.0

package/src/index.ts

@@ -0,0 +1,7 @@
+export * from './bullet-list/index.js'
+export * from './item/index.js'
+export * from './keymap/index.js'
+export * from './kit/index.js'
+export * from './ordered-list/index.js'
+export * from './task-item/index.js'
+export * from './task-list/index.js'

package/src/item/index.ts

@@ -0,0 +1 @@
+export * from './list-item.js'

package/src/item/list-item.ts

@@ -0,0 +1,64 @@
+import { mergeAttributes, Node } from '@tiptap/core'
+
+export interface ListItemOptions {
+  /**
+   * The HTML attributes for a list item node.
+   * @default {}
+   * @example { class: 'foo' }
+   */
+  HTMLAttributes: Record<string, any>
+
+  /**
+   * The node type for bulletList nodes
+   * @default 'bulletList'
+   * @example 'myCustomBulletList'
+   */
+  bulletListTypeName: string
+
+  /**
+   * The node type for orderedList nodes
+   * @default 'orderedList'
+   * @example 'myCustomOrderedList'
+   */
+  orderedListTypeName: string
+}
+
+/**
+ * This extension allows you to create list items.
+ * @see https://www.tiptap.dev/api/nodes/list-item
+ */
+export const ListItem = Node.create<ListItemOptions>({
+  name: 'listItem',
+
+  addOptions() {
+    return {
+      HTMLAttributes: {},
+      bulletListTypeName: 'bulletList',
+      orderedListTypeName: 'orderedList',
+    }
+  },
+
+  content: 'paragraph block*',
+
+  defining: true,
+
+  parseHTML() {
+    return [
+      {
+        tag: 'li',
+      },
+    ]
+  },
+
+  renderHTML({ HTMLAttributes }) {
+    return ['li', mergeAttributes(this.options.HTMLAttributes, HTMLAttributes), 0]
+  },
+
+  addKeyboardShortcuts() {
+    return {
+      Enter: () => this.editor.commands.splitListItem(this.name),
+      Tab: () => this.editor.commands.sinkListItem(this.name),
+      'Shift-Tab': () => this.editor.commands.liftListItem(this.name),
+    }
+  },
+})

package/src/keymap/index.ts

@@ -0,0 +1,2 @@
+export * from './list-keymap.js'
+export * as listHelpers from './listHelpers/index.js'

package/src/keymap/list-keymap.ts

@@ -0,0 +1,106 @@
+import { Extension } from '@tiptap/core'
+
+import { handleBackspace, handleDelete } from './listHelpers/index.js'
+
+export type ListKeymapOptions = {
+  /**
+   * An array of list types. This is used for item and wrapper list matching.
+   * @default []
+   * @example [{ itemName: 'listItem', wrapperNames: ['bulletList', 'orderedList'] }]
+   */
+  listTypes: Array<{
+    itemName: string
+    wrapperNames: string[]
+  }>
+}
+
+/**
+ * This extension registers custom keymaps to change the behaviour of the backspace and delete keys.
+ * By default Prosemirror keyhandling will always lift or sink items so paragraphs are joined into
+ * the adjacent or previous list item. This extension will prevent this behaviour and instead will
+ * try to join paragraphs from two list items into a single list item.
+ * @see https://www.tiptap.dev/api/extensions/list-keymap
+ */
+export const ListKeymap = Extension.create<ListKeymapOptions>({
+  name: 'listKeymap',
+
+  addOptions() {
+    return {
+      listTypes: [
+        {
+          itemName: 'listItem',
+          wrapperNames: ['bulletList', 'orderedList'],
+        },
+        {
+          itemName: 'taskItem',
+          wrapperNames: ['taskList'],
+        },
+      ],
+    }
+  },
+
+  addKeyboardShortcuts() {
+    return {
+      Delete: ({ editor }) => {
+        let handled = false
+
+        this.options.listTypes.forEach(({ itemName }) => {
+          if (editor.state.schema.nodes[itemName] === undefined) {
+            return
+          }
+
+          if (handleDelete(editor, itemName)) {
+            handled = true
+          }
+        })
+
+        return handled
+      },
+      'Mod-Delete': ({ editor }) => {
+        let handled = false
+
+        this.options.listTypes.forEach(({ itemName }) => {
+          if (editor.state.schema.nodes[itemName] === undefined) {
+            return
+          }
+
+          if (handleDelete(editor, itemName)) {
+            handled = true
+          }
+        })
+
+        return handled
+      },
+      Backspace: ({ editor }) => {
+        let handled = false
+
+        this.options.listTypes.forEach(({ itemName, wrapperNames }) => {
+          if (editor.state.schema.nodes[itemName] === undefined) {
+            return
+          }
+
+          if (handleBackspace(editor, itemName, wrapperNames)) {
+            handled = true
+          }
+        })
+
+        return handled
+      },
+      'Mod-Backspace': ({ editor }) => {
+        let handled = false
+
+        this.options.listTypes.forEach(({ itemName, wrapperNames }) => {
+          if (editor.state.schema.nodes[itemName] === undefined) {
+            return
+          }
+
+          if (handleBackspace(editor, itemName, wrapperNames)) {
+            handled = true
+          }
+        })
+
+        return handled
+      },
+    }
+  },
+})

package/src/keymap/listHelpers/findListItemPos.ts

@@ -0,0 +1,30 @@
+import { getNodeType } from '@tiptap/core'
+import type { NodeType } from '@tiptap/pm/model'
+import type { EditorState } from '@tiptap/pm/state'
+
+export const findListItemPos = (typeOrName: string | NodeType, state: EditorState) => {
+  const { $from } = state.selection
+  const nodeType = getNodeType(typeOrName, state.schema)
+
+  let currentNode = null
+  let currentDepth = $from.depth
+  let currentPos = $from.pos
+  let targetDepth: number | null = null
+
+  while (currentDepth > 0 && targetDepth === null) {
+    currentNode = $from.node(currentDepth)
+
+    if (currentNode.type === nodeType) {
+      targetDepth = currentDepth
+    } else {
+      currentDepth -= 1
+      currentPos -= 1
+    }
+  }
+
+  if (targetDepth === null) {
+    return null
+  }
+
+  return { $pos: state.doc.resolve(currentPos), depth: targetDepth }
+}

package/src/keymap/listHelpers/getNextListDepth.ts

@@ -0,0 +1,16 @@
+import { getNodeAtPosition } from '@tiptap/core'
+import type { EditorState } from '@tiptap/pm/state'
+
+import { findListItemPos } from './findListItemPos.js'
+
+export const getNextListDepth = (typeOrName: string, state: EditorState) => {
+  const listItemPos = findListItemPos(typeOrName, state)
+
+  if (!listItemPos) {
+    return false
+  }
+
+  const [, depth] = getNodeAtPosition(state, typeOrName, listItemPos.$pos.pos + 4)
+
+  return depth
+}

package/src/keymap/listHelpers/handleBackspace.ts

@@ -0,0 +1,85 @@
+import type { Editor } from '@tiptap/core'
+import { isAtStartOfNode, isNodeActive } from '@tiptap/core'
+import type { Node } from '@tiptap/pm/model'
+
+import { findListItemPos } from './findListItemPos.js'
+import { hasListBefore } from './hasListBefore.js'
+import { hasListItemBefore } from './hasListItemBefore.js'
+import { listItemHasSubList } from './listItemHasSubList.js'
+
+export const handleBackspace = (editor: Editor, name: string, parentListTypes: string[]) => {
+  // this is required to still handle the undo handling
+  if (editor.commands.undoInputRule()) {
+    return true
+  }
+
+  // if the selection is not collapsed
+  // we can rely on the default backspace behavior
+  if (editor.state.selection.from !== editor.state.selection.to) {
+    return false
+  }
+
+  // if the current item is NOT inside a list item &
+  // the previous item is a list (orderedList or bulletList)
+  // move the cursor into the list and delete the current item
+  if (!isNodeActive(editor.state, name) && hasListBefore(editor.state, name, parentListTypes)) {
+    const { $anchor } = editor.state.selection
+
+    const $listPos = editor.state.doc.resolve($anchor.before() - 1)
+
+    const listDescendants: Array<{ node: Node; pos: number }> = []
+
+    $listPos.node().descendants((node, pos) => {
+      if (node.type.name === name) {
+        listDescendants.push({ node, pos })
+      }
+    })
+
+    const lastItem = listDescendants.at(-1)
+
+    if (!lastItem) {
+      return false
+    }
+
+    const $lastItemPos = editor.state.doc.resolve($listPos.start() + lastItem.pos + 1)
+
+    return editor
+      .chain()
+      .cut({ from: $anchor.start() - 1, to: $anchor.end() + 1 }, $lastItemPos.end())
+      .joinForward()
+      .run()
+  }
+
+  // if the cursor is not inside the current node type
+  // do nothing and proceed
+  if (!isNodeActive(editor.state, name)) {
+    return false
+  }
+
+  // if the cursor is not at the start of a node
+  // do nothing and proceed
+  if (!isAtStartOfNode(editor.state)) {
+    return false
+  }
+
+  const listItemPos = findListItemPos(name, editor.state)
+
+  if (!listItemPos) {
+    return false
+  }
+
+  const $prev = editor.state.doc.resolve(listItemPos.$pos.pos - 2)
+  const prevNode = $prev.node(listItemPos.depth)
+
+  const previousListItemHasSubList = listItemHasSubList(name, editor.state, prevNode)
+
+  // if the previous item is a list item and doesn't have a sublist, join the list items
+  if (hasListItemBefore(name, editor.state) && !previousListItemHasSubList) {
+    return editor.commands.joinItemBackward()
+  }
+
+  // otherwise in the end, a backspace should
+  // always just lift the list item if
+  // joining / merging is not possible
+  return editor.chain().liftListItem(name).run()
+}

package/src/keymap/listHelpers/handleDelete.ts

@@ -0,0 +1,44 @@
+import type { Editor } from '@tiptap/core'
+import { isAtEndOfNode, isNodeActive } from '@tiptap/core'
+
+import { nextListIsDeeper } from './nextListIsDeeper.js'
+import { nextListIsHigher } from './nextListIsHigher.js'
+
+export const handleDelete = (editor: Editor, name: string) => {
+  // if the cursor is not inside the current node type
+  // do nothing and proceed
+  if (!isNodeActive(editor.state, name)) {
+    return false
+  }
+
+  // if the cursor is not at the end of a node
+  // do nothing and proceed
+  if (!isAtEndOfNode(editor.state, name)) {
+    return false
+  }
+
+  // if the selection is not collapsed, or not within a single node
+  // do nothing and proceed
+  const { selection } = editor.state
+  const { $from, $to } = selection
+
+  if (!selection.empty && $from.sameParent($to)) {
+    return false
+  }
+
+  // check if the next node is a list with a deeper depth
+  if (nextListIsDeeper(name, editor.state)) {
+    return editor
+      .chain()
+      .focus(editor.state.selection.from + 4)
+      .lift(name)
+      .joinBackward()
+      .run()
+  }
+
+  if (nextListIsHigher(name, editor.state)) {
+    return editor.chain().joinForward().joinBackward().run()
+  }
+
+  return editor.commands.joinItemForward()
+}

package/src/keymap/listHelpers/hasListBefore.ts

@@ -0,0 +1,15 @@
+import type { EditorState } from '@tiptap/pm/state'
+
+export const hasListBefore = (editorState: EditorState, name: string, parentListTypes: string[]) => {
+  const { $anchor } = editorState.selection
+
+  const previousNodePos = Math.max(0, $anchor.pos - 2)
+
+  const previousNode = editorState.doc.resolve(previousNodePos).node()
+
+  if (!previousNode || !parentListTypes.includes(previousNode.type.name)) {
+    return false
+  }
+
+  return true
+}

package/src/keymap/listHelpers/hasListItemAfter.ts

@@ -0,0 +1,17 @@
+import type { EditorState } from '@tiptap/pm/state'
+
+export const hasListItemAfter = (typeOrName: string, state: EditorState): boolean => {
+  const { $anchor } = state.selection
+
+  const $targetPos = state.doc.resolve($anchor.pos - $anchor.parentOffset - 2)
+
+  if ($targetPos.index() === $targetPos.parent.childCount - 1) {
+    return false
+  }
+
+  if ($targetPos.nodeAfter?.type.name !== typeOrName) {
+    return false
+  }
+
+  return true
+}

package/src/keymap/listHelpers/hasListItemBefore.ts

@@ -0,0 +1,17 @@
+import type { EditorState } from '@tiptap/pm/state'
+
+export const hasListItemBefore = (typeOrName: string, state: EditorState): boolean => {
+  const { $anchor } = state.selection
+
+  const $targetPos = state.doc.resolve($anchor.pos - 2)
+
+  if ($targetPos.index() === 0) {
+    return false
+  }
+
+  if ($targetPos.nodeBefore?.type.name !== typeOrName) {
+    return false
+  }
+
+  return true
+}

package/src/keymap/listHelpers/index.ts

@@ -0,0 +1,10 @@
+export * from './findListItemPos.js'
+export * from './getNextListDepth.js'
+export * from './handleBackspace.js'
+export * from './handleDelete.js'
+export * from './hasListBefore.js'
+export * from './hasListItemAfter.js'
+export * from './hasListItemBefore.js'
+export * from './listItemHasSubList.js'
+export * from './nextListIsDeeper.js'
+export * from './nextListIsHigher.js'

package/src/keymap/listHelpers/listItemHasSubList.ts

@@ -0,0 +1,21 @@
+import { getNodeType } from '@tiptap/core'
+import type { Node } from '@tiptap/pm/model'
+import type { EditorState } from '@tiptap/pm/state'
+
+export const listItemHasSubList = (typeOrName: string, state: EditorState, node?: Node) => {
+  if (!node) {
+    return false
+  }
+
+  const nodeType = getNodeType(typeOrName, state.schema)
+
+  let hasSubList = false
+
+  node.descendants(child => {
+    if (child.type === nodeType) {
+      hasSubList = true
+    }
+  })
+
+  return hasSubList
+}

package/src/keymap/listHelpers/nextListIsDeeper.ts

@@ -0,0 +1,19 @@
+import type { EditorState } from '@tiptap/pm/state'
+
+import { findListItemPos } from './findListItemPos.js'
+import { getNextListDepth } from './getNextListDepth.js'
+
+export const nextListIsDeeper = (typeOrName: string, state: EditorState) => {
+  const listDepth = getNextListDepth(typeOrName, state)
+  const listItemPos = findListItemPos(typeOrName, state)
+
+  if (!listItemPos || !listDepth) {
+    return false
+  }
+
+  if (listDepth > listItemPos.depth) {
+    return true
+  }
+
+  return false
+}

package/src/keymap/listHelpers/nextListIsHigher.ts

@@ -0,0 +1,19 @@
+import type { EditorState } from '@tiptap/pm/state'
+
+import { findListItemPos } from './findListItemPos.js'
+import { getNextListDepth } from './getNextListDepth.js'
+
+export const nextListIsHigher = (typeOrName: string, state: EditorState) => {
+  const listDepth = getNextListDepth(typeOrName, state)
+  const listItemPos = findListItemPos(typeOrName, state)
+
+  if (!listItemPos || !listDepth) {
+    return false
+  }
+
+  if (listDepth < listItemPos.depth) {
+    return true
+  }
+
+  return false
+}

package/src/kit/index.ts

@@ -0,0 +1,81 @@
+import { Extension } from '@tiptap/core'
+
+import type { BulletListOptions } from '../bullet-list/index.js'
+import { BulletList } from '../bullet-list/index.js'
+import type { ListItemOptions } from '../item/index.js'
+import { ListItem } from '../item/index.js'
+import type { ListKeymapOptions } from '../keymap/index.js'
+import { ListKeymap } from '../keymap/index.js'
+import type { OrderedListOptions } from '../ordered-list/index.js'
+import { OrderedList } from '../ordered-list/index.js'
+import type { TaskItemOptions } from '../task-item/index.js'
+import { TaskItem } from '../task-item/index.js'
+import type { TaskListOptions } from '../task-list/index.js'
+import { TaskList } from '../task-list/index.js'
+
+export interface ListKitOptions {
+  /**
+   * If set to false, the bulletList extension will not be registered
+   * @example table: false
+   */
+  bulletList: Partial<BulletListOptions> | false
+  /**
+   * If set to false, the listItem extension will not be registered
+   */
+  listItem: Partial<ListItemOptions> | false
+  /**
+   * If set to false, the listKeymap extension will not be registered
+   */
+  listKeymap: Partial<ListKeymapOptions> | false
+  /**
+   * If set to false, the orderedList extension will not be registered
+   */
+  orderedList: Partial<OrderedListOptions> | false
+  /**
+   * If set to false, the taskItem extension will not be registered
+   */
+  taskItem: Partial<TaskItemOptions> | false
+  /**
+   * If set to false, the taskList extension will not be registered
+   */
+  taskList: Partial<TaskListOptions> | false
+}
+
+/**
+ * The table kit is a collection of table editor extensions.
+ *
+ * It’s a good starting point for building your own table in Tiptap.
+ */
+export const ListKit = Extension.create<ListKitOptions>({
+  name: 'listKit',
+
+  addExtensions() {
+    const extensions = []
+
+    if (this.options.bulletList !== false) {
+      extensions.push(BulletList.configure(this.options.bulletList))
+    }
+
+    if (this.options.listItem !== false) {
+      extensions.push(ListItem.configure(this.options.listItem))
+    }
+
+    if (this.options.listKeymap !== false) {
+      extensions.push(ListKeymap.configure(this.options.listKeymap))
+    }
+
+    if (this.options.orderedList !== false) {
+      extensions.push(OrderedList.configure(this.options.orderedList))
+    }
+
+    if (this.options.taskItem !== false) {
+      extensions.push(TaskItem.configure(this.options.taskItem))
+    }
+
+    if (this.options.taskList !== false) {
+      extensions.push(TaskList.configure(this.options.taskList))
+    }
+
+    return extensions
+  },
+})

package/src/ordered-list/index.ts

@@ -0,0 +1 @@
+export * from './ordered-list.js'