@squadbase/vantage 0.0.1 → 0.1.1

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.

package/docs/en/ui/input.md

@@ -0,0 +1,28 @@
+# Input
+
+> The single-line text input.
+
+A plain `<input>` with the theme's border and focus ring. The props are the native ones, `type`
+included.
+
+```tsx
+import { Input } from "@squadbase/vantage/ui";
+```
+
+Tie a [`Label`](ui/label) to it with `htmlFor`.
+
+## States
+
+| Written as | Looks like |
+| --- | --- |
+| `disabled` | Dimmed, not interactive |
+| `aria-invalid` | Border and ring turn `destructive` |
+| `readOnly` | Unchanged, but not editable |
+
+Validation styling is just `aria-invalid` — pass the boolean straight through.
+
+```tsx
+<Input aria-invalid={Boolean(error)} />
+```
+
+To attach an icon or button on either end, use [`InputGroup`](ui/input-group).

package/docs/en/ui/label.md

@@ -0,0 +1,19 @@
+# Label
+
+> The form label.
+
+A `<label>` with consistent type and a dimmed disabled state. Either tie it with `htmlFor` or wrap
+the control.
+
+```tsx
+import { Label } from "@squadbase/vantage/ui";
+```
+
+Wrapping a checkbox or switch in a `Label` makes the text clickable too.
+
+```tsx
+<Label className="flex items-center gap-2">
+  <Switch />
+  Auto-refresh
+</Label>
+```

package/docs/en/ui/loading.md

@@ -0,0 +1,19 @@
+# Loading
+
+> A centred spinner with a label.
+
+The loading state for a whole panel. It carries `role="status"` and `aria-live="polite"`, so screen
+readers announce it too. One of the three state components Vantage adds on top of shadcn/ui,
+alongside `Empty` and `ErrorState`.
+
+```tsx
+import { Loading } from "@squadbase/vantage/ui";
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `label` | `string` | `"Loading…"` | Text shown next to the spinner. |
+| `className` | `string` |  | Classes to add. By default it centres within a 30vh minimum height. |
+
+To hold the layout while waiting use [`Skeleton`](ui/skeleton); in tight spots such
+as a button, [`Spinner`](ui/spinner).

package/docs/en/ui/popover.md

@@ -0,0 +1,34 @@
+# Popover
+
+> A bubble anchored to its trigger.
+
+A panel that opens anchored to an element. If you need to trap focus, use
+[`Dialog`](ui/dialog); for a caption alone, [`Tooltip`](ui/tooltip).
+
+```tsx
+import {
+  Popover,
+  PopoverTrigger,
+  PopoverContent,
+  PopoverHeader,
+  PopoverTitle,
+  PopoverDescription,
+} from "@squadbase/vantage/ui";
+```
+
+## Placement
+
+Set by `PopoverContent`'s `side` (default `bottom`), `align` (default `center`) and `sideOffset`
+(default `4`).
+
+## Matching the trigger's width
+
+Base UI exposes a `--anchor-width` CSS variable — the equivalent of Radix's
+`--radix-popover-trigger-width`.
+
+```tsx
+<PopoverContent className="w-(--anchor-width)">…</PopoverContent>
+```
+
+> [!NOTE]
+> To make the trigger a button write `render={<Button />}`. Base UI has no `asChild`.

package/docs/en/ui/progress.md

@@ -0,0 +1,28 @@
+# Progress
+
+> The progress bar, with optional label and value.
+
+A bar for 0–100 progress. Put a label or value inside `Progress` and the bar is drawn beneath them
+automatically.
+
+```tsx
+import {
+  Progress,
+  ProgressTrack,
+  ProgressIndicator,
+  ProgressLabel,
+  ProgressValue,
+} from "@squadbase/vantage/ui";
+```
+
+## Parts
+
+| Part | Role |
+| --- | --- |
+| `Progress` | The root. `value` (`null` for indeterminate) |
+| `ProgressLabel` | The heading |
+| `ProgressValue` | The current value, as a percentage by default |
+| `ProgressTrack` / `ProgressIndicator` | The bar itself — `Progress` renders these for you |
+
+Pass `value={null}` when the total isn't known. If you only mean "loading",
+[`Skeleton`](ui/skeleton) or [`Spinner`](ui/spinner) says it better.

package/docs/en/ui/scroll-area.md

@@ -0,0 +1,23 @@
+# ScrollArea
+
+> A scroll region with a consistent, non-native scrollbar.
+
+Gives a fixed-height region a styled scrollbar instead of the OS one — dropdown contents, long log
+output, and the like.
+
+```tsx
+import { ScrollArea, ScrollBar } from "@squadbase/vantage/ui";
+```
+
+Set the height (or width) via `className`. Vertical is the default; for horizontal scrolling add a
+`ScrollBar orientation="horizontal"` child.
+
+```tsx
+<ScrollArea className="w-96 whitespace-nowrap">
+  <div className="flex gap-3">…</div>
+  <ScrollBar orientation="horizontal" />
+</ScrollArea>
+```
+
+> [!NOTE]
+> If you only want to hide the scrollbar, `theme.css` defines a `no-scrollbar` utility.

package/docs/en/ui/select.md

@@ -0,0 +1,63 @@
+# Select
+
+> The single-choice select. Note that onValueChange can hand you null.
+
+Pick one option from a list. When there are many options and you want search, use
+[`SearchableSelect`](parts/searchable-select); for a handful shown side by side,
+[`SegmentedControl`](parts/segmented-control).
+
+```tsx
+import {
+  Select,
+  SelectTrigger,
+  SelectValue,
+  SelectContent,
+  SelectGroup,
+  SelectLabel,
+  SelectItem,
+  SelectSeparator,
+  SelectScrollUpButton,
+  SelectScrollDownButton,
+} from "@squadbase/vantage/ui";
+```
+
+## Parts
+
+| Part | Role |
+| --- | --- |
+| `Select` | The state: `value` / `defaultValue` / `onValueChange` / `items` |
+| `SelectTrigger` | The closed state. `size`: `default` \| `sm` |
+| `SelectValue` | What's selected; `placeholder` covers "nothing yet" |
+| `SelectContent` | The open list |
+| `SelectGroup` + `SelectLabel` | A group with a heading |
+| `SelectItem` | One option; `value` is required |
+
+> [!WARNING]
+> `onValueChange` hands you **`string | null`** — Base UI allows deselection. Always guard for `null`.
+>
+> ```tsx
+> <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`.
+>
+> ```tsx
+> const regions = { hokkaido: "Hokkaido", kanto: "Kanto", kansai: "Kansai" };
+>
+> <Select items={regions} value={region} onValueChange={…}>
+>   <SelectTrigger><SelectValue placeholder="Pick a region" /></SelectTrigger>
+>   …
+> </Select>;
+> ```
+>
+> If you'd rather not carry `items`, a function child on `SelectValue` does the same job.
+>
+> ```tsx
+> <SelectValue>{(value) => regions[value] ?? "Pick a region"}</SelectValue>
+> ```
+
+`SelectContent` opens over the trigger with the selected item aligned to it. For a plain dropdown
+below the trigger, pass `alignItemWithTrigger={false}`.

package/docs/en/ui/separator.md

@@ -0,0 +1,15 @@
+# Separator
+
+> A single dividing rule.
+
+A rule between sections. With `orientation="vertical"` the parent needs a height.
+
+```tsx
+import { Separator } from "@squadbase/vantage/ui";
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Which way the rule runs. |
+
+It is decorative, so assistive technology skips it.

