@squadbase/vantage 0.0.1 → 0.1.1

package/docs/en/parts/segmented-control.md

@@ -0,0 +1,25 @@
+# SegmentedControl
+
+> Single-choice segments — it hides ToggleGroup's array.
+
+A row of two to four choices. It is built on [`ToggleGroup`](ui/toggle-group), but
+**because it's single choice `value` is one string** — the array API is absorbed here.
+
+```tsx
+import { SegmentedControl } from "@squadbase/vantage/components";
+import type { SegmentOption } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `options` | `SegmentOption[]` |  | An array of `{ label, value, icon?, disabled? }`. |
+| `value` | `string` |  | The selected value — **a single string**. |
+| `onChange` | `(value: string) => void` |  | Fired on change. |
+| `size` | `"sm" \| "default" \| "lg"` | `"default"` | Icon scale. |
+| `fullWidth` | `boolean` |  | Stretch to the parent's width. |
+| `ariaLabel` | `string` |  | Describes the group. |
+
+Pass a `lucide-react` component straight to `icon`.
+
+Beyond five options, [`Select`](ui/select) reads better; when the choices are whole
+views, [`Tabs`](ui/tabs) fits.

package/docs/en/parts/sparkline.md

@@ -0,0 +1,47 @@
+# Sparkline
+
+> An inline trend chart for table cells and KPI tiles.
+
+Draws a sequence of numbers as a small line or bar chart — no axes, no legend. It is **a single
+`<svg>`, not an `EChart`**, so dozens of them inside table cells or tiles stay cheap.
+
+```tsx
+import { Sparkline } from "@squadbase/vantage/components";
+import type { SparklineDataPoint, SparklineVariant } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `data` | `SparklineDataPoint[]` |  | An array of `{ value: number; label?: string }`. **Required.** An empty array draws nothing. |
+| `variant` | `"line" \| "bar"` | `"line"` | Line or bars. |
+| `height` | `number` | `40` | Height in px; the width fills the parent. |
+| `color` | `string` | `"text-chart-1"` | A Tailwind **text-* class**; it drives stroke and fill through `currentColor`. |
+| `area` | `boolean` | `false` | Fill under the line (`line` only). |
+| `animate` | `boolean` | `false` | Draw in on mount. |
+| `className` | `string` |  | Classes to add. |
+
+Any remaining props go straight to the `<svg>`.
+
+> [!WARNING]
+> `color` is a **class name**. Something like `color="#3b82f6"` does nothing — both the stroke and the
+> fill read `currentColor`, so pass a utility such as `text-chart-2`. Change the theme tokens
+> (`--chart-1` … `--chart-5`) and the colours follow.
+
+## Sizing
+
+`preserveAspectRatio="none"` stretches the chart horizontally, so **the parent decides the width**.
+Inside a table cell, constrain both.
+
+```tsx
+<Sparkline data={points} height={16} className="w-20 shrink-0" />
+```
+
+## Sparkline or EChart
+
+Reach for [`EChart`](parts/echart) when you need axes, a legend, tooltips or multiple
+series. `Sparkline` conveys the *shape* of a series and nothing else — **no ticks, no numbers**.
+
+> [!NOTE]
+> It is `aria-hidden="true"`, so screen readers skip it. Put the actual number next to it as text —
+> [`MetricValue`](parts/metric-value) or
+> [`TrendIndicator`](parts/trend-indicator).

package/docs/en/parts/status-badge.md

