velt-comments-best-practices

Velt コメントのベストプラクティス

React および Next.js アプリケーションにおける Velt の共同コメント機能の包括的な実装ガイドです。13 のカテゴリにわたる 87 のルールを収録し、優先度に基づいて、自動コード生成と統合パターンをガイドします。

適用するタイミング

以下の場合に、これらのガイドラインを参照してください。

• React／Next.js アプリケーションに共同コメント機能を追加する場合
• Velt のコメントモード（Freestyle、Popover、Stream、Text、Page、Inline）を実装する場合
• リッチテキストエディター（TipTap、SlateJS、Lexical）とコメント機能を統合する場合
• PDF／docx ドキュメント向けに Apryse WebViewer とコメント機能を統合する場合
• メディアプレーヤー（Video、Lottie アニメーション）にコメント機能を追加する場合
• チャート（Highcharts、ChartJS、Nivo）にコメント機能を追加する場合
• 単独コンポーネントを使ってカスタムコメントインターフェースを構築する場合

優先度別ルールカテゴリ

優先度	カテゴリ	影響度	プレフィックス
1	コア設定	CRITICAL	core-
2	コメントモード	HIGH	mode-
3	単独コンポーネント	MEDIUM-HIGH	standalone-
4	コメントの表示領域	MEDIUM-HIGH	surface-
5	UI のカスタマイズ	MEDIUM	ui-
6	データモデル	MEDIUM	data-
7	デバッグとテスト	LOW-MEDIUM	debug-
8	モデレーションと権限	LOW	permissions-
9	添付ファイルとリアクション	MEDIUM	attach-
10	ワイヤーフレーム変数	MEDIUM	wireframe-variables-

クイックリファレンス

1. コア設定（CRITICAL）

• core-provider-setup - API キーを使って VeltProvider を初期化する
• core-authentication - コメント機能を使用する前にユーザーを認証する
• core-document-setup - コメントのドキュメントコンテキストを設定する

2. コメントモード（HIGH）

• mode-freestyle - ページ上の任意の場所にコメントをピン留めする
• mode-popover - Google Sheets 形式のセルコメント
• mode-stream - Google Docs 形式のサイドバーコメント一覧
• mode-text - テキストのハイライトに対するコメント
• mode-page - サイドバーを使ったページ単位のコメント
• mode-inline-comments - 従来形式のインラインスレッド
• mode-tiptap - TipTap エディターとの統合
• mode-slatejs - SlateJS エディターとの統合
• mode-lexical - Lexical エディターとの統合
• mode-canvas - キャンバス／描画へのコメント
• mode-lottie-player - Lottie アニメーションのフレームへのコメント
• mode-video-player-prebuilt - Velt の組み込みビデオプレーヤー
• mode-video-player-custom - カスタムビデオプレーヤーとの統合
• mode-chart-highcharts - Highcharts のデータポイントへのコメント
• mode-chart-chartjs - ChartJS のデータポイントへのコメント
• mode-chart-nivo - Nivo チャートのデータポイントへのコメント
• mode-chart-custom - カスタムチャートとの統合
• mode-apryse - @veltdev/apryse-velt-comments を使った Apryse WebViewer（PDF／docx）との統合 — ApryseVeltComments.configure(...).attach(instance)、addComment({ instance })、renderComments({ instance, commentAnnotations })、永続的な TextEditorConfig アンカー（text + occurrence + pageNumber）

3. 単独コンポーネント（MEDIUM-HIGH）

• standalone-comment-pin - コメントピンの位置を手動で設定する
• standalone-comment-thread - コメントスレッドを表示する
• standalone-comment-composer - プログラムからコメントを追加する

4. コメントの表示領域（MEDIUM-HIGH）

• surface-sidebar - コメントサイドバーコンポーネント
• surface-sidebar-setup - サイドバーの設定、表示モード（embed/floating/page/focused-thread/fullscreen）、filterConfig、groupConfig、sortOrder、V2 サイドバー、ナビゲーションイベント
• surface-sidebar-v2 - 27 個以上の組み合わせ可能なプリミティブ、統一されたフィルターモデル、スレッドにフォーカスしたビューを備えたプリミティブアーキテクチャの V2 サイドバー
• surface-sidebar-button - サイドバー切り替えボタン

5. UI のカスタマイズ（中）

• ui-comment-dialog - コメントダイアログをカスタマイズする
• ui-comment-bubble - コメントバブルをカスタマイズする
• ui-wireframes - ワイヤーフレームコンポーネントを使用する
• ui-autocomplete-primitives - VeltAutocomplete パネル全体を必要とせず、単独のオートコンプリートプリミティブコンポーネントを使用して、カスタムのオートコンプリート UI を構築する
• ui-agent-suggestion-primitives - カスタムの AI 提案の承認／却下 UI、解決バナー、ヘッダーメニュー、フッターナビゲーション向けの 21 個の VeltCommentDialogAgentSuggestion* プリミティブ
• ui-v2-primitives - ワイヤーフレーム構成でセクションを上書きする際、SDK のデフォルトの表示／非表示ロジックを回避するため、V2 プリミティブのサブコンポーネントに defaultCondition={false} を設定する