package/docs/en/ui/sheet.md

@@ -0,0 +1,28 @@
+# Sheet
+
+> A panel that slides in from an edge.
+
+A panel that slides in from the edge of the screen — for a full set of filters, or an edit form that
+wants more room than a modal.
+
+```tsx
+import {
+  Sheet,
+  SheetTrigger,
+  SheetContent,
+  SheetHeader,
+  SheetTitle,
+  SheetDescription,
+  SheetFooter,
+  SheetClose,
+} from "@squadbase/vantage/ui";
+```
+
+The structure matches [`Dialog`](ui/dialog); only the direction differs.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `side` | `"top" \| "right" \| "bottom" \| "left"` | `"right"` | Goes on `SheetContent`. Which edge it enters from. |
+
+`SheetTitle` is required for assistive technology. Keep it and add `className="sr-only"` if it
+shouldn't be visible.

package/docs/en/ui/sidebar.md

@@ -0,0 +1,92 @@
+# Sidebar
+
+> The full collapsible application sidebar kit.
+
+A kit of twenty-odd parts for building an application's navigation. If you'd rather just hand over
+an array of nav items, [`AppShell`](parts/app-shell) gets you there faster.
+
+```tsx
+import {
+  Sidebar,
+  SidebarProvider,
+  SidebarInset,
+  SidebarTrigger,
+  SidebarHeader,
+  SidebarContent,
+  SidebarFooter,
+  SidebarGroup,
+  SidebarGroupLabel,
+  SidebarGroupContent,
+  SidebarGroupAction,
+  SidebarMenu,
+  SidebarMenuItem,
+  SidebarMenuButton,
+  SidebarMenuAction,
+  SidebarMenuBadge,
+  SidebarMenuSkeleton,
+  SidebarMenuSub,
+  SidebarMenuSubItem,
+  SidebarMenuSubButton,
+  SidebarSeparator,
+  SidebarInput,
+  SidebarRail,
+  useSidebar,
+} from "@squadbase/vantage/ui";
+```
+
+## The skeleton
+
+`SidebarProvider` owns the open/closed state; `Sidebar` and `SidebarInset` (the content side) sit
+inside it.
+
+```tsx
+<SidebarProvider>
+  <Sidebar>
+    <SidebarHeader>Acme Analytics</SidebarHeader>
+    <SidebarContent>
+      <SidebarGroup>
+        <SidebarGroupLabel>Analytics</SidebarGroupLabel>
+        <SidebarGroupContent>
+          <SidebarMenu>
+            <SidebarMenuItem>
+              <SidebarMenuButton isActive>Overview</SidebarMenuButton>
+            </SidebarMenuItem>
+            <SidebarMenuItem>
+              <SidebarMenuButton>Sales</SidebarMenuButton>
+              <SidebarMenuBadge>12</SidebarMenuBadge>
+            </SidebarMenuItem>
+          </SidebarMenu>
+        </SidebarGroupContent>
+      </SidebarGroup>
+    </SidebarContent>
+    <SidebarRail />
+  </Sidebar>
+
+  <SidebarInset>
+    <SidebarTrigger />
+    {children}
+  </SidebarInset>
+</SidebarProvider>
+```
+
+## Worth knowing
+
+| Thing | Effect |
+| --- | --- |
+| `isActive` on `SidebarMenuButton` | Highlights the current page |
+| `tooltip` on `SidebarMenuButton` | Shows the label while collapsed |
+| `render` on `SidebarMenuButton` | Swaps in a link component |
+| `SidebarRail` | The thin strip you drag to collapse |
+| `SidebarMenuSkeleton` | A loading menu |
+| `useSidebar()` | Reads the open state and the mobile flag |
+
+## Making items links
+
+```tsx
+import { Link } from "@squadbase/vantage/router";
+
+<SidebarMenuButton render={<Link to="/sales" />}>Sales</SidebarMenuButton>;
+```
+
+> [!NOTE]
+> Base UI has no `asChild` — pass an element to `render`.

