@pilotiq/tiptap 0.1.0

package/src/extensions/DragHandleExtension.ts

@@ -0,0 +1,184 @@
+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

@@ -0,0 +1,31 @@
+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

@@ -0,0 +1,138 @@
+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

@@ -0,0 +1,248 @@
+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

@@ -0,0 +1,75 @@
+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 },
+          }),
+    }
+  },
+})