Merge branch 'main' of https://github.com/ueberdosis/tiptap-next into main

docs/src/components/PageNavigation/index.vue

@@ -14,7 +14,7 @@
       <g-link
         class="page-navigation__link"
         exact
-        :to="nextPage.link"
+        :to="nextPage.redirect || nextPage.link"
         v-if="nextPage"
       >
         {{ nextPage.title }} →
@@ -41,10 +41,11 @@ export default {
     flattenedItems() {
       const flattenedItems = []
 
-      this.items.forEach(({ title, link, items }) => {
+      this.items.forEach(({ title, link, redirect, items }) => {
         flattenedItems.push({
           title,
           link,
+          redirect,
         })
 
         if (items) {
@@ -68,7 +69,13 @@ export default {
     },
 
     previousPage() {
-      return this.flattenedItems[this.currentIndex - 1]
+      let previousIndex = this.currentIndex - 1
+
+      while (this.flattenedItems[previousIndex].redirect) {
+        previousIndex -= 1
+      }
+
+      return this.flattenedItems[previousIndex]
     },
   },
 }

docs/src/demos/Examples/Basic/index.vue

@@ -124,3 +124,50 @@ export default {
   },
 }
 </script>
+
+<style lang="scss">
+/* Basic editor styles */
+.ProseMirror {
+  > * + * {
+    margin-top: 0.75em;
+  }
+
+  ul,
+  ol {
+    padding: 0 1rem;
+  }
+
+  code {
+    background-color: rgba(#616161, 0.1);
+    color: #616161;
+  }
+
+  pre {
+    background: #0D0D0D;
+    color: #FFF;
+    font-family: 'JetBrainsMono', monospace;
+    padding: 0.75rem 1rem;
+    border-radius: 0.5rem;
+
+    code {
+      color: inherit;
+      background: none;
+      font-size: 0.8rem;
+    }
+  }
+
+  img {
+    max-width: 100%;
+    height: auto;
+  }
+
+  hr {
+    margin: 1rem 0;
+  }
+
+  blockquote {
+    padding-left: 1rem;
+    border-left: 2px solid rgba(#0D0D0D, 0.1);
+  }
+}
+</style>

docs/src/demos/Examples/CollaborativeEditing/index.vue

@@ -281,4 +281,49 @@ export default {
   border-radius: 3px;
   white-space: nowrap;
 }
+
+/* Basic editor styles */
+.ProseMirror {
+  > * + * {
+    margin-top: 0.75em;
+  }
+
+  ul,
+  ol {
+    padding: 0 1rem;
+  }
+
+  code {
+    background-color: rgba(#616161, 0.1);
+    color: #616161;
+  }
+
+  pre {
+    background: #0D0D0D;
+    color: #FFF;
+    font-family: 'JetBrainsMono', monospace;
+    padding: 0.75rem 1rem;
+    border-radius: 0.5rem;
+
+    code {
+      color: inherit;
+      background: none;
+      font-size: 0.8rem;
+    }
+  }
+
+  img {
+    max-width: 100%;
+    height: auto;
+  }
+
+  hr {
+    margin: 1rem 0;
+  }
+
+  blockquote {
+    padding-left: 1rem;
+    border-left: 2px solid rgba(#0D0D0D, 0.1);
+  }
+}
 </style>

docs/src/demos/Examples/ExportHtmlOrJson/index.vue

@@ -105,6 +105,7 @@ export default {
 </script>
 
 <style lang="scss">
+/* Style the export */
 .export {
   padding: 1rem 0 0;
 
@@ -126,4 +127,49 @@ export default {
     color: #495057;
   }
 }
+
+/* Basic editor styles */
+.ProseMirror {
+  > * + * {
+    margin-top: 0.75em;
+  }
+
+  ul,
+  ol {
+    padding: 0 1rem;
+  }
+
+  code {
+    background-color: rgba(#616161, 0.1);
+    color: #616161;
+  }
+
+  pre {
+    background: #0D0D0D;
+    color: #FFF;
+    font-family: 'JetBrainsMono', monospace;
+    padding: 0.75rem 1rem;
+    border-radius: 0.5rem;
+
+    code {
+      color: inherit;
+      background: none;
+      font-size: 0.8rem;
+    }
+  }
+
+  img {
+    max-width: 100%;
+    height: auto;
+  }
+
+  hr {
+    margin: 1rem 0;
+  }
+
+  blockquote {
+    padding-left: 1rem;
+    border-left: 2px solid rgba(#0D0D0D, 0.1);
+  }
+}
 </style>

docs/src/demos/Examples/Links/index.vue

@@ -64,3 +64,17 @@ export default {
   },
 }
 </script>
+
+<style lang="scss">
+/* Basic editor styles */
+.ProseMirror {
+  > * + * {
+    margin-top: 0.75em;
+  }
+
+  a {
+    text-decoration: underline;
+    color: blue;
+  }
+}
+</style>

docs/src/demos/Examples/MarkdownShortcuts/index.vue

@@ -6,6 +6,8 @@
 
 <script>
 import { Editor, EditorContent, defaultExtensions } from '@tiptap/vue-starter-kit'
+import Strike from '@tiptap/extension-strike'
+import Highlight from '@tiptap/extension-highlight'
 
 export default {
   components: {
@@ -28,10 +30,16 @@ export default {
           To test that, start a new line and type <code>#</code> followed by a space to get a heading. Try <code>#</code>, <code>##</code>, <code>###</code>, <code>####</code>, <code>#####</code>, <code>######</code> for different levels.
         </p>
         <p>
-          Those conventions are called input rules in tiptap. Some of them are enabled by default. Try <code>></code> for blockquotes, <code>*</code>, <code>-</code> or <code>+</code> for bullet lists, or <code>\`foobar\`</code> to highlight code. You can add your own input rules to existing extensions, and to your custom nodes and marks.
+          Those conventions are called input rules in tiptap. Some of them are enabled by default. Try <code>></code> for blockquotes, <code>*</code>, <code>-</code> or <code>+</code> for bullet lists, or <code>\`foobar\`</code> to highlight code, <code>~~tildes~~</code> to strike text, or <code>==equal signs==</code> to highlight text.
+        </p>
+        <p>
+          You can overwrite existing input rules or add your own to new nodes and marks.
         </p>
       `,
-      extensions: defaultExtensions(),
+      extensions: [
+        ...defaultExtensions(),
+        Highlight(),
+      ],
     })
   },
 
@@ -40,3 +48,50 @@ export default {
   },
 }
 </script>
+
+<style lang="scss">
+/* Basic editor styles */
+.ProseMirror {
+  > * + * {
+    margin-top: 0.75em;
+  }
+
+  ul,
+  ol {
+    padding: 0 1rem;
+  }
+
+  code {
+    background-color: rgba(#616161, 0.1);
+    color: #616161;
+  }
+
+  pre {
+    background: #0D0D0D;
+    color: #FFF;
+    font-family: 'JetBrainsMono', monospace;
+    padding: 0.75rem 1rem;
+    border-radius: 0.5rem;
+
+    code {
+      color: inherit;
+      background: none;
+      font-size: 0.8rem;
+    }
+  }
+
+  img {
+    max-width: 100%;
+    height: auto;
+  }
+
+  hr {
+    margin: 1rem 0;
+  }
+
+  blockquote {
+    padding-left: 1rem;
+    border-left: 2px solid rgba(#0D0D0D, 0.1);
+  }
+}
+</style>

docs/src/demos/Examples/Minimalist/index.vue

@@ -42,3 +42,12 @@ export default {
   },
 }
 </script>
+
+<style lang="scss">
+/* Basic editor styles */
+.ProseMirror {
+  > * + * {
+    margin-top: 0.75em;
+  }
+}
+</style>

docs/src/demos/Examples/ReadOnly/index.vue

@@ -53,6 +53,13 @@ export default {
 </script>
 
 <style lang="scss">
+/* Basic editor styles */
+.ProseMirror {
+  > * + * {
+    margin-top: 0.75em;
+  }
+}
+
 .checkbox {
   margin-bottom: 1rem;
 

docs/src/demos/Marks/Link/index.spec.js

@@ -72,4 +72,6 @@ context('/api/marks/link', () => {
         .should('have.attr', 'href', url)
     })
   })
+
+  // TODO: Test invalid URLs
 })

docs/src/docPages/api/commands.md

@@ -95,18 +95,18 @@ Have a look at all of the core commands listed below. They should give you a goo
 | .updateNodeAttributes() | Update attributes of a node.                              |
 
 ### Lists
-| Command          | Description                                            |
+| Command          | Description                                 |
-| ---------------- | ------------------------------------------------------ |
+| ---------------- | ------------------------------------------- |
-| .liftListItem()  | Lift the list item into a wrapping list.               |
+| .liftListItem()  | Lift the list item into a wrapping list.    |
-| .sinkListItem()  | Sink the list item down into an inner list.            |
+| .sinkListItem()  | Sink the list item down into an inner list. |
-| .splitListItem() | Splits a textblock of a list item into two list items. |
+| .splitListItem() | Splits one list item into two list items.   |
-| .toggleList()    | Toggle between different list types.                   |
+| .toggleList()    | Toggle between different list types.        |
-| .wrapInList()    | Wrap a node in a list.                                 |
+| .wrapInList()    | Wrap a node in a list.                      |
 
 ### Selection
 | Command            | Description                             |
 | ------------------ | --------------------------------------- |
-| .blur()            | Blurs the editor.                       |
+| .blur()            | Removes focus from the editor.          |
 | .deleteSelection() | Delete the selection, if there is one.  |
 | .focus()           | Focus the editor at the given position. |
 | .scrollIntoView()  | Scroll the selection into view.         |

docs/src/docPages/api/schema.md

@@ -179,7 +179,7 @@ createNode({
 #### Defining
 Nodes get dropped when their entire content is replaced (for example, when pasting new content) by default. If a node should be kept for such replace operations, configure them as `defining`.
 
-Typically, that applies to [`Blockquote`](/api/extensions/blockquote), [`CodeBlock`](/api/extensions/code-block), [`Heading`](/api/extensions/heading), and [`ListItem`](/api/extensions/list-item).
+Typically, that applies to [`Blockquote`](/api/node/blockquote), [`CodeBlock`](/api/node/code-block), [`Heading`](/api/node/heading), and [`ListItem`](/api/node/list-item).
 
 ```js
 createNode({

docs/src/docPages/guide/build-custom-extensions.md

@@ -282,6 +282,10 @@ const CustomParagraph = Paragraph.extend({
 })
 ```
 
+:::warning Use the commands parameter inside of addCommands
+All commands are also available through ~~this.editor.commands~~, but inside of `addCommands` you must use the `commands` parameter that’s passed to it.
+:::
+
 ### Keyboard shortcuts
 Most core extensions come with sensible keyboard shortcut defaults. Depending on what you want to build, you’ll likely want to change them though. With the `addKeyboardShortcuts()` method you can overwrite the predefined shortcut map:
 

docs/src/docPages/guide/working-with-typescript.md

@@ -3,10 +3,49 @@
 ## toc
 
 ## Introduction
+The whole tiptap is code base is written in TypeScript. If you haven’t heard of it or never used it, no worries. You don’t have to.
 
+TypeScript extends JavaScript by adding types (hence the name). It adds new syntax, which doesn’t exist in plain JavaScript. It’s actually removed before running in the browser, but this step – the compilation – is important to find bugs early. It checks if you passe the right types of data to functions. For a big and complex project, that’s very valuable. It means we’ll get notified of lot of bugs, before shipping code to you.
+
+Anyway, if you don’t use TypeScript in your project, that’s fine. You’ll still be able to use tiptap and even get a really nice autocomplete for the tiptap API (if your editor supports it, but most do).
+
+If you’re using TypeScript in your project and want to extend tiptap, there are two things that are good to know.
 
 ## Options type
+To extend or create default options for an extension, you’ll need to define a custom type, here is an example:
 
+```js
+import { createExtension } from '@tiptap/core'
 
-## Create a command
+export interface CustomExtensionOptions {
+  awesomeness: number,
+}
 
+const CustomExtension = createExtension({
+  defaultOptions: <CustomExtensionOptions>{
+    awesomeness: 100,
+  },
+})
+```
+
+## Command type
+The core package also exports a `Command` type, which needs to be added to all commands that you specify in your code. Here is an example:
+
+```js
+import { Command, createExtension } from '@tiptap/core'
+
+const CustomExtension = createExtension({
+  addCommands() {
+    return {
+      /**
+       * Comments will be added to the autocomplete.
+       */
+      yourCommand: (): Command => ({ commands }) => {
+        // …
+      },
+    }
+  },
+})
+```
+
+That’s basically it. We’re doing all the rest automatically.

docs/src/layouts/App/base.scss

@@ -90,45 +90,45 @@ code {
   color: white;
 }
 
-.ProseMirror {
+// TODO: Move to examples
+// .ProseMirror {
+//   > * + * {
+//     margin-top: 0.75em;
+//   }
 
-  > * + * {
+//   ul,
-    margin-top: 0.75em;
+//   ol {
-  }
+//     padding: 0 1rem;
+//   }
 
-  ul,
+//   pre {
-  ol {
+//     background: $colorBlack;
-    padding: 0 1rem;
+//     color: $colorWhite;
-  }
+//     font-family: 'JetBrainsMono', monospace;
+//     padding: 0.75rem 1rem;
+//     border-radius: 0.5rem;
 
-  pre {
+//     code {
-    background: $colorBlack;
+//       color: inherit;
-    color: $colorWhite;
+//       background: none;
-    font-family: 'JetBrainsMono', monospace;
+//       font-size: 0.8rem;
-    padding: 0.75rem 1rem;
+//     }
-    border-radius: 0.5rem;
+//   }
 
-    code {
+//   img {
-      color: inherit;
+//     max-width: 100%;
-      background: none;
+//     height: auto;
-      font-size: 0.8rem;
+//   }
-    }
-  }
 
-  img {
+//   hr {
-    max-width: 100%;
+//     margin: 1rem 0;
-    height: auto;
+//   }
-  }
 
-  hr {
+//   blockquote {
-    margin: 1rem 0;
+//     padding-left: 1rem;
-  }
+//     border-left: 2px solid rgba($colorBlack, 0.1);
-
+//   }
-  blockquote {
+// }
-    padding-left: 1rem;
-    border-left: 2px solid rgba($colorBlack, 0.1);
-  }
-}
 
 .DocSearch {
   filter: saturate(0);

docs/src/links.yaml

@@ -62,7 +62,6 @@
       draft: true
     - title: Working with TypeScript
       link: /guide/working-with-typescript
-      draft: true
 
 - title: API
   items:

packages/core/src/extensions/commands.ts

@@ -31,33 +31,117 @@ import wrapInList from '../commands/wrapInList'
 export const Commands = createExtension({
   addCommands() {
     return {
+      /**
+       * Removes focus from the editor.
+       */
       blur,
+      /**
+       * Clear the whole document.
+       */
       clearContent,
+      /**
+       * Normalize nodes to a simple paragraph.
+       */
       clearNodes,
+      /**
+       * Delete the selection, if there is one.
+       */
       deleteSelection,
+      /**
+       * Extends the text selection to the current mark.
+       */
       extendMarkRange,
+      /**
+       * Focus the editor at the given position.
+       */
       focus,
+      /**
+       * Insert a string of HTML at the current position.
+       */
       insertHTML,
+      /**
+       * Insert a string of text at the current position.
+       */
       insertText,
+      /**
+       * Lift the list item into a wrapping list.
+       */
       liftListItem,
+      /**
+       * Remove all marks in the current selection.
+       */
       removeMark,
+      /**
+       * Remove all marks in the current selection.
+       */
       removeMarks,
+      /**
+       * Resets all node attributes to the default value.
+       */
       resetNodeAttributes,
+      /**
+       * Scroll the selection into view.
+       */
       scrollIntoView,
+      /**
+       * Select the whole document.
+       */
       selectAll,
+      /**
+       * Select the parent node.
+       */
       selectParentNode,
+      /**
+       * Replace a given range with a node.
+       */
       setBlockType,
+      /**
+       * Replace the whole document with new content.
+       */
       setContent,
+      /**
+       * Sink the list item down into an inner list.
+       */
       sinkListItem,
+      /**
+       * Forks a new node from an existing node.
+       */
       splitBlock,
+      /**
+       * Splits one list item into two list items.
+       */
       splitListItem,
+      /**
+       * Toggle a node with another node.
+       */
       toggleBlockType,
+      /**
+       * Toggle between different list types.
+       */
       toggleList,
+      /**
+       * Toggle a mark on and off.
+       */
       toggleMark,
+      /**
+       * Wraps nodes in another node, or removes an existing wrap.
+       */
       toggleWrap,
+      /**
+       * Runs one command after the other and stops at the first which returns true.
+       */
       try: tryCommand,
+      /**
+       * Update a mark with new attributes.
+       */
       updateMarkAttributes,
+      /**
+       * Update attributes of a node.
+       */
       updateNodeAttributes,
+      /**
+       * Wrap a node in a list.
+       */
       wrapInList,
     }
   },

packages/extension-blockquote/src/index.ts

@@ -34,6 +34,9 @@ const Blockquote = createNode({
 
   addCommands() {
     return {
+      /**
+       * Toggle a blockquote node
+       */
       blockquote: (): Command => ({ commands }) => {
         return commands.toggleWrap('blockquote')
       },

packages/extension-bold/src/index.ts

@@ -43,7 +43,7 @@ const Bold = createMark({
   addCommands() {
     return {
       /**
-       * bold command
+       * Toggle a bold mark
        */
       bold: (): Command => ({ commands }) => {
         return commands.toggleMark('bold')

packages/extension-bullet-list/src/index.ts

@@ -32,6 +32,9 @@ const BulletList = createNode({
 
   addCommands() {
     return {
+      /**
+       * Toggle a bullet list
+       */
       bulletList: (): Command => ({ commands }) => {
         return commands.toggleList('bulletList', 'listItem')
       },

packages/extension-code-block/src/index.ts

@@ -74,6 +74,9 @@ const CodeBlock = createNode({
 
   addCommands() {
     return {
+      /**
+       * Toggle a code block
+       */
       codeBlock: (attrs?: CodeBlockOptions): Command => ({ commands }) => {
         return commands.toggleBlockType('codeBlock', 'paragraph', attrs)
       },

packages/extension-code/src/index.ts

@@ -35,6 +35,9 @@ const Code = createMark({
 
   addCommands() {
     return {
+      /**
+       * Toggle inline code
+       */
       code: (): Command => ({ commands }) => {
         return commands.toggleMark('code')
       },

packages/extension-collaboration-cursor/src/index.ts

@@ -30,6 +30,9 @@ const CollaborationCursor = createExtension({
 
   addCommands() {
     return {
+      /**
+       * Update details of the current user
+       */
       user: (attributes: {
         name: string,
         color: string,

packages/extension-font-family/src/index.ts

@@ -37,6 +37,9 @@ const FontFamily = createExtension({
 
   addCommands() {
     return {
+      /**
+       * Update the font family
+       */
       fontFamily: (fontFamily: string | null = null): Command => ({ chain }) => {
         return chain()
           .updateMarkAttributes('textStyle', { fontFamily })

packages/extension-hard-break/src/index.ts

@@ -22,6 +22,9 @@ const HardBreak = createNode({
 
   addCommands() {
     return {
+      /**
+       * Add a hard break
+       */
       hardBreak: (): Command => ({ commands, state, dispatch }) => {
         return commands.try([
           () => exitCode(state, dispatch),

packages/extension-heading/src/index.ts

@@ -53,7 +53,7 @@ const Heading = createNode({
   addCommands() {
     return {
       /**
-       * heading command
+       * Toggle a heading node
        */
       heading: (options: { level: Level }): Command => ({ commands }) => {
         if (!this.options.levels.includes(options.level)) {

packages/extension-highlight/src/index.ts

@@ -58,6 +58,9 @@ const Highlight = createMark({
 
   addCommands() {
     return {
+      /**
+       * Toggle a highlight mark
+       */
       highlight: (attributes?: { color: string }): Command => ({ commands }) => {
         return commands.toggleMark('highlight', attributes)
       },

packages/extension-history/src/index.ts

@@ -14,9 +14,15 @@ const History = createExtension({
 
   addCommands() {
     return {
+      /**
+       * Undo recent changes
+       */
       undo: (): Command => ({ state, dispatch }) => {
         return undo(state, dispatch)
       },
+      /**
+       * Reapply reverted changes
+       */
       redo: (): Command => ({ state, dispatch }) => {
         return redo(state, dispatch)
       },

packages/extension-horizontal-rule/src/index.ts

@@ -27,6 +27,9 @@ const HorizontalRule = createNode({
 
   addCommands() {
     return {
+      /**
+       * Add a horizontal rule
+       */
       horizontalRule: (): Command => ({ tr }) => {
         tr.replaceSelectionWith(this.type.create())
 

packages/extension-image/src/index.ts

@@ -55,6 +55,9 @@ const Image = createNode({
 
   addCommands() {
     return {
+      /**
+       * Add an image
+       */
       image: (options: { src: string, alt?: string, title?: string }): Command => ({ tr }) => {
         const { selection } = tr
         const node = this.type.create(options)

packages/extension-italic/src/index.ts

@@ -44,6 +44,9 @@ const Italic = createMark({
 
   addCommands() {
     return {
+      /**
+       * Toggle an italic mark
+       */
       italic: (): Command => ({ commands }) => {
         return commands.toggleMark('italic')
       },

packages/extension-link/src/index.ts

@@ -51,6 +51,9 @@ const Link = createMark({
 
   addCommands() {
     return {
+      /**
+       * Toggle or update a link mark
+       */
       link: (options: { href?: string, target?: string } = {}): Command => ({ commands }) => {
         if (!options.href) {
           return commands.removeMark('link')

packages/extension-ordered-list/src/index.ts

@@ -51,6 +51,9 @@ const OrderedList = createNode({
 
   addCommands() {
     return {
+      /**
+       * Toggle an ordered list
+       */
       orderedList: (): Command => ({ commands }) => {
         return commands.toggleList('orderedList', 'listItem')
       },

packages/extension-paragraph/src/index.ts

@@ -29,6 +29,9 @@ const Paragraph = createNode({
 
   addCommands() {
     return {
+      /**
+       * Toggle a paragraph
+       */
       paragraph: (): Command => ({ commands }) => {
         return commands.toggleBlockType('paragraph', 'paragraph')
       },

packages/extension-strike/src/index.ts

@@ -44,6 +44,9 @@ const Strike = createMark({
 
   addCommands() {
     return {
+      /**
+       * Toggle a strike mark
+       */
       strike: (): Command => ({ commands }) => {
         return commands.toggleMark('strike')
       },

packages/extension-task-list/src/index.ts

@@ -32,6 +32,9 @@ const TaskList = createNode({
 
   addCommands() {
     return {
+      /**
+       * Toggle a task list
+       */
       taskList: (): Command => ({ commands }) => {
         return commands.toggleList('taskList', 'taskItem')
       },

packages/extension-text-align/src/index.ts

@@ -34,6 +34,9 @@ const TextAlign = createExtension({
 
   addCommands() {
     return {
+      /**
+       * Update the text align attribute
+       */
       textAlign: (alignment: string): Command => ({ commands }) => {
         if (!this.options.alignments.includes(alignment)) {
           return false

packages/extension-text-style/src/index.ts

@@ -26,6 +26,9 @@ const TextStyle = createMark({
 
   addCommands() {
     return {
+      /**
+       * Remove spans without inline style attributes.
+       */
       removeEmptyTextStyle: (): Command => ({ state, commands }) => {
         const attributes = getMarkAttrs(state, this.type)
         const hasStyles = Object.entries(attributes).every(([, value]) => !!value)