@squadbase/vantage 0.0.1 → 0.1.1

package/docs/ja/ui/scroll-area.md

@@ -0,0 +1,24 @@
+# ScrollArea
+
+> OS 依存しないスクロールバーを持つ領域。
+
+高さを固定した領域に、OS 標準ではないスクロールバーを付けます。ドロップダウンの中身や、長い
+ログの表示に使います。
+
+```tsx
+import { ScrollArea, ScrollBar } from "@squadbase/vantage/ui";
+```
+
+高さ（または幅）は `className` で指定します。既定は縦スクロールで、横に流したいときは
+`ScrollBar orientation="horizontal"` を子に置きます。
+
+```tsx
+<ScrollArea className="w-96 whitespace-nowrap">
+  <div className="flex gap-3">…</div>
+  <ScrollBar orientation="horizontal" />
+</ScrollArea>
+```
+
+> [!NOTE]
+> スクロールバー自体を消したいだけなら、`no-scrollbar` ユーティリティが `theme.css` に定義されて
+> います。

package/docs/ja/ui/select.md

@@ -0,0 +1,64 @@
+# Select
+
+> 単一選択のセレクト。onValueChange は null を渡しうる。
+
+候補から 1 つ選ぶ入力です。候補が多くて検索したい場合は
+[`SearchableSelect`](parts/searchable-select)、少数を横並びで見せたい場合は
+[`SegmentedControl`](parts/segmented-control) を検討してください。
+
+```tsx
+import {
+  Select,
+  SelectTrigger,
+  SelectValue,
+  SelectContent,
+  SelectGroup,
+  SelectLabel,
+  SelectItem,
+  SelectSeparator,
+  SelectScrollUpButton,
+  SelectScrollDownButton,
+} from "@squadbase/vantage/ui";
+```
+
+## パーツ
+
+| パーツ | 役割 |
+| --- | --- |
+| `Select` | 状態。`value` / `defaultValue` / `onValueChange` / `items` |
+| `SelectTrigger` | 閉じているときの見た目。`size`: `default` \| `sm` |
+| `SelectValue` | 選択中の表示。`placeholder` は未選択時 |
+| `SelectContent` | 開いたときのリスト |
+| `SelectGroup` + `SelectLabel` | 見出し付きのグループ |
+| `SelectItem` | 1 項目。`value` は必須 |
+
+> [!WARNING]
+> `onValueChange` は **`string | null`** を渡します（Base UI では選択解除がありうるため）。
+> `null` を握りつぶすガードを必ず書いてください。
+>
+> ```tsx
+> <Select onValueChange={(value) => value !== null && setRegion(value)}>
+> ```
+
+> [!WARNING]
+> `SelectValue` は既定で**選択中の `value` をそのまま表示します** — `SelectItem` の中身は見ません。
+> `value="kanto"` なら、トリガーには「関東」ではなく `kanto` と出ます。値とラベルの対応を
+> `items` に渡してください。
+>
+> ```tsx
+> const regions = { hokkaido: "北海道", kanto: "関東", kansai: "関西" };
+>
+> <Select items={regions} value={region} onValueChange={…}>
+>   <SelectTrigger><SelectValue placeholder="地域を選ぶ" /></SelectTrigger>
+>   …
+> </Select>;
+> ```
+>
+> `items` を持たせたくない場合は、`SelectValue` の children に関数を渡しても同じことができます。
+>
+> ```tsx
+> <SelectValue>{(value) => regions[value] ?? "地域を選ぶ"}</SelectValue>
+> ```
+
+`SelectContent` は既定で選択中の項目をトリガーに重ねて開きます。素直に下へ開かせたいときは
+`alignItemWithTrigger={false}` を渡します。

package/docs/ja/ui/separator.md

@@ -0,0 +1,15 @@
+# Separator
+
+> 1 本の区切り線。
+
+内容を分ける線です。`orientation="vertical"` にするときは、親に高さが要ります。
+
+```tsx
+import { Separator } from "@squadbase/vantage/ui";
+```
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | 線の向き。 |
+
+装飾目的の線なので、支援技術には読み上げられません。

package/docs/ja/ui/sheet.md

