visx

visx

Airbnb visx（@visx/*）に関わる作業では、このスキルを使用してください。対象には、低レベルの React 可視化プリミティブ、@visx/xychart、インタラクションパッケージ、用途特化型レイアウト、v3 から v4 への移行が含まれます。

公開済みの安定版系列は 4.0.0（React 18/19）として扱ってください。パッケージルートからのインポート、インストール済みタグに対応するギャラリーのサンドボックス、古い深い階層からのインポート例よりも GitHub／visx.airbnb.tech を優先してください。4.1 のパッケージ（@visx/theme、@visx/a11y、@visx/chart、@visx/kernel、レジストリ）は、npm に公開されるまではインストール不可として扱ってください。

ワークフロー

1. コードを変更する前に、ローカル環境の状況を確認してください。
   • すべての @visx/* のバージョンが同じメジャーバージョンにそろっていること（^4.0.0 を推奨）。v3 と v4 を混在させないでください。
   • React の peer dependency が ^18 || ^19 であること（TypeScript を使用する場合は、対応する @types/react／@types/react-dom も確認してください）。
   • タスクが XYChart、プリミティブの組み合わせ、用途特化型レイアウト（geo/hierarchy/network/stats/…）のどれに該当するか。
   • アニメーション関連の peer dependency は、@visx/xychart または @visx/react-spring から Animated* をインポートする場合に限り、@react-spring/web を使用してください。
2. source-map.md を参照し、パッケージの根拠情報とドキュメントの URL を更新してください。
3. インストール戦略、メンタルモデル、スケール、シェイプ、曲線、グリフ、マーカー、テキスト、defs（クリップ／パターン／グラデーション）、@visx/vendor については、setup-core.md を参照してください。
4. 軸、グリッド、凡例、注釈、しきい値バンド、テーマ設定とアクセシビリティ（4.0 XYChart および 4.1 プレビュー）については、guides-decoration.md を参照してください。
5. ParentSize、境界、localPoint、ドラッグ、ブラシ、ズーム、ツールチップ／ポータルについては、interaction-layout.md を参照してください。
6. stats、heatmap、hierarchy、network、sankey、chord、geo、voronoi/delaunay、wordcloud、kernel の補足情報については、specialized-viz.md を参照してください。
7. XYChart の系列／プロバイダー／テーマ、react-spring、mock-data、@visx/visx のアンブレラパッケージについては、xychart-high-level.md を参照してください。
8. v3 から v4 への移行、判断ガイド、本番環境／SSR／アクセシビリティ／パフォーマンス、AI によるコード作成時の注意点については、production-migration.md を参照してください。

実装の判断

• visx は必要な機能がすべて揃ったチャートライブラリではありません。SVG を組み立てます：寸法 → スケール → マーク／ガイド → インタラクション。目的に応じて、必要最小限の @visx/* セットを選んでください。
• **D3 は計算を行い、DOM は React が管理します。**スケールやシェイプファクトリーが数値やパスの d 文字列を生成し、コンポーネントが SVG を描画します。visx のマークツリーに d3 の選択や enter／exit を混在させないでください。
• 連続的な y 範囲は反転させます（[innerHeight, 0]）。SVG の y は下方向に増加します。
• パッケージのルートから名前付きインポートを使用します（import { Bar } from '@visx/shape'）。v4 の exports では @visx/*/lib/... からのディープインポートは使用しないでください。
• 意図せず D3 を推移的にインポートするのではなく、@visx/vendor/d3-*（または独自に宣言した d3-*）を優先してください。意図がない限り、vendor 版とベアな d3-shape／d3-scale を重複して使わないでください。
• 共通のツールチップ／テーマ／注釈を使う標準的な直交座標の折れ線／面／棒／グリフ／積み上げ／グループ化には XYChart を使用します。xScale／yScale には、実際の d3 スケールインスタンスではなく ScaleConfig オブジェクト（{ type: 'band' }）を渡してください。
• 極座標、地理、階層、ネットワーク、統計、独自の SVG 構造、または最小限のバンドルには プリミティブを使用します。
• 新しい Voronoi／ヒットターゲットの実装では、従来の @visx/voronoi よりも @visx/delaunay を優先してください。
• @visx/network は力学レイアウトを実行しません。x／y を指定してください（例：外部の d3-force を使用）。
• @visx/kernel はKDE ではありません。密度の表示には、@visx/stats のビン／ViolinPlot、または外部の KDE と @visx/shape を使用してください。
• レスポンシブチャートは ParentSize／useParentSize でラップし、描画前に width < 10 をチェックしてください。テスト／SSR では固定サイズを指定してください。
• スケール設定や負荷の高いレイアウトは、幅／高さ／データに基づいてメモ化してください。可変な d3 スケールは、再レンダリングをまたぐ際に慎重に扱ってください。
• グラデーション、パターン、マーカー、clipPaths、Threshold のクリップには、SVG の一意な id を使用してください。特に、1 ページに複数のチャートがある場合は注意してください。
• チャートのセマンティクスを追加する際は、装飾的な要素（Grid*、Axis*、背景）に aria-hidden を設定してください。4.0.0 では XYChart の accessibilityLabel／シリーズのフォーカスハンドラーを使用してください。

検証

リポジトリに既存のチェックがあれば、そちらを優先してください。visx に意味のある変更を加える場合は、関連する項目を含めてください。

• @visx/*@^4 と React 18／19 のピア依存関係が揃っていることを示すパッケージ／バージョンチェック（Animated* を使用する場合は @react-spring/web も対象）。
• アクセサー、ScaleInput、シリーズの Datum／dataKey、軸／グリッドの props、ツールチップの状態を対象とする型チェック。ディープインポートの型は使用しないでください。
• 固定の width／height を使った決定的な SVG アサーション（ParentSize／ツールチップのポータルを使う場合は ResizeObserver をモックしてください）。
• これらの API を変更する場合は、ツールチップの表示／非表示、ブラシによるドメインフィルター、ズームのリセット、キーボードフォーカスのインタラクションテスト。
• テーマトークン、積み上げ／グループ化された棒、注釈の配置に関するビジュアルスモークテスト。
• umbrella の @visx/visx、アニメーション、地理関連の TopoJSON、大規模な階層／ネットワークのデモを追加する場合は、バンドル／インポートの監査。
• ディープインポート、React 16／17 のピア依存関係、withBoundingRects における nodeRef の不足、useParentSize の後の parentRef.current を対象とする移行スキャン。