@@ -0,0 +1,44 @@
+# StatusBadge
+
+> A dot-and-label status badge, coloured by name.
+
+Shows a row's or record's state as a coloured dot with a label. A built-in map turns the status
+string into a colour, and `colorMap` extends or overrides it.
+
+```tsx
+import { StatusBadge } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `status` | `string` | The status string; it picks the colour. |
+| `label` | `string` | The text to show; defaults to `status`. |
+| `colorMap` | `Record<string, string>` | Status → colour name, merged over the built-in map. |
+| `className` | `string` | Classes to add. |
+
+## The built-in map
+
+| `status` | Colour |
+| --- | --- |
+| `active` | green |
+| `inactive` | gray |
+| `warning` | yellow |
+| `error` | red |
+| `pending` | blue |
+
+Anything unknown falls back to gray. To add your own states, map them to one of
+`green` / `gray` / `yellow` / `red` / `blue`.
+
+```tsx
+<StatusBadge status="reviewing" label="Reviewing" colorMap={{ reviewing: "blue" }} />
+```
+
+It drops straight into a table cell.
+
+```tsx
+{
+  accessorKey: "status",
+  header: "Status",
+  cell: ({ row }) => <StatusBadge status={row.original.status} />,
+}
+```

package/docs/en/parts/trend-indicator.md

@@ -0,0 +1,26 @@
+# TrendIndicator
+
+> An arrow and a percentage; positiveIsGood decides the colour.
+
+Shows a change as an arrow plus a percentage. **Up doesn't always mean good**, so the colour comes
+from `direction` combined with `positiveIsGood` — pass `positiveIsGood={false}` for metrics like
+churn, where down is the good direction.
+
+```tsx
+import { TrendIndicator } from "@squadbase/vantage/components";
+import type { TrendDirection } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `number` |  | The change (`12.4` means 12.4%). |
+| `direction` | `"up" \| "down" \| "neutral"` |  | Which way the arrow points. **Required.** |
+| `positiveIsGood` | `boolean` | `true` | Whether up is good; `false` flips the colours. |
+| `className` | `string` |  | Classes to add. |
+
+> [!WARNING]
+> `direction` is required — it is never inferred from the sign of `value`, so that "it went down, and
+> that's good" stays expressible.
+
+There are three colours: `--chart-1` for the good direction, `--primary` for the bad one, and
+`--muted-foreground` for `neutral`. Change the theme tokens and these follow.

package/docs/en/routing.md