@@ -0,0 +1,28 @@
+# Sheet
+
+> 画面の端から出るパネル。
+
+画面の端から滑り出すパネルです。フィルタ一式や詳細の編集など、モーダルより広い面積が要る場面に
+向いています。
+
+```tsx
+import {
+  Sheet,
+  SheetTrigger,
+  SheetContent,
+  SheetHeader,
+  SheetTitle,
+  SheetDescription,
+  SheetFooter,
+  SheetClose,
+} from "@squadbase/vantage/ui";
+```
+
+構成は [`Dialog`](ui/dialog) と同じで、違うのは出てくる向きだけです。
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `side` | `"top" \| "right" \| "bottom" \| "left"` | `"right"` | `SheetContent` に渡す。どの端から出すか。 |
+
+`SheetTitle` は支援技術のために必須です。見せたくない場合も置いた上で `className="sr-only"` に
+してください。

package/docs/ja/ui/sidebar.md

@@ -0,0 +1,92 @@
+# Sidebar
+
+> 折りたためるアプリのサイドバー一式。
+
+アプリ全体のナビゲーションを組むための、20 以上のパーツからなるキットです。ナビゲーションの
+定義を配列で渡すだけで済ませたいなら、これを直接使うより
+[`AppShell`](parts/app-shell) の方が早く終わります。
+
+```tsx
+import {
+  Sidebar,
+  SidebarProvider,
+  SidebarInset,
+  SidebarTrigger,
+  SidebarHeader,
+  SidebarContent,
+  SidebarFooter,
+  SidebarGroup,
+  SidebarGroupLabel,
+  SidebarGroupContent,
+  SidebarGroupAction,
+  SidebarMenu,
+  SidebarMenuItem,
+  SidebarMenuButton,
+  SidebarMenuAction,
+  SidebarMenuBadge,
+  SidebarMenuSkeleton,
+  SidebarMenuSub,
+  SidebarMenuSubItem,
+  SidebarMenuSubButton,
+  SidebarSeparator,
+  SidebarInput,
+  SidebarRail,
+  useSidebar,
+} from "@squadbase/vantage/ui";
+```
+
+## 骨組み
+
+`SidebarProvider` が開閉の状態を持ち、`Sidebar` と `SidebarInset`（本文側）がその中に並びます。
+
+```tsx
+<SidebarProvider>
+  <Sidebar>
+    <SidebarHeader>Acme Analytics</SidebarHeader>
+    <SidebarContent>
+      <SidebarGroup>
+        <SidebarGroupLabel>分析</SidebarGroupLabel>
+        <SidebarGroupContent>
+          <SidebarMenu>
+            <SidebarMenuItem>
+              <SidebarMenuButton isActive>概要</SidebarMenuButton>
+            </SidebarMenuItem>
+            <SidebarMenuItem>
+              <SidebarMenuButton>売上</SidebarMenuButton>
+              <SidebarMenuBadge>12</SidebarMenuBadge>
+            </SidebarMenuItem>
+          </SidebarMenu>
+        </SidebarGroupContent>
+      </SidebarGroup>
+    </SidebarContent>
+    <SidebarRail />
+  </Sidebar>
+
+  <SidebarInset>
+    <SidebarTrigger />
+    {children}
+  </SidebarInset>
+</SidebarProvider>
+```
+
+## 覚えておくと効くもの
+
+| もの | 効果 |
+| --- | --- |
+| `SidebarMenuButton` の `isActive` | 現在地の強調 |
+| `SidebarMenuButton` の `tooltip` | 折りたたみ時にラベルをツールチップで見せる |
+| `SidebarMenuButton` の `render` | リンクコンポーネントに差し替える |
+| `SidebarRail` | 端をドラッグして開閉できる細い帯 |
+| `SidebarMenuSkeleton` | 読み込み中のメニュー |
+| `useSidebar()` | 開閉状態とモバイル判定を読む |
+
+## リンクにする
+
+```tsx
+import { Link } from "@squadbase/vantage/router";
+
+<SidebarMenuButton render={<Link to="/sales" />}>売上</SidebarMenuButton>;
+```
+
+> [!NOTE]
+> `asChild` は Base UI にはありません。`render` に要素を渡します。

