@pilotiq/tiptap 3.10.4 → 3.10.6

package/src/extensions/DragHandleExtension.ts

@@ -1,184 +0,0 @@
-import { Extension } from '@tiptap/core'
-import { NodeSelection, Plugin, PluginKey } from '@tiptap/pm/state'
-import type { EditorView } from '@tiptap/pm/view'
-
-const dragHandlePluginKey = new PluginKey('pilotiqDragHandle')
-
-// Node types whose direct children are the draggable units (e.g. each
-// `listItem` of a `bulletList` is a draggable unit). Listed forward-compat
-// includes `taskList` even though StarterKit 3 doesn't ship it; if a consumer
-// registers it later it'll just work.
-const LIST_CONTAINERS = new Set(['bulletList', 'orderedList', 'taskList'])
-
-/**
- * Hand-built drag handle: floats a six-dot button in the gutter on the left
- * of whichever top-level block the cursor is hovering. Click-drag to reorder.
- *
- * Implementation (kept self-contained, no `tiptap-extension-global-drag-handle`
- * dep — that pkg uses Tiptap internals that break across versions):
- *
- *  1. On mount, append a single `<button>` to `document.body`. It's the
- *     handle. Position lives in CSS `top` / `left`.
- *  2. On `mousemove` over the editor, find the top-level block under the
- *     cursor via `posAtCoords` + climb to depth 1, then read its DOM rect
- *     and align the handle to its top-left.
- *  3. On `mousedown` on the handle, set `node` selection on that block and
- *     dispatch a synthetic `dragstart` from the editor DOM — ProseMirror's
- *     own drop logic handles reorder.
- */
-export const DragHandleExtension = Extension.create({
-  name: 'pilotiqDragHandle',
-
-  addProseMirrorPlugins() {
-    return [
-      new Plugin({
-        key: dragHandlePluginKey,
-        view: (view) => createDragHandleView(view),
-      }),
-    ]
-  },
-})
-
-function createDragHandleView(view: EditorView): {
-  update?: () => void
-  destroy: () => void
-} {
-  const handle = document.createElement('button')
-  handle.type = 'button'
-  handle.setAttribute('data-pilotiq-drag-handle', '')
-  handle.setAttribute('contenteditable', 'false')
-  handle.setAttribute('aria-label', 'Drag block')
-  handle.setAttribute('draggable', 'true')
-  handle.style.cssText = [
-    'position: absolute',
-    'display: none',
-    'cursor: grab',
-    'background: transparent',
-    'border: 0',
-    'padding: 2px',
-    'color: var(--muted-foreground, #888)',
-    'opacity: 0',
-    'transition: opacity 0.15s',
-    'z-index: 50',
-    'line-height: 1',
-    'border-radius: 4px',
-  ].join(';')
-  handle.innerHTML = '<svg width="8" height="12" viewBox="0 0 8 12" fill="currentColor" aria-hidden="true"><circle cx="2" cy="2" r="1"/><circle cx="2" cy="6" r="1"/><circle cx="2" cy="10" r="1"/><circle cx="6" cy="2" r="1"/><circle cx="6" cy="6" r="1"/><circle cx="6" cy="10" r="1"/></svg>'
-  document.body.appendChild(handle)
-
-  let activePos: number | null = null
-
-  const onMouseMove = (event: MouseEvent): void => {
-    const editorRect = view.dom.getBoundingClientRect()
-    const inside =
-      event.clientX >= editorRect.left - 60 &&
-      event.clientX <= editorRect.right &&
-      event.clientY >= editorRect.top &&
-      event.clientY <= editorRect.bottom
-    if (!inside) {
-      hide()
-      return
-    }
-    const pos = view.posAtCoords({ left: event.clientX, top: event.clientY })
-    if (!pos) {
-      hide()
-      return
-    }
-    const $pos = view.state.doc.resolve(pos.pos)
-    // Pick the deepest ancestor whose parent is the doc OR a list container —
-    // that's the "unit" the user expects the handle to grab. So inside a
-    // bullet list, hovering an item resolves to the list_item (not the whole
-    // bullet_list); inside a blockquote, hovering its inner paragraph resolves
-    // to the blockquote (since the blockquote's parent is the doc).
-    let blockDepth = 1
-    for (let d = $pos.depth; d >= 1; d--) {
-      const parentName = $pos.node(d - 1).type.name
-      if (parentName === 'doc' || LIST_CONTAINERS.has(parentName)) {
-        blockDepth = d
-        break
-      }
-    }
-    const blockPos  = $pos.before(blockDepth)
-    const blockNode = view.nodeDOM(blockPos) as HTMLElement | null
-    if (!blockNode) {
-      hide()
-      return
-    }
-    const rect = blockNode.getBoundingClientRect()
-    handle.style.display = 'block'
-    handle.style.opacity = '1'
-    handle.style.top = `${rect.top + window.scrollY + 4}px`
-    // Pin X to the editor's left gutter (not the block's left edge). For
-    // nested content the block's `rect.left` sits past the indent / bullet
-    // gutter, so handles for list items would overlap their bullets. Keeping
-    // the handle in a fixed column lets the eye track which block it points
-    // at by vertical alignment alone.
-    handle.style.left = `${editorRect.left + window.scrollX + 16}px`
-    activePos = blockPos
-  }
-
-  const hide = (): void => {
-    handle.style.opacity = '0'
-    handle.style.display = 'none'
-    activePos = null
-  }
-
-  const onMouseLeave = (event: MouseEvent): void => {
-    // Don't hide while moving onto the handle itself.
-    if (event.relatedTarget === handle) return
-    hide()
-  }
-
-  const onDragStart = (event: DragEvent): void => {
-    if (activePos === null || !event.dataTransfer) return
-    const node = view.state.doc.nodeAt(activePos)
-    if (!node) return
-
-    // Select the block as a NodeSelection so PM treats the drag as a node
-    // move, not a text-range move.
-    const selection = NodeSelection.create(view.state.doc, activePos)
-    view.dispatch(view.state.tr.setSelection(selection))
-
-    // PM's drop handler reads `view.dragging` for in-editor drags. Without
-    // it the drop falls back to clipboard-HTML parsing and silently no-ops
-    // (drop returns to origin). This is the line that actually fixes drop.
-    const slice = selection.content()
-    ;(view as unknown as { dragging: { slice: typeof slice; move: boolean } }).dragging = {
-      slice,
-      move: !event.ctrlKey && !event.metaKey,
-    }
-
-    // Use PM's clipboard serializer so the drag carries proper HTML — both
-    // for cross-editor pastes and as the visible drag image.
-    const { dom, text } = view.serializeForClipboard(slice)
-    event.dataTransfer.clearData()
-    event.dataTransfer.setData('text/html', dom.innerHTML)
-    event.dataTransfer.setData('text/plain', text)
-    event.dataTransfer.effectAllowed = 'copyMove'
-
-    // Drag image = the actual block, not the handle button.
-    const blockNode = view.nodeDOM(activePos) as HTMLElement | null
-    if (blockNode) event.dataTransfer.setDragImage(blockNode, 0, 0)
-
-    handle.style.cursor = 'grabbing'
-  }
-
-  const onDragEnd = (): void => {
-    handle.style.cursor = 'grab'
-  }
-
-  view.dom.addEventListener('mousemove', onMouseMove)
-  view.dom.addEventListener('mouseleave', onMouseLeave)
-  handle.addEventListener('dragstart', onDragStart)
-  handle.addEventListener('dragend', onDragEnd)
-
-  return {
-    destroy: () => {
-      view.dom.removeEventListener('mousemove', onMouseMove)
-      view.dom.removeEventListener('mouseleave', onMouseLeave)
-      handle.removeEventListener('dragstart', onDragStart)
-      handle.removeEventListener('dragend', onDragEnd)
-      handle.remove()
-    },
-  }
-}

