@squadbase/vantage 0.2.0 → 0.2.2

package/dist/index.d.ts

@@ -10,6 +10,6 @@ import 'react';
  */
 
 /** Framework version, kept in sync with package.json at build time. */
-declare const VERSION = "0.2.0";
+declare const VERSION = "0.2.2";
 
 export { VERSION };

package/dist/index.js

@@ -6,7 +6,7 @@ function definePage(config) {
 }
 
 // src/index.ts
-var VERSION = "0.2.0";
+var VERSION = "0.2.2";
 
 export { VERSION, definePage };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/runtime/define-page.ts","../src/index.ts"],"names":[],"mappings":";;;AAyCO,SAAS,WAAW,MAAA,EAAgC;AACzD,EAAA,OAAO,MAAA;AACT;;;AChCO,IAAM,OAAA,GAAU","file":"index.js","sourcesContent":["import type { ComponentType, ReactNode } from \"react\"\n\n/**\n * Optional per-page configuration. The only required part of a page module is\n * its default-exported component; `definePage` covers everything else.\n */\nexport interface PageConfig {\n  /** Document title applied when this route is active. */\n  title?: string\n  /** Description metadata for the page. */\n  description?: string\n  /**\n   * Short label for navigation built from `useRoutes()`. Defaults to `title`,\n   * which is often too long for a nav (\"Overview · Acme Analytics\").\n   */\n  navLabel?: string\n  /**\n   * Component rendered while the route is loading.\n   * (Reserved — not yet applied to Vantage's code-split routes in the prototype.)\n   */\n  pendingComponent?: ComponentType\n  /**\n   * Component rendered when the route throws.\n   * (Reserved — not yet applied to Vantage's code-split routes in the prototype.)\n   */\n  errorComponent?: ComponentType<{ error: unknown }>\n  /**\n   * Validate/transform the URL search params for this route.\n   * (Reserved — not yet applied to Vantage's code-split routes in the prototype.)\n   */\n  validateSearch?: (search: Record<string, unknown>) => Record<string, unknown>\n}\n\n/**\n * Declare optional page configuration.\n *\n * ```tsx\n * export const page = definePage({ title: \"Monthly Analysis\" })\n * export default function MonthlyAnalysis() { return <div/> }\n * ```\n */\nexport function definePage(config: PageConfig): PageConfig {\n  return config\n}\n\n/** Convenience type for a Vantage page component. */\nexport type PageComponent = ComponentType & { (): ReactNode }\n","/**\n * `@squadbase/vantage` — public runtime surface.\n *\n * The only import most pages need. Server state lives in\n * `@squadbase/vantage/query`, navigation in `@squadbase/vantage/router`,\n * UI in `@squadbase/vantage/ui`, and API types in `@squadbase/vantage/server`.\n */\nexport { definePage } from \"./runtime/define-page\"\nexport type { PageConfig, PageComponent } from \"./runtime/define-page\"\n\n/** Framework version, kept in sync with package.json at build time. */\nexport const VERSION = \"0.2.0\"\n"]}
+{"version":3,"sources":["../src/runtime/define-page.ts","../src/index.ts"],"names":[],"mappings":";;;AAyCO,SAAS,WAAW,MAAA,EAAgC;AACzD,EAAA,OAAO,MAAA;AACT;;;AChCO,IAAM,OAAA,GAAU","file":"index.js","sourcesContent":["import type { ComponentType, ReactNode } from \"react\"\n\n/**\n * Optional per-page configuration. The only required part of a page module is\n * its default-exported component; `definePage` covers everything else.\n */\nexport interface PageConfig {\n  /** Document title applied when this route is active. */\n  title?: string\n  /** Description metadata for the page. */\n  description?: string\n  /**\n   * Short label for navigation built from `useRoutes()`. Defaults to `title`,\n   * which is often too long for a nav (\"Overview · Acme Analytics\").\n   */\n  navLabel?: string\n  /**\n   * Component rendered while the route is loading.\n   * (Reserved — not yet applied to Vantage's code-split routes in the prototype.)\n   */\n  pendingComponent?: ComponentType\n  /**\n   * Component rendered when the route throws.\n   * (Reserved — not yet applied to Vantage's code-split routes in the prototype.)\n   */\n  errorComponent?: ComponentType<{ error: unknown }>\n  /**\n   * Validate/transform the URL search params for this route.\n   * (Reserved — not yet applied to Vantage's code-split routes in the prototype.)\n   */\n  validateSearch?: (search: Record<string, unknown>) => Record<string, unknown>\n}\n\n/**\n * Declare optional page configuration.\n *\n * ```tsx\n * export const page = definePage({ title: \"Monthly Analysis\" })\n * export default function MonthlyAnalysis() { return <div/> }\n * ```\n */\nexport function definePage(config: PageConfig): PageConfig {\n  return config\n}\n\n/** Convenience type for a Vantage page component. */\nexport type PageComponent = ComponentType & { (): ReactNode }\n","/**\n * `@squadbase/vantage` — public runtime surface.\n *\n * The only import most pages need. Server state lives in\n * `@squadbase/vantage/query`, navigation in `@squadbase/vantage/router`,\n * UI in `@squadbase/vantage/ui`, and API types in `@squadbase/vantage/server`.\n */\nexport { definePage } from \"./runtime/define-page\"\nexport type { PageConfig, PageComponent } from \"./runtime/define-page\"\n\n/** Framework version, kept in sync with package.json at build time. */\nexport const VERSION = \"0.2.2\"\n"]}

package/dist/router/index.d.ts

