@squadbase/vantage 0.2.0 → 0.2.1

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.1";
 
 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.1";
 
 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.1\"\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/changelog.md

@@ -9,6 +9,41 @@ 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.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/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,21 @@ 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 the `.dark` class going on
+and off, and re-reads the tokens when it changes.
+
+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 +40,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/changelog.md

@@ -8,6 +8,41 @@ Vantage のリリースごとの変更点です。新しいものが上に来ま
 > まだプロトタイプ(**0.x**)です。0.x の間は **minor が実質のメジャー**扱いで、後方互換性の
 > ない変更は minor で入ることがあります。patch は後方互換の機能追加とバグ修正のみです。
 
+## 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/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,21 @@ 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` の付け外しを見張っていて、切り替われば
+読み直します。
+
+系列に固有の色を当てたいときは `option.color`(または `series[].itemStyle.color`)で上書きします。
+option はテーマより優先されるので、**軸・凡例・ツールチップのトークン追従は残ります**。
 
 ```ts
 const option: EChartsOption = {
@@ -34,8 +40,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` プロップに渡します。この場合は
+トークン追従が**完全に無効**になり、明暗の切り替えにも追従しなくなります。
 
 ## 凡例と重ならないようにする
 

package/docs/ja/ui/select.md

@@ -40,24 +40,31 @@ import {
 > <Select onValueChange={(value) => value !== null && setRegion(value)}>
 > ```
 
-> [!WARNING]
-> `SelectValue` は既定で**選択中の `value` をそのまま表示します** — `SelectItem` の中身は見ません。
-> `value="kanto"` なら、トリガーには「関東」ではなく `kanto` と出ます。値とラベルの対応を
-> `items` に渡してください。
+> [!NOTE]
+> Base UI の `SelectValue` は**選択中の `value` をそのまま表示する**部品で、`SelectItem` の中身は
+> 見ません。`value="kanto"` ならトリガーには `kanto` と出ます。
 >
-> ```tsx
-> const regions = { hokkaido: "北海道", kanto: "関東", kansai: "関西" };
+> Vantage の `Select` はこの癖を**吸収します** — children を辿って `SelectItem` の `value` →
+> ラベルの対応を組み、Base UI の `items` に渡すので、下の書き方でトリガーに「関東」と出ます。
+> `SegmentedControl` が `ToggleGroup` の配列 API を吸収しているのと同じ扱いです。
 >
-> <Select items={regions} value={region} onValueChange={…}>
+> ```tsx
+> <Select value={region} onValueChange={…}>
 >   <SelectTrigger><SelectValue placeholder="地域を選ぶ" /></SelectTrigger>
->   …
+>   <SelectContent>
+>     <SelectItem value="kanto">関東</SelectItem>
+>   </SelectContent>
 > </Select>;
 > ```
 >
-> `items` を持たせたくない場合は、`SelectValue` の children に関数を渡しても同じことができます。
+> 自動で拾えるのは、**その場に書かれた `SelectItem`** だけです(`map` で並べるのは拾えます)。
+> 項目を別のコンポーネントが返す形にしているときは `items` を明示してください。明示した `items`
+> は常に優先されます。
 >
 > ```tsx
-> <SelectValue>{(value) => regions[value] ?? "地域を選ぶ"}</SelectValue>
+> const regions = { hokkaido: "北海道", kanto: "関東", kansai: "関西" };
+>
+> <Select items={regions} value={region} onValueChange={…}>
 > ```
 
 `SelectContent` は既定で選択中の項目をトリガーに重ねて開きます。素直に下へ開かせたいときは

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@squadbase/vantage",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Data dashboard framework for Squadbase Editor. Vite-powered, config-free, one-file first.",
   "type": "module",
   "license": "MIT",