@pilotiq/tiptap 0.1.0

package/src/extensions/SlashCommandExtension.test.ts

@@ -0,0 +1,147 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import { buildSlashItems } from './SlashCommandExtension.js'
+
+describe('SlashCommandExtension built-ins', () => {
+  it('always exposes the Table entry', () => {
+    const items = buildSlashItems([], [], '', {
+      hasUpload: false,
+      onInsertImage: () => {},
+    })
+    const table = items.find((i) => i.key === 'table')
+    assert.ok(table, 'expected a "table" slash entry')
+    assert.equal(table!.label, 'Table')
+    assert.equal(table!.group, 'Insert')
+  })
+
+  it('omits the Image entry when no upload adapter is wired', () => {
+    const items = buildSlashItems([], [], '', {
+      hasUpload: false,
+      onInsertImage: () => {},
+    })
+    const image = items.find((i) => i.key === 'image')
+    assert.equal(image, undefined)
+  })
+
+  it('surfaces the Image entry when hasUpload is true', () => {
+    const items = buildSlashItems([], [], '', {
+      hasUpload: true,
+      onInsertImage: () => {},
+    })
+    const image = items.find((i) => i.key === 'image')
+    assert.ok(image, 'expected an "image" slash entry when hasUpload')
+    assert.equal(image!.label, 'Image')
+    assert.equal(image!.group, 'Insert')
+  })
+
+  it('Image command fires the onInsertImage callback', () => {
+    let calls = 0
+    const items = buildSlashItems([], [], '', {
+      hasUpload: true,
+      onInsertImage: () => { calls += 1 },
+    })
+    const image = items.find((i) => i.key === 'image')
+    // Stand-in editor — the slash command chains through `.deleteRange(...)`
+    // before firing the callback. We don't assert on the chain output;
+    // confirming `calls === 1` proves the wire is connected.
+    const stubChain = {
+      focus:        () => stubChain,
+      deleteRange:  () => stubChain,
+      run:          () => true,
+    }
+    image!.command({
+      editor: { chain: () => stubChain } as never,
+      range:  { from: 0, to: 0 } as never,
+    })
+    assert.equal(calls, 1)
+  })
+
+  it('respects the search query against label / searchKey / group', () => {
+    const items = buildSlashItems([], [], 'tab', {
+      hasUpload: true,
+      onInsertImage: () => {},
+    })
+    assert.ok(items.some((i) => i.key === 'table'),
+      'expected `table` to match the "tab" query via label/searchKey')
+    assert.equal(items.some((i) => i.key === 'paragraph'), false,
+      'expected unrelated entries to drop out of the filtered list')
+  })
+
+  it('exposes lead + small entries under the Style group', () => {
+    const items = buildSlashItems([], [], '', {
+      hasUpload: false,
+      onInsertImage: () => {},
+    })
+    const lead  = items.find((i) => i.key === 'lead')
+    const small = items.find((i) => i.key === 'small')
+    assert.ok(lead,  'expected a "lead" slash entry')
+    assert.ok(small, 'expected a "small" slash entry')
+    assert.equal(lead!.group,  'Style')
+    assert.equal(small!.group, 'Style')
+  })
+
+  it('always exposes the Details entry under the Insert group', () => {
+    const items = buildSlashItems([], [], '', {
+      hasUpload: false,
+      onInsertImage: () => {},
+    })
+    const details = items.find((i) => i.key === 'details')
+    assert.ok(details, 'expected a "details" slash entry')
+    assert.equal(details!.label, 'Collapsible block')
+    assert.equal(details!.group, 'Insert')
+  })
+
+  it('Details search matches "collapsible" / "summary" / "toggle"', () => {
+    for (const q of ['collapsible', 'summary', 'toggle']) {
+      const items = buildSlashItems([], [], q, {
+        hasUpload: false,
+        onInsertImage: () => {},
+      })
+      assert.ok(
+        items.some((i) => i.key === 'details'),
+        `expected the Details entry to match search query "${q}"`,
+      )
+    }
+  })
+
+  it('exposes Two-column and Three-column grid entries under Insert', () => {
+    const items = buildSlashItems([], [], '', {
+      hasUpload: false,
+      onInsertImage: () => {},
+    })
+    const two   = items.find((i) => i.key === 'grid-2')
+    const three = items.find((i) => i.key === 'grid-3')
+    assert.ok(two,   'expected a "grid-2" slash entry')
+    assert.ok(three, 'expected a "grid-3" slash entry')
+    assert.equal(two!.label,   'Two-column grid')
+    assert.equal(two!.group,   'Insert')
+    assert.equal(three!.label, 'Three-column grid')
+    assert.equal(three!.group, 'Insert')
+  })
+
+  it('Grid search matches "columns" / "split" / "layout"', () => {
+    for (const q of ['columns', 'split', 'layout']) {
+      const items = buildSlashItems([], [], q, {
+        hasUpload: false,
+        onInsertImage: () => {},
+      })
+      assert.ok(
+        items.some((i) => i.key === 'grid-2'),
+        `expected the Two-column grid entry to match search query "${q}"`,
+      )
+    }
+  })
+
+  it('Three-column grid distinguishes by "three" / "3"', () => {
+    for (const q of ['three', '3']) {
+      const items = buildSlashItems([], [], q, {
+        hasUpload: false,
+        onInsertImage: () => {},
+      })
+      assert.ok(
+        items.some((i) => i.key === 'grid-3'),
+        `expected the Three-column grid entry to match search query "${q}"`,
+      )
+    }
+  })
+})

