bklit-ui-migrate

Recharts / TanStack Charts → Bklit UI への移行

Bklit のチャートは shadcn レジストリのコンポーネントです。npx shadcn@latest add @bklit/<slug> を実行すると、ソースがユーザーのプロジェクトにコピーされ、コードでは @/components/charts/line-chart のように、プロジェクト独自のエイリアスからインポートします。@bklitui/ui/charts からは絶対にインポートしないでください。これは bklit のプライベートなモノレポパッケージです。

手順は順番どおりに進めてください。手順 1 のインベントリと手順 2 の分類をユーザーに提示する前に、書き換えを始めないでください。

参考資料

ファイル	用途
references/component-map.md	Recharts のコンポーネント → bklit のエクスポート、レジストリの slug、インポートパス
references/prop-map.md	プロパティごとの対応付け、単位、デフォルト値
references/shadcn-chart.md	ChartContainer / ChartConfig / ChartTooltipContent / ChartLegendContent、var(--color-*)、変更前と変更後の全体例
references/examples.md	変更前と変更後の例：複数折れ線、積み上げ棒、横棒、ドーナツ、レーダー、グラデーションエリア、小型の折れ線／エリア／棒グラフ → スパークライン、TanStack の KPI スパークライン
references/tanstack-charts.md	TanStack Charts（@tanstack/charts）：マーク → スパークライン（詳しく説明）と、通常のチャート（概要のみ）
rules/gaps.md	bklit に対応するプロパティがない機能 — 回避策を使うか Recharts を維持（誤り／正しい例）
scripts/detect-recharts.mjs	依存関係なしでインベントリと分類を実行（Recharts、shadcn ラッパー、TanStack Charts、小型チャート → スパークライン）

各チャートのドキュメント：https://bklit.com/docs/components/<slug>。

基本ルール

1. プロパティを捏造しないでください。 Recharts のプロパティが prop-map.md に記載されていない場合は、未対応です。rules/gaps.md を確認してください。bklit の XAxis には tickFormatter がなく、YAxis には domain がなく、stackId、layout、connectNulls、syncId もありません。
2. Line / Area / Composed / Scatter は時系列チャートです。 x 値は Date（または ISO 文字列／エポックミリ秒）である必要があります。カテゴリ値の x 軸には BarChart または回避策を使用してください。 小型チャートはスパークラインです。 系列が 1 つで、軸／グリッド／凡例がなく、小さく表示される場合は、@bklit/sparkline の LineSparkline / AreaSparkline / BarSparkline を使用してください（x は行の順序を示すため、日付は不要です）。LineChart と非表示のチャート要素で作り直さないでください。
3. データ、色、ラベルを維持してください。 同じ系列、同じ色（ChartConfig から解決）、ツールチップと凡例に同じ人間向けのラベルを使用してください。
4. 一度に 1 ファイルずつ変更し、その都度型チェックを実行してください。
5. 「回避策が必要」と分類された変換を行う前に、必ず確認してください — チャートの見た目や読み取り方が変わります。
6. 「Recharts を維持」と分類されたチャートには手を加えないでください。 一部のみの移行でも問題ありません。

ステップ 1 — 検出と一覧作成

プロジェクトのルートから検出ツールを実行します（Node ≥ 18、インストール不要）。

node <skill-dir>/scripts/detect-recharts.mjs . --format=table   # human table
node <skill-dir>/scripts/detect-recharts.mjs .                  # full JSON

ソースファイルを走査し（node_modules、.next、dist、build、ドットで始まるディレクトリはスキップ）、recharts のインポート（名前付きインポート、または import * as RechartsPrimitive）、shadcn ラッパーのインポート、@tanstack/charts のインポートを検出します（各 defineChart(...) は "library": "@tanstack/charts" を持つ 1 つのチャートとして扱います）。ファイルごとに、使用コンポーネント、行番号付きの各チャートルート、注目すべきプロパティ（stackId、layout="vertical"、syncId、XAxis type="number"、Treemap、LabelList、ErrorBar、カスタムの shape／content、Brush など）、提案する bklit の移行先、インストールするスラッグ、分類を報告します。スパークラインとして読み取ったチャートには "sparkline": true と移行先 @bklit/sparkline を付与します。軸がなくサイズが不明なチャートには、その旨の注記を表示します。shadcnWrappers[].importedBy には、まだ components/ui/chart.tsx をインポートしているファイルが一覧表示されます。例外は発生せず、読み取りできないパスは errors に記録されます。