package/src/extensions/GridExtension.test.ts

@@ -1,31 +0,0 @@
-import { describe, it } from 'node:test'
-import assert from 'node:assert/strict'
-import { clampGridColumns } from './GridExtension.js'
-
-describe('clampGridColumns', () => {
-  it('passes through 2 and 3', () => {
-    assert.equal(clampGridColumns(2), 2)
-    assert.equal(clampGridColumns(3), 3)
-  })
-
-  it('falls back to 2 for 1', () => {
-    assert.equal(clampGridColumns(1), 2)
-  })
-
-  it('falls back to 2 for 4+ / NaN / negative / undefined / non-numeric strings', () => {
-    assert.equal(clampGridColumns(4),         2)
-    assert.equal(clampGridColumns(99),        2)
-    assert.equal(clampGridColumns(NaN),       2)
-    assert.equal(clampGridColumns(-1),        2)
-    assert.equal(clampGridColumns(undefined), 2)
-    assert.equal(clampGridColumns(null),      2)
-    assert.equal(clampGridColumns(''),        2)
-    assert.equal(clampGridColumns('abc'),     2)
-  })
-
-  it('coerces numeric strings before clamping', () => {
-    assert.equal(clampGridColumns('2'), 2)
-    assert.equal(clampGridColumns('3'), 3)
-    assert.equal(clampGridColumns('4'), 2)
-  })
-})