@@ -0,0 +1,177 @@
+# File-based routing
+
+> Dropping a file creates a route. Conventions for pages, layouts, dynamic params, and 404/error.
+
+In Vantage, **where you place a file is its URL**. You never configure a router.
+
+## Page conventions
+
+| File | Route |
+|---|---|
+| `index.tsx` | `/` |
+| `monthly-analysis.tsx` | `/monthly-analysis` |
+| `sales/index.tsx` | `/sales` |
+| `sales/[customerId].tsx` | `/sales/:customerId` |
+| `sales/[...path].tsx` | `/sales/*` (catchall) |
+| `_layout.tsx` | Layout for that directory (nestable) |
+| `_404.tsx` | Not-found UI (**root only**) |
+| `_error.tsx` | Error UI (**root only**) |
+
+- `[name]` → dynamic param, `[...name]` → catchall.
+- `index` maps to its own directory (the name drops from the URL).
+- Files starting with `_` are reserved (`_layout`/`_404`/`_error`) or private (not routed).
+
+## Directories that are never routed
+
+These directories are never scanned. Put whatever code you like here.
+
+```text
+components/   Reusable React components
+hooks/        Custom hooks
+lib/          Utilities
+server/       API (its presence enables the server)
+public/       Static assets
+```
+
+> [!NOTE]
+> Imports between files use **runtime `.js` specifiers** (e.g. `./components/revenue-chart.js`) —
+> required for ESM Node resolution.
+
+## The three spellings of a dynamic param
+
+The same param appears in three spellings depending on where it is. **They must match.**
+
+| Where | Spelling | Example |
+|---|---|---|
+| Filename | `[id]` | `sales/[customerId].tsx` |
+| Display route | `:id` | `/sales/:customerId` |
+| Link | `$id` + `params` | `to="/sales/$customerId"` `params={{ customerId }}` |
+
+```tsx
+import { Link, useParams } from "@squadbase/vantage/router";
+
+function Row({ customerId }: { customerId: string }) {
+  return (
+    <Link to="/sales/$customerId" params={{ customerId }}>
+      Open customer
+    </Link>
+  );
+}
+
+// sales/[customerId].tsx
+export default function Customer() {
+  const { customerId } = useParams({ strict: false });
+  return <div>Customer {customerId}</div>;
+}
+```
+
+## Layouts and nesting
+
+`_layout.tsx` renders an `<Outlet />` that wraps child routes. Place one per directory to nest them.
+
+```tsx
+// _layout.tsx
+import { Outlet } from "@squadbase/vantage/router";
+
+export default function RootLayout() {
+  return (
+    <div className="min-h-screen">
+      <nav className="border-b p-4">My Dashboard</nav>
+      <Outlet />
+    </div>
+  );
+}
+```
+
+`_404.tsx` and `_error.tsx` are recognized at the **root only**.
+
+## Build a nav from the route list
+
+`useRoutes()` returns every page route in the app. The file system is the source of truth, so adding
+one page file adds one nav entry — there is no link array to maintain.
+
+```tsx
+// _layout.tsx
+import { Link, Outlet, useCurrentRoute, useRoutes } from "@squadbase/vantage/router";
+
+export default function RootLayout() {
+  // Dynamic routes (/sales/:customerId) have no single URL, so leave them out.
+  const routes = useRoutes().filter((route) => !route.dynamic);
+  const current = useCurrentRoute();
+
+  return (
+    <div>
+      <nav>
+        {routes.map((route) => (
+          <Link key={route.path} to={route.to} aria-current={route.path === current?.path}>
+            {route.label}
+          </Link>
+        ))}
+      </nav>
+      <Outlet />
+    </div>
+  );
+}
+```
+
+The order is Vantage's scan order — shallow before deep, static before dynamic, alphabetical — which
+is the order a nav wants.
+
+Each entry is a `RouteInfo`:
+
+| Field | Type | Contents |
+|---|---|---|
+| `path` | `string` | Display path, `/sales/:customerId` |
+| `to` | `string` | The form `Link`'s `to` expects, `/sales/$customerId` |
+| `params` | `string[]` | Dynamic parameter names; a catch-all is `_splat` |
+| `dynamic` | `boolean` | Whether the route has dynamic parameters |
+| `index` | `boolean` | Whether it is a directory's index route |
+| `label` | `string` | Display name: `navLabel`, else `title`, else `path` |
+| `title` / `description` / `navLabel` | `string \| undefined` | Values from [`definePage`](pages-and-metadata) |
+
+`useCurrentRoute()` returns the route being rendered, or `undefined` on the 404 route. Beyond the
+"you are here" check above, it fits breadcrumbs and page headings.
+
+> [!NOTE]
+> `label` prefers `navLabel` because `title` drives `document.title` and therefore tends to carry the
+> site name, which is usually too long for a nav.
+
+## Keep filter state in the URL
+
+A dashboard's filters belong in the URL: the view survives a reload and can be pasted to a colleague.
+`useSearchParam` reads and writes one search-param key with a `useState` shape.
+
+```tsx
+import { useSearchParam } from "@squadbase/vantage/router";
+import { SegmentedControl } from "@squadbase/vantage/components";
+
+export default function Sales() {
+  const [region, setRegion] = useSearchParam("region", "all");
+
+  return <SegmentedControl options={REGIONS} value={region} onChange={setRegion} />;
+}
+```
+
+- The value is **always a string** (`?year=2024` parses as a number; this hook normalizes it back).
+- Writing the **default value** (`"all"` above) or `null` removes the key from the URL.
+- History defaults to `replace`, so filtering doesn't fill the back button. Pass `{ replace: false }`
+  to push instead.
+
+For anything JSON-serializable — an array, an object — use `useSearchState`, which also accepts a
+functional update.
+
+```tsx
+import { useSearchState } from "@squadbase/vantage/router";
+
+const [segments, setSegments] = useSearchState<string[]>("segments", []);
+setSegments((prev) => [...prev, "enterprise"]);
+```
+
+## HMR and route regeneration
+
+Adding or removing a `.tsx` page or a `server/api` file regenerates routes and triggers a full
+reload. Editing a page body applies in place via React Fast Refresh.
+
+## What to read next
+
+- [Pages & definePage](pages-and-metadata) — the page contract and metadata