6. データモデル（中）

• data-context-metadata - カスタムメタデータを追加する
• data-comment-annotations - アノテーションを扱う
• data-filtering-grouping - コメントをフィルタリングおよびグループ化する
• data-activity-action-types - 生の文字列ではなく CommentActivityActionTypes 定数を使用して、型安全なコメントアクティビティのフィルタリングを行う
• data-trigger-activities - CommentData に triggerActivities を設定し、POST /v2/commentannotations/add を通じてアクティビティレコードを自動作成する
• data-comment-annotation-data-provider - プレースホルダーコールバックを使わずに、CommentAnnotationDataProvider で設定ベースの URL エンドポイントを使用する。additionalFields は Velt のストレージに保持したままフィールドをリゾルバーに複製し、fieldsToRemove は PII の削除のために Velt の DB からフィールドを取り除く
• data-agent-fields-query - CommentRequestQuery の agentFields を使用して、getCommentAnnotationCount() をエージェントタグ付きアノテーションに絞り込む。agentFields が設定されている場合、未読数は合計数と同じになる

7. デバッグとテスト（低～中）

• debug-common-issues - よくある問題と解決策
• debug-verification - 検証チェックリスト

8. モデレーションと権限（低）

• permissions-private-mode - enablePrivateMode/disablePrivateMode でコメントの表示範囲を全体的に制御し、updateVisibility でアノテーションごとの表示範囲を更新する
• permissions-comment-saved-event - commentSaved イベントを購読し、永続化後の副作用（Webhook、分析、外部同期）を確実に実行する
• permissions-visibility-option-dropdown - コメント入力欄で表示範囲のドロップダウンを有効にし、ユーザーが送信前に公開または非公開を選択できるようにする。また、visibilityOptionClicked イベントを購読する
• permissions-comment-save-triggered-event - commentSaveTriggered を使用して、保存ボタンのクリック時に、非同期のデータベース書き込みが完了する前に UI をすぐにフィードバックする（スピナー、無効状態など）
• permissions-visibility-routing - レガシーの iam.accessMode と新しい visibilityConfig.type（restricted、organizationPrivate）を横断してプライバシーを統一的に確認するために、isAnnotationPrivate() ユーティリティを使用する
• permissions-submit-in-flight - カスタムアクションのサイドバーホストでの重複送信を防ぐため、CommentDialogActionService.isSubmitInFlight(dialogInstanceId) を使用する
• permissions-comment-interaction-events - 新しいコードでは、現在形の元のイベントよりも過去形のイベントエイリアス commentToolClicked と sidebarButtonClicked を優先する
• permissions-anonymous-user-data-provider - setAnonymousUserDataProvider() を登録し、コメント保存時にタグ付けされた連絡先メールアドレスを userIds に解決する

9. 添付ファイルとリアクション（中）

• attach-download-control - 添付ファイルのダウンロード動作を制御し、クリックをインターセプトする

10. 設定（中級）

• config-mentions-contacts - @メンション、連絡先、ユーザーの割り当て、オートコンプリート
• config-status-priority - カスタムのステータスと優先度レベル、解決／更新のワークフロー
• config-reactions - 絵文字リアクション — 有効化、カスタマイズ、追加／削除／切り替え
• config-attachments - ファイル添付 — 有効化、アップロード、削除、許可するファイル形式
• config-text-formatting - 作成欄のリッチテキスト書式設定オプション
• config-navigation - ナビゲーション、ディープリンク、コメントへのスクロール、共有可能なリンク
• config-dom-controls - コメントを特定の DOM 要素にのみ配置できるように制限
• config-sidebar-management - プログラムによるサイドバーのデータ、フィルタリング、設定
• config-sidebar-access-modes - setCommentSidebarFilters() で accessModes フィルターを使用した、プライバシーに基づくサイドバーのフィルタリング（公開／非公開）
• config-ui-behavior - UI/UX の切り替えメソッド — 表示、インタラクション、動作（20 以上のメソッド）
• config-moderation - モデレーションのワークフロー — 承認、受諾、却下、読み取り専用
• config-component-props - VeltComments、VeltCommentDialog、VeltCommentsSidebar、VeltInlineCommentsSection 用の型付き props インターフェース — 編集モードのプレースホルダーの上書き、assignToType、フォーカス動作

11. ワイヤーフレーム変数（中級）