package/src/extensions/GridExtension.ts

@@ -1,138 +0,0 @@
-import { Node, mergeAttributes } from '@tiptap/core'
-
-declare module '@tiptap/core' {
-  interface Commands<ReturnType> {
-    grid: {
-      /**
-       * Insert a multi-column grid at the cursor. Each column gets one
-       * empty paragraph. Defaults to 2 columns; pass `{ columns: 3 }` for
-       * the three-column variant.
-       */
-      setGrid: (options?: { columns?: GridColumns }) => ReturnType
-      /**
-       * Unwrap the enclosing grid: replace the grid node with the flat
-       * concatenation of every column's children. No-op when the cursor
-       * isn't inside a grid.
-       */
-      unsetGrid: () => ReturnType
-    }
-  }
-}
-
-/** Allowed column counts. */
-export type GridColumns = 2 | 3
-
-const ALLOWED_COLUMNS: ReadonlyArray<GridColumns> = [2, 3] as const
-
-/**
- * Coerce any input into one of the allowed column counts. Out-of-range
- * values, NaN, undefined, and non-numeric strings all fall back to 2 — the
- * conservative default.
- *
- * Exported for unit tests and so the renderer in `render.ts` can share the
- * same validator with the editor's `parseHTML`.
- */
-export function clampGridColumns(raw: unknown): GridColumns {
-  const n = typeof raw === 'number' ? raw : Number(raw)
-  if (!Number.isFinite(n)) return 2
-  const trunc = Math.trunc(n)
-  return ALLOWED_COLUMNS.includes(trunc as GridColumns) ? (trunc as GridColumns) : 2
-}
-
-/**
- * Multi-column grid container. Schema constrains it to exactly 2 or 3
- * `gridColumn` children, so the user can't construct a 1-column or
- * 4-column grid through any path (toolbar, slash, paste).
- *
- * Renders to `<div data-type="grid" data-columns="N" class="pilotiq-grid
- * pilotiq-grid-cols-N">` — consumers ship the matching CSS (Tailwind
- * `grid grid-cols-N gap-4` or hand-rolled). Same posture as `lead` /
- * `small` size marks: the package stays CSS-free.
- */
-export const Grid = Node.create({
-  name:     'grid',
-  group:    'block',
-  content:  'gridColumn{2,3}',
-  defining: true,
-
-  addAttributes() {
-    return {
-      columns: {
-        default: 2 as GridColumns,
-        parseHTML: (el) => clampGridColumns(el.getAttribute('data-columns')),
-        renderHTML: (attrs) => {
-          const cols = clampGridColumns(attrs['columns'])
-          return {
-            'data-columns': String(cols),
-            class:          `pilotiq-grid pilotiq-grid-cols-${cols}`,
-          }
-        },
-      },
-    }
-  },
-
-  parseHTML() {
-    return [{ tag: 'div[data-type="grid"]' }]
-  },
-
-  renderHTML({ HTMLAttributes }) {
-    return ['div', mergeAttributes(HTMLAttributes, { 'data-type': 'grid' }), 0]
-  },
-
-  addCommands() {
-    return {
-      setGrid:
-        (options) =>
-        ({ chain }) => {
-          const columns = clampGridColumns(options?.columns ?? 2)
-          const content = Array.from({ length: columns }, () => ({
-            type:    'gridColumn',
-            content: [{ type: 'paragraph' }],
-          }))
-          return chain()
-            .focus()
-            .insertContent({ type: 'grid', attrs: { columns }, content })
-            .run()
-        },
-
-      unsetGrid:
-        () =>
-        ({ state, tr, dispatch }) => {
-          const $head = state.selection.$head
-          for (let depth = $head.depth; depth > 0; depth--) {
-            const node = $head.node(depth)
-            if (node.type.name !== 'grid') continue
-            const start = $head.before(depth)
-            const end   = $head.after(depth)
-            // Concatenate each column's children into a flat block list.
-            const flat: unknown[] = []
-            node.forEach((col) => {
-              col.forEach((child) => flat.push(child))
-            })
-            if (dispatch) tr.replaceWith(start, end, flat as never)
-            return true
-          }
-          return false
-        },
-    }
-  },
-})
-
-/**
- * Individual column inside a `grid`. Belongs to its own custom group so the
- * top-level document only accepts `Grid` (not bare `gridColumn`s).
- */
-export const GridColumn = Node.create({
-  name:     'gridColumn',
-  group:    'gridColumn',
-  content:  'block+',
-  defining: true,
-
-  parseHTML() {
-    return [{ tag: 'div[data-type="gridColumn"]' }]
-  },
-
-  renderHTML({ HTMLAttributes }) {
-    return ['div', mergeAttributes(HTMLAttributes, { 'data-type': 'gridColumn' }), 0]
-  },
-})