package/docs/en/ui/accordion.md

@@ -0,0 +1,36 @@
+# Accordion
+
+> A stack of headings that open and close. One at a time by default.
+
+A list whose headings toggle their content open and closed. One panel at a time by default; add
+`openMultiple` to let several stay open at once.
+
+```tsx
+import {
+  Accordion,
+  AccordionItem,
+  AccordionTrigger,
+  AccordionContent,
+} from "@squadbase/vantage/ui";
+```
+
+## Parts
+
+| Part | Role |
+| --- | --- |
+| `Accordion` | The root. `value` / `defaultValue` is an **array of open items** |
+| `AccordionItem` | One item, identified by `value` |
+| `AccordionTrigger` | The heading button; the chevron comes for free |
+| `AccordionContent` | The panel that opens |
+
+## Several open at once
+
+```tsx
+<Accordion openMultiple defaultValue={["a", "b"]}>
+```
+
+> [!NOTE]
+> `value` is an **array**, not the string Radix used — that's Base UI's API. Even for a single open
+> panel you pass `defaultValue={["freshness"]}`.
+
+For one standalone disclosure, [`Collapsible`](ui/collapsible) is lighter.

package/docs/en/ui/alert.md

@@ -0,0 +1,31 @@
+# Alert
+
+> An in-page notice that flags something while the content is still shown.
+
+An in-page notice. Where [`ErrorState`](ui/error-state) says "this view failed",
+`Alert` flags something while the content is still shown.
+
+```tsx
+import { Alert, AlertTitle, AlertDescription, AlertAction } from "@squadbase/vantage/ui";
+```
+
+## Parts and variants
+
+| Part | Role |
+| --- | --- |
+| `Alert` | The frame. `variant`: `default` \| `destructive` |
+| `AlertTitle` | The heading |
+| `AlertDescription` | The body |
+| `AlertAction` | An action pinned to the right |
+
+Drop an icon as a direct child of `Alert` and the grid becomes two columns on its own. Importing
+straight from `lucide-react` is fine.
+
+```tsx
+import { Info } from "lucide-react";
+
+<Alert>
+  <Info />
+  <AlertTitle>This view is read-only</AlertTitle>
+</Alert>;
+```

package/docs/en/ui/badge.md

@@ -0,0 +1,23 @@
+# Badge
+
+> A small label for counts, states and tags.
+
+A small label to sit beside text. For a row's status with a coloured dot, reach for
+[`StatusBadge`](parts/status-badge) instead.
+
+```tsx
+import { Badge, badgeVariants } from "@squadbase/vantage/ui";
+```
+
+## Variants
+
+`default` / `secondary` / `destructive` / `outline` / `ghost` / `link`.
+
+`badgeVariants` returns the class string, for when you want the badge look on a different element
+such as an `<a>`.
+
+```tsx
+<a href="/docs" className={badgeVariants({ variant: "outline" })}>
+  Documentation
+</a>
+```

package/docs/en/ui/breadcrumb.md

@@ -0,0 +1,38 @@
+# Breadcrumb
+
+> A breadcrumb trail showing where the page sits.
+
+Shows where the current page sits in the hierarchy. Most useful on drill-down detail pages such as
+`/sales/$customerId`.
+
+```tsx
+import {
+  Breadcrumb,
+  BreadcrumbList,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+  BreadcrumbEllipsis,
+} from "@squadbase/vantage/ui";
+```
+
+## Parts
+
+| Part | Role |
+| --- | --- |
+| `BreadcrumbLink` | An ancestor (a link) |
+| `BreadcrumbPage` | Where you are now — not a link |
+| `BreadcrumbSeparator` | The divider; pass children to swap the glyph |
+| `BreadcrumbEllipsis` | Collapsed middle levels |
+
+## With the router's link
+
+`BreadcrumbLink` takes a `render` prop to become another component. Pass Vantage's
+[`Link`](routing) for client-side navigation.
+
+```tsx
+import { Link } from "@squadbase/vantage/router";
+
+<BreadcrumbLink render={<Link to="/sales" />}>Sales</BreadcrumbLink>;
+```