package/docs/ja/ui/skeleton.md

@@ -0,0 +1,16 @@
+# Skeleton
+
+> 中身と同じ形をした読み込み中の箱。
+
+あとから入る中身と同じ形の箱を、読み込み中に置いておくためのものです。
+[`Loading`](ui/loading) の全画面スピナーと違い、レイアウトを保ったまま待てます。
+
+```tsx
+import { Skeleton } from "@squadbase/vantage/ui";
+```
+
+大きさは `className` で決めます（`h-4 w-32` のように）。実際に入る要素と同じ高さにしておくと、
+読み込み完了時に画面が跳ねません。
+
+ダッシュボードのタイルには、同じ形をあらかじめ組んである
+[`DashboardCardSkeleton`](parts/dashboard-card) が使えます。

package/docs/ja/ui/slider.md

@@ -0,0 +1,21 @@
+# Slider
+
+> つまみで数値を選ぶ。範囲指定にも対応。
+
+数値をつまみで選ぶ入力です。`value` に配列を渡すとつまみが増え、範囲指定になります。
+
+```tsx
+import { Slider } from "@squadbase/vantage/ui";
+```
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `value` | `number \| number[]` |  | つまみの位置。配列なら範囲指定になる。 |
+| `defaultValue` | `number \| number[]` |  | 非制御時の初期値。 |
+| `onValueChange` | `(value: number \| number[]) => void` |  | 変更時。`value` に渡した形と同じ形が返る。 |
+| `min` | `number` | `0` | 下限。 |
+| `max` | `number` | `100` | 上限。 |
+| `step` | `number` | `1` | 刻み。 |
+| `disabled` | `boolean` |  | 操作を無効にする。 |
+
+つまみは端で内側に収まるよう配置されるので、`min` / `max` のところでトラックからはみ出しません。

package/docs/ja/ui/spinner.md

@@ -0,0 +1,14 @@
+# Spinner
+
+> いちばん小さい待機表示。
+
+回転するアイコンだけの待機表示です。ボタンの中など、狭い場所に置きます。
+
+```tsx
+import { Spinner } from "@squadbase/vantage/ui";
+```
+
+`<svg>` そのものなので、大きさは `size-*`、色は `text-*` で決まります。
+
+画面ぶんの読み込みには [`Loading`](ui/loading)、レイアウトを保ったまま待たせるなら
+[`Skeleton`](ui/skeleton) を使ってください。

package/docs/ja/ui/switch.md

@@ -0,0 +1,19 @@
+# Switch
+
+> 即時に効く設定のトグル。
+
+その場で効く設定の切り替えです。フォームを送信して初めて効く項目には
+[`Checkbox`](ui/checkbox) の方が適しています。
+
+```tsx
+import { Switch } from "@squadbase/vantage/ui";
+```
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `checked` | `boolean` |  | オン/オフ。 |
+| `onCheckedChange` | `(checked: boolean) => void` |  | 変更時。 |
+| `size` | `"default" \| "sm"` | `"default"` | 大きさ。 |
+| `disabled` | `boolean` |  | 操作を無効にする。 |
+
+ラベルは [`Label`](ui/label) で包むと、文字の側を押しても切り替わります。

package/docs/ja/ui/table.md

@@ -0,0 +1,24 @@
+# Table
+
+> 素の表プリミティブ。並べ替えや検索が要るなら DataTable を。
+
+`<table>` 一式にテーマの罫線と余白を付けただけのプリミティブです。並べ替え・検索・ページングが
+要るなら [`DataTable`](parts/data-table) を使ってください。
+
+```tsx
+import {
+  Table,
+  TableHeader,
+  TableBody,
+  TableFooter,
+  TableRow,
+  TableHead,
+  TableCell,
+  TableCaption,
+} from "@squadbase/vantage/ui";
+```
+
+対応は素の HTML そのままです — `Table` は `<table>`、`TableHeader` は `<thead>`、`TableHead` は
+`<th>`、`TableCell` は `<td>`。props もネイティブのものが通ります。
+
+数値の列は `text-right tabular-nums` を付けると桁が揃います。