• wireframe-variables-comment-bubble - {annotation.*}、{selectedAnnotationsMap[...]}、globalConfigSignal.featureState.* を使用して、Comment Bubble と Comment Pin のワイヤーフレームスロットをバインドします
• wireframe-variables-comment-dialog - 約 110 スロットの Comment Dialog ワイヤーフレーム群をバインドします（App / Data / UI / Feature State の名前空間、comment / commentIndex のループスコープ、ルートレベルのプレースホルダーと未読マップのパス、v1 エイリアス）
• wireframe-variables-comment-tool - フラット設定の {addCommentMode} / {commentToolEnabled} エイリアスと、正規の globalConfig.featureState.* / componentConfig.* パスを使用して Comment Tool ワイヤーフレームをバインドします
• wireframe-variables-inline-comments-section - Inline Comments Section ワイヤーフレームをバインドします（{annotations}、{skeletonLoading}、{filterState.*} / {sortState.*}、行ごとのループスコープ filter / sortOption / isActive / isAscending、featureState.* の競合パス、リストと作成欄内のネストされた Comment Dialog プリミティブ）
• wireframe-variables-multithread-comments - Multithread Comments ワイヤーフレームをバインドします（{nonDraftCommentsCount}、{minimalFilter}、空状態とフィルターリセットの条件、isSelected のループスコープを持つ最小限のフィルター／ソートと一括操作のドロップダウン、data.user / uiState.shadowDom の競合パス）
• wireframe-variables-autocomplete - オートコンプリートの @メンションピッカーのワイヤーフレームをバインドします（flattenedItems / customGroupsEnabled / newUserContactError へのフラット設定 componentConfig.<path> アクセス、option / chip のループスコープ、option / group-option / chip / empty-state サブコンポーネント、チップのツールチップの子要素）
• wireframe-variables-text-comment - Text Comment ツールバーのワイヤーフレームをバインドします（{selectedWordsCount} / {selectedCharactersCount} / {position.*}、isUserAllowed / enableTextComments / rewriterEnabled の機能フラグ、競合する名前の明示的なパス 5 つ）
• wireframe-variables-comment-sidebar-button - フラット設定を使用して Comment Sidebar Button ワイヤーフレームをバインドします（globalConfig.featureState.sidebarVisible、componentConfig.data.unreadCount / annotations.length、componentConfig.uiState.commentCountType / floatingMode）
• wireframe-variables-comment-sidebar - 約 80 タグの Comment Sidebar ワイヤーフレーム群をバインドします — ハイブリッドアクセス（マッピングされた focusedAnnotation / appliedFiltersCount / unreadCommentAnnotationCount と、フラットな componentConfig.skeletonLoading / noCommentsFound* / virtualScrollData / filterConfig.* を併用）、ループスコープ（focusedAnnotation、filter、item、group、tag）、リスト／フォーカス中のスレッド／ページモードの作成欄におけるネストされた Comment Dialog のスコープ

エージェントのコメント — 重要な API リファレンス

AI エージェントによるコメントの作成、またはエージェントの提案の承認・却下が関わるタスクでは、次のパターンをそのまま使用してください。

エージェントの注釈を作成する — POST /v2/commentannotations/add:

data: {
  organizationId: "...",
  documentId: "...",
  commentAnnotations: [{
    type: "suggestion",                    // REQUIRED for Accept/Reject buttons
    commentData: [{
      commentText: "Finding text",
      from: { userId: "agent-id" },
      agent: {                             // On commentData[0], NOT annotation root
        agentSource: "external",           // "external" for non-Velt agents
        agentName: "My Agent",             // REQUIRED for external agents
        agentId: "my-agent",
        executionId: "run_123",
        reason: {                          // REQUIRED — finding details
          title: "Issue title",
          description: "Details",
          severity: "high",
        },
      },
    }],
  }],
}

エージェントの注釈を読み取る — POST /v2/commentannotations/get:

• 特定の実行には executionId フィルターを使用します
• 保留中（未承認）の提案のみを取得するには agentSuggestions: true を使用します

クライアントで承認・却下を処理する — commentSaved ではなく、専用のイベントを使用します。

import { useCommentEventCallback } from '@veltdev/react';
const accepted = useCommentEventCallback('suggestionAccepted');
const rejected = useCommentEventCallback('suggestionRejected');

使用方法

詳細な説明とコード例については、各ルールファイルをお読みください。

rules/shared/core/core-provider-setup.md
rules/shared/mode/mode-popover.md

各ルールファイルには、次の内容が含まれています。

• 重要である理由の簡単な説明
• 説明付きの誤ったコード例
• 説明付きの正しいコード例
• 公式ドキュメントへの参照

コンパイル済みドキュメント

• AGENTS.md — ファイルパス付きの全ルールの簡潔なインデックス（まずはこちらをご覧ください）
• AGENTS.full.md — すべてのルールをインラインで詳しく展開したガイド