package/src/extensions/SlashCommandExtension.ts

@@ -0,0 +1,332 @@
+import { Extension, type Editor, type Range } from '@tiptap/core'
+import Suggestion, { type SuggestionOptions } from '@tiptap/suggestion'
+import { PluginKey } from '@tiptap/pm/state'
+
+const SLASH_PLUGIN_KEY = new PluginKey('pilotiqSlashSuggestion')
+import type { BlockMeta } from '../Block.js'
+
+export interface SlashItem {
+  /** Stable id used to dedupe + as React key. */
+  key:        string
+  label:      string
+  icon:       string | undefined
+  group?:     string
+  /** Free-text searched against label + group. */
+  searchKey:  string
+  /** Run when the user picks this item. `range` is the slash + query slice. */
+  command:    (args: { editor: Editor; range: Range }) => void
+}
+
+/**
+ * State the React side of the editor needs to render the slash menu. Set to
+ * `null` when the menu should be unmounted.
+ */
+export interface SlashState {
+  items:      SlashItem[]
+  /** Pick item — Suggestion will replace the slash range and run the command. */
+  command:    (item: SlashItem) => void
+  /**
+   * Cursor / range coords in viewport space. Re-call this every layout tick
+   * (the popover positioner does) so scroll/resize tracking comes for free.
+   */
+  clientRect: () => DOMRect | null
+  query:      string
+}
+
+export interface SlashCommandOptions {
+  /** Custom blocks contributed by RichTextField.blocks([...]). */
+  blocks: BlockMeta[]
+  /** Merge-tag identifiers contributed by RichTextField.mergeTags([...]). */
+  mergeTags: string[]
+  /**
+   * Called whenever the menu should mount, update, or unmount. TiptapEditor
+   * holds the React state and passes a setter here.
+   */
+  onStateChange: (state: SlashState | null) => void
+  /**
+   * `true` when the panel has wired an `UploadAdapter` (mirrors the
+   * toolbar's `attachFiles` gating). Drives whether the "Image" entry
+   * appears in the menu — it would have nowhere to upload otherwise.
+   */
+  hasUpload: boolean
+  /**
+   * Called when the user picks the "Image" slash entry. The slash range
+   * is already deleted before this fires; the callback just opens the
+   * shared attach-files dialog (whose UI lives in `Toolbar`).
+   */
+  onInsertImage: () => void
+}
+
+/**
+ * `/`-triggered slash menu. The plugin owns the suggestion lifecycle (range
+ * detection + command invocation); rendering is React-side via a Base UI
+ * Popover anchored to a virtual element. Keyboard events are NOT forwarded
+ * through the Suggestion plugin — TiptapEditor installs a document-level
+ * capture-phase keydown listener while the menu is open, because Base UI's
+ * focus manager can briefly steal focus from the editor when the popup mounts
+ * and the suggestion plugin's `handleKeyDown` only fires when the editor has
+ * focus.
+ */
+export const SlashCommandExtension = Extension.create<SlashCommandOptions>({
+  name: 'slashCommand',
+
+  addOptions() {
+    return {
+      blocks:        [],
+      mergeTags:     [],
+      onStateChange: () => {},
+      hasUpload:     false,
+      onInsertImage: () => {},
+    }
+  },
+
+  addProseMirrorPlugins() {
+    const blocks        = this.options.blocks
+    const mergeTags     = this.options.mergeTags
+    const emit          = this.options.onStateChange
+    const hasUpload     = this.options.hasUpload
+    const onInsertImage = this.options.onInsertImage
+
+    return [
+      Suggestion({
+        pluginKey: SLASH_PLUGIN_KEY,
+        editor: this.editor,
+        char: '/',
+        startOfLine: false,
+        allowSpaces: false,
+        items: ({ query }: { query: string }) => buildSlashItems(blocks, mergeTags, query, { hasUpload, onInsertImage }),
+        command: ({ editor, range, props }: { editor: Editor; range: Range; props: SlashItem }) => {
+          props.command({ editor, range })
+        },
+        render: () => ({
+          onStart:   (props) => emit(stateFrom(props)),
+          onUpdate:  (props) => emit(stateFrom(props)),
+          // Keys are handled at the document level by TiptapEditor; nothing
+          // to do here. Returning false lets PM's keymap handle anything we
+          // don't intercept (typing more of the slash query, etc.).
+          onKeyDown: () => false,
+          onExit:    () => emit(null),
+        }),
+      } satisfies SuggestionOptions<SlashItem, SlashItem>),
+    ]
+  },
+})
+
+function stateFrom(props: {
+  items:      SlashItem[]
+  command:    (item: SlashItem) => void
+  clientRect?: (() => DOMRect | null) | null
+  query:      string
+}): SlashState {
+  return {
+    items:      props.items,
+    command:    props.command,
+    clientRect: props.clientRect ?? (() => null),
+    query:      props.query,
+  }
+}
+
+export interface SlashInsertEntries {
+  hasUpload:     boolean
+  onInsertImage: () => void
+}
+
+// Built-in items mirror the standard rich-text-editor slash menu. Custom
+// blocks append, then merge-tag placeholders.
+//
+// Exported so tests can pin down the menu contents without spinning up an
+// editor instance — the function is pure and deterministic given its
+// inputs.
+export function buildSlashItems(
+  blocks:    BlockMeta[],
+  mergeTags: string[],
+  query:     string,
+  insert:    SlashInsertEntries,
+): SlashItem[] {
+  const builtins: SlashItem[] = [
+    {
+      key: 'paragraph', label: 'Text', icon: '¶', group: 'Basic',
+      searchKey: 'text paragraph p',
+      command: ({ editor, range }) => editor.chain().focus().deleteRange(range).setNode('paragraph').run(),
+    },
+    ...[1, 2, 3, 4, 5, 6].map((level) => ({
+      key:       `heading-${level}`,
+      label:     `Heading ${level}`,
+      icon:      `H${level}`,
+      group:     'Headings',
+      searchKey: `heading ${level} h${level}${level === 1 ? ' title' : level === 2 ? ' subtitle' : ''}`,
+      command: ({ editor, range }: { editor: Editor; range: Range }) =>
+        editor.chain().focus().deleteRange(range).setNode('heading', { level }).run(),
+    })),
+    {
+      key: 'bullet-list', label: 'Bullet list', icon: '•', group: 'Lists',
+      searchKey: 'bullet list ul unordered',
+      command: ({ editor, range }) => editor.chain().focus().deleteRange(range).toggleBulletList().run(),
+    },
+    {
+      key: 'ordered-list', label: 'Numbered list', icon: '1.', group: 'Lists',
+      searchKey: 'numbered ordered list ol',
+      command: ({ editor, range }) => editor.chain().focus().deleteRange(range).toggleOrderedList().run(),
+    },
+    {
+      key: 'quote', label: 'Quote', icon: '❝', group: 'Basic',
+      searchKey: 'quote blockquote',
+      command: ({ editor, range }) => editor.chain().focus().deleteRange(range).toggleBlockquote().run(),
+    },
+    {
+      key: 'code', label: 'Code block', icon: '</>', group: 'Basic',
+      searchKey: 'code block pre',
+      command: ({ editor, range }) => editor.chain().focus().deleteRange(range).toggleCodeBlock().run(),
+    },
+    {
+      key: 'hr', label: 'Divider', icon: '—', group: 'Basic',
+      searchKey: 'divider hr horizontal rule',
+      command: ({ editor, range }) => editor.chain().focus().deleteRange(range).setHorizontalRule().run(),
+    },
+    // 3×3 table with a header row — same shape as the toolbar `table` button.
+    // No upload gate; tables are pure schema, available everywhere.
+    {
+      key: 'table', label: 'Table', icon: '⊞', group: 'Insert',
+      searchKey: 'table grid rows columns',
+      command: ({ editor, range }) =>
+        editor.chain().focus().deleteRange(range)
+          .insertTable({ rows: 3, cols: 3, withHeaderRow: true }).run(),
+    },
+    // Collapsible `<details>` block. `setDetails` wraps the cursor's
+    // paragraph in a details node with an empty summary; the user starts
+    // typing the summary and presses Enter to drop into the body. No
+    // upload gate — pure schema, available everywhere.
+    {
+      key: 'details', label: 'Collapsible block', icon: '▸', group: 'Insert',
+      searchKey: 'details collapsible disclosure summary toggle expand',
+      command: ({ editor, range }) =>
+        editor.chain().focus().deleteRange(range).setDetails().run(),
+    },
+    // Multi-column grid layout. Two distinct entries (2-col + 3-col) so
+    // the user picks the column count from the slash menu directly,
+    // matching how the toolbar's `grid` button defaults to 2 cols.
+    {
+      key: 'grid-2', label: 'Two-column grid', icon: '⊞', group: 'Insert',
+      searchKey: 'grid columns layout 2 two split side',
+      command: ({ editor, range }) =>
+        editor.chain().focus().deleteRange(range).setGrid({ columns: 2 }).run(),
+    },
+    {
+      key: 'grid-3', label: 'Three-column grid', icon: '⊞', group: 'Insert',
+      searchKey: 'grid columns layout 3 three split',
+      command: ({ editor, range }) =>
+        editor.chain().focus().deleteRange(range).setGrid({ columns: 3 }).run(),
+    },
+    // Image entry shares the toolbar's attach-files dialog; only surfaced
+    // when the panel has wired an `UploadAdapter`. Without one, the dialog
+    // would post to a missing endpoint — the slash item degrades the same
+    // way the toolbar's `attachFiles` button does (server-stripped at meta
+    // build time when no adapter is set).
+    ...(insert.hasUpload ? [{
+      key: 'image', label: 'Image', icon: '🖼', group: 'Insert',
+      searchKey: 'image upload media file attach',
+      command: ({ editor, range }: { editor: Editor; range: Range }) => {
+        // Drop the slash range first so the user doesn't return to a
+        // dangling `/image` after closing the dialog. Inserting the
+        // actual image happens inside the dialog's upload handler.
+        editor.chain().focus().deleteRange(range).run()
+        insert.onInsertImage()
+      },
+    }] satisfies SlashItem[] : []),
+    {
+      key: 'align-left', label: 'Align left', icon: '⇤', group: 'Align',
+      searchKey: 'align left start',
+      command: ({ editor, range }) => editor.chain().focus().deleteRange(range).setTextAlign('left').run(),
+    },
+    {
+      key: 'align-center', label: 'Align center', icon: '⇔', group: 'Align',
+      searchKey: 'align center middle',
+      command: ({ editor, range }) => editor.chain().focus().deleteRange(range).setTextAlign('center').run(),
+    },
+    {
+      key: 'align-right', label: 'Align right', icon: '⇥', group: 'Align',
+      searchKey: 'align right end',
+      command: ({ editor, range }) => editor.chain().focus().deleteRange(range).setTextAlign('right').run(),
+    },
+    {
+      key: 'clear-format', label: 'Clear formatting', icon: '⌫', group: 'Basic',
+      searchKey: 'clear formatting reset',
+      command: ({ editor, range }) =>
+        editor.chain().focus().deleteRange(range).clearNodes().unsetAllMarks().run(),
+    },
+    // Inline-mark size variants. Slash-menu form leaves the slash range in
+    // place rather than swallowing it, so the user runs the command on the
+    // word they were just typing — the alternative ("/lead" deletes the
+    // range, then user types more) requires re-positioning the cursor and
+    // breaks the "type-toggle-keep-typing" rhythm authors use most.
+    {
+      key: 'lead', label: 'Lead', icon: 'P+', group: 'Style',
+      searchKey: 'lead lede intro paragraph emphasis',
+      command: ({ editor, range }) =>
+        editor.chain().focus().deleteRange(range).toggleMark('lead').run(),
+    },
+    {
+      key: 'small', label: 'Small', icon: 'P-', group: 'Style',
+      searchKey: 'small fine print footnote caption',
+      command: ({ editor, range }) =>
+        editor.chain().focus().deleteRange(range).toggleMark('small').run(),
+    },
+  ]
+
+  const customs: SlashItem[] = blocks.map((b) => ({
+    key:       `block:${b.name}`,
+    label:     b.label,
+    icon:      b.icon,
+    group:     'Blocks',
+    searchKey: `${b.label} ${b.name} block`,
+    command: ({ editor, range }) => {
+      // Use insertContent directly with explicit attrs rather than chaining
+      // through our custom `insertBlock` command — chained custom commands
+      // sometimes drop the `attrs` payload depending on Tiptap version.
+      editor
+        .chain()
+        .focus()
+        .deleteRange(range)
+        .insertContent({
+          type: 'pilotiqBlock',
+          attrs: {
+            blockType: b.name,
+            blockData: defaultsFromSchema(b),
+          },
+        })
+        .run()
+    },
+  }))
+
+  const merges: SlashItem[] = mergeTags.map((id) => ({
+    key:       `merge-tag:${id}`,
+    label:     `{{ ${id} }}`,
+    icon:      '{{}}',
+    group:     'Merge tags',
+    searchKey: `merge tag placeholder ${id}`,
+    command: ({ editor, range }) => {
+      editor
+        .chain()
+        .focus()
+        .deleteRange(range)
+        .insertContent({ type: 'mergeTag', attrs: { id } })
+        .run()
+    },
+  }))
+
+  const all = [...builtins, ...customs, ...merges]
+  if (!query) return all
+
+  const needle = query.toLowerCase()
+  return all.filter((item) =>
+    `${item.label} ${item.searchKey} ${item.group ?? ''}`.toLowerCase().includes(needle),
+  )
+}
+
+function defaultsFromSchema(block: BlockMeta): Record<string, unknown> {
+  const out: Record<string, unknown> = {}
+  for (const f of block.schema) {
+    out[f.name] = ''
+  }
+  return out
+}

