@squadbase/vantage 0.0.1 → 0.1.1

package/docs/ja/environment-variables.md

@@ -0,0 +1,68 @@
+# 環境変数
+
+> PUBLIC_ 接頭辞の env だけがクライアントに届く。シークレットはサーバーの env から読む。
+
+Vantage は、環境変数を**クライアントに漏らさない**ことを既定にしています。境界は接頭辞で決まります。
+
+## クライアントに届くのは `PUBLIC_` だけ
+
+`PUBLIC_` で始まる変数だけがクライアントバンドルに入り、`import.meta.env` から読めます。
+
+```tsx
+// クライアントコード
+const analyticsId = import.meta.env.PUBLIC_ANALYTICS_ID;
+```
+
+クライアントで参照できるのは次だけです。
+
+- `PUBLIC_*`（あなたが定義した公開値）
+- `MODE` / `DEV` / `PROD` / `SSR` / `BASE_URL`（Vite の標準）
+
+> [!WARNING]
+> `PUBLIC_` 接頭辞の**付いていない** env をクライアントで読もうとすると、`vantage check` が
+> `PUBLIC_ENV_MISUSE` 警告を出します。ユーザー向けの `VITE_` API は存在しません。
+
+## シークレットはサーバーの `env` から
+
+API キーやトークンなどの秘密情報は、**クライアントに出さず**サーバーの `ApiContext.env` から
+読みます。これらは接頭辞を付けません。
+
+```ts
+// server/api/report.ts
+import type { ApiContext } from "@squadbase/vantage/server";
+
+export async function GET({ env }: ApiContext) {
+  const apiKey = env.SECRET_API_KEY; // クライアントには決して届かない
+  // …外部サービスを呼ぶ
+  return Response.json({ ok: true });
+}
+```
+
+## `.env` の例
+
+```bash
+# .env
+PUBLIC_ANALYTICS_ID=UA-XXXX     # クライアントに届く
+SECRET_API_KEY=sk_live_xxx      # サーバー専用（ApiContext.env）
+```
+
+> [!NOTE]
+> dev サーバーはリクエストごとに env を読み直します。本番の Node サーバーは起動時に一度だけ
+> `process.env` をスナップショットします。
+
+## デプロイで使う env
+
+フロントとサーバーを別オリジンにデプロイするときは、次の env が関わります。
+
+| 変数 | 側 | 役割 |
+|---|---|---|
+| `PUBLIC_API_BASE_URL` | クライアント(公開) | クライアントが `/api` を呼ぶベースURL。`--api-base-url` でも上書き可 |
+| `CORS_ORIGIN` | サーバー | `/api` に対して許可するオリジン。未設定なら CORS 無効 |
+| `CORS_CREDENTIALS` | サーバー | `true` で資格情報(Cookie 等)を許可 |
+
+使い方は[ビルドとデプロイ](build-and-deploy)で詳しく解説します。
+
+## 次に読む
+
+- [ビルドとデプロイ](build-and-deploy) — 本番の env と別オリジン構成
+- [UI とテーマ](ui-and-theming) — 見た目を整える

package/docs/ja/getting-started.md

