@squadbase/vantage 0.0.1 → 0.1.1

package/docs/en/components.md

@@ -0,0 +1,235 @@
+# Components
+
+> Reference for the bundled shadcn/ui (Base UI) kit and the composite dashboard components.
+
+Vantage ships **shadcn/ui** as-is. Nothing to install, nothing to copy — just import. There are three
+public entry points, and **the sidebar is sectioned by those three**.
+
+| Subpath | What's in it | Count |
+| --- | --- | --- |
+| [`@squadbase/vantage/ui`](ui/button) | The shadcn/ui primitives (Base UI build) plus utilities like `cn()` | 37 |
+| [`@squadbase/vantage/components`](parts/page-shell) | Dashboard parts composed from them | 15 |
+| [`@squadbase/vantage/markdown`](markdown/markdown-renderer) | Markdown rendering alone (kept apart — it's heavy) | 1 |
+
+```tsx
+import { Button, Card, Badge } from "@squadbase/vantage/ui";
+import { PageShell, DashboardCardPreset, EChart } from "@squadbase/vantage/components";
+import { MarkdownRenderer } from "@squadbase/vantage/markdown";
+```
+
+> [!NOTE]
+> The UI kit is meant to be **imported from the package**, not copied. Pull an editable source with
+> [`vantage add`](cli-reference) only when you need to change a component's internals.
+
+## It's the Base UI build
+
+What ships is the **Base UI variant** of shadcn/ui. In July 2026 shadcn/ui switched its default
+primitives from Radix UI to [Base UI](https://base-ui.com), and Vantage follows the new one. Coming
+from the Radix build, four differences matter.
+
+- **There is no `asChild`.** Pass an element to the `render` prop instead.
+
+  ```tsx
+  // Radix build
+  <PopoverTrigger asChild><Button>Open</Button></PopoverTrigger>
+
+  // Base UI build (Vantage)
+  <PopoverTrigger render={<Button />}>Open</PopoverTrigger>
+  ```
+
+- **[`Checkbox`](ui/checkbox)'s `checked` is strictly a boolean.** The mixed state is
+  the separate `indeterminate` prop.
+- **[`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.
+
+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
+`data-open:animate-in` work either way.
+
+## `@squadbase/vantage/ui`
+
+The shadcn/ui primitives. The names and props are shadcn/ui's own, so
+[their docs](https://ui.shadcn.com/docs/components) apply directly. The sidebar is alphabetical;
+here they're grouped by what they're for.
+
+### Forms and input
+
+[`Button`](ui/button) ·
+[`Input`](ui/input) ·
+[`InputGroup`](ui/input-group) ·
+[`Textarea`](ui/textarea) ·
+[`Label`](ui/label) ·
+[`Select`](ui/select) ·
+[`Checkbox`](ui/checkbox) ·
+[`Switch`](ui/switch) ·
+[`Slider`](ui/slider) ·
+[`Toggle`](ui/toggle) ·
+[`ToggleGroup`](ui/toggle-group) ·
+[`Calendar`](ui/calendar) ·
+[`Command`](ui/command)
+
+### Layout and navigation
+
+[`Card`](ui/card) ·
+[`Tabs`](ui/tabs) ·
+[`Separator`](ui/separator) ·
+[`ScrollArea`](ui/scroll-area) ·
+[`Sidebar`](ui/sidebar) ·
+[`Breadcrumb`](ui/breadcrumb) ·
+[`Accordion`](ui/accordion) ·
+[`Collapsible`](ui/collapsible)
+
+### Data display
+
+[`Table`](ui/table) ·
+[`Badge`](ui/badge) ·
+[`Progress`](ui/progress)
+
+### Overlays
+
+[`Dialog`](ui/dialog) ·
+[`Sheet`](ui/sheet) ·
+[`Popover`](ui/popover) ·
+[`Tooltip`](ui/tooltip) ·
+[`DropdownMenu`](ui/dropdown-menu)
+
+### States
+
+[`Alert`](ui/alert) ·
+[`Skeleton`](ui/skeleton) ·
+[`Spinner`](ui/spinner) ·
+[`Loading`](ui/loading) ·
+[`Empty`](ui/empty) ·
+[`ErrorState`](ui/error-state)
+
+`Loading` / `Empty` / `ErrorState` are the only three that aren't shadcn/ui — Vantage adds them.
+
+### Utilities
+
+[`cn()`](ui/cn) · [`useIsMobile()`](ui/use-is-mobile)
+
+## `@squadbase/vantage/components`
+
+Dashboard parts composed from `ui/`.
+
+| Component | What it is |
+| --- | --- |
+| [`PageShell`](parts/page-shell) | The page frame: header band, summary, content |
+| [`AppShell`](parts/app-shell) | The app frame — hand it your nav |
+| [`SectionHeader`](parts/section-header) | A section heading with actions |
+| [`DashboardCard`](parts/dashboard-card) | The dashboard tile, with preset and skeleton |
+| [`DataTable`](parts/data-table) | Sorting, search, pagination, selection |
+| [`EChart`](parts/echart) | The Apache ECharts wrapper |
+| [`FunnelSteps`](parts/funnel-steps) | A funnel drawn as bars |
+| [`Sparkline`](parts/sparkline) | An inline trend chart for cells and tiles |
+| [`FilterBar`](parts/filter-bar) | A row of filters driven by one value |
+| [`DateRangePicker`](parts/date-range-picker) | Date range with presets |
+| [`SegmentedControl`](parts/segmented-control) | Single-choice segments |
+| [`SearchableSelect`](parts/searchable-select) | Single choice with search |
+| [`MultiSelect`](parts/multi-select) | Multiple choice with search |
+| [`MetricValue`](parts/metric-value) | A KPI's number and unit |
+| [`TrendIndicator`](parts/trend-indicator) | An arrow and a percentage |
+| [`StatusBadge`](parts/status-badge) | A dot-and-label status badge |
+| [`Placeholder`](parts/placeholder) | An inline marker for sample data |
+
+## `@squadbase/vantage/markdown`
+
+A subpath holding only [`MarkdownRenderer`](markdown/markdown-renderer). Markdown
+rendering carries Shiki with every language grammar; mixed into the `components` barrel it would add
+over 10 MB to every build, so it is deliberately kept apart.
+
+## Putting it together
+
+```tsx
+import { Button } from "@squadbase/vantage/ui";
+import {
+  PageShell,
+  PageShellHeader,
+  PageShellHeading,
+  PageShellTitle,
+  PageShellDescription,
+  PageShellHeaderEnd,
+  PageShellActions,
+  PageShellContent,
+  DashboardCardPreset,
+  MetricValue,
+  TrendIndicator,
+  EChart,
+  type EChartsOption,
+} from "@squadbase/vantage/components";
+
+const option: EChartsOption = {
+  xAxis: { type: "category", data: monthly.map((m) => m.month) },
+  yAxis: { type: "value" },
+  series: [{ type: "bar", data: monthly.map((m) => m.revenue) }],
+};
+
+export default function Overview() {
+  return (
+    <PageShell>
+      <PageShellHeader>
+        <PageShellHeading>
+          <PageShellTitle>Sales dashboard</PageShellTitle>
+          <PageShellDescription>The last six months</PageShellDescription>
+        </PageShellHeading>
+        <PageShellHeaderEnd>
+          <PageShellActions>
+            <Button variant="outline">Export</Button>
+          </PageShellActions>
+        </PageShellHeaderEnd>
+      </PageShellHeader>
+
+      <PageShellContent>
+        <div className="grid gap-4 md:grid-cols-3">
+          <DashboardCardPreset title="Revenue">
+            <MetricValue className="my-0">$12,400</MetricValue>
+            <TrendIndicator value={12.4} direction="up" />
+          </DashboardCardPreset>
+          <DashboardCardPreset title="New customers">
+            <MetricValue className="my-0">128</MetricValue>
+            <TrendIndicator value={3.1} direction="down" />
+          </DashboardCardPreset>
+          <DashboardCardPreset title="Churn">
+            <MetricValue className="my-0">2.1%</MetricValue>
+          </DashboardCardPreset>
+        </div>
+
+        <DashboardCardPreset title="Monthly revenue" className="mt-4">
+          <EChart option={option} height={320} />
+        </DashboardCardPreset>
+      </PageShellContent>
+    </PageShell>
+  );
+}
+```
+
+## Theming
+
+The look is decided by CSS variables (design tokens). To change colours or radii, override just the
+variables in a `styles.css` at the project root — see [UI & theming](ui-and-theming).
+
+## When you want to edit the source
+
+To change a component's internals, pull an editable copy.
+
+```bash
+vantage add ui data-table        # an editable DataTable into components/
+vantage add block sales-overview
+```
+
+> [!NOTE]
+> In the current prototype, `vantage add` can copy only `data-table` (ui) and `sales-overview` (block).
+> Everything else is import-only.
+
+## How to read these pages
+
+Every component page pairs a **live preview** with its **source**, in tabs. The
+`export const client = "only";` at the top of each source is this documentation site's own directive
+— your app doesn't need it.
+
+> [!NOTE]
+> The previews are shared between both locales, and their sample data is written in Japanese (the
+> site's default locale). The component APIs are the same either way.

package/docs/en/data-fetching.md

@@ -0,0 +1,142 @@
+# Data fetching
+
+> Handle server state with a managed TanStack Query (useQuery).
+
+Vantage ships a **managed TanStack Query** for server state. There is no `QueryClient` to set up —
+just import `useQuery` and friends from `@squadbase/vantage/query`. To call your own `server/api`,
+[`useApiQuery`](#call-your-own-api--useapiquery) below is the shortcut.
+
+```tsx
+import { useQuery } from "@squadbase/vantage/query";
+
+export default function Customers() {
+  const { data, isLoading, error } = useQuery({
+    queryKey: ["customers"],
+    queryFn: async () => {
+      const res = await fetch("/api/customers");
+      if (!res.ok) throw new Error("failed to load");
+      return res.json();
+    },
+  });
+
+  if (isLoading) return <p>Loading…</p>;
+  if (error) return <p>Something went wrong</p>;
+  return (
+    <ul>
+      {data.map((c: { id: string; name: string }) => (
+        <li key={c.id}>{c.name}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+## A single managed QueryClient
+
+Vantage provides exactly one `QueryClient` with these defaults:
+
+| Option | Value |
+|---|---|
+| `staleTime` | 30 seconds |
+| `retry` | 1 |
+| `refetchOnWindowFocus` | `false` |
+| `networkMode` | `"always"` (queries and mutations) |
+
+`networkMode: "always"` requests and retries regardless of the browser's offline heuristic. Under
+the default `"online"`, a failed query is *paused* the moment that heuristic reads offline — no
+error, just a loading state that never resolves. A dashboard talks to its own origin (or the
+configured API base), where that heuristic says nothing useful.
+
+Customize by **overriding per query**. Swapping the whole `QueryClient` is intentionally not exposed,
+to keep the stack managed.
+
+```tsx
+// Change behavior for this query only
+useQuery({
+  queryKey: ["metrics"],
+  queryFn: fetchMetrics,
+  staleTime: 5 * 60 * 1000, // 5 minutes
+  retry: 3,
+});
+```
+
+> [!NOTE]
+> Do not import `@tanstack/react-query` directly. Using the curated re-exports from
+> `@squadbase/vantage/query` lets Vantage evolve the underlying library safely.
+
+## Call your own API — useApiQuery
+
+For routes under `server/api`, use `useApiQuery`. It is `useQuery` plus the boilerplate every page
+was repeating: base-URL resolution, JSON parsing, non-2xx to an error, and a query key.
+
+```tsx
+import { useApiQuery } from "@squadbase/vantage/query";
+
+interface Monthly {
+  monthly: { month: string; revenue: number }[];
+}
+
+export default function MonthlyAnalysis() {
+  const { data, isPending, error } = useApiQuery<Monthly>("/api/monthly-analysis");
+
+  if (isPending) return <p>Loading…</p>;
+  if (error) return <p>{error.message}</p>;
+  return <Chart data={data.monthly} />;
+}
+```
+
+Pass the query string as `search`. `undefined` entries are dropped, so an unset filter appears
+neither in the URL nor in the query key.
+
+```tsx
+const query = useApiQuery<Row[]>("/api/customers", {
+  search: { segment, from: range.from, to: range.to },
+  enabled: Boolean(segment), // any useQuery option still works
+});
+```
+
+The query key defaults to `["api", <url with query string>]`, so changing `search` refetches, and
+`invalidateQueries({ queryKey: ["api"] })` drops everything that came from the API.
+
+### Errors arrive as ApiError
+
+A non-2xx response is thrown as an `ApiError`. Its `message` is what the API chose to disclose with
+[`HttpError`](api-and-server); anything else surfaces as generic status text.
+
+| Property | Contents |
+|---|---|
+| `message` | The message the server set with `HttpError` |
+| `status` | HTTP status |
+| `body` | Parsed response body |
+| `requestId` | `x-vantage-request-id`, to correlate with the dev terminal log |
+
+### Writes with useApiMutation
+
+The mutation variables are sent as the JSON body. The path may be a function.
+
+```tsx
+import { useApiMutation, useQueryClient } from "@squadbase/vantage/query";
+
+const queryClient = useQueryClient();
+const save = useApiMutation<Customer, { id: string; name: string }>(
+  (vars) => `/api/customers/${vars.id}`,
+  {
+    method: "PUT",
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: ["api"] }),
+  },
+);
+
+save.mutate({ id: "1", name: "Northwind" });
+```
+
+Where a hook doesn't fit (an event handler, say), call `apiJson(path, init)` directly. For the raw
+`Response`, use `apiFetch`.
+
+> [!TIP]
+> For an external API, keep using `useQuery` + `fetch`. `useApiQuery` goes through `apiFetch`, so
+> setting [`PUBLIC_API_BASE_URL`](build-and-deploy) lets you deploy the client and server on
+> different origins without touching page code.
+
+## What to read next
+
+- [API & server](api-and-server) — write a backend

package/docs/en/environment-variables.md

@@ -0,0 +1,69 @@
+# Environment variables
+
+> Only PUBLIC_-prefixed env reaches the client. Read secrets from the server's env.
+
+Vantage's default is to **never leak** environment variables to the client. The boundary is the prefix.
+
+## Only `PUBLIC_` reaches the client
+
+Only variables beginning with `PUBLIC_` are included in the client bundle and readable via
+`import.meta.env`.
+
+```tsx
+// client code
+const analyticsId = import.meta.env.PUBLIC_ANALYTICS_ID;
+```
+
+The client can only see:
+
+- `PUBLIC_*` (the public values you define)
+- `MODE` / `DEV` / `PROD` / `SSR` / `BASE_URL` (Vite standard)
+
+> [!WARNING]
+> Reading an env variable **without** the `PUBLIC_` prefix on the client triggers a `PUBLIC_ENV_MISUSE`
+> warning from `vantage check`. There is no user-facing `VITE_` API.
+
+## Secrets come from the server's `env`
+
+Read secrets like API keys and tokens from the server's `ApiContext.env` — **never expose them to
+the client**. These carry no prefix.
+
+```ts
+// server/api/report.ts
+import type { ApiContext } from "@squadbase/vantage/server";
+
+export async function GET({ env }: ApiContext) {
+  const apiKey = env.SECRET_API_KEY; // never reaches the client
+  // …call an external service
+  return Response.json({ ok: true });
+}
+```
+
+## An `.env` example
+
+```bash
+# .env
+PUBLIC_ANALYTICS_ID=UA-XXXX     # reaches the client
+SECRET_API_KEY=sk_live_xxx      # server only (ApiContext.env)
+```
+
+> [!NOTE]
+> The dev server re-reads env on every request. The production Node server snapshots `process.env` once
+> at startup.
+
+## Env used at deploy time
+
+When you deploy the client and server on different origins, these env vars come into play.
+
+| Variable | Side | Role |
+|---|---|---|
+| `PUBLIC_API_BASE_URL` | Client (public) | Base URL the client uses to call `/api`. Also overridable via `--api-base-url` |
+| `CORS_ORIGIN` | Server | Origin(s) allowed for `/api`. Unset means CORS is off |
+| `CORS_CREDENTIALS` | Server | `true` to allow credentials (cookies, etc.) |
+
+See [Build & deploy](build-and-deploy) for how to use them.
+
+## What to read next
+
+- [Build & deploy](build-and-deploy) — production env and split origins
+- [UI & theming](ui-and-theming) — shape the look

package/docs/en/getting-started.md

@@ -0,0 +1,95 @@
+# Getting started
+
+> From install to running your first Vantage app.
+
+## Prerequisites
+
+- **Node.js 20 or newer**
+- A package manager (pnpm, npm, or yarn)
+
+## Create the smallest app
+
+### Add Vantage
+
+Add `@squadbase/vantage` to your project.
+
+```bash
+pnpm add @squadbase/vantage
+```
+
+### Write index.tsx
+
+Put a single `index.tsx` at the project root. The **default-exported component** becomes the
+route `/`.
+
+```tsx
+// index.tsx
+export default function Dashboard() {
+  return (
+    <main className="p-6">
+      <h1 className="text-2xl font-semibold">Dashboard</h1>
+    </main>
+  );
+}
+```
+
+### Start the dev server
+
+```bash
+pnpm exec vantage dev
+```
+
+This starts `http://localhost:5173` with HMR. Editing a page applies via React Fast Refresh
+in place.
+
+> [!TIP]
+> Right after a plain `pnpm add`, the `vantage` binary isn't on your `PATH`, so run it via
+> `pnpm exec vantage` (or `npx vantage`). Add `"dev": "vantage dev"` to your `package.json`
+> `scripts` and you can use `pnpm dev` instead.
+
+## The development loop
+
+| Command | Role |
+|---|---|
+| `vantage dev` | Dev server (HMR + optional API). Default `:5173` |
+| `vantage build` | Production build → `dist/` (client + optional server) |
+| `vantage preview` | Run the production build locally |
+| `vantage check` | Static checks (routes, boundaries, forbidden files). Exit 1 on error |
+| `vantage routes` | Print the page + API URL map |
+
+> [!TIP]
+> While `vantage dev` runs, the browser's `console.*` and uncaught errors are forwarded to the dev
+> terminal as `[browser:…]`. Most issues can be diagnosed without opening the browser.
+
+## Quick mode (pass a path directly)
+
+Instead of `cd`-ing into a project, you can pass its **path directly** to start the dev server.
+Point at a folder or an entry file and `dev` boots on it.
+
+```bash
+vantage ./demo             # folder → run dev inside it
+vantage ./demo/index.tsx   # page file → use its parent folder as the root
+```
+
+When the first argument isn't a known command but points at a path, Vantage runs `dev` with that
+path as the root (printing `quick dev → <path>`). See the
+[CLI reference](cli-reference) for the full resolution rules.
+
+## You never write config files
+
+Vantage takes "convention over configuration" literally. These files are a **hard error**
+(`vantage check` fails) if present in your project:
+
+- `vite.config.*`
+- `tailwind.config.*`
+- `postcss.config.*`
+- `components.json`
+- `vantage.config.*`
+
+Everything they used to configure is owned by Vantage. When you need to customize, use the
+explicit escape hatches described throughout this guide.
+
+## What to read next
+
+- [File-based routing](routing) — add more pages
+- [Pages & definePage](pages-and-metadata) — the page contract and metadata

package/docs/en/index.md

@@ -0,0 +1,65 @@
+# What is Vantage
+
+> A config-free React dashboard framework. You only write index.tsx.
+
+A **vantage** point is a place with a clear, commanding view — and that's the idea behind the name:
+give you a dashboard that sees all of your data at a glance, with the least possible effort.
+
+**Vantage** is a config-free React dashboard framework for
+[Squadbase Editor](https://squadbase.dev), built on Vite 8. As an app author you write a
+**single `index.tsx`** — routing, React setup, TanStack Query, Tailwind CSS, the UI kit, the dev
+server, an optional API server, and the build are all **owned by Vantage**.
+
+```tsx
+// index.tsx  →  route "/"
+export default function Dashboard() {
+  return (
+    <main className="p-6">
+      <h1 className="text-2xl font-semibold">Dashboard</h1>
+    </main>
+  );
+}
+```
+
+Those seven lines are a working dashboard app. You never write `vite.config`, `tailwind.config`,
+`postcss.config`, `components.json`, or `vantage.config`.
+
+> [!NOTE]
+> This site is a guide for **app authors** — people building dashboards *with* Vantage. For the
+> framework's own internals, see the repository's `README.md` and design document.
+
+## Highlights
+
+### One-file first
+
+A single `index.tsx` is a complete app. Add a `.tsx` file when you want another page.
+
+### Convention over configuration
+
+Config files aren't just unnecessary — they're forbidden. File and directory conventions drive everything.
+
+### Managed stack
+
+React, Vite, TanStack Router/Query, Tailwind, and the UI kit are pinned by Vantage.
+
+### Server is optional
+
+Add `server/` to enable an API. Without it, your app is a client-only SPA.
+
+## Next steps
+
+### Getting started
+
+From install to running your first app.
+
+### File-based routing
+
+How dropping a file creates a route.
+
+### Data fetching
+
+Handle server state with a managed TanStack Query.
+
+### API & server
+
+Write a backend under `server/api`.

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

@@ -0,0 +1,44 @@
+# MarkdownRenderer
+
+> Renders markdown, syntax highlighting included.
+
+Renders a markdown string — tables, code blocks with syntax highlighting, and maths included. Good
+for LLM output, or for prose that lives in your database.
+
+```tsx
+import { MarkdownRenderer } from "@squadbase/vantage/markdown";
+```
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `content` | `string` | The markdown to render. |
+| `className` | `string` | Classes to add. |
+
+## Why it's on its own subpath
+
+It is **deliberately not re-exported** from `@squadbase/vantage/components`. Markdown rendering
+carries Shiki with every language grammar, and the import edge alone is something bundlers cannot
+drop. Sitting in the shared barrel, it would add roughly 11 MB and 300 files to the build output of
+apps that never render markdown.
+
+Behind its own entry, **only the apps that import it** pay for it.
+
+```tsx
+// This one is heavy — and that's fine
+import { MarkdownRenderer } from "@squadbase/vantage/markdown";
+
+// This one stays light
+import { DashboardCardPreset } from "@squadbase/vantage/components";
+```
+
+## Streaming LLM output
+
+Since only `content` changes, you can hand it a partially-streamed string. Incomplete markdown — an
+unclosed code fence, say — still renders without breaking.
+
+```tsx
+const [text, setText] = useState("");
+// …setText((prev) => prev + chunk) as chunks arrive
+
+<MarkdownRenderer content={text} />;
+```