package/src/extensions/MentionExtension.ts

@@ -1,248 +0,0 @@
-import { Node, mergeAttributes, type Editor, type Range } from '@tiptap/core'
-import Suggestion, { type SuggestionOptions } from '@tiptap/suggestion'
-import { PluginKey } from '@tiptap/pm/state'
-import type { MentionItem, MentionProviderMeta } from '../MentionProvider.js'
-
-declare module '@tiptap/core' {
-  interface Commands<ReturnType> {
-    mention: {
-      /**
-       * Insert a `mention` atom node. `trigger` is the character the
-       * provider was registered with (`@` / `#` / …) and is rendered
-       * inline together with the resolved label.
-       */
-      insertMention: (args: { id: string; label: string; trigger: string }) => ReturnType
-    }
-  }
-}
-
-/**
- * State the React side of the editor needs to render the mention popover.
- * `null` when the popover should be unmounted.
- */
-export interface MentionState {
-  trigger:    string
-  items:      MentionItem[]
-  /** Pick item — Suggestion will replace the trigger range and run the command. */
-  command:    (item: MentionItem) => void
-  clientRect: () => DOMRect | null
-  query:      string
-}
-
-export interface MentionOptions {
-  providers: MentionProviderMeta[]
-  /**
-   * Called whenever the popover should mount, update, or unmount. TiptapEditor
-   * holds the React state and passes a setter here.
-   */
-  onStateChange: (state: MentionState | null) => void
-  /**
-   * URL the field's `tagRichTextMentionUrls` walker stamped on the wire-side
-   * meta. Required for async providers (`MentionProvider.itemsUsing(fn)`);
-   * unused when every provider on this field is static. The client POSTs
-   * `{ field, trigger, query }` per keystroke and expects `{ ok, items }`.
-   */
-  mentionsUrl?: string
-  /**
-   * Field path the route handler uses to find the RichTextField on the
-   * page. Equals `Field.name` for non-nested fields. Inside a Repeater
-   * row this is the dotted form `<repeaterName>.<index>.<innerName>`;
-   * inside a Builder row it's `<builderName>.<index>.data.<innerName>`.
-   * The route handler parses the prefix and looks up the field against
-   * the Repeater's template / each Builder block's schema.
-   */
-  fieldName?: string
-}
-
-/**
- * Inline atom node + a Suggestion plugin per registered provider.
- *
- * The node carries `id`, `label`, and `trigger` attributes. Storage is JSON:
- * `{ type: 'mention', attrs: { id: 'sleman', label: 'Sleman', trigger: '@' } }`.
- *
- * Each provider gets its own ProseMirror Suggestion plugin instance so users
- * can mix multiple trigger characters in the same editor (`@user`, `#room`).
- * Items are static — declared via `MentionProvider.make('@').items([...])`.
- *
- * Read-side rendering happens through `renderRichTextToHtml(content,
- * { resolveMention: (trigger, id) => latestLabel })`. Without an override
- * the cached label is used — the editor stamps it at insert time so
- * static-content snapshots stay self-contained.
- */
-export const MentionExtension = Node.create<MentionOptions>({
-  name: 'mention',
-  group: 'inline',
-  inline: true,
-  atom: true,
-  selectable: true,
-
-  addOptions() {
-    return {
-      providers:     [],
-      onStateChange: () => {},
-    }
-  },
-
-  addAttributes() {
-    return {
-      id: {
-        default: null,
-        parseHTML: (el) => el.getAttribute('data-id'),
-        renderHTML: (a) => (a['id'] ? { 'data-id': String(a['id']) } : {}),
-      },
-      label: {
-        default: null,
-        parseHTML: (el) => el.getAttribute('data-label'),
-        renderHTML: (a) => (a['label'] ? { 'data-label': String(a['label']) } : {}),
-      },
-      trigger: {
-        default: null,
-        parseHTML: (el) => el.getAttribute('data-trigger'),
-        renderHTML: (a) => (a['trigger'] ? { 'data-trigger': String(a['trigger']) } : {}),
-      },
-    }
-  },
-
-  parseHTML() {
-    return [{ tag: 'span[data-pilotiq-mention]' }]
-  },
-
-  renderHTML({ node, HTMLAttributes }) {
-    const trigger = String(node.attrs['trigger'] ?? '')
-    const label   = String(node.attrs['label']   ?? node.attrs['id'] ?? '')
-    return [
-      'span',
-      mergeAttributes(
-        {
-          'data-pilotiq-mention': '',
-          class: 'pilotiq-mention rounded bg-blue-500/10 px-1.5 py-0.5 text-xs font-medium text-blue-700 dark:text-blue-300 align-baseline',
-        },
-        HTMLAttributes,
-      ),
-      `${trigger}${label}`,
-    ]
-  },
-
-  addCommands() {
-    return {
-      insertMention:
-        ({ id, label, trigger }) =>
-        ({ commands }) =>
-          commands.insertContent([
-            { type: this.name, attrs: { id, label, trigger } },
-            { type: 'text', text: ' ' },
-          ]),
-    }
-  },
-
-  addProseMirrorPlugins() {
-    const providers = this.options.providers
-    const emit      = this.options.onStateChange
-    const editor    = this.editor
-    const url       = this.options.mentionsUrl
-    const fieldName = this.options.fieldName
-
-    return providers.map((provider, i) =>
-      Suggestion({
-        pluginKey: new PluginKey(`pilotiqMentionSuggestion-${i}`),
-        editor,
-        char: provider.trigger,
-        startOfLine: false,
-        allowSpaces: false,
-        items: provider.async
-          ? async ({ query }: { query: string }): Promise<MentionItem[]> =>
-              fetchAsyncMentionItems(url, fieldName, provider.trigger, query)
-          : ({ query }: { query: string }) => filterMentionItems(provider.items, query),
-        command: ({ editor: ed, range, props }: { editor: Editor; range: Range; props: MentionItem }) => {
-          ed
-            .chain()
-            .focus()
-            .deleteRange(range)
-            .insertContent([
-              {
-                type: 'mention',
-                attrs: { id: props.id, label: props.label, trigger: provider.trigger },
-              },
-              { type: 'text', text: ' ' },
-            ])
-            .run()
-        },
-        render: () => ({
-          onStart:  (props) => emit(stateFrom(provider.trigger, props)),
-          onUpdate: (props) => emit(stateFrom(provider.trigger, props)),
-          // Keys handled at the document level by TiptapEditor — same posture
-          // as the slash menu.
-          onKeyDown: () => false,
-          onExit:    () => emit(null),
-        }),
-      } satisfies SuggestionOptions<MentionItem, MentionItem>),
-    )
-  },
-})
-
-function stateFrom(
-  trigger: string,
-  props: {
-    items:       MentionItem[]
-    command:     (item: MentionItem) => void
-    clientRect?: (() => DOMRect | null) | null
-    query:       string
-  },
-): MentionState {
-  return {
-    trigger,
-    items:      props.items,
-    command:    props.command,
-    clientRect: props.clientRect ?? (() => null),
-    query:      props.query,
-  }
-}
-
-function filterMentionItems(items: MentionItem[], query: string): MentionItem[] {
-  if (!query) return items
-  const needle = query.toLowerCase()
-  return items.filter((item) =>
-    `${item.label} ${item.id} ${item.group ?? ''}`.toLowerCase().includes(needle),
-  )
-}
-
-/**
- * Async path — POST `{ field, trigger, query }` to the field's
- * `mentionsUrl` and return the resolved items. Returns `[]` for any
- * failure (missing URL / network error / non-200 response / malformed
- * payload) so the menu degrades to "no matches" instead of throwing
- * inside Suggestion's items pipeline.
- *
- * Suggestion handles its own debouncing; we don't need a setTimeout
- * wrapper. In-flight races aren't tracked here either — Suggestion's
- * internal sequence handling owns "newer query supersedes older one".
- */
-async function fetchAsyncMentionItems(
-  url:     string | undefined,
-  field:   string | undefined,
-  trigger: string,
-  query:   string,
-): Promise<MentionItem[]> {
-  if (!url || !field) return []
-  try {
-    const res = await fetch(url, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        'Accept':       'application/json',
-      },
-      body: JSON.stringify({ field, trigger, query }),
-    })
-    if (!res.ok) return []
-    const json = await res.json() as { ok?: boolean; items?: unknown }
-    if (!json.ok || !Array.isArray(json.items)) return []
-    return json.items.filter((item): item is MentionItem =>
-      item != null
-      && typeof item === 'object'
-      && typeof (item as Record<string, unknown>)['id'] === 'string'
-      && typeof (item as Record<string, unknown>)['label'] === 'string',
-    )
-  } catch {
-    return []
-  }
-}

