@squadbase/vantage 0.0.1 → 0.1.1

package/docs/en/pages-and-metadata.md

@@ -0,0 +1,59 @@
+# Pages & definePage
+
+> A page's only requirement is a default export. Use definePage to attach a static title and description.
+
+## The only requirement is a default export
+
+A Vantage page needs just one thing: a **default-exported React component**.
+
+```tsx
+export default function MonthlyAnalysis() {
+  return <h1>Monthly analysis</h1>;
+}
+```
+
+A page without a default export is flagged by `vantage check` with a `MISSING_DEFAULT_EXPORT` error.
+
+## Attach metadata with definePage
+
+To add a title or description, use `definePage`. It is optional.
+
+```tsx
+import { definePage } from "@squadbase/vantage";
+
+export const page = definePage({
+  title: "Monthly analysis · Acme Analytics",
+  navLabel: "Monthly analysis",
+  description: "A monthly summary of revenue and key metrics",
+});
+
+export default function MonthlyAnalysis() {
+  return <h1>Monthly analysis</h1>;
+}
+```
+
+- `title` drives `document.title` (the deepest route match's title wins; otherwise it falls back to
+  the document's initial `<title>`).
+- `navLabel` is the name a nav built with [`useRoutes()`](routing#build-a-nav-from-the-route-list)
+  renders. It defaults to `title`; set it separately when `title` carries the site name.
+- `title`/`description`/`navLabel` are **read statically at generation time**. Vantage parses the
+  source rather than executing your page, so keep the values **literal**.
+
+> [!WARNING]
+> The **export name must be `page`** in `export const page = definePage({...})`. A different name means
+> the metadata is not read.
+
+## Relationship to Fast Refresh
+
+Even with a non-component export like `page`, Vantage handles it internally so React Fast Refresh
+survives. Editing a page body updates in place while preserving state.
+
+## Prototype limitations
+
+`definePage` also accepts `pendingComponent` / `errorComponent` / `validateSearch` as types, but in
+the current prototype they are **not yet wired into lazy routes**. Per-page pending/error overrides
+are unimplemented — the framework's shared defaults render instead.
+
+## What to read next
+
+- [Data fetching](data-fetching) — handle server state

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

@@ -0,0 +1,54 @@
+# AppShell
+
+> The application frame — hand it your nav and you're done.
+
+The frame around the whole app. Hand `groups` an array of nav entries and you get a collapsible
+sidebar — or a header, for narrow screens. Use it instead of assembling
+[`Sidebar`](ui/sidebar) yourself.
+
+```tsx
+import { AppShell } from "@squadbase/vantage/components";
+import type { NavGroup, NavItem } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `groups` | `NavGroup[]` |  | The navigation: an array of `{ label?, items: NavItem[] }`. |
+| `variant` | `"sidebar" \| "header"` | `"sidebar"` | A sidebar frame, or a header with a select. |
+| `actions` | `ReactNode` |  | Rendered at the top right. |
+| `header` | `ReactNode` |  | Replaces the default header wholesale. |
+| `defaultOpen` | `boolean` | `true` | With `variant="sidebar"`, whether it starts open. |
+| `linkComponent` | `ElementType` |  | The link component used to render items. |
+| `onNavigate` | `(href: string) => void` |  | Fired when an item is chosen; defaults to `location.assign`. |
+
+## NavItem
+
+```ts
+interface NavItem {
+  label: string;
+  href: string;
+  icon?: ComponentType<{ className?: string }>;
+  isActive?: boolean;
+  disabled?: boolean;
+  badge?: string;
+  children?: NavItem[]; // collapsible sub-items
+}
+```
+
+An item with `children` becomes a disclosure.
+
+## Wiring it to the router
+
+Pass `onNavigate` for client-side navigation.
+
+```tsx
+import { useNavigate } from "@squadbase/vantage/router";
+
+const navigate = useNavigate();
+
+<AppShell groups={groups} onNavigate={(href) => navigate({ to: href })}>
+  {children}
+</AppShell>;
+```
+
+Highlighting is explicit: set `isActive` by comparing the current route's path with each `href`.

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

@@ -0,0 +1,38 @@
+# Placeholder
+
+> An inline marker for sample, not-yet-real data.
+
+Marks a spot where real data isn't wired up yet. The muted colour plus `animate-pulse` says
+**"this value is meant to be replaced"**, so a template never gets shared with sample numbers
+mistaken for real ones.
+
+```tsx
+import { Placeholder } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `children` | `ReactNode` | The sample value — text or elements. |
+| `className` | `string` | Override size and weight (e.g. `text-2xl font-medium`). |
+
+Any remaining props go straight to the `<span>`.
+
+## Placeholder or Skeleton
+
+| | Use for | Element |
+| --- | --- | --- |
+| [`Skeleton`](ui/skeleton) | **Loading** — it disappears when data arrives | block `<div>` |
+| `Placeholder` | **A stand-in value** — it stays until you replace it | inline `<span>` |
+
+Being inline, it is safe **inside a sentence** — in a `<p>` or a heading. `Skeleton` is a block
+element and breaks the line if you mix it into running text.
+
+```tsx
+<p>
+  Revenue this month was <Placeholder>$12,400</Placeholder>.
+</p>
+```
+
+> [!TIP]
+> When you start from a template, searching for `Placeholder` gives you the checklist of everything
+> still unwired.

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.