@puredesktop/platform-editor 1.0.0-beta.1

package/src/extensions/slashCommands.ts

@@ -0,0 +1,746 @@
+import { Extension, type Editor } from '@tiptap/core'
+import { Plugin, PluginKey, type EditorState } from '@tiptap/pm/state'
+import type { EditorView } from '@tiptap/pm/view'
+import {
+  insertEditableBlockMath,
+  insertEditableInlineMath,
+} from './mathEditing.js'
+
+export interface SlashCommandRange {
+  from: number
+  to: number
+}
+
+export interface SlashCommandRunOptions {
+  editor: Editor
+  range: SlashCommandRange
+  query: string
+  source: 'typed' | 'selection'
+}
+
+export interface SlashCommandItem {
+  id: string
+  title: string
+  description?: string
+  keywords?: string[]
+  section?: string
+  run: (options: SlashCommandRunOptions) => void
+}
+
+interface SlashCommandMatch {
+  range: SlashCommandRange
+  query: string
+}
+
+interface ActiveSlashCommandState extends SlashCommandMatch {
+  items: SlashCommandItem[]
+  source: 'typed' | 'selection'
+}
+
+interface SlashCommandsOptions {
+  items: SlashCommandItem[]
+}
+
+const SLASH_COMMAND_LIMIT = 32
+const SLASH_MENU_MARGIN_PX = 12
+const SLASH_MENU_GAP_PX = 8
+const SLASH_MENU_MAX_HEIGHT_PX = 360
+const SLASH_MENU_MIN_HEIGHT_PX = 120
+
+export const SlashCommands = Extension.create<SlashCommandsOptions>({
+  name: 'slashCommands',
+
+  addOptions() {
+    return {
+      items: [],
+    }
+  },
+
+  addProseMirrorPlugins() {
+    const extension = this
+    let active: ActiveSlashCommandState | null = null
+    let selectedIndex = 0
+    let menu: HTMLDivElement | null = null
+    let detachViewportListeners: (() => void) | null = null
+
+    const emitOpenState = (open: boolean): void => {
+      extension.editor?.view?.dom?.dispatchEvent(
+        new CustomEvent('ps-slash-menu-toggle', { detail: { open } }),
+      )
+    }
+
+    const closeMenu = (): void => {
+      const wasOpen = menu !== null
+      active = null
+      selectedIndex = 0
+      detachViewportListeners?.()
+      detachViewportListeners = null
+      menu?.remove()
+      menu = null
+      if (wasOpen) emitOpenState(false)
+    }
+
+    const positionMenu = (view: EditorView): void => {
+      if (!active || !menu) return
+
+      const coords = view.coordsAtPos(active.range.from)
+      const viewportWidth = window.innerWidth
+      const viewportHeight = window.innerHeight
+      const margin = SLASH_MENU_MARGIN_PX
+      const gap = SLASH_MENU_GAP_PX
+      const maxPanelWidth = Math.max(0, viewportWidth - margin * 2)
+
+      menu.style.maxHeight = `${SLASH_MENU_MAX_HEIGHT_PX}px`
+      menu.style.overflowY = 'auto'
+
+      const measured = menu.getBoundingClientRect()
+      const width = Math.min(
+        Math.max(measured.width || 280, 280),
+        maxPanelWidth,
+      )
+      const naturalHeight = Math.min(
+        menu.scrollHeight,
+        SLASH_MENU_MAX_HEIGHT_PX,
+      )
+      const spaceBelow = Math.max(
+        0,
+        viewportHeight - coords.bottom - gap - margin,
+      )
+      const spaceAbove = Math.max(0, coords.top - gap - margin)
+      const openAbove = naturalHeight > spaceBelow && spaceAbove > spaceBelow
+      const availableSpace = openAbove ? spaceAbove : spaceBelow
+      const height = Math.max(
+        Math.min(naturalHeight, availableSpace),
+        Math.min(SLASH_MENU_MIN_HEIGHT_PX, naturalHeight, availableSpace),
+      )
+      const left = Math.min(
+        Math.max(margin, coords.left),
+        Math.max(margin, viewportWidth - width - margin),
+      )
+      const top = openAbove
+        ? Math.max(margin, coords.top - gap - height)
+        : Math.min(coords.bottom + gap, viewportHeight - margin - height)
+
+      menu.style.left = `${left}px`
+      menu.style.top = `${top}px`
+      menu.style.width = `${width}px`
+      menu.style.maxHeight = `${height}px`
+    }
+
+    const attachViewportListeners = (view: EditorView): void => {
+      if (detachViewportListeners) return
+
+      let animationFrame = 0
+      const reposition = (): void => {
+        cancelAnimationFrame(animationFrame)
+        animationFrame = requestAnimationFrame(() => {
+          positionMenu(view)
+        })
+      }
+
+      window.addEventListener('resize', reposition)
+      window.addEventListener('scroll', reposition, true)
+      detachViewportListeners = () => {
+        cancelAnimationFrame(animationFrame)
+        window.removeEventListener('resize', reposition)
+        window.removeEventListener('scroll', reposition, true)
+      }
+    }
+
+    const renderMenu = (view: EditorView): void => {
+      if (!active || !active.items.length) {
+        closeMenu()
+        return
+      }
+
+      const justOpened = !menu
+      if (!menu) {
+        menu = document.createElement('div')
+        menu.className = 'ps-slash-command-menu'
+        document.body.appendChild(menu)
+      }
+      attachViewportListeners(view)
+      if (justOpened) emitOpenState(true)
+
+      menu.replaceChildren()
+
+      let previousSection: string | null = null
+
+      active.items.forEach((item, index) => {
+        const section = item.section ?? 'Writing'
+        if (section !== previousSection) {
+          if (previousSection !== null) {
+            const divider = document.createElement('div')
+            divider.className = 'ps-slash-command-divider'
+            menu?.appendChild(divider)
+          }
+
+          const heading = document.createElement('div')
+          heading.className = 'ps-slash-command-section'
+          heading.textContent = section
+          menu?.appendChild(heading)
+          previousSection = section
+        }
+
+        const button = document.createElement('button')
+        button.type = 'button'
+        button.className = 'ps-slash-command-item'
+        button.dataset.active = String(index === selectedIndex)
+        button.addEventListener('mousedown', event => {
+          event.preventDefault()
+          runItem(view, item)
+        })
+
+        const title = document.createElement('span')
+        title.className = 'ps-slash-command-title'
+        title.textContent = item.title
+        button.appendChild(title)
+
+        if (item.description) {
+          const description = document.createElement('span')
+          description.className = 'ps-slash-command-description'
+          description.textContent = item.description
+          button.appendChild(description)
+        }
+
+        menu?.appendChild(button)
+      })
+
+      positionMenu(view)
+      menu
+        .querySelector<HTMLButtonElement>(
+          '.ps-slash-command-item[data-active="true"]',
+        )
+        ?.scrollIntoView({ block: 'nearest' })
+    }
+
+    const runItem = (view: EditorView, item: SlashCommandItem): void => {
+      if (!active) return
+      const current = active
+      closeMenu()
+      item.run({
+        editor: extension.editor,
+        range: current.range,
+        query: current.query,
+        source: current.source,
+      })
+      view.focus()
+    }
+
+    const updateActiveState = (state: EditorState): void => {
+      // A selection-opened menu has no typed "/" to match, so the typed-match
+      // logic below would close it on the next view update. Keep it open until
+      // the selection collapses (or it's dismissed via Escape/click/run).
+      if (active?.source === 'selection') {
+        if (state.selection.empty) closeMenu()
+        return
+      }
+
+      const match = findSlashCommandMatch(state)
+      if (!match) {
+        closeMenu()
+        return
+      }
+
+      const items = filterSlashCommandItems(
+        extension.options.items,
+        match.query,
+      )
+      if (!items.length) {
+        closeMenu()
+        return
+      }
+
+      active = { ...match, items, source: 'typed' }
+      selectedIndex = Math.min(selectedIndex, items.length - 1)
+    }
+
+    return [
+      new Plugin({
+        key: new PluginKey('slashCommands'),
+        props: {
+          handleKeyDown(view, event) {
+            if (!active && event.key === '/') {
+              const { from, to, empty } = view.state.selection
+              if (!empty) {
+                event.preventDefault()
+                const items = filterSlashCommandItems(extension.options.items, '')
+                if (!items.length) return true
+                active = {
+                  range: { from, to },
+                  query: '',
+                  items,
+                  source: 'selection',
+                }
+                selectedIndex = 0
+                renderMenu(view)
+                return true
+              }
+            }
+
+            if (!active) return false
+
+            if (active.source === 'selection') {
+              if (event.key.length === 1 && !event.metaKey && !event.ctrlKey) {
+                event.preventDefault()
+                active = {
+                  ...active,
+                  query: `${active.query}${event.key}`.trim(),
+                  items: filterSlashCommandItems(
+                    extension.options.items,
+                    `${active.query}${event.key}`.trim(),
+                  ),
+                }
+                selectedIndex = 0
+                renderMenu(view)
+                return true
+              }
+
+              if (event.key === 'Backspace') {
+                event.preventDefault()
+                const query = active.query.slice(0, -1)
+                active = {
+                  ...active,
+                  query,
+                  items: filterSlashCommandItems(extension.options.items, query),
+                }
+                selectedIndex = 0
+                renderMenu(view)
+                return true
+              }
+            }
+
+            if (event.key === 'ArrowDown') {
+              event.preventDefault()
+              selectedIndex = (selectedIndex + 1) % active.items.length
+              renderMenu(view)
+              return true
+            }
+
+            if (event.key === 'ArrowUp') {
+              event.preventDefault()
+              selectedIndex =
+                (selectedIndex - 1 + active.items.length) % active.items.length
+              renderMenu(view)
+              return true
+            }
+
+            if (event.key === 'Enter') {
+              event.preventDefault()
+              runItem(view, active.items[selectedIndex])
+              return true
+            }
+
+            if (event.key === 'Escape') {
+              event.preventDefault()
+              closeMenu()
+              return true
+            }
+
+            return false
+          },
+        },
+        view(view) {
+          injectSlashCommandStyles()
+          updateActiveState(view.state)
+          renderMenu(view)
+
+          return {
+            update(nextView) {
+              updateActiveState(nextView.state)
+              renderMenu(nextView)
+            },
+            destroy() {
+              closeMenu()
+            },
+          }
+        },
+      }),
+    ]
+  },
+})
+
+interface DefaultSlashCommandOptions {
+  includePrompts?: boolean
+}
+
+type ChainWithOptionalCommands = ReturnType<Editor['chain']> & {
+  toggleUnderline?: () => ChainWithOptionalCommands
+  toggleCode?: () => ChainWithOptionalCommands
+  toggleTaskList?: () => ChainWithOptionalCommands
+  sinkListItem?: (type: string) => ChainWithOptionalCommands
+  liftListItem?: (type: string) => ChainWithOptionalCommands
+  insertTable?: (options: {
+    rows: number
+    cols: number
+    withHeaderRow: boolean
+  }) => ChainWithOptionalCommands
+  insertFootnote?: () => ChainWithOptionalCommands
+  toggleIndexMarker?: () => ChainWithOptionalCommands
+  insertInlineMath?: (options: { latex: string }) => ChainWithOptionalCommands
+  insertBlockMath?: (options: { latex: string }) => ChainWithOptionalCommands
+  insertMermaidBlock?: () => ChainWithOptionalCommands
+  setLink?: (attributes: { href: string }) => ChainWithOptionalCommands
+}
+
+function commandChain(
+  editor: Editor,
+  range: SlashCommandRange,
+  source: SlashCommandRunOptions['source'],
+): ChainWithOptionalCommands {
+  const chain = editor.chain().focus() as ChainWithOptionalCommands
+  if (source === 'typed') return chain.deleteRange(range)
+  // Opened from a selection: re-assert the original range so toggles like
+  // bold/italic actually transform the selected text (a bare focus() can land
+  // on a collapsed cursor and no-op).
+  if (source === 'selection') return chain.setTextSelection(range)
+  return chain
+}
+
+export function createDefaultSlashCommands(
+  options: DefaultSlashCommandOptions = {},
+): SlashCommandItem[] {
+  const promptEnabled = options.includePrompts ?? true
+  return [
+    {
+      id: 'paragraph',
+      title: 'Text',
+      description: 'Start a normal paragraph',
+      keywords: ['paragraph', 'normal'],
+      section: 'Writing',
+      run: ({ editor, range, source }) => {
+        commandChain(editor, range, source).setParagraph().run()
+      },
+    },
+    {
+      id: 'heading-1',
+      title: 'Heading 1',
+      description: 'Large section heading',
+      keywords: ['title', 'h1'],
+      section: 'Writing',
+      run: ({ editor, range, source }) => {
+        commandChain(editor, range, source).setNode('heading', { level: 1 }).run()
+      },
+    },
+    {
+      id: 'heading-2',
+      title: 'Heading 2',
+      description: 'Medium section heading',
+      keywords: ['subtitle', 'h2'],
+      section: 'Writing',
+      run: ({ editor, range, source }) => {
+        commandChain(editor, range, source).setNode('heading', { level: 2 }).run()
+      },
+    },
+    {
+      id: 'heading-3',
+      title: 'Heading 3',
+      description: 'Small section heading',
+      keywords: ['subtitle', 'h3'],
+      section: 'Writing',
+      run: ({ editor, range, source }) => {
+        commandChain(editor, range, source).setNode('heading', { level: 3 }).run()
+      },
+    },
+    {
+      id: 'bold',
+      title: 'Bold',
+      description: 'Emphasize the selected text',
+      keywords: ['strong'],
+      section: 'Formatting',
+      run: ({ editor, range, source }) => {
+        commandChain(editor, range, source).toggleBold().run()
+      },
+    },
+    {
+      id: 'italic',
+      title: 'Italic',
+      description: 'Italicize the selected text',
+      keywords: ['emphasis'],
+      section: 'Formatting',
+      run: ({ editor, range, source }) => {
+        commandChain(editor, range, source).toggleItalic().run()
+      },
+    },
+    {
+      id: 'underline',
+      title: 'Underline',
+      description: 'Underline the selected text',
+      section: 'Formatting',
+      run: ({ editor, range, source }) => {
+        commandChain(editor, range, source).toggleUnderline?.()?.run()
+      },
+    },
+    {
+      id: 'inline-code',
+      title: 'Inline code',
+      description: 'Mark text as code',
+      keywords: ['code'],
+      section: 'Formatting',
+      run: ({ editor, range, source }) => {
+        commandChain(editor, range, source).toggleCode?.()?.run()
+      },
+    },
+    {
+      id: 'link',
+      title: 'Link',
+      description: 'Add a link to the selected text',
+      keywords: ['url', 'href'],
+      section: 'Formatting',
+      run: ({ editor, range, source }) => {
+        if (!promptEnabled) return
+        const href = window.prompt('Link URL')?.trim()
+        if (!href) return
+        commandChain(editor, range, source).setLink?.({ href })?.run()
+      },
+    },
+    {
+      id: 'bullet-list',
+      title: 'Bullet list',
+      description: 'Create a simple list',
+      keywords: ['unordered', 'list'],
+      section: 'Lists',
+      run: ({ editor, range, source }) => {
+        commandChain(editor, range, source).toggleBulletList().run()
+      },
+    },
+    {
+      id: 'numbered-list',
+      title: 'Numbered list',
+      description: 'Create an ordered list',
+      keywords: ['ordered', 'list'],
+      section: 'Lists',
+      run: ({ editor, range, source }) => {
+        commandChain(editor, range, source).toggleOrderedList().run()
+      },
+    },
+    {
+      id: 'task-list',
+      title: 'Task list',
+      description: 'Create a checklist',
+      keywords: ['todo', 'checkbox'],
+      section: 'Lists',
+      run: ({ editor, range, source }) => {
+        commandChain(editor, range, source).toggleTaskList?.()?.run()
+      },
+    },
+    {
+      id: 'indent-list',
+      title: 'Indent list item',
+      description: 'Nest the current list item',
+      keywords: ['sink', 'nest'],
+      section: 'Lists',
+      run: ({ editor, range, source }) => {
+        commandChain(editor, range, source).sinkListItem?.('listItem')?.run()
+      },
+    },
+    {
+      id: 'outdent-list',
+      title: 'Outdent list item',
+      description: 'Lift the current list item',
+      keywords: ['lift', 'unnest'],
+      section: 'Lists',
+      run: ({ editor, range, source }) => {
+        commandChain(editor, range, source).liftListItem?.('listItem')?.run()
+      },
+    },
+    {
+      id: 'quote',
+      title: 'Quote',
+      description: 'Call out a quoted passage',
+      keywords: ['blockquote', 'citation'],
+      section: 'Blocks',
+      run: ({ editor, range, source }) => {
+        commandChain(editor, range, source).toggleBlockquote().run()
+      },
+    },
+    {
+      id: 'code-block',
+      title: 'Code block',
+      description: 'Insert a code section',
+      keywords: ['code', 'pre'],
+      section: 'Blocks',
+      run: ({ editor, range, source }) => {
+        commandChain(editor, range, source).toggleCodeBlock().run()
+      },
+    },
+    {
+      id: 'table',
+      title: 'Table',
+      description: 'Insert a simple table',
+      keywords: ['grid'],
+      section: 'Blocks',
+      run: ({ editor, range, source }) => {
+        commandChain(editor, range, source)
+          .insertTable?.({ rows: 3, cols: 3, withHeaderRow: true })
+          ?.run()
+      },
+    },
+    {
+      id: 'footnote',
+      title: 'Footnote',
+      description: 'Insert a footnote marker',
+      keywords: ['note', 'reference'],
+      section: 'Blocks',
+      run: ({ editor, range, source }) => {
+        commandChain(editor, range, source).insertFootnote?.()?.run()
+      },
+    },
+    {
+      id: 'index-marker',
+      title: 'Index marker',
+      description: 'Mark selected text for the index',
+      keywords: ['index'],
+      section: 'Blocks',
+      run: ({ editor, range, source }) => {
+        commandChain(editor, range, source).toggleIndexMarker?.()?.run()
+      },
+    },
+    {
+      id: 'inline-equation',
+      title: 'Inline equation',
+      description: 'Insert an editable inline equation',
+      keywords: ['math', 'latex'],
+      section: 'Blocks',
+      run: ({ editor, range, source }) => {
+        // Remove the typed "/…" text, then insert an empty equation and open
+        // its editor immediately (live preview; renders in place on blur).
+        commandChain(editor, range, source).run()
+        insertEditableInlineMath(editor)
+      },
+    },
+    {
+      id: 'display-equation',
+      title: 'Display equation',
+      description: 'Insert an editable centered equation',
+      keywords: ['math', 'latex', 'block'],
+      section: 'Blocks',
+      run: ({ editor, range, source }) => {
+        commandChain(editor, range, source).run()
+        insertEditableBlockMath(editor)
+      },
+    },
+    {
+      id: 'mermaid',
+      title: 'Mermaid diagram',
+      description: 'Insert a diagram block',
+      keywords: ['diagram', 'flowchart'],
+      section: 'Blocks',
+      run: ({ editor, range, source }) => {
+        commandChain(editor, range, source).insertMermaidBlock?.()?.run()
+      },
+    },
+  ]
+}
+
+function findSlashCommandMatch(state: EditorState): SlashCommandMatch | null {
+  const { selection } = state
+  if (!selection.empty) return null
+
+  const { $from } = selection
+  const textBefore = $from.parent.textBetween(0, $from.parentOffset, '\0', '\0')
+  const match = /(?:^|\s)\/([\w\s-]{0,48})$/.exec(textBefore)
+  if (!match) return null
+
+  const fullMatch = match[0]
+  const slashOffset = fullMatch.lastIndexOf('/')
+  const from = $from.pos - (fullMatch.length - slashOffset)
+
+  return {
+    range: { from, to: $from.pos },
+    query: match[1]?.trim() ?? '',
+  }
+}
+
+function filterSlashCommandItems(
+  items: SlashCommandItem[],
+  query: string,
+): SlashCommandItem[] {
+  const normalizedQuery = query.toLowerCase()
+  if (!normalizedQuery) return items
+
+  return items
+    .filter(item => {
+      const haystack = [
+        item.title,
+        item.description ?? '',
+        ...(item.keywords ?? []),
+      ]
+        .join(' ')
+        .toLowerCase()
+      return haystack.includes(normalizedQuery)
+    })
+    .slice(0, SLASH_COMMAND_LIMIT)
+}
+
+function injectSlashCommandStyles(): void {
+  if (document.getElementById('ps-slash-command-styles')) return
+
+  const style = document.createElement('style')
+  style.id = 'ps-slash-command-styles'
+  style.textContent = `
+    .ps-slash-command-menu {
+      position: fixed;
+      z-index: var(--platform-z-index-zi-app-menus, 1000);
+      box-sizing: border-box;
+      min-width: 280px;
+      max-width: 340px;
+      padding: 6px;
+      border: 1px solid var(--platform-colors-border, #d7dbe0);
+      border-radius: 10px;
+      background: var(--platform-colors-surface, #fff);
+      box-shadow: 0 14px 34px rgb(23 29 36 / 0.14);
+      color: var(--platform-colors-text, #2e3338);
+      font-family: var(--platform-typography-font-family, system-ui, sans-serif);
+      overflow-x: hidden;
+      overscroll-behavior: contain;
+    }
+
+    .ps-slash-command-item {
+      display: grid;
+      width: 100%;
+      gap: 2px;
+      padding: 8px 10px;
+      border: 0;
+      border-radius: 7px;
+      background: transparent;
+      color: inherit;
+      font: inherit;
+      text-align: left;
+      cursor: pointer;
+    }
+
+    .ps-slash-command-section {
+      color: var(--platform-colors-text-tertiary, #8a9097);
+      font-size: 10px;
+      font-weight: 700;
+      letter-spacing: 0.08em;
+      line-height: 1.2;
+      padding: 9px 10px 5px;
+      text-transform: uppercase;
+    }
+
+    .ps-slash-command-divider {
+      border-top: 1px solid var(--platform-colors-border, #d7dbe0);
+      margin: 6px 4px 2px;
+    }
+
+    .ps-slash-command-item[data-active="true"],
+    .ps-slash-command-item:hover {
+      background: var(--platform-colors-surface-active, #edeff2);
+    }
+
+    .ps-slash-command-title {
+      font-size: 13px;
+      font-weight: 650;
+      line-height: 1.25;
+    }
+
+    .ps-slash-command-description {
+      color: var(--platform-colors-text-secondary, #6e737a);
+      font-size: 12px;
+      line-height: 1.25;
+    }
+  `
+  document.head.appendChild(style)
+}