package/docs/en/ui/skeleton.md

@@ -0,0 +1,16 @@
+# Skeleton
+
+> A box shaped like the content that will replace it.
+
+A placeholder shaped like whatever is coming. Unlike [`Loading`](ui/loading)'s
+full-panel spinner, it keeps the layout intact while you wait.
+
+```tsx
+import { Skeleton } from "@squadbase/vantage/ui";
+```
+
+Size it with `className` (`h-4 w-32` and friends). Match the height of the real element and the page
+won't jump when the data lands.
+
+For dashboard tiles, [`DashboardCardSkeleton`](parts/dashboard-card) is already the
+right shape.

package/docs/en/ui/slider.md

@@ -0,0 +1,21 @@
+# Slider
+
+> Pick a number by dragging. Ranges included.
+
+Choose a number by dragging. Pass an array as `value` and you get one thumb per entry — a range.
+
+```tsx
+import { Slider } from "@squadbase/vantage/ui";
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `number \| number[]` |  | Thumb position(s). An array makes it a range. |
+| `defaultValue` | `number \| number[]` |  | Initial value when uncontrolled. |
+| `onValueChange` | `(value: number \| number[]) => void` |  | Fired on change, in the same shape you passed to `value`. |
+| `min` | `number` | `0` | Lower bound. |
+| `max` | `number` | `100` | Upper bound. |
+| `step` | `number` | `1` | Increment. |
+| `disabled` | `boolean` |  | Disable interaction. |
+
+Thumbs are aligned to the track's edges, so they never overhang it at `min` or `max`.

package/docs/en/ui/spinner.md

@@ -0,0 +1,14 @@
+# Spinner
+
+> The smallest waiting indicator.
+
+Just a spinning icon — for tight spots like inside a button.
+
+```tsx
+import { Spinner } from "@squadbase/vantage/ui";
+```
+
+It is an `<svg>`, so `size-*` sets the size and `text-*` the colour.
+
+For a whole panel use [`Loading`](ui/loading); to hold the layout while you wait,
+[`Skeleton`](ui/skeleton).

package/docs/en/ui/switch.md

@@ -0,0 +1,19 @@
+# Switch
+
+> A toggle for settings that take effect at once.
+
+For a setting that applies immediately. If it only takes effect on submit,
+[`Checkbox`](ui/checkbox) is the better fit.
+
+```tsx
+import { Switch } from "@squadbase/vantage/ui";
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `checked` | `boolean` |  | On or off. |
+| `onCheckedChange` | `(checked: boolean) => void` |  | Fired on change. |
+| `size` | `"default" \| "sm"` | `"default"` | Scale. |
+| `disabled` | `boolean` |  | Disable interaction. |
+
+Wrap it in a [`Label`](ui/label) so the text is clickable too.