package/src/extensions/TextSizeMarks.ts

@@ -0,0 +1,73 @@
+import { Mark, mergeAttributes } from '@tiptap/core'
+
+declare module '@tiptap/core' {
+  interface Commands<ReturnType> {
+    lead: {
+      /** Toggle the `lead` mark on the current selection. */
+      toggleLead: () => ReturnType
+    }
+    small: {
+      /** Toggle the `small` mark on the current selection. */
+      toggleSmall: () => ReturnType
+    }
+  }
+}
+
+/**
+ * Two inline marks for paragraph-style size variants beyond the standard
+ * heading levels:
+ *
+ *   - `lead`  — opening / lede paragraph styling. Renders as
+ *               `<span class="lead">…</span>` so authors keep paragraph
+ *               semantics; styling is owned by the consumer's CSS (the
+ *               adapter doesn't ship a `.lead` rule — every site already
+ *               has one).
+ *   - `small` — semantic `<small>` mark. Mirrors the HTML element so
+ *               read-side renderers don't need a special class to style
+ *               fine print.
+ *
+ * Both marks live in the standard inline group so they compose with bold,
+ * italic, color, etc. without exclusivity rules. Excluding each other isn't
+ * useful — a `<small lead>` selection would be inert visually anyway.
+ */
+export const LeadMarkExtension = Mark.create({
+  name: 'lead',
+
+  parseHTML() {
+    return [{ tag: 'span.lead' }]
+  },
+
+  renderHTML({ HTMLAttributes }) {
+    return ['span', mergeAttributes({ class: 'lead' }, HTMLAttributes), 0]
+  },
+
+  addCommands() {
+    return {
+      toggleLead:
+        () =>
+        ({ commands }) =>
+          commands.toggleMark(this.name),
+    }
+  },
+})
+
+export const SmallMarkExtension = Mark.create({
+  name: 'small',
+
+  parseHTML() {
+    return [{ tag: 'small' }]
+  },
+
+  renderHTML({ HTMLAttributes }) {
+    return ['small', mergeAttributes(HTMLAttributes), 0]
+  },
+
+  addCommands() {
+    return {
+      toggleSmall:
+        () =>
+        ({ commands }) =>
+          commands.toggleMark(this.name),
+    }
+  },
+})

