@squadbase/vantage 0.0.1 → 0.1.0

package/docs/en/parts/dashboard-card.md

@@ -0,0 +1,64 @@
+# DashboardCard
+
+> The dashboard tile, with a preset and a matching skeleton.
+
+The tile you line up on a dashboard. Tighter than the plain [`Card`](ui/card), with a
+skeleton of the same shape for loading. The common arrangement is one component:
+`DashboardCardPreset`.
+
+```tsx
+import {
+  DashboardCard,
+  DashboardCardHeader,
+  DashboardCardTitle,
+  DashboardCardDescription,
+  DashboardCardAction,
+  DashboardCardContent,
+  DashboardCardFooter,
+  DashboardCardSkeleton,
+  DashboardCardPreset,
+} from "@squadbase/vantage/components";
+```
+
+## DashboardCardPreset
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `title` | `ReactNode` | The heading. |
+| `description` | `ReactNode` | Supporting text beneath it. |
+| `actions` | `ReactNode` | The right end of the heading row. |
+| `footer` | `ReactNode` | The bottom row. |
+| `children` | `ReactNode` | The body. |
+| `headerClassName` | `string` |  |
+| `contentClassName` | `string` |  |
+| `footerClassName` | `string` |  |
+
+With no `title`, `description` or `actions` the header is dropped entirely — same for `footer`.
+
+## Composing it yourself
+
+When you want a different arrangement, use the parts directly.
+
+```tsx
+<DashboardCard>
+  <DashboardCardHeader>
+    <div>
+      <DashboardCardTitle>Revenue</DashboardCardTitle>
+      <DashboardCardDescription>This month</DashboardCardDescription>
+    </div>
+    <DashboardCardAction>
+      <Button variant="ghost" size="xs">Details</Button>
+    </DashboardCardAction>
+  </DashboardCardHeader>
+  <DashboardCardContent>…</DashboardCardContent>
+  <DashboardCardFooter>+12.4% vs last month</DashboardCardFooter>
+</DashboardCard>
+```
+
+## While loading
+
+`DashboardCardSkeleton` draws a box of the same size, so the page doesn't jump when the data lands.
+
+```tsx
+{isLoading ? <DashboardCardSkeleton /> : <DashboardCardPreset title="Revenue">…</DashboardCardPreset>}
+```

package/docs/en/parts/data-table.md

@@ -0,0 +1,86 @@
+# DataTable
+
+> The TanStack Table–backed table: sorting, search, pagination, selection.
+
+A table with sorting, search, pagination, row selection and column visibility. TanStack Table sits
+underneath, and the column definitions are TanStack's own `ColumnDef`. If you just want the whole
+thing, `DataTablePreset` is a single component.
+
+```tsx
+import {
+  DataTable,
+  DataTableToolbar,
+  DataTableContent,
+  DataTablePagination,
+  DataTableColumnVisibility,
+  DataTablePreset,
+  useDataTable,
+} from "@squadbase/vantage/components";
+import type { ColumnDef, SortingState, PaginationState } from "@squadbase/vantage/components";
+```
+
+## DataTablePreset
+
+Start here. It assembles the toolbar, the table and the pager in the usual order.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `columns` | `ColumnDef<TData>[]` | TanStack Table column definitions. |
+| `data` | `TData[]` | The rows. |
+| `enableSorting` | `boolean` | Sort by clicking a header. |
+| `enableFiltering` | `boolean` | Put a search box in the toolbar. |
+| `enablePagination` | `boolean` | Show the pager. |
+| `enableRowSelection` | `boolean` | Add a leading checkbox column. |
+| `enableColumnVisibility` | `boolean` | Add the column-picker menu. |
+| `columnLabels` | `Record<string, string>` | Display names for the column menu. |
+| `toolbar` | `ReactNode` | Extra content for the toolbar. |
+| `bulkActions` | `(selectedRows: TData[]) => ReactNode` | Actions shown while rows are selected. |
+| `pageCount` | `number` | Total pages, when paginating on the server. |
+
+Pass `sorting` / `columnFilters` / `globalFilter` / `pagination` / `rowSelection` /
+`columnVisibility` together with their `on…Change` and the table becomes controlled. Omit them and
+it keeps the state internally.
+
+## Composing it yourself
+
+Use the parts directly for a different arrangement. `DataTable` owns the state and the children read
+it.
+
+```tsx
+<DataTable columns={columns} data={data} enableSorting enableFiltering>
+  <DataTableToolbar showSearch toolbar={<FilterBarPreset … />} />
+  <DataTableContent />
+  <DataTablePagination pageSizeOptions={[10, 25, 50]} />
+</DataTable>
+```
+
+`useDataTable()` gives a child component the TanStack `table` instance directly.
+
+## Paginating on the server
+
+Own `pagination` and `onPaginationChange`, and pass the total in `pageCount`.
+
+```tsx
+const [pagination, setPagination] = useState({ pageIndex: 0, pageSize: 25 });
+
+const { data } = useQuery({
+  queryKey: ["sales", pagination],
+  queryFn: () => apiFetch(`/api/sales?page=${pagination.pageIndex}`).then((r) => r.json()),
+});
+
+<DataTablePreset
+  columns={columns}
+  data={data.rows}
+  pagination={pagination}
+  onPaginationChange={setPagination}
+  pageCount={data.pageCount}
+/>;
+```
+
+## When you want to edit the source
+
+`DataTable` is one of the two components with a copyable source.
+
+```bash
+vantage add ui data-table
+```