@@ -0,0 +1,95 @@
+# はじめに
+
+> インストールから最初の Vantage アプリを起動するまで。
+
+## 前提
+
+- **Node.js 20 以上**
+- パッケージマネージャ（pnpm / npm / yarn のいずれか）
+
+## 最小のアプリを作る
+
+### Vantage を追加する
+
+プロジェクトに `@squadbase/vantage` を追加します。
+
+```bash
+pnpm add @squadbase/vantage
+```
+
+### index.tsx を書く
+
+プロジェクトルートに `index.tsx` を 1 つ置きます。**default export されたコンポーネント**が
+ルート `/` になります。
+
+```tsx
+// index.tsx
+export default function Dashboard() {
+  return (
+    <main className="p-6">
+      <h1 className="text-2xl font-semibold">Dashboard</h1>
+    </main>
+  );
+}
+```
+
+### 開発サーバーを起動する
+
+```bash
+pnpm exec vantage dev
+```
+
+`http://localhost:5173` が立ち上がります。HMR（ホットリロード）が効き、ページを編集すると
+React Fast Refresh がその場で反映します。
+
+> [!TIP]
+> 素の `pnpm add` 直後は `vantage` バイナリが PATH に無いため、`pnpm exec vantage`（または
+> `npx vantage`）で起動します。`package.json` の `scripts` に `"dev": "vantage dev"` を足せば
+> `pnpm dev` で起動できます。
+
+## 開発ループ
+
+| コマンド | 役割 |
+|---|---|
+| `vantage dev` | 開発サーバー（HMR + オプションの API）。既定 `:5173` |
+| `vantage build` | 本番ビルド → `dist/`（クライアント + オプションのサーバー） |
+| `vantage preview` | 本番ビルドをローカルで起動 |
+| `vantage check` | 静的検査（ルート・境界・禁止ファイル）。エラー時は exit 1 |
+| `vantage routes` | ページ + API の URL マップを表示 |
+
+> [!TIP]
+> `vantage dev` の実行中は、ブラウザの `console.*` と未捕捉のエラーが開発ターミナルへ
+> `[browser:…]` として転送されます。多くの不具合はブラウザを開かずに診断できます。
+
+## クイックモード（パスを直接渡す）
+
+`cd` せずに、**プロジェクトのパスを直接**渡して開発サーバーを起動できます。手元のフォルダや
+エントリファイルをそのまま指すだけで `dev` が立ち上がります。
+
+```bash
+vantage ./demo             # フォルダ → その中で dev を起動
+vantage ./demo/index.tsx   # ページファイル → 親フォルダを root にして dev
+```
+
+第 1 引数が既知コマンドでなくパスを指すとき、Vantage はそれを root として `dev` を起動します
+（`quick dev → <path>` と表示）。詳しい解決ルールは
+[CLI リファレンス](cli-reference)を参照してください。
+
+## 設定ファイルは書かない
+
+Vantage は「設定より規約」を徹底しています。次のファイルはプロジェクトに置くと **ハードエラー**
+（`vantage check` が失敗）になります。
+
+- `vite.config.*`
+- `tailwind.config.*`
+- `postcss.config.*`
+- `components.json`
+- `vantage.config.*`
+
+これらが担っていた役割は、すべて Vantage 側が持っています。カスタマイズが必要なときは、
+各ガイドで説明する「明示的なエスケープハッチ」を使います。
+
+## 次に読む
+
+- [ファイルベースルーティング](routing) — ページを増やす
+- [ページと definePage](pages-and-metadata) — ページの契約とメタデータ

package/docs/ja/index.md

