tanstack-charts

TanStack Charts

TanStack Charts を扱う作業、特にマークの構成、変換、scales レジストリ、コンパクトスケールと D3 スケール、React の Chart、SSR、ツールチップ／フォーカス、Canvas、オプションの motion()、React Native、空間／階層／ネットワーク関連の項目、移行に関する作業で、このスキルを使用してください。

このライブラリは Alpha として扱ってください（スキル更新時点では 0.18.0。0.16.0 から公式 Alpha です）。Alpha は評価および初期統合向けです。マイナーリリースでも API が破壊的に変更される可能性があるため、正確なバージョンを固定してください。エッジ API を利用する前に、最新のドキュメントと npm の latest バージョンを確認してください。古い検索結果、ルートに x／y を指定する Alpha 前のスニペット、アーカイブ済みの react-charts よりも、GitHub のタグ v0.18.0 のドキュメントを優先してください。

ワークフロー

1. 統合パッケージを使用する新しい TanStack Charts であることを確認します。
   • 正しい方法：bun add @tanstack/charts と、フレームワークのピア依存関係を追加します。Chart は @tanstack/charts/react から、スケールは @tanstack/charts/scales/linear（および /band、/point、/ordinal）からインポートします。
   • 互換性のためのみ：既存のアプリ向けに、@tanstack/react-charts、@tanstack/charts-scales、その他の @tanstack/*-charts アダプターパッケージも引き続き存在します。新しいコードには追加しないでください。
   • 誤り：スコープなしの react-charts、または options／primaryAxis／secondaryAxes／UserSerie。
2. バージョンと URL を source-map.md から更新します。
3. インストール、defineChart、scales レジストリ、名前付きスケール／複数軸、軸とガイドのスタイル、凡例、ツールチップ拡張については、setup-core.md を参照してください。
4. マーク、バーの角丸、decorative、マークごとの Canvas、極座標／地理、複合要素については、marks-composition.md を参照してください。
5. 即時変換とマークのレイアウトについては、transforms-layouts.md を参照してください。
6. アダプター、サイズ設定、フォーカス、クロスヘア、ブラシ／ズーム／カーソル／選択、モーション、SSR については、frameworks-interaction.md を参照してください。
7. Alpha の安定性、破壊的変更を伴う移行（ルートのスケールから scales への移行）、テスト、大規模データ、Canvas、カスタムマーク、AI チェックについては、production-patterns.md を参照してください。

実装上の判断

• チャートはチャート種別のコンポーネントではなく、マークの組み合わせです。問いに答えるために必要な最小限のマークセットを優先してください。
• 行は自然な形のまま扱ってください。ライブラリ独自の系列ラッパーを作らないでください。
• インストールするパッケージは1つです：@tanstack/charts。コンパクトスケールは正確なパス @tanstack/charts/scales/* を使ってください（/scales のバレルはありません）。アプリケーションのソースコードで使う d3-* はすべてインポートして宣言してください。ドメインを推論する場合はファクトリーを、固定ドメインの場合は設定済みのインスタンスを渡してください。チャートが所有する位置スケールにピクセル範囲を設定しないでください。
• 位置スケールは scales レジストリーに置きます。すべての定義で scales: { x, y } を指定する必要があります（使わない次元には null を指定します）。極座標ビューでは polar({ scales: { angle, radius } }) を使います。ルートの x／y／angle／radius は 0.16.0 で削除されました。実際に第2軸が必要な場合に限り、名前付きスケール（channel、side）とマークの xScale／yScale を追加してください。
• 軸の表示設定は axis／axis.ticks／axis.tickLabels の下に置きます。axis: false はガイドを非表示にし、スケールは維持します。該当する次元を使うマークがない場合に限り、scales の項目を null にしてください。
• 捕捉する値すべてを依存対象として、defineChart(...) 全体をメモ化してください。定義の同一性が更新の境界になります。レスポンシブな { chart: ({ width }) => …, svgAnimation, tooltip, … } は外側のオプションを保持します。
• SVG アニメーションのデフォルトオプションは animate ではなく、svgAnimation です。motion() は svgAnimation を無視し、定義レベルの motion を参照します。
• 長さチャンネルが1つの棒やエリアは、暗黙的に積み上げられます。棒を横並びにするには layout: group() を使ってください。順序やオフセットを明示する必要がある場合に限り、layout: stack({ order, offset }) を使ってください。y1／y2 または x1／x2 を使うと積み上げは無効になります。
• ネイティブのツールチップには @tanstack/charts/tooltip の tooltip を使います。クリッピングを回避するには @tanstack/charts/tooltip/portal の portal を使います。React の renderTooltipBody には @tanstack/charts/react/tooltip が必要です。グループ化された行は、デフォルトで視覚上のマーク順になります。
• チャンネルおよび変換のアクセサーは (datum, { index, data }) を使い、(datum, index, data) は使いません。
• ローリング変換には window ではなく、rollingWindow を使います。リデューサーヘルパーには difference ではなく、delta を使います。
• マウントするすべてのチャートに ariaLabel を指定してください。生成されるフォーカス用ジオメトリーを省くには focus: false を使います。独自のフォーカスマークでリングを置き換える場合は focusRing: false を使います。アプリのジェスチャーがサーフェスを制御する場合は focusDisabled を使います。放射状にグループ化されたフォーカスには、@tanstack/charts/polar の focusGroupAngle を使います。
• デフォルトでは SVG を使います。描画負荷の高いレイヤーには、チャート全体を切り替えるのではなく、それらのマークに renderer: canvasChartRenderer を指定してください。極座標、地理、Canvas、エクスポート、モーション、空間、階層、ネットワーク、ブラシ／ズームの機能は、正確なサブパスからのみインポートしてください。
• createMark より前に、組み込みマーク（boxY、waffleY、violinY、複合マーク）を優先してください。ヒットテストを担うレイヤーが1つだけでよい場合は、隣接するレイヤーを decorative(...) でラップしてください。

検証

リポジトリに既存のチェックがあれば、それを優先してください。Charts に関する重要な作業では、関連する項目を実施してください。

• パッケージの確認：@tanstack/charts は正確な 0.18.x（またはプロジェクトで指定されたバージョン）に固定してください。新しいコードでは、@tanstack/react-charts／@tanstack/charts-scales ではなく、そのパッケージからアダプターやスケールをインポートしてください。定義では scales.x／scales.y を使ってください。
• チャンネル、スケール、軸オプション、ツールチップのホストブランド、モーション、ChartPoint コールバックを型チェックし、予期しない型キャストがないことを確認してください。
• createChartScene／renderChartSvg でドメイン、ジオメトリー、キー、アクセシビリティ用マークアップを確認してください。
• インタラクションテスト：フォーカス、キーボード、ツールチップ、選択、ブラシ／ズーム、リサイズ、空データ、破棄。
• テーマトークンやツールチップのサーフェス CSS を変更した場合は、ライト／ダークモードのスモークテストを行ってください。
• initialWidth、フォーマッター、Canvas シェル、idPrefix について、SSR／ハイドレーションのスモークテストを行ってください。
• 極座標、地理、Canvas、エクスポート、モーション、空間、階層、ネットワーク、または追加の D3 モジュールを追加する場合は、バンドルサイズを測定してください。