package/docs/ja/ui/tabs.md

@@ -0,0 +1,24 @@
+# Tabs
+
+> 表示を切り替えるタブ。
+
+同じ場所に複数の内容を出し分けます。ボタン 2〜4 個で切り替えるだけなら
+[`SegmentedControl`](parts/segmented-control) の方が場所を取りません。
+
+```tsx
+import { Tabs, TabsList, TabsTrigger, TabsContent, tabsListVariants } from "@squadbase/vantage/ui";
+```
+
+## パーツ
+
+| パーツ | 役割 |
+| --- | --- |
+| `Tabs` | 状態。`value` / `defaultValue` / `onValueChange`、`orientation` |
+| `TabsList` | タブの帯。`variant`: `default`（塗り）\| `line`（下線） |
+| `TabsTrigger` | タブ 1 つ。`value` は必須 |
+| `TabsContent` | 対応する中身 |
+
+URL に状態を残したい場合は、`value` を検索パラメータと結び付けてください
+（[ルーティング](routing) を参照）。
+
+`orientation="vertical"` にすると縦並びになります。

package/docs/ja/ui/textarea.md

@@ -0,0 +1,15 @@
+# Textarea
+
+> 複数行のテキスト入力。
+
+複数行の入力です。props はネイティブの `<textarea>` と同じです。
+
+```tsx
+import { Textarea } from "@squadbase/vantage/ui";
+```
+
+高さは `rows` か `className`（`min-h-32` など）で決めます。`aria-invalid` を付けるとエラー色に
+なるのは [`Input`](ui/input) と同じです。
+
+上下にツールバーを付けたいときは、[`InputGroup`](ui/input-group) の
+`InputGroupTextarea` と `align="block-end"` の組み合わせが使えます。

package/docs/ja/ui/toggle-group.md