package/docs/en/parts/date-range-picker.md

@@ -0,0 +1,41 @@
+# DateRangePicker
+
+> A date-range picker with presets.
+
+Presets such as "Today" and "Last 7 days" alongside a two-month calendar. For picking a period on a
+dashboard, this is all you need.
+
+```tsx
+import { DateRangePicker, defaultPresets } from "@squadbase/vantage/components";
+import type { DateRange, PresetItem } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `DateRange` |  | `{ from, to }`; both are `Date \| undefined`. |
+| `onChange` | `(range: DateRange) => void` |  | Fired on selection. |
+| `presets` | `PresetItem[]` | `defaultPresets` | The presets listed down the left. |
+| `showPresets` | `boolean` | `true` | Whether to show that column. |
+| `minDate` | `Date` |  | Earliest selectable date. |
+| `maxDate` | `Date` |  | Latest selectable date. |
+| `placeholder` | `string` |  | Trigger text before anything is chosen. |
+| `align` | `"start" \| "center" \| "end"` |  | How the popover aligns. |
+| `disabled` | `boolean` |  | Disable interaction. |
+
+## Replacing the presets
+
+`defaultPresets` is Today / Yesterday / Last 7 days / Last 14 days / … . For your own, `getValue`
+returns a `DateRange`.
+
+```tsx
+const presets: PresetItem[] = [
+  { label: "This quarter", getValue: () => ({ from: quarterStart, to: today }) },
+  ...defaultPresets,
+];
+
+<DateRangePicker presets={presets} value={range} onChange={setRange} />;
+```
+
+> [!NOTE]
+> `onChange` also fires mid-selection, when only `from` is set. Guard against refetching while `to` is
+> still `undefined`.

package/docs/en/parts/echart.md

@@ -0,0 +1,53 @@
+# EChart
+
+> A thin Apache ECharts wrapper. Set colours in your option.
+
+A thin wrapper around Apache ECharts. It only handles the canvas lifecycle (init, resize, dispose),
+the loading overlay, event subscriptions and PNG export. **The palette and axes do not auto-follow
+the theme** — set colours inside `option`, or pass an ECharts theme to `theme`.
+
+```tsx
+import { EChart } from "@squadbase/vantage/components";
+import type { EChartsOption } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `option` | `EChartsOption` | The ECharts option, passed straight through. |
+| `height` | `string \| number` | Height; a number means px. `className` works too. |
+| `loading` | `boolean` | Show ECharts' loading overlay. |
+| `theme` | `string \| object` | The theme passed to `echarts.init` (a name or a registered theme). |
+| `onEvents` | `Record<string, (params: unknown) => void>` | Subscribe to ECharts events such as `click`. |
+| `ariaLabel` | `string` | A description of the chart. |
+| `actions` | `boolean` | Show actions such as save-as-image. |
+| `fileName` | `string` | File name used when saving. |
+
+## Setting the palette
+
+Series colours come from `option.color`. To match the theme's `--chart-1` through `--chart-5`, pass
+the resolved values — ECharts paints to canvas and cannot read CSS variables.
+
+```ts
+const option: EChartsOption = {
+  color: ["#3b82f6", "#f59e0b", "#10b981"],
+  series: [{ type: "bar", data: [1, 2, 3] }],
+};
+```
+
+To reuse a palette across charts, register a theme with
+[`echarts.registerTheme`](https://echarts.apache.org/en/api.html#echarts.registerTheme) and pass its
+name to the `theme` prop.
+
+## Keeping the legend off the plot
+
+When you show a `legend`, give it `top: 0` and push the plot down with `grid.top`. Omit this and the
+legend overlaps the plot area.
+
+```ts
+legend: { top: 0 },
+grid: { top: 32, containLabel: true },
+```
+
+> [!NOTE]
+> Don't import `echarts` directly. The seam is deliberately narrow — `EChart` plus the `EChartsOption`
+> type — so the managed stack can move underneath you.

package/docs/en/parts/filter-bar.md

@@ -0,0 +1,66 @@
+# FilterBar
+
+> A row of filters driven by one value object.
+
+A row that treats several filters as one thing. The value is a single `FilterValues` object
+(`{ [key]: string | string[] }`), and the bar can show the active choices as chips and clear them
+all at once.
+
+```tsx
+import {
+  FilterBar,
+  FilterBarSelect,
+  FilterBarMultiSelect,
+  FilterBarActiveChips,
+  FilterBarClearButton,
+  FilterBarPreset,
+} from "@squadbase/vantage/components";
+import type { FilterConfig, FilterValues, FilterOption } from "@squadbase/vantage/components";
+```
+
+## FilterBarPreset
+
+List the definitions in `filters` and you get the selects, the multi-selects, the chips and the
+clear button.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `filters` | `FilterConfig[]` | The filter definitions. |
+| `value` | `FilterValues` | The current values. |
+| `onChange` | `(values: FilterValues) => void` | Fired on change. |
+| `onClear` | `() => void` | Fired by the clear button. |
+
+```ts
+interface FilterConfig {
+  key: string;
+  label: string;
+  type: "select" | "multiselect" | "date" | "daterange" | "search";
+  options?: FilterOption[]; // { label, value, count?, disabled? }
+  placeholder?: string;
+  defaultValue?: string | string[];
+}
+```
+
+Give a `FilterOption` a `count` and the number shows beside the option.
+
+## Composing it yourself
+
+```tsx
+<FilterBar value={values} onChange={setValues} onClear={() => setValues({})}>
+  <FilterBarSelect filterKey="region" label="Region" options={regions} />
+  <FilterBarMultiSelect filterKey="status" label="Status" options={statuses} />
+  <FilterBarClearButton />
+  <FilterBarActiveChips filters={filters} />
+</FilterBar>
+```
+
+## Wiring it to a query
+
+Drop `FilterValues` straight into the `queryKey` and the data refetches only when the filters change.
+
+```tsx
+const { data } = useQuery({
+  queryKey: ["sales", values],
+  queryFn: () => apiFetch(`/api/sales?${new URLSearchParams(values as never)}`).then((r) => r.json()),
+});
+```

package/docs/en/parts/funnel-steps.md

@@ -0,0 +1,33 @@
+# FunnelSteps
+
+> A funnel drawn as bars, with conversion rates.
+
+Draws each funnel stage as a bar, with the first stage at full width, and optionally the conversion
+between stages. A light visualisation that doesn't need ECharts.
+
+```tsx
+import { FunnelSteps, funnelStepsVariants } from "@squadbase/vantage/components";
+import type { FunnelStep } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `data` | `FunnelStep[]` |  | The stages. **The first one is the full-width bar.** |
+| `showConversion` | `boolean` |  | Show the conversion between stages. |
+| `formatValue` | `(value: number) => string` |  | Format the numbers; raw by default. |
+| `animate` | `boolean` |  | Grow the bars on mount. |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` |  |
+| `direction` | `"vertical" \| "horizontal"` | `"vertical"` |  |
+
+## FunnelStep
+
+```ts
+interface FunnelStep {
+  label: string;
+  value: number;
+  color?: string; // defaults to the theme's chart colours
+  onClick?: () => void;
+}
+```
+
+A stage with `onClick` becomes pressable — use it to drill into that stage's breakdown.

package/docs/en/parts/metric-value.md

@@ -0,0 +1,23 @@
+# MetricValue
+
+> The KPI number, with MetricUnit for the unit.
+
+A tight-tracking display for a KPI's number. Units and other trailing text go in `MetricUnit`.
+
+```tsx
+import { MetricValue, MetricUnit, metricValueVariants } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `size` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` | Type scale. |
+| `className` | `string` |  | Classes to add. |
+
+It carries vertical margin (`my-4`) by default. Inside a card, pass `className="my-0"` to sit flush.
+
+```tsx
+<DashboardCardPreset title="Revenue">
+  <MetricValue className="my-0">$12,400</MetricValue>
+  <TrendIndicator value={12.4} direction="up" />
+</DashboardCardPreset>
+```

package/docs/en/parts/multi-select.md

@@ -0,0 +1,27 @@
+# MultiSelect
+
+> Multiple choice with search; selections show as chips.
+
+Multiple choice with a search box. Selections appear as chips on the trigger, and anything past
+`maxCount` collapses into a "+N".
+
+```tsx
+import { MultiSelect } from "@squadbase/vantage/components";
+import type { SelectOption, SelectOptionGroup } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `options` | `SelectOption[] \| SelectOptionGroup[]` | The options; an array of groups adds headings. |
+| `value` | `string[]` | The selected values. |
+| `onChange` | `(value: string[]) => void` | Fired on change. |
+| `maxCount` | `number` | How many chips to show before collapsing to "+N". |
+| `onSearch` | `(query: string) => void` | Called on every keystroke — for server-side search. |
+| `isLoading` | `boolean` | Options are being fetched. |
+| `placeholder` | `string` | Trigger text before anything is chosen. |
+| `searchPlaceholder` | `string` | Placeholder for the search box. |
+| `emptyText` | `string` | Shown when nothing matches. |
+| `disabled` | `boolean` | Disable interaction. |
+
+Inside a filter row, [`FilterBar`](parts/filter-bar)'s `FilterBarMultiSelect` handles
+the value plumbing for you.

package/docs/en/parts/page-shell.md

@@ -0,0 +1,45 @@
+# PageShell
+
+> The page frame: header band, summary row, content.
+
+The frame for one page: a full-width header band, an optional row of summary cards inside it, and
+the content below. Every part is a thin `<div>`, so use only the ones you need.
+
+```tsx
+import {
+  PageShell,
+  PageShellHeader,
+  PageShellHeading,
+  PageShellTitle,
+  PageShellDescription,
+  PageShellHeaderEnd,
+  PageShellMeta,
+  PageShellActions,
+  PageShellSummary,
+  PageShellSummaryCard,
+  PageShellContent,
+  pageShellSummaryCardVariants,
+} from "@squadbase/vantage/components";
+```
+
+## Parts
+
+| Part | Role |
+| --- | --- |
+| `PageShell` | The outer stack |
+| `PageShellHeader` | The underlined header band: heading on the left, `HeaderEnd` on the right |
+| `PageShellHeading` / `PageShellTitle` / `PageShellDescription` | The heading block |
+| `PageShellHeaderEnd` | The right-hand stack |
+| `PageShellMeta` | Asides such as "updated 10 minutes ago" |
+| `PageShellActions` | The button row |
+| `PageShellSummary` | A grid of summary cards, full width inside the header |
+| `PageShellSummaryCard` | One summary card; `accent` colours it |
+| `PageShellContent` | The body |
+
+`PageShellSummaryCard`'s `accent` is `default` / `accent` / `amber` / `blue` / `emerald` / `red`.
+`accent` uses the theme's `--chart-1`, so it follows your tokens.
+
+## Use it from a layout
+
+Rather than repeating it per page, put it in `_layout.tsx` and share it — see
+[Routing](routing).

package/docs/en/parts/searchable-select.md

@@ -0,0 +1,47 @@
+# SearchableSelect
+
+> Single choice with search, for long option lists.
+
+Single choice with a search box, for when there are too many options to scan in
+[`Select`](ui/select). Pass `onSearch` to search on the server instead.
+
+```tsx
+import { SearchableSelect } from "@squadbase/vantage/components";
+import type { SelectOption, SelectOptionGroup } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `options` | `SelectOption[] \| SelectOptionGroup[]` | The options; an array of groups adds headings. |
+| `value` | `string` | The selected value. |
+| `onChange` | `(value: string \| undefined) => void` | Fired on change. |
+| `onSearch` | `(query: string) => void` | Called on every keystroke — for server-side search. |
+| `clearable` | `boolean` | Allow clearing the selection. |
+| `isLoading` | `boolean` | Options are being fetched. |
+| `placeholder` | `string` | Trigger text before anything is chosen. |
+| `searchPlaceholder` | `string` | Placeholder for the search box. |
+| `emptyText` | `string` | Shown when nothing matches. |
+| `disabled` | `boolean` | Disable interaction. |
+
+## Searching on the server
+
+Pass `onSearch` and replace `options` yourself. Filtering becomes the server's job, so hand back
+whatever it returns.
+
+```tsx
+const [query, setQuery] = useState("");
+const { data, isFetching } = useQuery({
+  queryKey: ["customers", query],
+  queryFn: () => apiFetch(`/api/customers?q=${query}`).then((r) => r.json()),
+});
+
+<SearchableSelect
+  options={data ?? []}
+  onSearch={setQuery}
+  isLoading={isFetching}
+  value={value}
+  onChange={setValue}
+/>;
+```
+
+To allow several selections, use [`MultiSelect`](parts/multi-select).

package/docs/en/parts/section-header.md

@@ -0,0 +1,20 @@
+# SectionHeader
+
+> A section heading with its actions.
+
+The heading that divides a page into sections. Pick the heading level with `as`.
+
+```tsx
+import { SectionHeader } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` | `string` |  | The heading. |
+| `description` | `string` |  | Supporting text beneath it. |
+| `actions` | `ReactNode` |  | Rendered at the right. |
+| `as` | `"h1" \| "h2" \| "h3" \| "h4"` | `"h2"` | Heading level; the type scale follows. |
+| `className` | `string` |  | Classes to add. |
+
+For the page's own title use [`PageShell`](parts/page-shell)'s header band.
+`SectionHeader` is for sections within it.

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/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.