@squadbase/vantage 0.0.1 → 0.1.0

package/docs/en/routing.md

@@ -0,0 +1,95 @@
+# 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**.
+
+## 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.

package/docs/en/ui/command.md

@@ -0,0 +1,37 @@
+# Command
+
+> A filterable command list — the base for a ⌘K palette.
+
+A list that narrows as you type. It is what powers
+[`SearchableSelect`](parts/searchable-select) and
+[`MultiSelect`](parts/multi-select), and on its own it makes a ⌘K palette.
+
+```tsx
+import {
+  Command,
+  CommandDialog,
+  CommandInput,
+  CommandList,
+  CommandEmpty,
+  CommandGroup,
+  CommandItem,
+  CommandShortcut,
+  CommandSeparator,
+} from "@squadbase/vantage/ui";
+```
+
+## Parts
+
+| Part | Role |
+| --- | --- |
+| `Command` | The root; owns filtering and keyboard handling |
+| `CommandDialog` | The same thing inside a `Dialog` — for a ⌘K palette |
+| `CommandInput` | The search field |
+| `CommandList` | The scroll region |
+| `CommandEmpty` | Shown when nothing matches |
+| `CommandGroup` | A group with a `heading` |
+| `CommandItem` | One item; `value` / `onSelect` |
+| `CommandShortcut` | The key hint on the right |
+
+Filtering runs against the items' text by default. To search on the server, set
+`shouldFilter={false}` and replace the items yourself.

package/docs/en/ui/dialog.md

