tiptap-editor

Tiptap エディター API の使用パターン

概要

このスキルでは、vmark の開発における Tiptap API の適切な使用パターンについて説明します。Tiptap の高レベル API と ProseMirror への直接アクセスを使い分ける際に役立ちます。

Tiptap API を使用する場合

次の操作では、常に Tiptap API を優先してください。

• 書式コマンド（太字、斜体、下線など）
• ブロックタイプの変更（見出し、段落、コードブロック）
• リスト操作（箇条書き、番号付き、切り替え、インデント／インデント解除）
• Tiptap のテーブル拡張機能を使ったテーブル操作
• コンテンツの挿入と置換
• エディターの状態の確認（isActive、getAttributes）

使用する Tiptap のパターン

// Direct commands
editor.commands.toggleBold()
editor.commands.setHeading({ level: 2 })
editor.commands.setContent(doc, { emitUpdate: false })

// Chained commands (for multiple operations)
editor.chain().focus().setHeading({ level: 2 }).run()
editor.chain().focus().toggleMark("underline").run()

// State queries
editor.isActive("blockquote")
editor.isActive("heading", { level: 2 })
editor.getAttributes("link")

ProseMirror を直接使用するのが適切な場合

次の操作では ProseMirror を直接使用してください。

• Markdown 変換レイヤー（proseMirrorToMdast.ts、mdastToProseMirror.ts）
• 複数カーソル／選択範囲のサブクラス化（MultiSelection.ts）
• カスタムノードビュー
• 低レベルのトランザクション操作
• スキーマレベルの操作

vmark で確認されている問題

1. cursorHandlers.ts のブロック境界に関する問題

src/hooks/mcpBridge/cursorHandlers.ts では doc.textContent を使用していますが、これによってドキュメントが平坦化され、ブロック境界が失われます。正しくは $pos ヘルパーを使用します。

// WRONG - loses block structure
const text = doc.textContent;

// RIGHT - respects block boundaries
const $pos = doc.resolve(from);
const currentNode = $pos.parent;
const blockStart = $pos.before($pos.depth);
const blockEnd = $pos.after($pos.depth);

2. WYSIWYG 編集後のカーソル同期のずれ

sourceLine 属性は初回の解析時にのみ設定されます。ブロックを追加または削除する WYSIWYG 編集を行うと、行番号がソースと一致しなくなります。これは既知の制限事項です。

3. HtmlNodeView.ts のストアに関する問題

src/plugins/markdownArtifacts/HtmlNodeView.ts では、カーソル情報が誤ったストアに書き込まれます。

参考資料

• references/patterns.md - API の詳細な使用パターンと $pos の使い方
• references/examples.md - vmark のコードベースから抜粋した実際のコード例

ワークフロー

1. 操作の種類（書式、ブロック、選択範囲、走査）を特定します
2. Tiptap に組み込みコマンドがあるか確認します
3. 単一の操作には editor.commands.xxx() を使用します
4. フォーカスが必要な場合や操作を連結する場合は editor.chain().focus().xxx().run() を使用します
5. ノードの走査には doc.resolve(pos) を使用して $pos ヘルパーを取得します
6. 状態の確認には editor.isActive() または editor.getAttributes() を使用します