@@ -0,0 +1,27 @@
+# ToggleGroup
+
+> トグルの束。value は常に配列。
+
+複数のトグルをひとつの帯にまとめます。Base UI では**単一選択でも `value` は配列**です — 単一
+選択が欲しいだけなら [`SegmentedControl`](parts/segmented-control) がその面倒を
+引き受けます。
+
+```tsx
+import { ToggleGroup, ToggleGroupItem } from "@squadbase/vantage/ui";
+```
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `value` | `string[]` |  | 選択中の値。**単一選択でも配列**。 |
+| `onValueChange` | `(value: string[]) => void` |  | 変更時。配列で返る。 |
+| `toggleMultiple` | `boolean` |  | 複数選択を許す。 |
+| `variant` | `"default" \| "outline"` | `"default"` |  |
+| `size` | `"default" \| "sm" \| "lg"` | `"default"` |  |
+| `spacing` | `number` | `2` | 項目の間隔。`0` で連結された帯になる。 |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` |  |
+
+> [!WARNING]
+> Radix 版の `type="single"` / `type="multiple"` はありません。単一選択は「配列の長さを 1 に保つ」
+> という運用になります。その処理は
+> [`SegmentedControl`](parts/segmented-control) に入っているので、
+> 単一選択ならそちらを使うのが確実です。

package/docs/ja/ui/toggle.md

@@ -0,0 +1,19 @@
+# Toggle
+
+> 押した状態を保つボタン。
+
+押すとその状態が残るボタンです。複数を束ねたいときは
+[`ToggleGroup`](ui/toggle-group) を使います。
+
+```tsx
+import { Toggle, toggleVariants } from "@squadbase/vantage/ui";
+```
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `pressed` | `boolean` |  | 押された状態。 |
+| `onPressedChange` | `(pressed: boolean) => void` |  | 変更時。 |
+| `variant` | `"default" \| "outline"` | `"default"` | 見た目。 |
+| `size` | `"default" \| "sm" \| "lg"` | `"default"` | 大きさ。 |
+
+アイコンだけの場合は `aria-label` を必ず付けてください。

package/docs/ja/ui/tooltip.md

@@ -0,0 +1,22 @@
+# Tooltip
+
+> ホバーで出る短い説明。
+
+ホバーやフォーカスで出る短い説明です。中に操作を置きたくなったら
+[`Popover`](ui/popover) の出番です。
+
+```tsx
+import { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider } from "@squadbase/vantage/ui";
+```
+
+## パーツ
+
+| パーツ | 役割 |
+| --- | --- |
+| `TooltipProvider` | 遅延の共有設定。`delay`（既定 `0`、ミリ秒） |
+| `Tooltip` | 1 つ分の状態 |
+| `TooltipTrigger` | きっかけ。`render` で任意の要素にする |
+| `TooltipContent` | 中身。`side`（既定 `top`）/ `align` / `sideOffset` |
+
+> [!NOTE]
+> ツールチップはタッチ環境では出ません。**必要な情報をツールチップだけに置かないでください**。

package/docs/ja/ui/use-is-mobile.md

@@ -0,0 +1,18 @@
+# useIsMobile()
+
+> 画面幅が狭いかどうかを返すフック。
+
+ビューポートが狭い（768px 未満）かどうかを返すフックです。[`Sidebar`](ui/sidebar) が
+モバイルでシートに切り替わる判定にも使っています。
+
+```tsx
+import { useIsMobile } from "@squadbase/vantage/ui";
+
+export default function Overview() {
+  const isMobile = useIsMobile();
+  return <EChart option={option} height={isMobile ? 200 : 360} />;
+}
+```
+
+`matchMedia` を購読しているので、幅を変えると再描画されます。初回描画では `false` から始まる点に
+注意してください（レイアウトの分岐は、可能なら CSS のブレークポイントで書く方が確実です）。

package/docs/ja/ui-and-theming.md

@@ -0,0 +1,95 @@
+# UI とテーマ
+
+> 組み込み UI キットを import する。styles.css でテーマトークンを上書きする。add でソースをコピーする。
+
+Vantage は **shadcn/ui**（Base UI 版）と、Tailwind v4 ベースのテーマを同梱しています。設定不要で
+すぐ使えます。
+
+## UI キットを使う
+
+入り口は 2 つです。shadcn/ui のプリミティブは `@squadbase/vantage/ui`、それらを組み上げた
+ダッシュボード部品は `@squadbase/vantage/components` から import します。
+
+```tsx
+import { Button } from "@squadbase/vantage/ui";
+import { DashboardCardPreset, MetricValue } from "@squadbase/vantage/components";
+
+export default function Overview() {
+  return (
+    <div className="grid gap-4 p-6 md:grid-cols-3">
+      <DashboardCardPreset title="売上">
+        <MetricValue className="my-0">¥1,240,000</MetricValue>
+      </DashboardCardPreset>
+      <DashboardCardPreset title="新規顧客">
+        <MetricValue className="my-0">128</MetricValue>
+      </DashboardCardPreset>
+      <DashboardCardPreset title="解約率">
+        <MetricValue className="my-0">2.1%</MetricValue>
+      </DashboardCardPreset>
+    </div>
+  );
+}
+```
+
+`/ui` にあるもの（抜粋）: `Button`、`Card`、`Table` プリミティブ、`Tabs`、`Input` / `Select` /
+`Checkbox` / `Switch` / `Slider`、`Calendar`、`Dialog` / `Sheet` / `Popover` / `Tooltip` /
+`DropdownMenu`、`Sidebar`、`Alert` / `Skeleton` / `Spinner`、`Loading` / `Empty` / `ErrorState`。
+
+`/components` にあるもの（抜粋）: `PageShell`、`AppShell`、`DashboardCard`、`DataTable`、
+`EChart`、`FunnelSteps`、`FilterBar`、`DateRangePicker`、`MetricValue`、`TrendIndicator`。
+
+各コンポーネントの props と使い方は [コンポーネント](components) タブにまとめてあります。
+
+## Tailwind はそのまま使える
+
+`className` に Tailwind ユーティリティを書くだけで効きます。`tailwind.config` も `postcss.config`
+も書きません（書くと禁止ファイルとしてエラーになります）。クラス結合には `cn()` が使えます。
+
+```tsx
+import { cn } from "@squadbase/vantage/ui";
+
+<div className={cn("p-4", isActive && "bg-accent")} />;
+```
+
+## テーマトークンを上書きする
+
+色や角丸などのデザイントークンは CSS 変数です。上書きしたいときは、プロジェクトルートに
+`styles.css` を置き、**CSS 変数だけ**を上書きします。このファイルはテーマの後に自動 import されます。
+
+```css
+/* styles.css — CSS 変数の上書きのみ */
+:root {
+  --primary: oklch(0.55 0.22 265);
+}
+.dark,
+[data-theme="dark"] {
+  --primary: oklch(0.72 0.19 265);
+}
+```
+
+> [!WARNING]
+> `styles.css` で許されるのは **CSS 変数（テーマトークン）の上書き**です。`tailwind.config` の
+> 持ち込みはできません（禁止ファイル）。
+
+トークンは shadcn/ui の neutral パレット（oklch）に、チャート用の `--chart-1` 〜 `--chart-5` と
+サイドバー用の `--sidebar-*` を足したものです。`--chart-*` を変えると
+[`EChart`](parts/echart) の配色も一緒に変わります。チャートは CSS 変数を実際に読み取って
+テーマを組み立てるためです。
+
+## ソースを編集したいとき: `vantage add`
+
+コンポーネントの中身を自分のものにしたいときは、編集可能なソースを `components/` にコピーします。
+
+```bash
+vantage add ui data-table      # 編集可能な DataTable をコピー
+vantage add block sales-overview
+```
+
+> [!NOTE]
+> 現行プロトタイプで `vantage add` がコピーできるのは `data-table`（ui）と `sales-overview`（block）
+> のみです。その他の UI コンポーネントは import 専用です。
+
+## 次に読む
+
+- [コンポーネント](components) — 全コンポーネントの props リファレンス
+- [CLI リファレンス](cli-reference) — 全コマンド

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@squadbase/vantage",
-  "version": "0.0.1",
+  "version": "0.1.1",
   "description": "Data dashboard framework for Squadbase Editor. Vite-powered, config-free, one-file first.",
   "type": "module",
   "license": "MIT",
@@ -50,6 +50,14 @@
       "types": "./dist/ui/index.d.ts",
       "default": "./dist/ui/index.js"
     },
+    "./components": {
+      "types": "./dist/components/index.d.ts",
+      "default": "./dist/components/index.js"
+    },
+    "./markdown": {
+      "types": "./dist/markdown/index.d.ts",
+      "default": "./dist/markdown/index.js"
+    },
     "./server": {
       "types": "./dist/server/index.d.ts",
       "default": "./dist/server/index.js"
@@ -71,25 +79,42 @@
   },
   "files": [
     "dist",
+    "docs",
     "theme.css",
-    "registry"
+    "registry",
+    "skills",
+    "templates"
   ],
   "scripts": {
-    "build": "tsup",
+    "build": "node scripts/build-docs.mjs && tsup",
+    "build:docs": "node scripts/build-docs.mjs",
     "dev": "tsup --watch",
     "typecheck": "tsc --noEmit",
-    "prepublishOnly": "tsup"
+    "prepublishOnly": "node scripts/build-docs.mjs && tsup"
   },
   "dependencies": {
+    "@base-ui/react": "^1.6.0",
     "@hono/node-server": "^2.0.8",
+    "@streamdown/code": "^1.1.1",
     "@tailwindcss/vite": "^4.3.2",
     "@tanstack/react-query": "^5.101.2",
     "@tanstack/react-router": "^1.170.17",
+    "@tanstack/react-table": "^8.21.3",
     "@vitejs/plugin-react": "^6.0.3",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "cmdk": "^1.1.1",
+    "date-fns": "^4.1.0",
+    "echarts": "^6.0.0",
     "esbuild": "^0.28.1",
     "hono": "^4.12.30",
+    "lucide-react": "^0.468.0",
     "picocolors": "^1.1.1",
+    "react-day-picker": "^10.0.1",
+    "streamdown": "^2.5.0",
+    "tailwind-merge": "^3.0.0",
     "tailwindcss": "^4.3.2",
+    "tw-animate-css": "^1.0.0",
     "vite": "^8.1.4"
   },
   "peerDependencies": {