package/src/index.ts

@@ -0,0 +1,28 @@
+export {
+  RichTextField,
+  DEFAULT_TOOLBAR_GROUPS,
+  DEFAULT_TEXT_COLORS,
+  DEFAULT_HIGHLIGHT_COLORS,
+  type ColorSwatch,
+  type RichTextAttachmentVisibility,
+  type RichTextFieldMeta,
+  type RichTextStorage,
+  type ToolbarButtonId,
+  type ToolbarGroups,
+} from './RichTextField.js'
+export { Block, type BlockMeta } from './Block.js'
+export {
+  MentionProvider,
+  type MentionItem,
+  type MentionProviderMeta,
+} from './MentionProvider.js'
+export { registerTiptap } from './register.js'
+export { tiptap } from './plugin.js'
+export { TiptapEditor } from './react/TiptapEditor.js'
+export {
+  renderRichTextToHtml,
+  isRichTextValue,
+  type RenderRichTextOptions,
+  type TiptapNode,
+  type TiptapMark,
+} from './render.js'

package/src/plugin.test.ts

@@ -0,0 +1,19 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import { getFieldRenderer } from '@pilotiq/pilotiq/react'
+import { Pilotiq } from '@pilotiq/pilotiq'
+import { tiptap } from './plugin.js'
+
+describe('tiptap() plugin', () => {
+  it('exposes a Pilotiq plugin shape', () => {
+    const plugin = tiptap()
+    assert.equal(plugin.name, '@pilotiq/tiptap')
+    assert.equal(typeof plugin.register, 'function')
+  })
+
+  it('plugins([tiptap()]) wires the richtext field renderer', () => {
+    Pilotiq.make('test').plugins([tiptap()])
+    const renderer = getFieldRenderer('richtext')
+    assert.equal(typeof renderer, 'function')
+  })
+})

package/src/plugin.ts

@@ -0,0 +1,26 @@
+import type { PilotiqPlugin } from '@pilotiq/pilotiq'
+import { registerTiptap } from './register.js'
+
+/**
+ * Pilotiq plugin that registers the Tiptap rich-text renderer.
+ *
+ * Use with `Pilotiq.make(...).plugins([tiptap()])` instead of calling
+ * `registerTiptap()` directly from your app's client entry — the plugin
+ * runs through the panel module so it's wired in one place.
+ *
+ * @example
+ * ```ts
+ * import { Pilotiq } from '@pilotiq/pilotiq'
+ * import { tiptap } from '@pilotiq/tiptap'
+ *
+ * Pilotiq.make('Admin').plugins([tiptap()])
+ * ```
+ */
+export function tiptap(): PilotiqPlugin {
+  return {
+    name: '@pilotiq/tiptap',
+    register() {
+      registerTiptap()
+    },
+  }
+}