@squadbase/vantage 0.0.1 → 0.1.1

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.

package/docs/en/ui-and-theming.md

@@ -0,0 +1,95 @@
+# UI & theming
+
+> Import the built-in UI kit. Override theme tokens in styles.css. Copy sources with add.
+
+Vantage ships **shadcn/ui** (the Base UI variant) and a Tailwind v4 theme. No setup — use them
+immediately.
+
+## Use the UI kit
+
+There are two entry points: the shadcn/ui primitives live in `@squadbase/vantage/ui`, and the
+dashboard parts composed from them live in `@squadbase/vantage/components`.
+
+```tsx
+import { Button } from "@squadbase/vantage/ui";
+import { DashboardCardPreset, MetricValue } from "@squadbase/vantage/components";
+
+export default function Overview() {
+  return (
+    <div className="grid gap-4 p-6 md:grid-cols-3">
+      <DashboardCardPreset title="Revenue">
+        <MetricValue className="my-0">$12,400</MetricValue>
+      </DashboardCardPreset>
+      <DashboardCardPreset title="New customers">
+        <MetricValue className="my-0">128</MetricValue>
+      </DashboardCardPreset>
+      <DashboardCardPreset title="Churn">
+        <MetricValue className="my-0">2.1%</MetricValue>
+      </DashboardCardPreset>
+    </div>
+  );
+}
+```
+
+In `/ui` (a selection): `Button`, `Card`, the `Table` primitives, `Tabs`, `Input` / `Select` /
+`Checkbox` / `Switch` / `Slider`, `Calendar`, `Dialog` / `Sheet` / `Popover` / `Tooltip` /
+`DropdownMenu`, `Sidebar`, `Alert` / `Skeleton` / `Spinner`, `Loading` / `Empty` / `ErrorState`.
+
+In `/components` (a selection): `PageShell`, `AppShell`, `DashboardCard`, `DataTable`, `EChart`,
+`FunnelSteps`, `FilterBar`, `DateRangePicker`, `MetricValue`, `TrendIndicator`.
+
+Props and usage for every component live in the [Components](components) tab.
+
+## Tailwind just works
+
+Write Tailwind utilities in `className` and they apply. You never write `tailwind.config` or
+`postcss.config` (they're forbidden files and would error). Use `cn()` to combine classes.
+
+```tsx
+import { cn } from "@squadbase/vantage/ui";
+
+<div className={cn("p-4", isActive && "bg-accent")} />;
+```
+
+## Override theme tokens
+
+Design tokens like colors and radii are CSS variables. To override them, place a `styles.css` at the
+project root and override **only CSS variables**. The file is auto-imported after the theme.
+
+```css
+/* styles.css — CSS variable overrides only */
+:root {
+  --primary: oklch(0.55 0.22 265);
+}
+.dark,
+[data-theme="dark"] {
+  --primary: oklch(0.72 0.19 265);
+}
+```
+
+> [!WARNING]
+> `styles.css` may only **override CSS variables (theme tokens)**. You cannot bring a `tailwind.config`
+> (it's a forbidden file).
+
+The tokens are shadcn/ui's neutral palette (oklch), plus `--chart-1` through `--chart-5` for charts
+and `--sidebar-*` for the sidebar. Changing `--chart-*` also changes
+[`EChart`](parts/echart)'s palette — charts build their theme by reading those CSS
+variables directly.
+
+## When you want to edit the source: `vantage add`
+
+To make a component's internals your own, copy an editable source into `components/`.
+
+```bash
+vantage add ui data-table      # copy an editable DataTable
+vantage add block sales-overview
+```
+
+> [!NOTE]
+> In the current prototype, `vantage add` can copy only `data-table` (ui) and `sales-overview` (block).
+> All other UI components are import-only.
+
+## What to read next
+
+- [Components](components) — the props reference for every component
+- [CLI reference](cli-reference) — every command