package/docs/en/ui/button.md

@@ -0,0 +1,39 @@
+# Button
+
+> The button, with six variants and eight sizes.
+
+The component you'll reach for most. `variant` carries the meaning, `size` the scale.
+
+```tsx
+import { Button, buttonVariants } from "@squadbase/vantage/ui";
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `variant` | `"default" \| "secondary" \| "outline" \| "ghost" \| "destructive" \| "link"` | `"default"` | Look and meaning. |
+| `size` | `"default" \| "xs" \| "sm" \| "lg" \| "icon" \| "icon-xs" \| "icon-sm" \| "icon-lg"` | `"default"` | Height and padding. The `icon` sizes are square. |
+| `render` | `ReactElement` |  | Render as a different element (Radix's `asChild`). |
+
+Drop an icon in as a child and its size and spacing are handled. For icon-only buttons always pass
+`size="icon"` and an `aria-label`.
+
+## A link that looks like a button
+
+Pass an element to `render` — Base UI has no `asChild`.
+
+```tsx
+import { Link } from "@squadbase/vantage/router";
+
+<Button render={<Link to="/sales" />}>View sales</Button>;
+```
+
+When you only want the class string, call `buttonVariants({ variant, size })`.
+
+## Pending state
+
+```tsx
+<Button disabled={isPending}>
+  {isPending && <Spinner />}
+  Save
+</Button>
+```

package/docs/en/ui/calendar.md

@@ -0,0 +1,28 @@
+# Calendar
+
+> The date calendar, built on react-day-picker.
+
+A calendar for single dates, multiple dates or a range. For picking a period on a dashboard,
+[`DateRangePicker`](parts/date-range-picker) gets you there faster than using this
+directly.
+
+```tsx
+import { Calendar, CalendarDayButton } from "@squadbase/vantage/ui";
+```
+
+The props are [react-day-picker](https://daypicker.dev)'s `DayPicker` props. Vantage adds only
+three of its own:
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `captionLayout` | `"label" \| "dropdown" \| "dropdown-months" \| "dropdown-years"` | `"label"` | Whether the month/year caption is text or a select. |
+| `buttonVariant` | `Button variant` | `"ghost"` | Look of the previous/next month buttons. |
+| `showOutsideDays` | `boolean` | `true` | Dim and show the neighbouring months' days. |
+
+`mode` is `"single"` / `"multiple"` / `"range"`, and the types of `selected` and `onSelect` follow
+it. `CalendarDayButton` is one day cell — swap it when you want a dot or label under the date.
+
+> [!NOTE]
+> Change the locale by passing a `date-fns` locale to the `locale` prop. `date-fns` is one of
+> Vantage's dependencies, but avoid importing it directly from app code — keeping locale handling
+> inside [`DateRangePicker`](parts/date-range-picker) is the safer path.

package/docs/en/ui/card.md

@@ -0,0 +1,35 @@
+# Card
+
+> The generic card. For dashboard tiles use DashboardCard.
+
+The generic card. For dashboard tiles, [`DashboardCard`](parts/dashboard-card) —
+which already has the spacing and a skeleton — fits better.
+
+```tsx
+import {
+  Card,
+  CardHeader,
+  CardTitle,
+  CardDescription,
+  CardAction,
+  CardContent,
+  CardFooter,
+} from "@squadbase/vantage/ui";
+```
+
+## Parts
+
+| Part | Role |
+| --- | --- |
+| `Card` | The frame. `size`: `default` \| `sm` (changes inner spacing) |
+| `CardHeader` | The heading row |
+| `CardTitle` / `CardDescription` | Heading and supporting text |
+| `CardAction` | The right end of the heading row; adding it makes the header two columns |
+| `CardContent` | The body |
+| `CardFooter` | The bottom; adding it tightens the card's bottom padding |
+
+Spacing comes from a single `--card-spacing` CSS variable, so you can override it per card.
+
+```tsx
+<Card className="[--card-spacing:--spacing(6)]">…</Card>
+```

package/docs/en/ui/checkbox.md

@@ -0,0 +1,34 @@
+# Checkbox
+
+> The checkbox. The mixed state is a separate indeterminate prop.
+
+An on/off input. In the Base UI build `checked` is strictly a boolean and the mixed state lives on
+its own prop — the biggest difference if you're coming from Radix.
+
+```tsx
+import { Checkbox } from "@squadbase/vantage/ui";
+```
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `checked` | `boolean` | The checked state. `"indeterminate"` is not accepted. |
+| `indeterminate` | `boolean` | The mixed state, independent of `checked`. |
+| `onCheckedChange` | `(checked: boolean) => void` | Fired on change; the value is always a boolean. |
+| `disabled` | `boolean` | Disable interaction. |
+
+> [!WARNING]
+> Radix's `checked={"indeterminate"}` is a type error here. Under Base UI, pass `indeterminate` as its
+> own prop.
+
+## Select-all in a table
+
+This is exactly what [`DataTable`](parts/data-table)'s selection column does.
+
+```tsx
+<Checkbox
+  checked={table.getIsAllPageRowsSelected()}
+  indeterminate={table.getIsSomePageRowsSelected()}
+  onCheckedChange={(checked) => table.toggleAllPageRowsSelected(checked)}
+  aria-label="Select all"
+/>
+```

package/docs/en/ui/cn.md

@@ -0,0 +1,34 @@
+# cn()
+
+> The helper that builds class names and resolves conflicts.
+
+Builds a `className` conditionally: `clsx` resolves the conditions, `tailwind-merge` resolves
+conflicting utilities.
+
+```tsx
+import { cn } from "@squadbase/vantage/ui";
+import type { ClassValue } from "@squadbase/vantage/ui";
+
+<div className={cn("p-4", isActive && "bg-accent", className)} />;
+```
+
+## Last one wins
+
+Because it runs through `tailwind-merge`, conflicting utilities resolve **in favour of the later
+one**.
+
+```tsx
+cn("p-2", "p-4"); // → "p-4"
+```
+
+That is what lets a `className` you pass to a component override its defaults. Every built-in
+component runs its classes through `cn()`, so `className` always behaves as an override.
+
+```tsx
+// Reliably beats the default bg-primary
+<Button className="bg-emerald-600 hover:bg-emerald-700">Run</Button>
+```
+
+> [!NOTE]
+> You never need to import `clsx` or `tailwind-merge` yourself — and shouldn't from app code. `cn()`
+> is the public seam for both.

package/docs/en/ui/collapsible.md

@@ -0,0 +1,21 @@
+# Collapsible
+
+> A single unstyled disclosure.
+
+An unstyled primitive that opens and closes one region. For a stack of headings, use
+[`Accordion`](ui/accordion).
+
+```tsx
+import { Collapsible, CollapsibleTrigger, CollapsibleContent } from "@squadbase/vantage/ui";
+```
+
+Control it with `open` / `defaultOpen` / `onOpenChange`. Both the trigger and the panel get
+`data-open` while open, so the chevron can rotate in CSS alone.
+
+```tsx
+<ChevronRight className="transition-transform data-open:rotate-90" />
+```
+
+> [!NOTE]
+> `data-open` is a custom variant declared in Vantage's `theme.css`. The Radix spelling
+> `data-[state=open]:` is wired to the same variant, so either works.