@@ -67,7 +67,7 @@ interface SearchStateOptions {
  *
  * ```tsx
  * const [region, setRegion] = useSearchParam("region", "all")
- * <SegmentedControl value={region} onValueChange={setRegion} options={REGIONS} />
+ * <SegmentedControl value={region} onChange={setRegion} options={REGIONS} />
  * ```
  *
  * Writing the default value (or `null`) drops the key from the URL.

package/dist/router/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/router/routes.ts","../../src/router/search.ts","../../src/router/index.ts"],"names":["TanstackLink","useParamsBase","useSearch","useSearchBase","useNavigate","useNavigateBase"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Route-introspection hooks. The route list comes from the generated manifest,\n * so a nav built on `useRoutes()` picks up a new page file the moment it is\n * created — no hand-maintained link array.\n */\nimport { useRouterState } from \"@tanstack/react-router\"\nimport { findRoute, getRoutes, type RouteInfo } from \"./registry\"\n\n/**\n * Every page route in the app, in the framework's scan order (shallow before\n * deep, static before dynamic, alphabetical) — the order a nav wants.\n *\n * ```tsx\n * // Dynamic routes have no single URL, so a nav lists only static ones.\n * const routes = useRoutes().filter((route) => !route.dynamic)\n * routes.map((route) => <Link key={route.path} to={route.to}>{route.label}</Link>)\n * ```\n */\nexport function useRoutes(): readonly RouteInfo[] {\n  return getRoutes()\n}\n\n/**\n * The route currently rendered, or `undefined` on the 404 route (no page\n * matched). Use it for breadcrumbs or a page header that mirrors `definePage`.\n */\nexport function useCurrentRoute(): RouteInfo | undefined {\n  // Selecting the path string (not the match object) keeps the subscription\n  // stable — the component re-renders on navigation, not on every router tick.\n  const path = useRouterState({\n    select: (state) => {\n      const matches = state.matches\n      const leaf = matches[matches.length - 1] as\n        | { staticData?: { routePath?: string } }\n        | undefined\n      return leaf?.staticData?.routePath\n    },\n  })\n  return path ? findRoute(path) : undefined\n}\n","/**\n * URL-backed component state. A dashboard's filters belong in the URL: the view\n * survives a reload and can be pasted to a colleague. These hooks read and write\n * a single search-param key with a `useState`-shaped API.\n */\nimport { useCallback } from \"react\"\nimport { useNavigate, useSearch } from \"@tanstack/react-router\"\n\nexport interface SearchStateOptions {\n  /**\n   * Replace the current history entry instead of pushing a new one.\n   * Defaults to `true` so dragging a slider doesn't fill the back button.\n   */\n  replace?: boolean\n}\n\n/* eslint-disable @typescript-eslint/no-explicit-any */\n\nfunction useRawSearch(): Record<string, unknown> {\n  return useSearch({ strict: false }) as any\n}\n\n/**\n * Writer for one key. Passing `undefined` removes the key so defaults never\n * show up in the URL.\n */\nfunction useSearchWriter(key: string, options: SearchStateOptions): (next: unknown) => void {\n  const navigate = useNavigate() as any\n  const replace = options.replace ?? true\n  return useCallback(\n    (next: unknown) => {\n      // No `to`: TanStack keeps the current route and its path params, so this\n      // works unchanged on a dynamic route like `/sales/$customerId`.\n      navigate({\n        search: (prev: Record<string, unknown>) => {\n          const merged = { ...prev }\n          if (next === undefined) delete merged[key]\n          else merged[key] = next\n          return merged\n        },\n        replace,\n      })\n    },\n    [navigate, key, replace],\n  )\n}\n\n/**\n * A string search param, as `useState`. The value is always a string —\n * TanStack parses `?year=2024` into a number, and this hook normalizes it back.\n *\n * ```tsx\n * const [region, setRegion] = useSearchParam(\"region\", \"all\")\n * <SegmentedControl value={region} onValueChange={setRegion} options={REGIONS} />\n * ```\n *\n * Writing the default value (or `null`) drops the key from the URL.\n */\nexport function useSearchParam(\n  key: string,\n  defaultValue = \"\",\n  options: SearchStateOptions = {},\n): [string, (value: string | null) => void] {\n  const search = useRawSearch()\n  const write = useSearchWriter(key, options)\n\n  const raw = search[key]\n  const value = raw === undefined || raw === null ? defaultValue : String(raw)\n\n  const set = useCallback(\n    (next: string | null) => {\n      write(next === null || next === defaultValue ? undefined : next)\n    },\n    [write, defaultValue],\n  )\n\n  return [value, set]\n}\n\n/**\n * Any JSON-serializable search param, as `useState` — arrays for a multi-select,\n * an object for a whole filter bar. Supports a functional update.\n *\n * ```tsx\n * const [segments, setSegments] = useSearchState<string[]>(\"segments\", [])\n * setSegments((prev) => [...prev, \"enterprise\"])\n * ```\n *\n * Writing a value deep-equal to the default drops the key from the URL.\n */\nexport function useSearchState<T>(\n  key: string,\n  defaultValue: T,\n  options: SearchStateOptions = {},\n): [T, (value: T | ((prev: T) => T)) => void] {\n  const search = useRawSearch()\n  const write = useSearchWriter(key, options)\n\n  const raw = search[key]\n  const value = raw === undefined || raw === null ? defaultValue : (raw as T)\n\n  const set = useCallback(\n    (next: T | ((prev: T) => T)) => {\n      const resolved = typeof next === \"function\" ? (next as (prev: T) => T)(value) : next\n      // Structural comparison: the parsed value is plain JSON, so stringify is\n      // both sufficient and cheap at filter sizes.\n      const isDefault = JSON.stringify(resolved) === JSON.stringify(defaultValue)\n      write(isDefault ? undefined : resolved)\n    },\n    [write, value, defaultValue],\n  )\n\n  return [value, set]\n}\n","/**\n * Vantage's thin router API. Users depend on `@squadbase/vantage/router`\n * instead of `@tanstack/react-router`, so the underlying router can evolve\n * without touching user code. Only the ergonomic, SPA-relevant surface is\n * exposed; typed-route generics are intentionally relaxed to plain strings.\n */\nimport {\n  Link as TanstackLink,\n  Outlet,\n  useNavigate as useNavigateBase,\n  useParams as useParamsBase,\n  useSearch as useSearchBase,\n  useRouterState,\n  redirect,\n  notFound,\n} from \"@tanstack/react-router\"\nimport { createElement, type ReactNode } from \"react\"\n\nexport { Outlet, useRouterState, redirect, notFound }\n\nexport { useRoutes, useCurrentRoute } from \"./routes\"\nexport type { RouteInfo } from \"./registry\"\n\nexport { useSearchParam, useSearchState } from \"./search\"\nexport type { SearchStateOptions } from \"./search\"\n\nexport interface LinkProps {\n  to: string\n  params?: Record<string, string>\n  search?: Record<string, unknown>\n  hash?: string\n  replace?: boolean\n  className?: string\n  activeClassName?: string\n  children?: ReactNode\n  [key: string]: unknown\n}\n\n/** Client-side navigation link. */\nexport function Link({ activeClassName, className, ...props }: LinkProps): ReactNode {\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  const anyLink = TanstackLink as any\n  return createElement(anyLink, {\n    ...props,\n    className,\n    activeProps: activeClassName ? { className: `${className ?? \"\"} ${activeClassName}`.trim() } : undefined,\n  })\n}\n\n/** Route params for the current route (e.g. `{ customerId: \"42\" }`). */\nexport function useParams(): Record<string, string> {\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  return useParamsBase({ strict: false }) as any\n}\n\n/** Validated/raw search params for the current route. */\nexport function useSearch(): Record<string, unknown> {\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  return useSearchBase({ strict: false }) as any\n}\n\n/** Imperative navigation. `navigate({ to: \"/sales/42\" })`. */\nexport function useNavigate(): (opts: { to: string; params?: Record<string, string>; search?: Record<string, unknown>; replace?: boolean }) => void {\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  return useNavigateBase() as any\n}\n"]}
+{"version":3,"sources":["../../src/router/routes.ts","../../src/router/search.ts","../../src/router/index.ts"],"names":["TanstackLink","useParamsBase","useSearch","useSearchBase","useNavigate","useNavigateBase"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Route-introspection hooks. The route list comes from the generated manifest,\n * so a nav built on `useRoutes()` picks up a new page file the moment it is\n * created — no hand-maintained link array.\n */\nimport { useRouterState } from \"@tanstack/react-router\"\nimport { findRoute, getRoutes, type RouteInfo } from \"./registry\"\n\n/**\n * Every page route in the app, in the framework's scan order (shallow before\n * deep, static before dynamic, alphabetical) — the order a nav wants.\n *\n * ```tsx\n * // Dynamic routes have no single URL, so a nav lists only static ones.\n * const routes = useRoutes().filter((route) => !route.dynamic)\n * routes.map((route) => <Link key={route.path} to={route.to}>{route.label}</Link>)\n * ```\n */\nexport function useRoutes(): readonly RouteInfo[] {\n  return getRoutes()\n}\n\n/**\n * The route currently rendered, or `undefined` on the 404 route (no page\n * matched). Use it for breadcrumbs or a page header that mirrors `definePage`.\n */\nexport function useCurrentRoute(): RouteInfo | undefined {\n  // Selecting the path string (not the match object) keeps the subscription\n  // stable — the component re-renders on navigation, not on every router tick.\n  const path = useRouterState({\n    select: (state) => {\n      const matches = state.matches\n      const leaf = matches[matches.length - 1] as\n        | { staticData?: { routePath?: string } }\n        | undefined\n      return leaf?.staticData?.routePath\n    },\n  })\n  return path ? findRoute(path) : undefined\n}\n","/**\n * URL-backed component state. A dashboard's filters belong in the URL: the view\n * survives a reload and can be pasted to a colleague. These hooks read and write\n * a single search-param key with a `useState`-shaped API.\n */\nimport { useCallback } from \"react\"\nimport { useNavigate, useSearch } from \"@tanstack/react-router\"\n\nexport interface SearchStateOptions {\n  /**\n   * Replace the current history entry instead of pushing a new one.\n   * Defaults to `true` so dragging a slider doesn't fill the back button.\n   */\n  replace?: boolean\n}\n\n/* eslint-disable @typescript-eslint/no-explicit-any */\n\nfunction useRawSearch(): Record<string, unknown> {\n  return useSearch({ strict: false }) as any\n}\n\n/**\n * Writer for one key. Passing `undefined` removes the key so defaults never\n * show up in the URL.\n */\nfunction useSearchWriter(key: string, options: SearchStateOptions): (next: unknown) => void {\n  const navigate = useNavigate() as any\n  const replace = options.replace ?? true\n  return useCallback(\n    (next: unknown) => {\n      // No `to`: TanStack keeps the current route and its path params, so this\n      // works unchanged on a dynamic route like `/sales/$customerId`.\n      navigate({\n        search: (prev: Record<string, unknown>) => {\n          const merged = { ...prev }\n          if (next === undefined) delete merged[key]\n          else merged[key] = next\n          return merged\n        },\n        replace,\n      })\n    },\n    [navigate, key, replace],\n  )\n}\n\n/**\n * A string search param, as `useState`. The value is always a string —\n * TanStack parses `?year=2024` into a number, and this hook normalizes it back.\n *\n * ```tsx\n * const [region, setRegion] = useSearchParam(\"region\", \"all\")\n * <SegmentedControl value={region} onChange={setRegion} options={REGIONS} />\n * ```\n *\n * Writing the default value (or `null`) drops the key from the URL.\n */\nexport function useSearchParam(\n  key: string,\n  defaultValue = \"\",\n  options: SearchStateOptions = {},\n): [string, (value: string | null) => void] {\n  const search = useRawSearch()\n  const write = useSearchWriter(key, options)\n\n  const raw = search[key]\n  const value = raw === undefined || raw === null ? defaultValue : String(raw)\n\n  const set = useCallback(\n    (next: string | null) => {\n      write(next === null || next === defaultValue ? undefined : next)\n    },\n    [write, defaultValue],\n  )\n\n  return [value, set]\n}\n\n/**\n * Any JSON-serializable search param, as `useState` — arrays for a multi-select,\n * an object for a whole filter bar. Supports a functional update.\n *\n * ```tsx\n * const [segments, setSegments] = useSearchState<string[]>(\"segments\", [])\n * setSegments((prev) => [...prev, \"enterprise\"])\n * ```\n *\n * Writing a value deep-equal to the default drops the key from the URL.\n */\nexport function useSearchState<T>(\n  key: string,\n  defaultValue: T,\n  options: SearchStateOptions = {},\n): [T, (value: T | ((prev: T) => T)) => void] {\n  const search = useRawSearch()\n  const write = useSearchWriter(key, options)\n\n  const raw = search[key]\n  const value = raw === undefined || raw === null ? defaultValue : (raw as T)\n\n  const set = useCallback(\n    (next: T | ((prev: T) => T)) => {\n      const resolved = typeof next === \"function\" ? (next as (prev: T) => T)(value) : next\n      // Structural comparison: the parsed value is plain JSON, so stringify is\n      // both sufficient and cheap at filter sizes.\n      const isDefault = JSON.stringify(resolved) === JSON.stringify(defaultValue)\n      write(isDefault ? undefined : resolved)\n    },\n    [write, value, defaultValue],\n  )\n\n  return [value, set]\n}\n","/**\n * Vantage's thin router API. Users depend on `@squadbase/vantage/router`\n * instead of `@tanstack/react-router`, so the underlying router can evolve\n * without touching user code. Only the ergonomic, SPA-relevant surface is\n * exposed; typed-route generics are intentionally relaxed to plain strings.\n */\nimport {\n  Link as TanstackLink,\n  Outlet,\n  useNavigate as useNavigateBase,\n  useParams as useParamsBase,\n  useSearch as useSearchBase,\n  useRouterState,\n  redirect,\n  notFound,\n} from \"@tanstack/react-router\"\nimport { createElement, type ReactNode } from \"react\"\n\nexport { Outlet, useRouterState, redirect, notFound }\n\nexport { useRoutes, useCurrentRoute } from \"./routes\"\nexport type { RouteInfo } from \"./registry\"\n\nexport { useSearchParam, useSearchState } from \"./search\"\nexport type { SearchStateOptions } from \"./search\"\n\nexport interface LinkProps {\n  to: string\n  params?: Record<string, string>\n  search?: Record<string, unknown>\n  hash?: string\n  replace?: boolean\n  className?: string\n  activeClassName?: string\n  children?: ReactNode\n  [key: string]: unknown\n}\n\n/** Client-side navigation link. */\nexport function Link({ activeClassName, className, ...props }: LinkProps): ReactNode {\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  const anyLink = TanstackLink as any\n  return createElement(anyLink, {\n    ...props,\n    className,\n    activeProps: activeClassName ? { className: `${className ?? \"\"} ${activeClassName}`.trim() } : undefined,\n  })\n}\n\n/** Route params for the current route (e.g. `{ customerId: \"42\" }`). */\nexport function useParams(): Record<string, string> {\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  return useParamsBase({ strict: false }) as any\n}\n\n/** Validated/raw search params for the current route. */\nexport function useSearch(): Record<string, unknown> {\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  return useSearchBase({ strict: false }) as any\n}\n\n/** Imperative navigation. `navigate({ to: \"/sales/42\" })`. */\nexport function useNavigate(): (opts: { to: string; params?: Record<string, string>; search?: Record<string, unknown>; replace?: boolean }) => void {\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  return useNavigateBase() as any\n}\n"]}