package/src/extensions/MergeTagExtension.ts

@@ -1,75 +0,0 @@
-import { Node, mergeAttributes } from '@tiptap/core'
-
-declare module '@tiptap/core' {
-  interface Commands<ReturnType> {
-    mergeTag: {
-      /** Insert a `mergeTag` atom node carrying the given identifier. */
-      insertMergeTag: (id: string) => ReturnType
-    }
-  }
-}
-
-/**
- * Inline atom that represents a `{{ tag }}` placeholder in the document.
- *
- * The editor renders the node as a small chip — `{{ id }}` inside a styled
- * `<span>` — so the author sees what gets substituted at read time. Storage
- * is JSON: `{ type: 'mergeTag', attrs: { id: 'name' } }`.
- *
- * Read-side rendering happens through `renderRichTextToHtml(content,
- * { mergeTags: { name: 'Sleman' } })` — pass a substitution map and the
- * placeholder is replaced with the value (HTML-escaped). Without a map,
- * the renderer emits `<span class="merge-tag" data-id="name">{{ name }}</span>`
- * so previews on the server stay informative.
- */
-export const MergeTagExtension = Node.create({
-  name: 'mergeTag',
-  group: 'inline',
-  inline: true,
-  atom: true,
-  selectable: true,
-
-  addAttributes() {
-    return {
-      id: {
-        default: null,
-        parseHTML: (el) => el.getAttribute('data-id'),
-        renderHTML: (attrs) => {
-          if (!attrs['id']) return {}
-          return { 'data-id': String(attrs['id']) }
-        },
-      },
-    }
-  },
-
-  parseHTML() {
-    return [{ tag: 'span[data-pilotiq-merge-tag]' }]
-  },
-
-  renderHTML({ node, HTMLAttributes }) {
-    const id = String(node.attrs['id'] ?? '')
-    return [
-      'span',
-      mergeAttributes(
-        {
-          'data-pilotiq-merge-tag': '',
-          class: 'pilotiq-merge-tag rounded bg-primary/10 px-1.5 py-0.5 text-xs font-medium text-primary align-baseline',
-        },
-        HTMLAttributes,
-      ),
-      `{{ ${id} }}`,
-    ]
-  },
-
-  addCommands() {
-    return {
-      insertMergeTag:
-        (id: string) =>
-        ({ commands }) =>
-          commands.insertContent({
-            type: this.name,
-            attrs: { id },
-          }),
-    }
-  },
-})