@@ -0,0 +1,52 @@
+# Dialog
+
+> The modal dialog.
+
+A modal centred on the screen. For one that slides in from the edge use
+[`Sheet`](ui/sheet); for a light bubble use
+[`Popover`](ui/popover).
+
+```tsx
+import {
+  Dialog,
+  DialogTrigger,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+  DialogDescription,
+  DialogFooter,
+  DialogClose,
+  DialogOverlay,
+  DialogPortal,
+} from "@squadbase/vantage/ui";
+```
+
+## Parts
+
+| Part | Role |
+| --- | --- |
+| `Dialog` | The state: `open` / `defaultOpen` / `onOpenChange` |
+| `DialogTrigger` | What opens it; `render` turns it into a button |
+| `DialogContent` | The panel. `showCloseButton` (default `true`) toggles the × |
+| `DialogHeader` / `DialogTitle` / `DialogDescription` | The heading block |
+| `DialogFooter` | The button row; `showCloseButton` adds a close button |
+| `DialogClose` | Anything that closes it |
+
+`DialogTitle` is required for assistive technology. If you don't want it visible, keep it and add
+`className="sr-only"`.
+
+## Opening without a trigger
+
+To open from code — after a form submit, say — own the `open` state yourself.
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<Dialog open={open} onOpenChange={setOpen}>
+  <DialogContent>…</DialogContent>
+</Dialog>;
+```
+
+> [!NOTE]
+> Base UI has no `asChild`. Write `<DialogTrigger render={<Button />}>Label</DialogTrigger>` — the
+> label goes in `children`, not inside the element you pass to `render`.

package/docs/en/ui/dropdown-menu.md

@@ -0,0 +1,50 @@
+# DropdownMenu
+
+> A menu opened from a button, with checkbox, radio and submenu items.
+
+An action menu opened from a button — the per-row "…" menu, or a table's column-visibility toggle.
+
+```tsx
+import {
+  DropdownMenu,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuGroup,
+  DropdownMenuLabel,
+  DropdownMenuItem,
+  DropdownMenuCheckboxItem,
+  DropdownMenuRadioGroup,
+  DropdownMenuRadioItem,
+  DropdownMenuSeparator,
+  DropdownMenuShortcut,
+  DropdownMenuSub,
+  DropdownMenuSubTrigger,
+  DropdownMenuSubContent,
+  DropdownMenuPortal,
+} from "@squadbase/vantage/ui";
+```
+
+## The props you'll use
+
+| Prop | Goes on | Meaning |
+| --- | --- | --- |
+| `align` / `side` / `sideOffset` | `DropdownMenuContent` | Where it opens |
+| `variant="destructive"` | `DropdownMenuItem` | Destructive colouring |
+| `inset` | `Item` / `Label` / `SubTrigger` | Indent past the icon column |
+| `checked` / `onCheckedChange` | `DropdownMenuCheckboxItem` | Checked state |
+| `value` / `onValueChange` | `DropdownMenuRadioGroup` | Single choice |
+
+## Submenus
+
+```tsx
+<DropdownMenuSub>
+  <DropdownMenuSubTrigger>Export</DropdownMenuSubTrigger>
+  <DropdownMenuSubContent>
+    <DropdownMenuItem>CSV</DropdownMenuItem>
+    <DropdownMenuItem>JSON</DropdownMenuItem>
+  </DropdownMenuSubContent>
+</DropdownMenuSub>
+```
+
+> [!NOTE]
+> Use `render` to make the trigger a button — Base UI has no `asChild`.

package/docs/en/ui/empty.md

@@ -0,0 +1,22 @@
+# Empty
+
+> The zero-results state.
+
+What to show when there are no results. The icon, description and action are all optional.
+
+```tsx
+import { Empty } from "@squadbase/vantage/ui";
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` | `string` | `"Nothing here yet"` | The heading. |
+| `description` | `string` |  | Supporting text under the heading. |
+| `icon` | `ReactNode` |  | Artwork above the heading. |
+| `action` | `ReactNode` |  | The next step — a button or link — at the bottom. |
+| `className` | `string` |  | Classes to add. |
+
+> [!NOTE]
+> When it has no rows, [`DataTable`](parts/data-table) draws its own "no data" row
+> inside the table. Reach for `Empty` when you want to replace the table entirely — for instance, when
+> nothing has been created yet.

package/docs/en/ui/error-state.md

@@ -0,0 +1,50 @@
+# ErrorState
+
+> The failure state.
+
+Shown when a load or an action failed. It carries `role="alert"` and is framed in the destructive
+colours.
+
+```tsx
+import { ErrorState } from "@squadbase/vantage/ui";
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` | `string` | `"Something went wrong"` | The heading. |
+| `message` | `ReactNode` |  | The details — an error message can go straight in. |
+| `action` | `ReactNode` |  | A retry button, typically. |
+| `className` | `string` |  | Classes to add. |
+
+## All three states together
+
+The usual shape is to map the query's state onto the three branches.
+
+```tsx
+import { useQuery, apiFetch } from "@squadbase/vantage/query";
+import { Button, Loading, Empty, ErrorState } from "@squadbase/vantage/ui";
+import { DataTablePreset } from "@squadbase/vantage/components";
+
+export default function Customers() {
+  const { data, isLoading, error, refetch } = useQuery({
+    queryKey: ["customers"],
+    queryFn: () => apiFetch("/api/customers").then((r) => r.json()),
+  });
+
+  if (isLoading) return <Loading label="Loading customers…" />;
+  if (error)
+    return (
+      <ErrorState
+        message={error.message}
+        action={<Button variant="outline" onClick={() => refetch()}>Retry</Button>}
+      />
+    );
+  if (data.length === 0) return <Empty title="No customers yet" />;
+
+  return <DataTablePreset columns={columns} data={data} />;
+}
+```
+
+> [!NOTE]
+> To surface a deliberate error message from your API, throw `HttpError(status, message)` in
+> `server/api`. Anything else becomes a generic 500 — see [API & server](api-and-server).

package/docs/en/ui/input-group.md

@@ -0,0 +1,30 @@
+# InputGroup
+
+> Attach icons, text or buttons to either end of an input.
+
+A frame that places icons, units or small buttons inside the field — search boxes, or inputs with a
+`%` or currency suffix.
+
+```tsx
+import {
+  InputGroup,
+  InputGroupInput,
+  InputGroupTextarea,
+  InputGroupAddon,
+  InputGroupText,
+  InputGroupButton,
+} from "@squadbase/vantage/ui";
+```
+
+## Parts
+
+| Part | Role |
+| --- | --- |
+| `InputGroup` | The frame; the focus ring lives here |
+| `InputGroupInput` / `InputGroupTextarea` | The field itself, borderless |
+| `InputGroupAddon` | Where attachments go. `align`: `inline-start` (default) \| `inline-end` \| `block-start` \| `block-end` |
+| `InputGroupText` | Short text such as a unit |
+| `InputGroupButton` | A small button. `size`: `xs` (default) \| `sm` \| `icon-xs` \| `icon-sm` |
+
+`block-start` / `block-end` place the addon above or below the field — pair either with
+`InputGroupTextarea` for a textarea with its own toolbar.