@squadbase/vantage 0.0.1 → 0.1.0

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.

package/docs/en/ui/table.md

@@ -0,0 +1,24 @@
+# Table
+
+> The bare table primitives. For sorting and search, use DataTable.
+
+The `<table>` family with the theme's rules and spacing, nothing more. If you need sorting, search
+or pagination, use [`DataTable`](parts/data-table).
+
+```tsx
+import {
+  Table,
+  TableHeader,
+  TableBody,
+  TableFooter,
+  TableRow,
+  TableHead,
+  TableCell,
+  TableCaption,
+} from "@squadbase/vantage/ui";
+```
+
+The mapping is the plain HTML one — `Table` is `<table>`, `TableHeader` is `<thead>`, `TableHead` is
+`<th>`, `TableCell` is `<td>` — and the native props pass through.
+
+Add `text-right tabular-nums` to numeric columns so the digits line up.

package/docs/en/ui/tabs.md

@@ -0,0 +1,23 @@
+# Tabs
+
+> Tabs that switch between views.
+
+Show one of several views in the same place. For a two-to-four-way toggle,
+[`SegmentedControl`](parts/segmented-control) takes less room.
+
+```tsx
+import { Tabs, TabsList, TabsTrigger, TabsContent, tabsListVariants } from "@squadbase/vantage/ui";
+```
+
+## Parts
+
+| Part | Role |
+| --- | --- |
+| `Tabs` | The state: `value` / `defaultValue` / `onValueChange`, plus `orientation` |
+| `TabsList` | The strip. `variant`: `default` (filled) \| `line` (underline) |
+| `TabsTrigger` | One tab; `value` is required |
+| `TabsContent` | The matching panel |
+
+To keep the active tab in the URL, wire `value` to a search param — see [Routing](routing).
+
+`orientation="vertical"` stacks them.

package/docs/en/ui/textarea.md

@@ -0,0 +1,15 @@
+# Textarea
+
+> The multi-line text input.
+
+Multi-line input. The props are the native `<textarea>` ones.
+
+```tsx
+import { Textarea } from "@squadbase/vantage/ui";
+```
+
+Set the height with `rows` or `className` (`min-h-32` and friends). `aria-invalid` turns it the
+error colour, exactly as with [`Input`](ui/input).
+
+For a toolbar above or below, pair [`InputGroup`](ui/input-group)'s
+`InputGroupTextarea` with `align="block-end"`.

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

@@ -0,0 +1,26 @@
+# ToggleGroup
+
+> A band of toggles. value is always an array.
+
+Groups toggles into one band. Under Base UI **`value` is an array even for single choice** — if
+single choice is all you want, [`SegmentedControl`](parts/segmented-control) already
+handles that for you.
+
+```tsx
+import { ToggleGroup, ToggleGroupItem } from "@squadbase/vantage/ui";
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `string[]` |  | The selected values — **an array even for single choice**. |
+| `onValueChange` | `(value: string[]) => void` |  | Fired on change, with an array. |
+| `toggleMultiple` | `boolean` |  | Allow more than one selection. |
+| `variant` | `"default" \| "outline"` | `"default"` |  |
+| `size` | `"default" \| "sm" \| "lg"` | `"default"` |  |
+| `spacing` | `number` | `2` | Gap between items; `0` welds them into one band. |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` |  |
+
+> [!WARNING]
+> There is no Radix-style `type="single"` / `type="multiple"`. Single choice means keeping the array's
+> length at one yourself. [`SegmentedControl`](parts/segmented-control) already does
+> that, so prefer it when you want single choice.

package/docs/en/ui/toggle.md

@@ -0,0 +1,19 @@
+# Toggle
+
+> A button that stays pressed.
+
+A button that keeps its pressed state. To group several, use
+[`ToggleGroup`](ui/toggle-group).
+
+```tsx
+import { Toggle, toggleVariants } from "@squadbase/vantage/ui";
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `pressed` | `boolean` |  | The pressed state. |
+| `onPressedChange` | `(pressed: boolean) => void` |  | Fired on change. |
+| `variant` | `"default" \| "outline"` | `"default"` | Look. |
+| `size` | `"default" \| "sm" \| "lg"` | `"default"` | Scale. |
+
+Icon-only toggles need an `aria-label`.

package/docs/en/ui/tooltip.md

@@ -0,0 +1,22 @@
+# Tooltip
+
+> A short caption on hover.
+
+A short caption shown on hover or focus. The moment you want something interactive inside it, reach
+for [`Popover`](ui/popover).
+
+```tsx
+import { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider } from "@squadbase/vantage/ui";
+```
+
+## Parts
+
+| Part | Role |
+| --- | --- |
+| `TooltipProvider` | Shared timing. `delay` (default `0`, ms) |
+| `Tooltip` | One tooltip's state |
+| `TooltipTrigger` | What triggers it; `render` makes it any element |
+| `TooltipContent` | The bubble. `side` (default `top`) / `align` / `sideOffset` |
+
+> [!NOTE]
+> Tooltips never appear on touch devices. **Don't put information there that a reader needs.**

package/docs/en/ui/use-is-mobile.md

@@ -0,0 +1,18 @@
+# useIsMobile()
+
+> A hook that reports whether the viewport is narrow.
+
+Returns whether the viewport is narrow (under 768px). It is the same check
+[`Sidebar`](ui/sidebar) uses to switch to a sheet on mobile.
+
+```tsx
+import { useIsMobile } from "@squadbase/vantage/ui";
+
+export default function Overview() {
+  const isMobile = useIsMobile();
+  return <EChart option={option} height={isMobile ? 200 : 360} />;
+}
+```
+
+It subscribes to `matchMedia`, so resizing re-renders. Note that the first render starts at `false`
+— where you can, express layout branches as CSS breakpoints instead.