このスクリプトはヒューリスティックです（データ値やヘルパー関数内で構築された軸は認識できません）。一覧にあるファイルはすべて開いて、提示する前に内容を確認してください。ユーザーには次の表を提示します。

ファイル	Recharts／shadcn コンポーネント	チャートの種類	bklit の移行先	分類
components/chart-area-interactive.tsx:51	AreaChart, Area, CartesianGrid, XAxis, ChartContainer, ChartTooltip(Content), ChartLegend(Content)	Area（積み上げ）	AreaChart	回避策が必要
components/storage-treemap.tsx:25	Treemap, Tooltip, ResponsiveContainer	Treemap	—	Recharts を継続使用

また、components.json を確認します。@bklit レジストリ（"registries": { "@bklit": "https://ui.bklit.com/r/{name}.json" }）を確認し、aliases.components を記録します。これはインポートのプレフィックスを決定します（デフォルトの @/components の場合、ファイルは components/charts/ に配置されます）。

ステップ 2 — 分類と確認

各チャートについて、次のいずれかを示します。

• 問題なし — すべてのコンポーネントとプロパティに対応するマッピングがあります（component-map.md、prop-map.md を参照）。ただし、データの再構成が必要な場合があります（pie、radar、radial、ring）。
• 回避策が必要 — 妥協すれば変換できます。典型例：時系列チャート上のカテゴリカルまたは数値の x 軸、Area stackId、複数の棒グループのスタック、固定された YAxis domain、負の棒の値、x 軸の tickFormatter／傾斜目盛り、LabelList、syncId、Brush（bklit の brush はどのレジストリアイテムにも含まれていません）、ReferenceLine／ReferenceDot、null のギャップ、ネストされた円グラフ。
• Recharts を継続使用 — Treemap、ErrorBar、Customized、カスタムの shape／ノードレンダラー、ZAxis のバブル、棒グラフ以外での layout="vertical"。
• TanStack Charts を継続使用（keep-tanstack）— bklit にマッピングがないマーク（dot、cell、rect、text、ruleY、hexagon、facet など）を使う定義。完全な lineY／areaY／barY チャートには回避策が必要です（高レベルのマッピングのみ）。スパークラインの定義は問題ありません。tanstack-charts.md を参照してください。
• スパークライン — 小さなチャートに Tooltip（または TanStack の tooltip）がある場合は、回避策が必要です。スパークラインにはツールチップがないため、useSparklineHover を使って値をチャートの横に表示します。

問題のないチャート以外は、それぞれの理由（プロパティを引用）と、rules/gaps.md に記載された回避策を提示してください。ユーザーに、回避策が必要なチャートのうちどれを変換するか、またどのように変換するか（例：重ね合わせるか累積エリアにするか）を尋ねてください。ユーザーが各チャートの確認を求めている場合を除き、問題のないチャートは追加の質問をせずに変換します。

手順 3 — bklit 項目をインストールする

確認済みのチャートに必要なものだけを、プロジェクトのパッケージランナーを使ってインストールします。

npx shadcn@latest add @bklit/line-chart @bklit/bar-chart @bklit/y-axis @bklit/legend
# pnpm dlx shadcn@latest add …   |   bunx --bun shadcn@latest add …

必要な用途	スラッグ
小さな LineChart / AreaChart / BarChart、TanStack の lineY / areaY / barY スパークライン	sparkline（LineSparkline、AreaSparkline、BarSparkline、useSparklineHover。グリッド、軸、ツールチップは取り込まれません）
LineChart / AreaChart / BarChart / ComposedChart / ScatterChart	line-chart / area-chart / bar-chart / composed-chart / scatter-chart（それぞれ grid、chart-tooltip が追加されます。時間軸チャートには x-axis が、棒グラフには BarXAxis / BarYAxis が追加されます）
PieChart / RadarChart / リング（RadialBarChart）/ 単一値のゲージ	pie-chart / radar-chart / ring-chart / gauge-chart
FunnelChart / Sankey / SunburstChart	funnel-chart / sankey-chart / sunburst-chart
表示する値の YAxis	y-axis（line/area/bar には同梱されていません）
Legend	legend
ReferenceArea	reference-area
ReferenceDot / イベントマーカー	markers