@@ -0,0 +1,65 @@
+# Vantage とは
+
+> 設定ファイル不要（config-free）な React ダッシュボードフレームワーク。書くのは index.tsx だけ。
+
+**Vantage**(ヴァンテージ)は「見晴らしのいい地点」を意味する言葉です。データ全体を一望できる
+ダッシュボードを、最小の手間で用意する ― その姿勢を名前に込めています。
+
+**Vantage** は [Squadbase Editor](https://squadbase.dev) 向けの、設定ファイル不要（config-free）な
+React ダッシュボードフレームワークです。Vite 8 の上に構築されており、アプリ作者が書くのは
+`index.tsx` **1 ファイルだけ**。ルーティング・React のセットアップ・TanStack Query・Tailwind CSS・
+UI キット・開発サーバー・オプションの API サーバー・ビルドは、すべて **Vantage が所有**します。
+
+```tsx
+// index.tsx  →  ルート "/"
+export default function Dashboard() {
+  return (
+    <main className="p-6">
+      <h1 className="text-2xl font-semibold">Dashboard</h1>
+    </main>
+  );
+}
+```
+
+この 7 行が、そのまま動くダッシュボードアプリになります。`vite.config`・`tailwind.config`・
+`postcss.config`・`components.json`・`vantage.config` は **一切書きません**。
+
+> [!NOTE]
+> このサイトは **アプリ作者**（Vantage を使ってダッシュボードを作る人）向けのガイドです。
+> フレームワーク自体の内部実装については、リポジトリの `README.md` と設計ドキュメントを参照してください。
+
+## 特徴
+
+### まず 1 ファイル
+
+単一の `index.tsx` が完結したアプリになる。ページを増やしたくなったら `.tsx` を足すだけ。
+
+### 設定より規約
+
+設定ファイルは不要どころか禁止。ファイル名とディレクトリの規約がすべてを駆動する。
+
+### 管理されたスタック
+
+React・Vite・TanStack Router/Query・Tailwind・UI キットのバージョンは Vantage が固定する。
+
+### サーバーはオプション
+
+`server/` を足すと API が有効になる。なければクライアントのみの SPA。
+
+## 次のステップ
+
+### はじめに
+
+インストールから最初のアプリの起動まで。
+
+### ファイルベースルーティング
+
+ファイルを置くだけでルートが生まれる仕組み。
+
+### データ取得
+
+管理された TanStack Query でサーバー状態を扱う。
+
+### API とサーバー
+
+`server/api` でバックエンドを書く。

package/docs/ja/markdown/markdown-renderer.md

@@ -0,0 +1,43 @@
+# MarkdownRenderer
+
+> Markdown を描画する。シンタックスハイライト込み。
+
+Markdown 文字列を描画します。表・コードブロック（シンタックスハイライト付き）・数式まで扱える
+ので、LLM の出力や、データベースに入っている説明文をそのまま出すのに使えます。
+
+```tsx
+import { MarkdownRenderer } from "@squadbase/vantage/markdown";
+```
+
+| Prop | Type | 説明 |
+| --- | --- | --- |
+| `content` | `string` | 描画する Markdown。 |
+| `className` | `string` | 足すクラス。 |
+
+## なぜ別のサブパスなのか
+
+`@squadbase/vantage/components` からは**意図的に再エクスポートしていません**。Markdown の描画は
+Shiki の全言語文法を抱えており、import の辺があるだけでバンドラは落とせません。共有のバレルに
+置くと、Markdown を使わないアプリのビルド出力まで約 11 MB / 300 ファイル増えます。
+
+別サブパスにしてあるので、**このコンポーネントを import したアプリだけ**がその重さを負担します。
+
+```tsx
+// これは重い（そして、それでよい）
+import { MarkdownRenderer } from "@squadbase/vantage/markdown";
+
+// これは軽いまま
+import { DashboardCardPreset } from "@squadbase/vantage/components";
+```
+
+## LLM の出力を流す
+
+`content` を差し替えるだけなので、ストリーミングされてくる途中の文字列をそのまま渡せます。
+未完成の Markdown（閉じていないコードブロックなど）も壊れずに描画されます。
+
+```tsx
+const [text, setText] = useState("");
+// …チャンクが来るたびに setText((prev) => prev + chunk)
+
+<MarkdownRenderer content={text} />;
+```

package/docs/ja/pages-and-metadata.md

@@ -0,0 +1,59 @@
+# ページと definePage
+
+> ページの唯一の要件は default export。definePage でタイトルと説明を静的に付与する。
+
+## 唯一の要件は default export
+
+Vantage のページに必要なのは、**React コンポーネントの default export だけ**です。
+
+```tsx
+export default function MonthlyAnalysis() {
+  return <h1>月次分析</h1>;
+}
+```
+
+default export が無いページは `vantage check` が `MISSING_DEFAULT_EXPORT` エラーで指摘します。
+
+## definePage でメタデータを付ける
+
+タイトルや説明を付けたいときは `definePage` を使います。任意です。
+
+```tsx
+import { definePage } from "@squadbase/vantage";
+
+export const page = definePage({
+  title: "月次分析 · Acme Analytics",
+  navLabel: "月次分析",
+  description: "売上と主要指標の月次サマリー",
+});
+
+export default function MonthlyAnalysis() {
+  return <h1>月次分析</h1>;
+}
+```
+
+- `title` は `document.title` を駆動します（末端のルートマッチのタイトルが使われ、無ければ
+  ドキュメント初期の `<title>` にフォールバック）。
+- `navLabel` は [`useRoutes()`](routing#ルート一覧からナビを作る) で組むナビの表示名です。
+  省略すると `title` が使われます。`title` にサイト名を含めるときに分けます。
+- `title`/`description`/`navLabel` は **生成時に静的に読まれます**。Vantage はページを実行して
+  読むのではなく、ソースを静的に解析します。したがって値は**リテラル**にしてください。
+
+> [!WARNING]
+> `export const page = definePage({...})` の**エクスポート名は `page` 固定**です。別名にすると
+> メタデータが読まれません。
+
+## Fast Refresh との関係
+
+`page` のような非コンポーネントのエクスポートがあっても、Vantage はそれを内部で扱うため
+React Fast Refresh は生き残ります。ページ本体を編集しても、state を保ったまま更新されます。
+
+## プロトタイプの制約
+
+`definePage` は `pendingComponent` / `errorComponent` / `validateSearch` も型として受け付けますが、
+現行プロトタイプでは **lazy ルートにまだ結線されていません**。ページごとの pending/error UI の
+上書きは未実装で、フレームワーク共通のデフォルトが描画されます。
+
+## 次に読む
+
+- [データ取得](data-fetching) — サーバー状態を扱う

package/docs/ja/parts/app-shell.md

@@ -0,0 +1,54 @@
+# AppShell
+
+> ナビゲーション定義を渡すだけのアプリ枠。
+
+アプリ全体の外枠です。`groups` にナビゲーションを配列で渡すだけで、折りたためるサイドバー
+（または狭い画面向けのヘッダー）が組み上がります。[`Sidebar`](ui/sidebar) を自分で
+組む代わりに使ってください。
+
+```tsx
+import { AppShell } from "@squadbase/vantage/components";
+import type { NavGroup, NavItem } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `groups` | `NavGroup[]` |  | ナビゲーション。`{ label?, items: NavItem[] }` の配列。 |
+| `variant` | `"sidebar" \| "header"` | `"sidebar"` | サイドバー枠か、セレクト式のヘッダー枠か。 |
+| `actions` | `ReactNode` |  | 上部右端に置く要素。 |
+| `header` | `ReactNode` |  | 既定のヘッダーを丸ごと差し替える。 |
+| `defaultOpen` | `boolean` | `true` | `variant="sidebar"` のとき、初期状態で開いているか。 |
+| `linkComponent` | `ElementType` |  | 項目を描くリンクコンポーネント。 |
+| `onNavigate` | `(href: string) => void` |  | 項目が選ばれたとき。既定では `location.assign`。 |
+
+## NavItem
+
+```ts
+interface NavItem {
+  label: string;
+  href: string;
+  icon?: ComponentType<{ className?: string }>;
+  isActive?: boolean;
+  disabled?: boolean;
+  badge?: string;
+  children?: NavItem[]; // 折りたたむサブ項目
+}
+```
+
+`children` を持つ項目は、開閉するサブメニューになります。
+
+## ルーターと繋ぐ
+
+クライアントサイド遷移にしたいときは `onNavigate` を渡します。
+
+```tsx
+import { useNavigate } from "@squadbase/vantage/router";
+
+const navigate = useNavigate();
+
+<AppShell groups={groups} onNavigate={(href) => navigate({ to: href })}>
+  {children}
+</AppShell>;
+```
+
+現在地の強調は `isActive` で指定します — ルートのパスと `href` を突き合わせて立ててください。

package/docs/ja/parts/dashboard-card.md

@@ -0,0 +1,64 @@
+# DashboardCard
+
+> ダッシュボードのタイル。プリセットとスケルトン付き。
+
+ダッシュボードに並べるタイルです。素の [`Card`](ui/card) より余白が詰まっており、
+読み込み中用のスケルトンが同じ形で用意されています。よくある組み方は
+`DashboardCardPreset` 一つで済みます。
+
+```tsx
+import {
+  DashboardCard,
+  DashboardCardHeader,
+  DashboardCardTitle,
+  DashboardCardDescription,
+  DashboardCardAction,
+  DashboardCardContent,
+  DashboardCardFooter,
+  DashboardCardSkeleton,
+  DashboardCardPreset,
+} from "@squadbase/vantage/components";
+```
+
+## DashboardCardPreset
+
+| Prop | Type | 説明 |
+| --- | --- | --- |
+| `title` | `ReactNode` | 見出し。 |
+| `description` | `ReactNode` | 見出しの下の補足。 |
+| `actions` | `ReactNode` | 見出し行の右端。 |
+| `footer` | `ReactNode` | 下端の行。 |
+| `children` | `ReactNode` | 本文。 |
+| `headerClassName` | `string` |  |
+| `contentClassName` | `string` |  |
+| `footerClassName` | `string` |  |
+
+`title` / `description` / `actions` がすべて未指定ならヘッダーごと省かれます。`footer` も同様です。
+
+## 自分で組む
+
+配置を変えたいときは、パーツを直接使います。
+
+```tsx
+<DashboardCard>
+  <DashboardCardHeader>
+    <div>
+      <DashboardCardTitle>売上</DashboardCardTitle>
+      <DashboardCardDescription>今月</DashboardCardDescription>
+    </div>
+    <DashboardCardAction>
+      <Button variant="ghost" size="xs">詳細</Button>
+    </DashboardCardAction>
+  </DashboardCardHeader>
+  <DashboardCardContent>…</DashboardCardContent>
+  <DashboardCardFooter>前月比 +12.4%</DashboardCardFooter>
+</DashboardCard>
+```
+
+## 読み込み中
+
+`DashboardCardSkeleton` は同じ寸法の箱を描くので、データが届いても画面が跳ねません。
+
+```tsx
+{isLoading ? <DashboardCardSkeleton /> : <DashboardCardPreset title="売上">…</DashboardCardPreset>}
+```

package/docs/ja/parts/data-table.md

@@ -0,0 +1,85 @@
+# DataTable
+
+> TanStack Table ベースの表。並べ替え・検索・ページング・選択。
+
+並べ替え・検索・ページング・行選択・列の表示切り替えを備えた表です。中身は TanStack Table で、
+列定義は TanStack の `ColumnDef` そのものです。ひととおり揃った形が欲しいだけなら
+`DataTablePreset` の 1 コンポーネントで済みます。
+
+```tsx
+import {
+  DataTable,
+  DataTableToolbar,
+  DataTableContent,
+  DataTablePagination,
+  DataTableColumnVisibility,
+  DataTablePreset,
+  useDataTable,
+} from "@squadbase/vantage/components";
+import type { ColumnDef, SortingState, PaginationState } from "@squadbase/vantage/components";
+```
+
+## DataTablePreset
+
+まずこれを試してください。ツールバー・本体・ページャを既定の並びで組み上げます。
+
+| Prop | Type | 説明 |
+| --- | --- | --- |
+| `columns` | `ColumnDef<TData>[]` | TanStack Table の列定義。 |
+| `data` | `TData[]` | 行データ。 |
+| `enableSorting` | `boolean` | ヘッダークリックで並べ替える。 |
+| `enableFiltering` | `boolean` | ツールバーに検索欄を出す。 |
+| `enablePagination` | `boolean` | ページャを出す。 |
+| `enableRowSelection` | `boolean` | 先頭にチェックボックス列を足す。 |
+| `enableColumnVisibility` | `boolean` | 表示する列を選ぶメニューを出す。 |
+| `columnLabels` | `Record<string, string>` | 列メニューに出す表示名。 |
+| `toolbar` | `ReactNode` | ツールバーに差し込む要素。 |
+| `bulkActions` | `(selectedRows: TData[]) => ReactNode` | 行を選択しているときに出す操作。 |
+| `pageCount` | `number` | サーバー側ページングのときの総ページ数。 |
+
+`sorting` / `columnFilters` / `globalFilter` / `pagination` / `rowSelection` /
+`columnVisibility` は、対応する `on…Change` と一緒に渡せば制御コンポーネントになります。渡さな
+ければ内部で状態を持ちます。
+
+## 自分で組む
+
+配置を変えたいときはパーツを直接使います。状態は `DataTable` が持ち、子のパーツが読みます。
+
+```tsx
+<DataTable columns={columns} data={data} enableSorting enableFiltering>
+  <DataTableToolbar showSearch toolbar={<FilterBarPreset … />} />
+  <DataTableContent />
+  <DataTablePagination pageSizeOptions={[10, 25, 50]} />
+</DataTable>
+```
+
+`useDataTable()` を使うと、子コンポーネントから TanStack の `table` インスタンスを直接触れます。
+
+## サーバー側でページングする
+
+`pagination` と `onPaginationChange` を自分で持ち、`pageCount` に総ページ数を渡します。
+
+```tsx
+const [pagination, setPagination] = useState({ pageIndex: 0, pageSize: 25 });
+
+const { data } = useQuery({
+  queryKey: ["sales", pagination],
+  queryFn: () => apiFetch(`/api/sales?page=${pagination.pageIndex}`).then((r) => r.json()),
+});
+
+<DataTablePreset
+  columns={columns}
+  data={data.rows}
+  pagination={pagination}
+  onPaginationChange={setPagination}
+  pageCount={data.pageCount}
+/>;
+```
+
+## ソースを編集したいとき
+
+`DataTable` だけは編集可能なソースをコピーできます。
+
+```bash
+vantage add ui data-table
+```

package/docs/ja/parts/date-range-picker.md

@@ -0,0 +1,41 @@
+# DateRangePicker
+
+> プリセット付きの期間選択。
+
+「今日」「直近 7 日」といったプリセットと、2 か月分のカレンダーを組み合わせた期間選択です。
+ダッシュボードの期間指定はこれで足ります。
+
+```tsx
+import { DateRangePicker, defaultPresets } from "@squadbase/vantage/components";
+import type { DateRange, PresetItem } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `value` | `DateRange` |  | `{ from, to }`。どちらも `Date \| undefined`。 |
+| `onChange` | `(range: DateRange) => void` |  | 確定時。 |
+| `presets` | `PresetItem[]` | `defaultPresets` | 左側に並べるプリセット。 |
+| `showPresets` | `boolean` | `true` | プリセット列を出すか。 |
+| `minDate` | `Date` |  | 選べる下限。 |
+| `maxDate` | `Date` |  | 選べる上限。 |
+| `placeholder` | `string` |  | 未選択時のトリガー表示。 |
+| `align` | `"start" \| "center" \| "end"` |  | ポップオーバーの寄せ方。 |
+| `disabled` | `boolean` |  | 操作を無効にする。 |
+
+## プリセットを差し替える
+
+`defaultPresets` は「今日 / 昨日 / 直近 7 日 / 直近 14 日 / …」です。自分で定義するときは
+`getValue` が `DateRange` を返すようにします。
+
+```tsx
+const presets: PresetItem[] = [
+  { label: "今四半期", getValue: () => ({ from: quarterStart, to: today }) },
+  ...defaultPresets,
+];
+
+<DateRangePicker presets={presets} value={range} onChange={setRange} />;
+```
+
+> [!NOTE]
+> `onChange` は `from` だけが決まった途中の状態でも呼ばれます。`to` が `undefined` のあいだは
+> 再取得しない、という分岐を入れてください。

package/docs/ja/parts/echart.md

@@ -0,0 +1,52 @@
+# EChart
+
+> Apache ECharts の薄いラッパー。配色は option で指定する。
+
+Apache ECharts をそのまま使えるようにした薄いラッパーです。キャンバスの初期化・リサイズ・破棄と、
+ローディング表示・イベント購読・PNG 保存だけを面倒みます。**配色や軸の見た目はテーマに自動追従
+しません** — `option` の中で色を決めるか、`theme` に ECharts のテーマを渡してください。
+
+```tsx
+import { EChart } from "@squadbase/vantage/components";
+import type { EChartsOption } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | 説明 |
+| --- | --- | --- |
+| `option` | `EChartsOption` | ECharts の option。そのまま渡す。 |
+| `height` | `string \| number` | 高さ。数値は px。`className` で決めても良い。 |
+| `loading` | `boolean` | ECharts のローディング表示を出す。 |
+| `theme` | `string \| object` | `echarts.init` に渡すテーマ（名前または登録済みテーマ）。 |
+| `onEvents` | `Record<string, (params: unknown) => void>` | ECharts のイベント購読（`click` など）。 |
+| `ariaLabel` | `string` | チャートの説明。 |
+| `actions` | `boolean` | 画像保存などの操作を出す。 |
+| `fileName` | `string` | 保存時のファイル名。 |
+
+## 配色を決める
+
+系列の色は `option.color` で指定します。テーマの `--chart-1` 〜 `--chart-5` に揃えたいときは、
+ECharts はキャンバス描画で CSS 変数を読めないため、色の実値を渡してください。
+
+```ts
+const option: EChartsOption = {
+  color: ["#3b82f6", "#f59e0b", "#10b981"],
+  series: [{ type: "bar", data: [1, 2, 3] }],
+};
+```
+
+複数チャートで配色を使い回すなら、[`echarts.registerTheme`](https://echarts.apache.org/en/api.html#echarts.registerTheme)
+でテーマを登録し、その名前を `theme` プロップに渡すのが簡潔です。
+
+## 凡例と重ならないようにする
+
+`legend` を出すときは `top: 0` を付け、`grid.top` でプロット領域を下げてください。省くと凡例が
+プロットに重なります。
+
+```ts
+legend: { top: 0 },
+grid: { top: 32, containLabel: true },
+```
+
+> [!NOTE]
+> `echarts` を直接 import しないでください。管理されたスタックを差し替えられるようにするため、
+> 入り口は `EChart` と `EChartsOption` 型に絞ってあります。