package/dist/ui/index.d.ts

@@ -181,7 +181,7 @@ declare function ProgressValue({ className, ...props }: Progress$1.Value.Props):
 declare function ScrollArea({ className, children, ...props }: ScrollArea$1.Root.Props): React$1.JSX.Element;
 declare function ScrollBar({ className, orientation, ...props }: ScrollArea$1.Scrollbar.Props): React$1.JSX.Element;
 
-declare const Select: typeof Select$1.Root;
+declare function Select<Value, Multiple extends boolean | undefined = false>({ items, children, ...props }: Select$1.Root.Props<Value, Multiple>): React$1.JSX.Element;
 declare function SelectGroup({ className, ...props }: Select$1.Group.Props): React$1.JSX.Element;
 declare function SelectValue({ className, ...props }: Select$1.Value.Props): React$1.JSX.Element;
 declare function SelectTrigger({ className, size, children, ...props }: Select$1.Trigger.Props & {

package/dist/ui/index.js

@@ -1,4 +1,4 @@
-export { Badge, Button, Calendar, CalendarDayButton, Checkbox, Collapsible, CollapsibleContent, CollapsibleTrigger, Command, CommandDialog, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, CommandSeparator, CommandShortcut, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, Input, InputGroup, InputGroupAddon, InputGroupButton, InputGroupInput, InputGroupText, InputGroupTextarea, Popover, PopoverContent, PopoverDescription, PopoverHeader, PopoverTitle, PopoverTrigger, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, Separator, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetTitle, SheetTrigger, Sidebar, SidebarContent, SidebarFooter, SidebarGroup, SidebarGroupAction, SidebarGroupContent, SidebarGroupLabel, SidebarHeader, SidebarInput, SidebarInset, SidebarMenu, SidebarMenuAction, SidebarMenuBadge, SidebarMenuButton, SidebarMenuItem, SidebarMenuSkeleton, SidebarMenuSub, SidebarMenuSubButton, SidebarMenuSubItem, SidebarProvider, SidebarRail, SidebarSeparator, SidebarTrigger, Skeleton, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, Textarea, Toggle, ToggleGroup, ToggleGroupItem, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, badgeVariants, buttonVariants, toggleVariants, useIsMobile, useSidebar } from '../chunk-DIABD3KZ.js';
+export { Badge, Button, Calendar, CalendarDayButton, Checkbox, Collapsible, CollapsibleContent, CollapsibleTrigger, Command, CommandDialog, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, CommandSeparator, CommandShortcut, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, Input, InputGroup, InputGroupAddon, InputGroupButton, InputGroupInput, InputGroupText, InputGroupTextarea, Popover, PopoverContent, PopoverDescription, PopoverHeader, PopoverTitle, PopoverTrigger, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, Separator, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetTitle, SheetTrigger, Sidebar, SidebarContent, SidebarFooter, SidebarGroup, SidebarGroupAction, SidebarGroupContent, SidebarGroupLabel, SidebarHeader, SidebarInput, SidebarInset, SidebarMenu, SidebarMenuAction, SidebarMenuBadge, SidebarMenuButton, SidebarMenuItem, SidebarMenuSkeleton, SidebarMenuSub, SidebarMenuSubButton, SidebarMenuSubItem, SidebarProvider, SidebarRail, SidebarSeparator, SidebarTrigger, Skeleton, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, Textarea, Toggle, ToggleGroup, ToggleGroupItem, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, badgeVariants, buttonVariants, toggleVariants, useIsMobile, useSidebar } from '../chunk-JC6MT5UU.js';
 import { cn } from '../chunk-A2UUGASH.js';
 export { cn } from '../chunk-A2UUGASH.js';
 import { Accordion as Accordion$1 } from '@base-ui/react/accordion';

package/docs/en/agent-skills.md

@@ -22,12 +22,29 @@ The skills ship inside the `@squadbase/vantage` package. `vantage add skill` cop
 your app. They land **directly under the project root** by default; `--dir` puts them elsewhere.
 
 ```bash
-vantage add skill --all                       # every bundled skill, under the root
+vantage add skill                             # list the skills and where they sit (writes nothing)
+vantage add skill --all                       # every skill that isn't placed yet, under the root
 vantage add skill vantage-app                 # a single skill by name
 vantage add skill --all --dir .claude/skills  # where Claude Code looks for them
-vantage add skill vantage-app --force         # overwrite an existing copy
+vantage add skill --all --force               # refresh the placed copies in place
 ```
 
+**The destination is scanned for, not assumed.** `add skill` walks the project first (skipping
+`node_modules` and friends) and **skips any skill that is already placed, reporting where it is** —
+under the root, under `.claude/skills/`, under `.squadbase/skills/`, it doesn't matter, so
+**re-running never creates a second copy**. Drop the name to get just the list:
+
+```text
+$ vantage add skill
+Bundled skills:
+  vantage-add-feature  .claude/skills/vantage-add-feature/
+  vantage-app          .claude/skills/vantage-app/
+  vantage-pitfalls     not placed
+```
+
+With `--force`, the copies that were found are rewritten **where they are** (an explicit `--dir`
+still wins as the destination).
+
 A `--dir` path resolves from the project root (absolute paths work too). To have Claude Code pick
 them up automatically, place them in `.claude/skills/`:
 
@@ -54,8 +71,8 @@ skill based on the task at hand. For other agents, pass whatever directory that
 
 - **The source of truth lives in the package.** Skills are distributed and updated together with
   the framework version, so bumping `@squadbase/vantage` gets you the latest procedures. To refresh
-  copies you've already placed, run `vantage add skill --all --force` with the same `--dir` you
-  used originally.
+  copies you've already placed, run `vantage add skill --all --force` — the destination is scanned
+  for, so you don't have to remember the `--dir` you used originally.
 - **The Squadbase template ships them pre-placed.** Apps created from the template already contain
   `.claude/skills/`. For a hand-made app, add them with `vantage add skill`.
 

package/docs/en/changelog.md

@@ -9,6 +9,72 @@ What changed in each Vantage release. Newest is on top.
 > minor release may include backwards-incompatible changes. A patch is limited to
 > backwards-compatible additions and bug fixes.
 
+## v0.2.2
+
+`vantage add skill` now scans for where the skills already are, and charts follow
+stylesheet swaps too. Both are backwards-compatible.
+
+### Changed
+
+- **`vantage add skill` looks for placed skills before copying** — it walks the
+  project for `<skill>/SKILL.md` and **skips anything already placed, reporting
+  where it is**. Under the root, under `.claude/skills/`, under
+  `.squadbase/skills/` — it makes no difference, so **re-running never creates a
+  second copy**, and an agent no longer has to know the candidate locations.
+  - `--force` rewrites the copies **where they were found** (an explicit `--dir`
+    still wins as the destination), so refreshing placed copies doesn't require
+    remembering the `--dir` you used originally.
+  - `vantage add skill` with no name is now a listing command: it prints the
+    bundled skills and where each one sits, and writes nothing.
+  - The bundled `AGENTS.md` drops its `ls`-the-usual-places routine in favour of
+    letting the CLI find them (a placed `AGENTS.md` is synced by `vantage upgrade`).
+
+### Fixed
+
+- **[`EChart`](parts/echart) could miss a CSS update** — token
+  changes were only watched through attributes on `<html>` / `<body>`, so a
+  change that **only rewrites the injected `<style>`** (editing `styles.css` with
+  the dev server running, applying a theme preset, …) left the chart painted in
+  the previous colours while the DOM tokens were already new. A reload fixed it,
+  which made it read as "the preset didn't apply". Stylesheet swaps are now
+  watched as well, and the chart repaints **only when the token values actually
+  change**.
+
+## v0.2.1
+
+Charts now follow the theme tokens, and `Select` works out the value-to-label
+map for you. Both are backwards-compatible.
+
+> [!NOTE]
+> **Chart colours change.** Charts without an explicit `option.color` used to paint
+> in ECharts' own defaults; they now use the theme's `--chart-1` through
+> `--chart-5`. Charts that set `option.color` are unaffected.
+
+### Changed
+
+- **[`EChart`](parts/echart) follows the theme tokens** — series
+  come from `--chart-1` through `--chart-5`, while axes, legend and tooltip are
+  built from the text and border tokens, and a light/dark switch is picked up.
+  ECharts can't read CSS variables *while painting*, so the tokens are resolved
+  once at init. Set `option.color` to override just the series — axes keep
+  following the tokens. To paint the whole chart yourself, pass the `theme` prop
+  (that turns token-following off entirely).
+- **[`Select`](ui/select) no longer needs `items`** — Base UI's
+  `SelectValue` renders the raw selected *value*, so a trigger would read
+  `kanto` where the list said "Kanto". Vantage now derives the map from your
+  `SelectItem`s. **An explicit `items` still wins**, so existing code is
+  unchanged (keep passing it when a separate component returns the options).
+
+### Fixed
+
+- The `SegmentedControl` example in `useSearchParam`'s JSDoc passed a
+  non-existent `onValueChange` prop (it's `onChange`).
+- Refreshed the bundled `AGENTS.md` and Skills: `vantage add ui|block` can copy
+  only `data-table` and `sales-overview`; the mode follows from whether `server/`
+  exists rather than being a "promote the SPA to fullstack" procedure; and look
+  for already-placed Skills before adding them. A placed `AGENTS.md` is synced by
+  `vantage upgrade`.
+
 ## v0.2.0
 
 Makes the destination of `vantage add skill` selectable, and drops the `.js`

package/docs/en/cli-reference.md

@@ -13,7 +13,7 @@
 | `vantage preview` | Run the production build locally (fullstack default `:4173`; spa via Vite preview) |
 | `vantage check` | Static checks (routes, boundaries, forbidden files). Exit 1 on error |
 | `vantage routes` | Print the page + API URL map |
-| `vantage add <kind> <name>` | Scaffold or place a `page` / `api` / `ui` / `block` / `skill` / `agents` (`--force` to overwrite; `skill` takes `--dir` for the destination) |
+| `vantage add <kind> <name>` | Scaffold or place a `page` / `api` / `ui` / `block` / `skill` / `agents` (`--force` to overwrite; `skill` scans for copies already placed and skips them, `--dir` picks the destination) |
 | `vantage docs [name]` | Show the bundled guide and component reference |
 | `vantage search <query>` | Search that same reference in full text (natural language or `--regex`) |
 | `vantage doctor` | Diagnose environment / installation health |

package/docs/en/components.md

@@ -42,8 +42,8 @@ from the Radix build, four differences matter.
 - **[`ToggleGroup`](ui/toggle-group)'s `value` is an array.** For single choice, use
   [`SegmentedControl`](parts/segmented-control).
 - **[`Select`](ui/select)'s `onValueChange` gives `string | null`.** You need a
-  `null` guard. And `SelectValue` shows the raw value by default — pass the value-to-label map as
-  `items` to get labels.
+  `null` guard. The value-to-label `items` map is derived from your `SelectItem`s automatically, so
+  you rarely write it (only when a separate component returns the options).
 
 State is expressed as `data-open` / `data-checked` rather than `data-state="open"`. Vantage's
 `theme.css` declares custom variants that accept both spellings, so classes like

package/docs/en/parts/echart.md

@@ -1,10 +1,11 @@
 # EChart
 
-> A thin Apache ECharts wrapper. Set colours in your option.
+> A thin Apache ECharts wrapper whose colours follow the theme tokens.
 
-A thin wrapper around Apache ECharts. It only handles the canvas lifecycle (init, resize, dispose),
-the loading overlay, event subscriptions and PNG export. **The palette and axes do not auto-follow
-the theme** — set colours inside `option`, or pass an ECharts theme to `theme`.
+A thin wrapper around Apache ECharts. It handles the canvas lifecycle (init, resize, dispose), the
+loading overlay, event subscriptions and PNG export. **Colours follow the theme tokens** — series
+come from `--chart-1` through `--chart-5`, while axes, legend and tooltip are built from the text
+and border tokens. A light/dark switch is picked up too.
 
 ```tsx
 import { EChart } from "@squadbase/vantage/components";
@@ -16,16 +17,23 @@ import type { EChartsOption } from "@squadbase/vantage/components";
 | `option` | `EChartsOption` | The ECharts option, passed straight through. |
 | `height` | `string \| number` | Height; a number means px. `className` works too. |
 | `loading` | `boolean` | Show ECharts' loading overlay. |
-| `theme` | `string \| object` | The theme passed to `echarts.init` (a name or a registered theme). |
+| `theme` | `string \| object` | The theme passed to `echarts.init` (a name or a registered theme). Passing one turns token-following off. |
 | `onEvents` | `Record<string, (params: unknown) => void>` | Subscribe to ECharts events such as `click`. |
 | `ariaLabel` | `string` | A description of the chart. |
 | `actions` | `boolean` | Show actions such as save-as-image. |
 | `fileName` | `string` | File name used when saving. |
 
-## Setting the palette
+## Overriding the palette
 
-Series colours come from `option.color`. To match the theme's `--chart-1` through `--chart-5`, pass
-the resolved values — ECharts paints to canvas and cannot read CSS variables.
+By default the theme's `--chart-1` through `--chart-5` become the series colours. ECharts can't read
+CSS variables *while painting*, but `EChart` resolves the tokens once at init with
+`getComputedStyle` and passes them in as an ECharts theme. It watches for anything that can change
+those tokens and re-reads them when the values actually move — the `.dark` class going on and off,
+and **stylesheet swaps** too (editing `styles.css` with the dev server running, applying a theme
+preset, …).
+
+To give series their own colours, set `option.color` (or `series[].itemStyle.color`). Your option
+wins over the theme, so **axes, legend and tooltip keep following the tokens**.
 
 ```ts
 const option: EChartsOption = {
@@ -34,9 +42,10 @@ const option: EChartsOption = {
 };
 ```
 
-To reuse a palette across charts, register a theme with
-[`echarts.registerTheme`](https://echarts.apache.org/en/api.html#echarts.registerTheme) and pass its
-name to the `theme` prop.
+To paint the whole chart with a theme of your own, register it with
+[`echarts.registerTheme`](https://echarts.apache.org/en/api.html#echarts.registerTheme) and pass the
+name (or the theme object) to `theme`. That turns token-following off entirely — including the
+light/dark switch.
 
 ## Keeping the legend off the plot
 

package/docs/en/ui/select.md

@@ -39,24 +39,30 @@ import {
 > <Select onValueChange={(value) => value !== null && setRegion(value)}>
 > ```
 
-> [!WARNING]
-> `SelectValue` shows the **raw selected `value`** by default — it never looks inside `SelectItem`.
-> With `value="kanto"` the trigger reads `kanto`, not "Kanto". Give `Select` the value-to-label map
-> via `items`.
+> [!NOTE]
+> Base UI's `SelectValue` renders the **raw selected `value`** — it never looks inside `SelectItem`.
+> With `value="kanto"` the trigger would read `kanto`.
 >
-> ```tsx
-> const regions = { hokkaido: "Hokkaido", kanto: "Kanto", kansai: "Kansai" };
+> Vantage's `Select` **absorbs that quirk**: it walks its children, collects each `SelectItem`'s
+> `value` → label pair and hands them to Base UI as `items`, so the code below puts "Kanto" in the
+> trigger. It's the same treatment `SegmentedControl` gives `ToggleGroup`'s array API.
 >
-> <Select items={regions} value={region} onValueChange={…}>
+> ```tsx
+> <Select value={region} onValueChange={…}>
 >   <SelectTrigger><SelectValue placeholder="Pick a region" /></SelectTrigger>
->   …
+>   <SelectContent>
+>     <SelectItem value="kanto">Kanto</SelectItem>
+>   </SelectContent>
 > </Select>;
 > ```
 >
-> If you'd rather not carry `items`, a function child on `SelectValue` does the same job.
+> Only `SelectItem`s **written in place** are picked up (a `map` over them counts). When the options
+> come back from a separate component, pass `items` yourself — an explicit `items` always wins.
 >
 > ```tsx
-> <SelectValue>{(value) => regions[value] ?? "Pick a region"}</SelectValue>
+> const regions = { hokkaido: "Hokkaido", kanto: "Kanto", kansai: "Kansai" };
+>
+> <Select items={regions} value={region} onValueChange={…}>
 > ```
 
 `SelectContent` opens over the trigger with the selected item aligned to it. For a plain dropdown

package/docs/index.json

@@ -549,7 +549,7 @@
       "section": "components/parts",
       "sectionTitle": "@squadbase/vantage/components",
       "title": "EChart",
-      "description": "Apache ECharts の薄いラッパー。配色は option で指定する。",
+      "description": "Apache ECharts の薄いラッパー。配色はテーマトークンに追従する。",
       "file": "ja/parts/echart.md",
       "order": 4
     },
@@ -1230,7 +1230,7 @@
       "section": "components/parts",
       "sectionTitle": "@squadbase/vantage/components",
       "title": "EChart",
-      "description": "A thin Apache ECharts wrapper. Set colours in your option.",
+      "description": "A thin Apache ECharts wrapper whose colours follow the theme tokens.",
       "file": "en/parts/echart.md",
       "order": 4
     },

package/docs/ja/agent-skills.md

@@ -22,12 +22,29 @@ Skill のソースは `@squadbase/vantage` パッケージに同梱されてい
 対象アプリにコピーします。配置先は既定で**プロジェクトルート直下**で、`--dir` で変えられます。
 
 ```bash
-vantage add skill --all                       # 同梱スキルをすべて、ルート直下に配置
+vantage add skill                             # 一覧と配置場所を表示するだけ(何も書かない)
+vantage add skill --all                       # 未配置のものを、ルート直下に配置
 vantage add skill vantage-app                 # 名前を指定して1つだけ配置
 vantage add skill --all --dir .claude/skills  # Claude Code が読む場所に配置
-vantage add skill vantage-app --force         # 既存を上書き
+vantage add skill --all --force               # 配置済みのコピーをその場で最新に更新
 ```
 
+**配置先は決め打ちではなく、走査して見つけます。** `add skill` はまずプロジェクト内
+(`node_modules` などを除く)を走査し、**既に配置されている skill はスキップして場所を報告**
+します。ルート直下でも `.claude/skills/` でも `.squadbase/skills/` でも同じで、**再実行しても
+二重に配置されません**。名前を省いて実行すると、一覧と配置場所だけが出ます:
+
+```text
+$ vantage add skill
+Bundled skills:
+  vantage-add-feature  .claude/skills/vantage-add-feature/
+  vantage-app          .claude/skills/vantage-app/
+  vantage-pitfalls     not placed
+```
+
+`--force` を付けると、**見つかった場所をそのまま**新しい内容で書き換えます(`--dir` を明示した
+ときは、そちらが配置先として優先されます)。
+
 `--dir` のパスはプロジェクトルートからの相対で解決されます（絶対パスも可）。Claude Code に
 自動認識させるなら `.claude/skills/` に置きます:
 
@@ -54,8 +71,8 @@ Skill の手順を読み込んで実行します。他のエージェントに
 
 - **source-of-truth はパッケージ内**にあります。Skill はフレームワークのバージョンと一緒に
   配布・更新されるため、`@squadbase/vantage` を上げれば最新の手順が手に入ります。配置済みの
-  コピーを更新したいときは、配置したときと同じ `--dir` を付けて
-  `vantage add skill --all --force` を実行します。
+  コピーを更新したいときは `vantage add skill --all --force` を実行します(置き場所は走査して
+  見つけるので、`--dir` を覚えておく必要はありません)。
 - **Squadbase テンプレートには配置済み**です。テンプレートから作ったアプリには、最初から
   `.claude/skills/` が入っています。手で作ったアプリには `vantage add skill` で足してください。
 

package/docs/ja/changelog.md

@@ -8,6 +8,69 @@ Vantage のリリースごとの変更点です。新しいものが上に来ま
 > まだプロトタイプ(**0.x**)です。0.x の間は **minor が実質のメジャー**扱いで、後方互換性の
 > ない変更は minor で入ることがあります。patch は後方互換の機能追加とバグ修正のみです。
 
+## v0.2.2
+
+`vantage add skill` が配置先を走査するようになり、チャートがスタイルシートの差し替えにも
+追従するようになりました。どちらも後方互換です。
+
+### 変更
+
+- **`vantage add skill` が配置済みの Skill を探してからコピーします** ― プロジェクト内を
+  走査して `<skill>/SKILL.md` を探し、**既にあればスキップして場所を報告**します。ルート直下
+  でも `.claude/skills/` でも `.squadbase/skills/` でも同じなので、**再実行しても二重に配置
+  されません**。エージェント側が置き場所の候補を覚えておく必要がなくなります。
+  - `--force` は**見つかった場所をその場で**書き換えます(`--dir` を明示したときは、そちらが
+    配置先として優先されます)。配置済みコピーの更新に、前回と同じ `--dir` を思い出す必要は
+    ありません。
+  - 名前を省いた `vantage add skill` は、**一覧と配置場所を出すだけ**の表示コマンドに
+    なりました(何も書き込まず exit 0)。
+  - 同梱の `AGENTS.md` も更新し、置き場所を `ls` で当てにいく手順を「CLI が探す」に
+    置き換えました(配置済みの `AGENTS.md` は `vantage upgrade` で同期されます)。
+
+### 修正
+
+- **[`EChart`](parts/echart) が CSS の更新に追従しない場合がありました** ―
+  トークンの変化を `html` / `body` の属性でしか見ていなかったため、**注入済みの `<style>` の
+  中身だけが差し替わる経路**(開発中の `styles.css` の書き換え、テーマプリセットの適用など)で
+  DOM のトークンは新しいのにチャートだけ前の色のまま残っていました(リロードで直るため
+  「プリセットが効いていない」と誤解しやすい状態でした)。スタイルシートの差し替えも監視
+  対象になり、**トークンの値が実際に変わったときだけ**描き直します。
+
+## v0.2.1
+
+チャートをテーマトークンに追従させ、`Select` の値とラベルの対応を Vantage 側で組むように
+しました。API はどちらも後方互換です。
+
+> [!NOTE]
+> **チャートの配色が変わります。** これまで `option.color` を書いていないチャートは ECharts の
+> 既定色で描かれていましたが、テーマの `--chart-1` 〜 `--chart-5` で描かれるようになります。
+> 自分で `option.color` を指定しているチャートは今までどおりです。
+
+### 変更
+
+- **[`EChart`](parts/echart) がテーマトークンに追従するようになりました** ―
+  系列色は `--chart-1` 〜 `--chart-5`、軸・凡例・ツールチップは文字色と境界色のトークンから
+  組まれ、ライト / ダークの切り替えにも追いかけます。ECharts が CSS 変数を読めないのは
+  **キャンバスの描画中**の話なので、init のタイミングでトークンの実値を解決しています。
+  系列の色だけ変えたいときは `option.color` で上書きでき、その場合も軸まわりの追従は
+  残ります。チャート全体を自前のテーマで描きたいときは `theme` プロップを渡してください
+  (このときトークン追従は完全に無効になります)。
+- **[`Select`](ui/select) の `items` を書かなくてよくなりました** ―
+  Base UI の `SelectValue` は選択中の *value* をそのまま描く部品で、値とラベルが違うと
+  トリガーに `kanto` のような生の値が出ていました。`SelectItem` から対応表を組む処理を
+  Vantage 側に入れたので、普通に書けばラベルが出ます。**明示した `items` は今までどおり
+  優先される**ので、既存のコードはそのまま動きます(項目を別のコンポーネントが返している
+  場合は、これまでどおり `items` を渡してください)。
+
+### 修正
+
+- `useSearchParam` の JSDoc に載せていた `SegmentedControl` の例が、存在しない
+  `onValueChange` を渡していました(正しくは `onChange`)。
+- 同梱の `AGENTS.md` と Skill を更新しました ― `vantage add ui|block` でコピーできるのが
+  `data-table` と `sales-overview` の 2 つだけであること、モードは `server/` の有無で決まり
+  「SPA から fullstack へ昇格する」手順ではないこと、配置済みの Skill を先に探すこと。
+  配置済みの `AGENTS.md` は `vantage upgrade` で同期されます。
+
 ## v0.2.0
 
 `vantage add skill` の配置先を選べるようにし、相対 import の `.js` 指定子の規約を廃止しました。

package/docs/ja/cli-reference.md

@@ -13,7 +13,7 @@
 | `vantage preview` | 本番ビルドをローカルで起動（fullstack は既定 `:4173`、spa は Vite プレビュー） |
 | `vantage check` | 静的検査（ルート・境界・禁止ファイル）。エラーがあれば exit 1 |
 | `vantage routes` | ページ + API の URL マップを表示 |
-| `vantage add <kind> <name>` | `page` / `api` / `ui` / `block` / `skill` / `agents` を雛形生成・配置（`--force` で上書き、`skill` は `--dir` で配置先を指定） |
+| `vantage add <kind> <name>` | `page` / `api` / `ui` / `block` / `skill` / `agents` を雛形生成・配置（`--force` で上書き、`skill` は配置済みを走査してスキップ・`--dir` で配置先を指定） |
 | `vantage docs [name]` | 同梱のガイド + コンポーネントリファレンスを表示 |
 | `vantage search <query>` | 同じリファレンスを全文検索（自然言語 or `--regex`） |
 | `vantage doctor` | 環境・インストールの健全性を診断 |

package/docs/ja/components.md

@@ -42,8 +42,8 @@ Radix UI から [Base UI](https://base-ui.com) へ切り替えており、Vantag
 - **[`ToggleGroup`](ui/toggle-group) の `value` は配列。** 単一選択にしたいときは
   [`SegmentedControl`](parts/segmented-control) を使ってください。
 - **[`Select`](ui/select) の `onValueChange` は `string | null`。** `null` のガードが
-  要ります。また `SelectValue` は既定で選択中の値をそのまま表示するので、ラベルを出すには
-  `items` に対応表を渡します。
+  要ります。値とラベルが違うときの `items` は Vantage 側が `SelectItem` から自動で組むので、
+  通常は書かなくて済みます(別コンポーネントが項目を返す形のときだけ明示)。
 
 状態は `data-state="open"` ではなく `data-open` / `data-checked` のような属性で表現されます。
 Vantage の `theme.css` は両方の綴りを受ける custom variant を定義しているので、

package/docs/ja/parts/echart.md

@@ -1,10 +1,11 @@
 # EChart
 
-> Apache ECharts の薄いラッパー。配色は option で指定する。
+> Apache ECharts の薄いラッパー。配色はテーマトークンに追従する。
 
 Apache ECharts をそのまま使えるようにした薄いラッパーです。キャンバスの初期化・リサイズ・破棄と、
-ローディング表示・イベント購読・PNG 保存だけを面倒みます。**配色や軸の見た目はテーマに自動追従
-しません** — `option` の中で色を決めるか、`theme` に ECharts のテーマを渡してください。
+ローディング表示・イベント購読・PNG 保存を面倒みます。**配色はテーマトークンに追従します** —
+系列色は `--chart-1` 〜 `--chart-5`、軸・凡例・ツールチップは文字色と境界色のトークンから組まれ、
+ライト / ダークの切り替えにも追いかけます。
 
 ```tsx
 import { EChart } from "@squadbase/vantage/components";
@@ -16,16 +17,22 @@ import type { EChartsOption } from "@squadbase/vantage/components";
 | `option` | `EChartsOption` | ECharts の option。そのまま渡す。 |
 | `height` | `string \| number` | 高さ。数値は px。`className` で決めても良い。 |
 | `loading` | `boolean` | ECharts のローディング表示を出す。 |
-| `theme` | `string \| object` | `echarts.init` に渡すテーマ（名前または登録済みテーマ）。 |
+| `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 変数を読めないため、色の実値を渡してください。
+既定ではテーマの `--chart-1` 〜 `--chart-5` がそのまま系列色になります。ECharts は**描画中**には
+CSS 変数を読めませんが、`EChart` は init のタイミングで `getComputedStyle` からトークンの実値を
+解決し、ECharts のテーマとして渡しています。**トークンが変わりうる操作は見張っていて**、値が
+実際に変わったときだけ読み直します ― `.dark` の付け外しだけでなく、**スタイルシートの差し替え**
+(開発中に `styles.css` を書き換えた・テーマプリセットを当てた、など)も拾います。
+
+系列に固有の色を当てたいときは `option.color`(または `series[].itemStyle.color`)で上書きします。
+option はテーマより優先されるので、**軸・凡例・ツールチップのトークン追従は残ります**。
 
 ```ts
 const option: EChartsOption = {
@@ -34,8 +41,9 @@ const option: EChartsOption = {
 };
 ```
 
-複数チャートで配色を使い回すなら、[`echarts.registerTheme`](https://echarts.apache.org/en/api.html#echarts.registerTheme)
-でテーマを登録し、その名前を `theme` プロップに渡すのが簡潔です。
+チャート全体を自前のテーマで描きたいときは、[`echarts.registerTheme`](https://echarts.apache.org/en/api.html#echarts.registerTheme)
+で登録したテーマ名(またはテーマオブジェクト)を `theme` プロップに渡します。この場合は
+トークン追従が**完全に無効**になり、明暗の切り替えにも追従しなくなります。
 
 ## 凡例と重ならないようにする