shadcn は bklit の CSS 変数（--chart-line-primary、--chart-grid、--chart-crosshair、ツールチップの色など）をグローバルスタイルシートに追加しますが、既存の変数は上書きしません。そのため、ユーザーの --chart-1 … --chart-5 はそのまま維持されます。インポートを記述する前に、ファイルが aliases.components で指定された場所に配置されていることを確認してください。

ステップ 4 — 1 ファイルずつ変換する

各チャートについて：

1. データを整形します。
   • 時系列チャート：row[xDataKey] を Date にします。"2024-04-01" のような単独の文字列は UTC の午前0時として解析されるため、UTC より西の地域では前日として表示されます → new Date(\${d}T00:00:00`)。x でソートします。キーが "date"でない場合はxDataKeyを設定します（bar のデフォルトは"name"`）。
   • 系列レベルの data（<Scatter data>、<Line data>）→ ルートの data にマージします。
   • Pie：{ label, value, color? }[]。Radar：metrics {key,label}[] + 正規化された 0–100 の data {label, color?, values}[]。Ring：{ label, value, maxValue, color? }[]。Funnel：{ label, value, color? }[]。Sankey：変更しません。
2. component-map.md と prop-map.md を使ってコンポーネントとプロパティを対応付けます。間違えやすいポイント：
   • ResponsiveContainer → 削除します。aspectRatio（デフォルトは "2 / 1"）または className="h-[300px]" でサイズを指定します。
   • layout="vertical" → BarChart orientation="horizontal"（名称が逆になっています）+ BarYAxis。
   • すべてのバーで同じ stackId を使っている場合 → ルートに stacked を指定します。
   • type="monotone" → @visx/curve の curve={curveMonotoneX}。Recharts のデフォルトの曲線は linear です。bklit の Line のデフォルトは curveNatural、Area のデフォルトは curveMonotoneX です。
   • dot → showMarkers／markers。activeDot → ChartTooltip showDots／dotSize。
   • isAnimationActive={false} → 系列に animate={false} を指定します（ルートの animationDuration のデフォルトは 1100 ms）。
   • Bar radius → lineCap（デフォルトは "round"。Recharts の角形バーには "butt"、px 単位の数値も指定できます）。
   • paddingAngle（度）→ padAngle（ラジアン）。pie の角度：rad = (90 − deg) · π / 180。
   • YAxis tickFormatter → formatValue。domain → 対応するものはありません。
   • Tooltip → ラベルや書式設定には rows={(point) => [...]}（行の順序は系列の子要素の順序と同じです）、完全に制御するには content={({ point, index }) => …} を指定した ChartTooltip。cursor={false} → showCrosshair={false}。
   • Legend → @/components/charts/legend の <Legend items>。チャートのルートの外側にレンダリングします。
   • margin：形状は同じですが、軸ラベルがマージン内に配置されるため、bklit のデフォルトは全辺で 40 です。
   • スパークライン（prop-map.md →「Tiny charts」）：stroke／fill → color、type="monotone" → curve="monotone"（文字列）、margin → padding、radius → barRadius、isAnimationActive={false} → animate={false}、ResponsiveContainer → width を省略、Tooltip → useSparklineHover + 独自の値。@/components/charts/sparkline からインポートします。
   • TanStack Charts：defineChart(...) と <Chart definition> 要素を置き換えます。マークのチャネルはプロパティになります（y → dataKey、stroke → color、curve → curve、y スケールの domain → yDomain、margin → padding、ariaLabel → aria-label、svgAnimation／motion() → animate）。詳細は tanstack-charts.md を参照してください。
3. ChartConfig（shadcn）の色とラベルを維持します。 すべての var(--color-<key>) を設定の色に置き換えます（例：var(--chart-1)）。これらの変数は ChartContainer の内側でのみ使用できます。ラベルは rows と Legend items に指定します。詳細は shadcn-chart.md を参照してください。
4. コンポーネントの公開 API（名前、プロパティ、エクスポート）を維持し、呼び出し元を変更しないようにします。
5. ファイルが関数（rows、content、formatValue）を渡していて、まだクライアントコンポーネントでない場合は、"use client" を追加します。

ステップ 5 — インポートを書き換える（名前の衝突に注意）

レジストリがインストールしたファイルから各要素をインポートします：

import { Line, LineChart } from "@/components/charts/line-chart";
import { Grid } from "@/components/charts/grid";
import { XAxis } from "@/components/charts/x-axis";
import { YAxis } from "@/components/charts/y-axis";
import { ChartTooltip } from "@/components/charts/tooltip";
import { Legend, LegendItem, LegendLabel, LegendMarker } from "@/components/charts/legend";
import { AreaSparkline, BarSparkline, LineSparkline, useSparklineHover } from "@/components/charts/sparkline";

ファイル内で使われなくなったら、recharts と @/components/ui/chart のインポートを削除します。ライブラリ間で名前が衝突します。ChartTooltip、ChartLegend（shadcn のラッパー）、および LineChart、Line、Area、Bar、XAxis、YAxis、Legend、ReferenceArea、PieChart、…（Recharts）が該当します。Recharts のチャートを引き続きレンダリングするファイルでは、どちらか一方に別名を付けます：

import { Treemap, Tooltip as RechartsTooltip } from "recharts";
import { ChartTooltip as BklitChartTooltip } from "@/components/charts/tooltip";

レジストリの凡例項目のエクスポート名は LegendItem です（ドキュメントにある LegendItemComponent の別名は bklit のモノレポの barrel 内でのみ使用できます）。

ステップ 6 — 未使用の場合に限り、古いコードを削除する

• components/ui/chart.tsx は、どのファイルからもインポートされていない場合に限り削除します。検出ツールを再実行して（shadcnWrappers[].importedBy が空であることを確認）、ストーリー、テスト、ドキュメントを含めてリポジトリ全体を検索します（rg "ui/chart"）。
• recharts の依存関係は、検出ツールで recharts のインポートが残っていない（維持するチャートがない）と報告され、かつ rg "from ['\"]recharts" の検索結果が空の場合に限り削除します。プロジェクトのパッケージマネージャーを使用します（npm uninstall recharts、pnpm remove recharts など）。
• @tanstack/charts は、検出ツールで @tanstack/charts のインポートが残っていないと報告され、かつ rg "@tanstack/charts" の検索結果が空の場合に限り削除します。
• Recharts または TanStack Charts を使うチャートを残す場合は、その依存関係も残し、概要にその旨を記載します。

ステップ 7 — 検証する

1. 各ファイルの変更後に型チェックとリンターを実行し、その後ビルドします。npx tsc --noEmit（またはプロジェクトの typecheck スクリプト）、プロジェクトの lint スクリプト、続けて build を実行します。
2. 見た目を比較します。開発サーバーを起動し、変換した各チャートを元のチャートと比較します（ライトモードとダークモードで変更前後のスクリーンショットを撮影）。系列の数と色、ツールチップと凡例のラベル、x 軸ラベル／日付（UTC のずれ）、y 軸の範囲、積み上げ表示、サイズ、ホバー、空の状態を確認します。
3. 許容される差異として、次の項目を明記します。bklit の表示アニメーション、破線／端がフェードするグリッド、十字線と日付ピルのツールチップ、固定の "MMM d" x 軸ラベル、デフォルトで角が丸いバー。

• 検出ツールを再実行し、Recharts を使う箇所とその理由を報告します。

完了

ユーザー向けに、変換したチャート（ファイル → bklit チャート）、適用した回避策、Recharts を使い続けるチャートとその理由、インストールした項目、削除したファイル／依存関係、検証結果をまとめます。

移行したチャートのスタイル変更（パレット、トークン、タイポグラフィ、モーション）は bklit-ui-design スキルに引き継ぎます。bklit の構成に関する一般的な質問には bklit-ui スキルを使用します。