docs: add a custom shortcuts example (#5981)

demos/src/Examples/EnterShortcuts/React/index.spec.js

@@ -0,0 +1,34 @@
+/// <reference types="cypress" />
+
+context('/src/Examples/EnterShortcuts/React/', () => {
+  before(() => {
+    cy.visit('/src/Examples/EnterShortcuts/React/')
+  })
+
+  beforeEach(() => {
+    cy.get('.tiptap').then(([{ editor }]) => {
+      editor.commands.setContent('<p>Example Text</p>')
+    })
+  })
+
+  it('should update the hint html when the keyboard shortcut is pressed', () => {
+    cy.get('.tiptap')
+      .trigger('keydown', { metaKey: true, key: 'Enter' })
+    cy.get('.hint')
+      .should('contain', 'Meta-Enter was the last shortcut')
+  })
+
+  it('should update the hint html when the keyboard shortcut is pressed', () => {
+    cy.get('.tiptap')
+      .trigger('keydown', { shiftKey: true, key: 'Enter' })
+    cy.get('.hint')
+      .should('contain', 'Shift-Enter was the last shortcut')
+  })
+
+  it('should update the hint html when the keyboard shortcut is pressed', () => {
+    cy.get('.tiptap')
+      .trigger('keydown', { ctrlKey: true, key: 'Enter' })
+    cy.get('.hint')
+      .should('contain', 'Ctrl-Enter was the last shortcut')
+  })
+})

demos/src/Examples/EnterShortcuts/React/index.tsx

@@ -0,0 +1,88 @@
+import './styles.scss'
+
+import { EditorContent, Extension, useEditor } from '@tiptap/react'
+import StarterKit from '@tiptap/starter-kit'
+import React from 'react'
+
+const CustomKeyboardShortcutExtension = Extension.create({
+  name: 'customKeyboardShortcuts',
+  // Set a higher priority to make sure this extension is executed first before the default keyboard shortcuts
+  priority: 101,
+  addKeyboardShortcuts() {
+    return {
+      'Ctrl-Enter': ctx => {
+        // Creates a transaction with this custom meta set
+        return ctx.editor.commands.setMeta('customKeyboardShortcutHandler', 'Ctrl-Enter')
+      },
+      'Meta-Enter': ctx => {
+        // Creates a transaction with this custom meta set
+        return ctx.editor.commands.setMeta('customKeyboardShortcutHandler', 'Meta-Enter')
+      },
+      'Shift-Enter': ctx => {
+        return ctx.editor.commands.setMeta('customKeyboardShortcutHandler', 'Shift-Enter')
+      },
+    }
+  },
+})
+
+export default () => {
+  const [lastShortcut, setLastShortcut] = React.useState<string | null>(null)
+  const editor = useEditor({
+    extensions: [StarterKit, CustomKeyboardShortcutExtension],
+    // Listen for the custom meta set in the transaction
+    onTransaction: ({ transaction }) => {
+      if (transaction.getMeta('customKeyboardShortcutHandler')) {
+        switch (transaction.getMeta('customKeyboardShortcutHandler')) {
+          case 'Ctrl-Enter':
+            setLastShortcut('Ctrl-Enter')
+            break
+          case 'Meta-Enter':
+            setLastShortcut('Meta-Enter')
+            break
+          case 'Shift-Enter':
+            setLastShortcut('Shift-Enter')
+            break
+          default:
+            break
+        }
+      }
+    },
+    content: `
+      <p>
+        Hey, try to hit Shift+Enter, Ctrl+Enter or Meta+Enter. The last shortcut hit will be displayed above.
+      </p>
+    `,
+  })
+
+  if (!editor) {
+    return null
+  }
+
+  return (
+    <>
+      <div className="control-group">
+        <div className="button-group">
+          <button
+            onClick={() => editor.chain().focus().toggleBold().run()}
+            className={editor.isActive('bold') ? 'is-active' : ''}
+          >
+            Bold
+          </button>
+          <button
+            onClick={() => editor.chain().focus().toggleItalic().run()}
+            className={editor.isActive('italic') ? 'is-active' : ''}
+          >
+            Italic
+          </button>
+        </div>
+        <div className="hint">
+          {lastShortcut
+            ? `${lastShortcut} was the last shortcut hit, and was handled by React`
+            : 'No shortcut has been hit yet, use Shift+Enter to trigger a shortcut handler'}
+        </div>
+      </div>
+
+      <EditorContent editor={editor} />
+    </>
+  )
+}

demos/src/Examples/EnterShortcuts/React/styles.scss

@@ -0,0 +1,91 @@
+/* Basic editor styles */
+.tiptap {
+  :first-child {
+    margin-top: 0;
+  }
+
+  /* List styles */
+  ul, 
+  ol {
+    padding: 0 1rem;
+    margin: 1.25rem 1rem 1.25rem 0.4rem;
+
+    li p {
+      margin-top: 0.25em;
+      margin-bottom: 0.25em;
+    }
+  }
+
+  /* Heading styles */
+  h1, 
+  h2, 
+  h3, 
+  h4, 
+  h5, 
+  h6 {
+    line-height: 1.1;
+    margin-top: 2.5rem;
+    text-wrap: pretty;
+  }
+
+  h1, 
+  h2 {
+    margin-top: 3.5rem;
+    margin-bottom: 1.5rem;
+  }
+
+  h1 { 
+    font-size: 1.4rem; 
+  }
+
+  h2 { 
+    font-size: 1.2rem; 
+  }
+
+  h3 { 
+    font-size: 1.1rem; 
+  }
+
+  h4, 
+  h5, 
+  h6 { 
+    font-size: 1rem; 
+  }
+
+  /* Code and preformatted text styles */
+  code {
+    background-color: var(--purple-light);
+    border-radius: 0.4rem;
+    color: var(--black);
+    font-size: 0.85rem;
+    padding: 0.25em 0.3em;
+  }
+
+  pre {
+    background: var(--black);
+    border-radius: 0.5rem;
+    color: var(--white);
+    font-family: 'JetBrainsMono', monospace;
+    margin: 1.5rem 0;
+    padding: 0.75rem 1rem;
+
+    code {
+      background: none;
+      color: inherit;
+      font-size: 0.8rem;
+      padding: 0;
+    }
+  }
+
+  blockquote {
+    border-left: 3px solid var(--gray-3);
+    margin: 1.5rem 0;
+    padding-left: 1rem;
+  }
+
+  hr {
+    border: none;
+    border-top: 1px solid var(--gray-2);
+    margin: 2rem 0;
+  }
+}

demos/src/Examples/EnterShortcuts/Vue/index.spec.js

@@ -0,0 +1,32 @@
+context('/src/Examples/EnterShortcuts/Vue/', () => {
+  before(() => {
+    cy.visit('/src/Examples/EnterShortcuts/Vue/')
+  })
+
+  beforeEach(() => {
+    cy.get('.tiptap').then(([{ editor }]) => {
+      editor.commands.setContent('<p>Example Text</p>')
+    })
+  })
+
+  it('should update the hint html when the keyboard shortcut is pressed', () => {
+    cy.get('.tiptap')
+      .trigger('keydown', { metaKey: true, key: 'Enter' })
+    cy.get('.hint')
+      .should('contain', 'Meta-Enter was the last shortcut')
+  })
+
+  it('should update the hint html when the keyboard shortcut is pressed', () => {
+    cy.get('.tiptap')
+      .trigger('keydown', { shiftKey: true, key: 'Enter' })
+    cy.get('.hint')
+      .should('contain', 'Shift-Enter was the last shortcut')
+  })
+
+  it('should update the hint html when the keyboard shortcut is pressed', () => {
+    cy.get('.tiptap')
+      .trigger('keydown', { ctrlKey: true, key: 'Enter' })
+    cy.get('.hint')
+      .should('contain', 'Ctrl-Enter was the last shortcut')
+  })
+})