@antelopejs/interface-dms 0.10.4 → 0.12.0

package/docs/3.base/5.charts-and-widgets.md

@@ -1,10 +1,9 @@
 ---
-title: "Charts and Widgets"
+title: "Charts and widgets"
 description: "The chart module and the three card modules cover dashboard surfaces: a chart of a series, a single figure with a delta, a ranked list, and the period selector the others read their date range from."
+mode: reference
 ---
 
-# Charts and Widgets
-
 ## Overview
 
 The chart module and the three card modules cover dashboard surfaces: a chart of a series, a single figure with a delta, a ranked list, and the period selector the others read their date range from. Each one is a builder that produces a component description; each one either carries its data inline (`staticDataset`, `staticItems`, `staticValue`) or names a `fetchUrl` the frontend calls.
@@ -23,9 +22,9 @@ import {
 import { ChartLine, ChartType } from "@antelopejs/interface-dms/base/chart";
 ```
 
-## A Dashboard in One Page
+## A dashboard in one page
 
-The widgets compose through the layout builders from [Layout and Containers](/docs/interfaces/base/layout). One `PeriodSelector` declares a scope id; every widget that names the same `periodScope` follows its range.
+The widgets compose through the layout builders from [Layout and containers](/docs/interfaces/base/layout). One `PeriodSelector` declares a scope id; every widget that names the same `periodScope` follows its range.
 
 ```typescript
 import {
@@ -102,9 +101,9 @@ export class OverviewPage extends PageController(
 }
 ```
 
-## Chart Builders
+## Chart builders
 
-There is one builder per chart type. Each takes its own props with the `type` discriminant optional — the builder fills it in — and returns a `ComponentBuilder` for that props type.
+There is one builder per chart type. Each takes its own props with the `type` discriminant optional, since the builder fills it in, and returns a `ComponentBuilder` for that props type.
 
 | Builder | `ChartType` | Props interface |
 | --- | --- | --- |
@@ -126,7 +125,7 @@ There is one builder per chart type. Each takes its own props with the `type` di
 
 Every builder gives the component a display name from `title`, falling back to the chart's own name (`"Line Chart"`, `"Donut Chart"`, …), and a matching icon.
 
-### Common Options
+### Common options
 
 Every chart props interface extends [`BaseComponentProps`](/docs/interfaces/base/types) and adds:
 
@@ -151,7 +150,7 @@ Every chart props interface extends [`BaseComponentProps`](/docs/interfaces/base
 
 When `realtimeTopic` is set, the builder registers each topic against the page it is declared on, using `RegisterPageTopic` from `@antelopejs/interface-dms/realtime`.
 
-### Cartesian Charts
+### Cartesian charts
 
 `LineChartProps`, `AreaChartProps`, `RangeAreaChartProps`, `BarChartProps`, `ColumnChartProps`, `ScatterChartProps`, `MixedChartProps`, `RadarChartProps` and `CandlestickChartProps` share a second layer of options on top of the common ones:
 
@@ -189,13 +188,13 @@ And each adds its own:
 | `ScatterChartProps` | `pointSize?: number`, `showLabels?: boolean` |
 | `MixedChartProps` | `seriesDefs?: MixedChartSeriesDef[]` |
 | `RadarChartProps` | `fillOpacity?: number` |
-| `CandlestickChartProps` | — |
+| `CandlestickChartProps` | None |
 
 `MixedChartSeriesDef` declares how one series of a mixed chart is drawn: `{ name: string; type: ChartType.LINE | ChartType.AREA | ChartType.COLUMN | ChartType.RANGE_AREA; color?: ChartColorValue }`.
 
 `ChartCurve` is `"smooth" | "straight" | "stepline"`. Prefer it to `smooth`, which only chooses between the first two.
 
-`ChartAnnotation` draws a horizontal reference on the Y axis — a spend cap, a max bound, a volume capacity:
+`ChartAnnotation` draws a horizontal reference on the Y axis, such as a spend cap, a max bound or a volume capacity:
 
 | Field | Type | Description |
 | --- | --- | --- |
@@ -207,21 +206,21 @@ And each adds its own:
 
 `syncGroup` is what turns a grid of separate metrics into one readable timeline: give every chart on the page the same group name and hovering one moves the crosshair on all of them.
 
-### Circular Charts
+### Circular charts
 
-`CircularChartProps` extends the common options with `staticDataset?: DonutRecord[]` — a flat list of `{ label: string; value: number }` rather than series.
+`CircularChartProps` extends the common options with `staticDataset?: DonutRecord[]`: a flat list of `{ label: string; value: number }` rather than series.
 
 | Props | Extra options |
 | --- | --- |
 | `DonutChartProps` | `centralLabel?: string`, `centralSubLabel?: string`, `arcWidth?: number` |
-| `PieChartProps` | — |
+| `PieChartProps` | None |
 | `RadialBarChartProps` | `hollowSize?: string`, `showTotal?: boolean` |
 
 ### Heatmap
 
-`HeatmapChartProps` extends the common options directly — not the cartesian layer — with `staticDataset?: ChartSeries[]`, `shadeIntensity?: number` and `distributed?: boolean`.
+`HeatmapChartProps` extends the common options directly, not the cartesian layer, with `staticDataset?: ChartSeries[]`, `shadeIntensity?: number` and `distributed?: boolean`.
 
-## Series and Points
+## Series and points
 
 ```typescript
 import type {
@@ -247,7 +246,7 @@ const series: ChartSeries[] = [
 | `ChartSeries` | `name: string`, `data: Array<ChartSeriesPoint \| ChartCandlePoint \| ChartRangePoint \| number>`, `type?: ChartType`, `color?: ChartColorValue`, `strokeWidth?: number`, `strokeDashArray?: number` |
 | `ChartSeriesPoint` | `x: string \| number \| Date`, `y: number \| null`, `label?: string` |
 | `ChartCandlePoint` | `x: string \| number \| Date`, `y: [number, number, number, number]` |
-| `ChartRangePoint` | `x: string \| number \| Date`, `y: [number, number]` — the low and high bound a range area fills between |
+| `ChartRangePoint` | `x: string \| number \| Date`, `y: [number, number]`: the low and high bound a range area fills between |
 | `DonutRecord` | `label: string`, `value: number` |
 
 A `null` `y` marks a gap. `ChartSeries.type` overrides the chart's own type for that series, which is what a mixed chart uses.
@@ -258,7 +257,7 @@ Each property falls back independently to the existing chart configuration when
 
 These properties also survive mixed-series definition projection. Set them on the data series, not on the positional `seriesDefs`. Rendering follows the chart type's stroke support; circular records do not expose series strokes. This API does not change fills, interpolation, markers, axes or legends.
 
-## Colours and Formats
+## Colors and formats
 
 | Type | Values |
 | --- | --- |
@@ -268,16 +267,16 @@ These properties also survive mixed-series definition projection. Set them on th
 | `ComparisonStyle` | `"dashed"`, `"solid"`, `"dimmed"` |
 | `ValueFormat` | `"number"`, `"currency"`, `"percent"`, `"compact"` |
 
-`ColorName` is the chart palette and is distinct from the `Color` enum in [Shared Types](/docs/interfaces/base/types): it adds `accent` and it is a string union rather than an enum. `ValueFormat` is used by the three card components rather than by the charts themselves.
+`ColorName` is the chart palette and is distinct from the `Color` enum in [Shared types](/docs/interfaces/base/types): it adds `accent` and it is a string union rather than an enum. `ValueFormat` is used by the three card components rather than by the charts themselves.
 
-## Chart Events
+## Chart events
 
 | Namespace member | Value |
 | --- | --- |
 | `ChartEvents.SEGMENT_CLICK` | `"DmsComponent.Chart.SegmentClick"` |
 | `ChartEvents.POINT_CLICK` | `"DmsComponent.Chart.PointClick"` |
 
-## ChartCard
+## `ChartCard`
 
 `ChartCard` wraps a chart in a card that owns the title, the fetch URL and the delta display, and holds the chart as a child under the id `"chart"`.
 
@@ -313,13 +312,13 @@ const card = ChartCard({
 | `currencyCode` | `string` | Currency for `valueFormat: "currency"`. |
 | `valuePrecision` | `ValuePrecision` | Fixed fraction digits or `"native"` Intl defaults; omitted keeps legacy formatting. Also applies to the previous value and nested chart's value axis and tooltip. |
 | `showDelta` | `boolean` | Show the change against the comparison period. |
-| `invert` | `boolean` | Treat an increase as bad — for metrics where lower is better. |
+| `invert` | `boolean` | Treat an increase as bad, for metrics where lower is better. |
 | `showLegend` | `boolean` | Show the primary / comparison legend. Defaults to `true`. |
 | `showSeriesLegend` | `boolean` | Show the nested chart's legend, naming each series. Defaults to `false`. |
 | `primaryLabel` | `string` | Label of the primary series. |
 | `comparisonLabel` | `string` | Label of the comparison series. Without it, a card with a `periodScope` names the selected comparison ("Previous year"). |
 
-## KpiCard
+## `KpiCard`
 
 `KpiCard` shows a single figure with an optional delta and sparkline.
 
@@ -355,14 +354,14 @@ const denied = KpiCard({
 | `showPreviousValue` | `boolean` | Show the route's `previousValue` next to the change ("vs €42,900"), formatted as the value. Defaults to `true`. |
 | `showSparkline` | `boolean` | Show the sparkline. |
 | `sparklineAccent` | `ChartColorValue \| "auto"` | Sparkline colour. |
-| `invert` | `boolean` | Treat an increase as bad — for metrics where lower is better. |
+| `invert` | `boolean` | Treat an increase as bad, for metrics where lower is better. |
 | `compareLabel` | `string` | Label next to the delta. Without it (and without `description`), a card with a `periodScope` names the selected comparison ("vs previous year"). Shown with the delta only: with no comparison, the `description` shows instead. |
 | `staticValue` | `number` | Inline value, as an alternative to `fetchUrl`. |
 | `staticDelta` | `number` | Inline delta, in percent (`12.5` reads +12.5 %). |
 | `staticPreviousValue` | `number` | Inline value compared against, as a fetched `previousValue`. |
 | `staticSparkline` | `number[]` | Inline sparkline points. |
 
-## TopListCard
+## `TopListCard`
 
 `TopListCard` shows a ranked list of items, each with a value and optionally a delta, a sparkline and an avatar.
 
@@ -421,7 +420,7 @@ const topSkills = TopListCard({
 | `avatar` | `TopListItemAvatar` | Leading avatar, `{ src: string; alt?: string }`. |
 | `to` | `string` | Link target for the item. `{{params.X}}` / `{{query.X}}` name the page URL; a query pair whose token has no value is left out. |
 
-## PeriodSelector
+## `PeriodSelector`
 
 `PeriodSelector` owns a date range and a comparison mode, and publishes them under its `id`. Every widget carrying the same value in `periodScope` uses that range.
 
@@ -454,7 +453,7 @@ const selector = PeriodSelector({
 | `size` | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | Control size. |
 | `showRangeLabel` | `boolean` | Show the resolved date range as text. |
 | `rangeLabel` | `PeriodRangeLabel` | `"absolute"` (default): both bounds. `"relative"`: the start of a window reaching now, "since yesterday 11:52". |
-| `comparisonControl` | `PeriodComparisonControl` | `"menu"`, `"toggle"` (one inline button switching a comparison on and off) or `"hidden"` (nothing drawn, the comparison kept on). Defaults to `"toggle"` when `comparisons` offers a single comparison besides `"none"`, `"menu"` otherwise. The menu's trigger names the compared window ("vs 16 – 17 Oct", the option's name in its tooltip and its list), so the range label beside it keeps the current window only. |
+| `comparisonControl` | `PeriodComparisonControl` | `"menu"`, `"toggle"` (one inline button switching a comparison on and off) or `"hidden"` (nothing drawn, the comparison kept on). Defaults to `"toggle"` when `comparisons` offers a single comparison besides `"none"`, `"menu"` otherwise. The menu's trigger names the compared window (`vs 16 – 17 Oct`, the option's name in its tooltip and its list), so the range label beside it keeps the current window only. |
 | `rememberKey` | `string` | Selectors carrying the same key share the remembered last choice, on any page. |
 | `variant` | `PeriodSelectorVariant` | `"default"` or `"segmented"`. |
 | `maxDays` | `number` | The longest custom range, in days (both ends included), the user can pick in the calendar or the date fields. Presets and a range given by the URL are not limited. |
@@ -465,6 +464,6 @@ The selector keeps its period in the page URL, under keys prefixed with its `id`
 
 `PeriodSelectorVariant` is `"default" | "segmented"`. `segmented` renders the presets as inline pills for one-click range switching; the custom range stays in its popover calendar either way.
 
-## Next Steps
+## Next steps
 
-- [Layout and Containers](/docs/interfaces/base/layout) - Grids, stacks, tabs, layouts and the custom-component escape hatch.
+- [Layout and containers](/docs/interfaces/base/layout): Grids, stacks, tabs, layouts and the custom-component escape hatch.

package/docs/3.base/6.layout.md

@@ -1,10 +1,9 @@
 ---
-title: "Layout and Containers"
+title: "Layout and containers"
 description: "Grid, stacks, tabs, guard, placeholder and the page layouts that hold every other component."
+mode: reference
 ---
 
-# Layout and Containers
-
 ## Overview
 
 Layout components hold other components. They come in two kinds.
@@ -18,7 +17,7 @@ See the [settings-page screenshot](/docs/building/settings-pages) for the frame
 
 **Containers** are builders: `Grid`, `GridRow`, `HStack`, `VStack`, `Spacer`, `Tab`, `Guard` and `Placeholder` return a `ComponentBuilder`, and you nest components inside them with `.child(id, component)`. They are assigned to a static field of a page class like any other component.
 
-**Page layouts** are not builders: `DefaultLayout`, `FormPageLayout`, `SettingsLayout` and `EmptyLayout` return a plain `ComponentInfo` and are passed as the third argument of `PageController` — or as the `layout` option of a page or category, the default of everything declared under it — to say how the page's chrome is drawn.
+**Page layouts** are not builders: `DefaultLayout`, `FormPageLayout`, `SettingsLayout` and `EmptyLayout` return a plain `ComponentInfo` and are passed as the third argument of `PageController`, or as the `layout` option of a page or category (the default of everything declared under it), to say how the page's chrome is drawn.
 
 `CustomComponent` sits outside both: it names a Vue component from the frontend registry and gives you a builder for it, which is the escape hatch when the vocabulary on this page is not enough.
 
@@ -38,7 +37,7 @@ import { CustomComponent } from "@antelopejs/interface-dms/base/custom";
 
 `Grid` is a container whose direct children are `GridRow`s. The number of columns follows the widest row.
 
-```typescript
+```typescript fragment
 import { Grid, GridRow } from "@antelopejs/interface-dms/base/grid";
 import { KpiCard } from "@antelopejs/interface-dms/base";
 
@@ -60,9 +59,9 @@ static kpis = Grid({ gap: "1rem" }).child(
 
 `GridRow()` takes no options. Its children are laid out horizontally within the row.
 
-`.child()` accepts a third argument of extra metadata, which is carried verbatim onto the serialized child alongside its `id` — that is how a child declares that it spans more than one column:
+`.child()` accepts a third argument of extra metadata, which is carried verbatim onto the serialized child alongside its `id`. That is how a child declares that it spans more than one column:
 
-```typescript
+```typescript fragment
 GridRow().child("chart", chartCard, { colSpan: 2 }).child("list", topListCard);
 ```
 
@@ -70,7 +69,7 @@ GridRow().child("chart", chartCard, { colSpan: 2 }).child("list", topListCard);
 
 `HStack` and `VStack` arrange their children along one axis; `Spacer` fills the leftover space between them.
 
-```typescript
+```typescript fragment
 import { HStack, Spacer } from "@antelopejs/interface-dms/base/stack";
 
 static toolbar = HStack({ alignment: "center", distribution: "space-between", spacing: "16px" })
@@ -81,7 +80,7 @@ static toolbar = HStack({ alignment: "center", distribution: "space-between", sp
 
 `StackAlignment` is `"start" | "center" | "end" | "stretch"` and `StackDistribution` is `"start" | "center" | "end" | "space-between" | "space-around" | "space-evenly"`.
 
-### HStackOptions
+### `HStackOptions`
 
 | Option | Type | Description |
 | --- | --- | --- |
@@ -91,7 +90,7 @@ static toolbar = HStack({ alignment: "center", distribution: "space-between", sp
 | `wrap` | `boolean` | Wrap children onto the next line when the row runs out of space. Defaults to `false`. |
 | `grow` | `number` | Share of the parent stack's free space this stack takes, against its siblings. Unset, a stack nested in an `HStack` shares the row equally with its sibling stacks, or keeps its content width when the row has a `Spacer`. |
 
-### VStackOptions
+### `VStackOptions`
 
 | Option | Type | Description |
 | --- | --- | --- |
@@ -100,7 +99,7 @@ static toolbar = HStack({ alignment: "center", distribution: "space-between", sp
 | `spacing` | `string` | Space between children, as a CSS length. Defaults to `"8px"`. |
 | `grow` | `number` | Share of the parent stack's free space this stack takes, against its siblings. Unset, a stack nested in an `HStack` shares the row equally with its sibling stacks, or keeps its content width when the row has a `Spacer`. |
 
-### SpacerOptions
+### `SpacerOptions`
 
 | Option | Type | Description |
 | --- | --- | --- |
@@ -114,7 +113,7 @@ The three builders apply their defaults into the options they carry, so a `Space
 
 `Tab` declares a tab bar. Each `TabItem` names a `slot`, and the component that belongs in a tab is attached as a child with that slot.
 
-```typescript
+```typescript fragment
 import { Tab, TabVariant } from "@antelopejs/interface-dms/base/tab";
 import { Color, Size } from "@antelopejs/interface-dms/base/types";
 
@@ -133,7 +132,7 @@ static tabs = Tab({
   .child("members", membersTable, { slot: "members" });
 ```
 
-### TabProps
+### `TabProps`
 
 `TabProps` extends [`BaseComponentProps`](/docs/interfaces/base/types).
 
@@ -149,7 +148,7 @@ static tabs = Tab({
 | `persistState` | `boolean` | Keep the active tab in the URL by its slot (`?<stateKey>=<slot>`); an index (`?tab=2`) is still read. |
 | `stateKey` | `string` | Key the state is stored under. |
 
-### TabItem
+### `TabItem`
 
 | Field | Type | Description |
 | --- | --- | --- |
@@ -165,261 +164,11 @@ static tabs = Tab({
 
 `TabEvents.TAB_CHANGE` is `"DmsComponent.Tab.Change"`.
 
-## Page Layouts
-
-A page layout is the third argument of `PageController`. It is optional: a page that omits it is registered with `DefaultLayout()` and its default options.
-
-```typescript
-import {
-  PageController,
-  pagesCategory,
-  RegisterPage,
-} from "@antelopejs/interface-dms/page";
-import { DefaultLayout } from "@antelopejs/interface-dms/base/layouts";
-
-@RegisterPage()
-export class OverviewPage extends PageController(
-  "overview",
-  { displayName: "Overview", icon: "i-ph-gauge", category: pagesCategory },
-  DefaultLayout({ hideHeader: true }),
-) {
-  static content = overviewGrid;
-}
-```
-
-`DefaultLayout(options?)` returns the `ComponentInfo` for `dms-default-layout`.
-
-| Option | Type | Description |
-| --- | --- | --- |
-| `fullWidth` | `boolean` | Let the content span the whole panel instead of a constrained column. Defaults to `true`. |
-| `hideHeader` | `boolean` | Omit the page header. |
-| `fillHeight` | `boolean` | Let the page fill the height of the panel instead of growing with its content, for a tool that scrolls inside itself — see [Pages that fill the panel](#pages-that-fill-the-panel). Defaults to `false`. |
-| `headerActions` | `CustomButton[]` | Buttons right of the page title, in order — see [Header actions](#header-actions). |
-| `record` | `PageRecordLoader` | Reads the record the page shows, with the layout, for the header buttons acting on it and every `availability` of the page — see [Buttons acting on the page's record](#buttons-acting-on-the-pages-record). |
-
-Dashboard pages are full-width unless they opt out, which is what a table, a grid of cards or a chart wants. Set `fullWidth: false` for a page that only holds a form, where a constrained column stays readable — or use `FormPageLayout`, which is exactly that:
-
-```typescript
-import { FormPageLayout } from "@antelopejs/interface-dms/base/layouts";
-
-const layout = FormPageLayout({ hideHeader: true });
-```
-
-Its optional argument accepts `DefaultLayoutOptions` without `fullWidth`; the return value is a `ComponentInfo`.
-
-The generated `new` and `edit` pages of a table view use it, unless their page's category chain declares a layout, so a form page you write by hand matches them without your having to remember the flag.
-
-`SettingsLayout(options?)` returns the `ComponentInfo` for `dms-settings-layout`: the dashboard frame with the settings navigation next to the page, in the column width every settings page shares. Its options are `DefaultLayoutOptions` without `fullWidth`. `settingsCategory` declares it as its `layout`, so the pages under the settings root get it without naming it ([Settings pages](/docs/building/settings-pages)).
-
-`EmptyLayout()` takes no options and returns the `ComponentInfo` for `dms-empty-layout`, with an empty options object. Use it for pages that draw their own chrome — sign-in and onboarding screens, for instance.
-
-Because they return a plain `ComponentInfo` rather than a `ComponentBuilder`, the page layouts have no `.child()`, `.meta()` or `.watch()`.
-
-### Header actions
-
-A page puts its main actions next to its title — a primary "New invoice", an "Export", a link to the docs — with `headerActions`: the same `CustomButton`s as a table's toolbar (see [Tables](/docs/components/tables)), plus an `order` (`PageHeaderButton`), so a header button opens a link, runs a [quick action](/docs/interfaces/core/quick-actions), opens a drawer or a modal, calls an API or runs an export, with a confirmation and an availability of its own:
-
-```typescript
-import { DefaultLayout } from "@antelopejs/interface-dms/base/layouts";
-
-DefaultLayout({
-  headerActions: [
-    {
-      id: "docs",
-      label: "Documentation",
-      icon: "i-ph-book-open",
-      target: { type: "external", url: "https://antelopejs.com/docs", newTab: true },
-    },
-    // An empty label lends the quick action's name (and its icon).
-    { id: "new", label: "", color: "primary", target: { type: "quickAction", id: "billing:new-invoice" } },
-    {
-      id: "audit",
-      label: "Audit log",
-      icon: "i-ph-scroll",
-      target: { type: "page", url: "/audit" },
-      permission: "audit", // pages.billing.audit on the page pages.billing
-    },
-  ],
-});
-```
-
-| Field | Type | Description |
-| --- | --- | --- |
-| `id` | `string` | Key of the button, unique in the header. Defaults to its place (`header-0`, …). |
-| `label` | `string` | Button text (i18n key with `$` or literal). A quick action lends its own name to an empty label. |
-| `icon` | `string` | Icon name. A quick action lends its own icon. |
-| `target` | `ActionTarget` | What the button does: `page` or `external` (drawn as a link), `quickAction` (`{ id }`: `category:id`, or the bare id), `drawer`, `modal`, `api`, `exportJob`, `download` (`{ url, filename? }`: fetched with the user's session and saved). |
-| `confirm` | `ConfirmDialog \| { from }` | Asked before the target runs. |
-| `color` | `"primary" \| "neutral" \| …` | Defaults to `neutral`, an outline button; any other color is solid. |
-| `variant` | `ButtonVariant` | Overrides the fill derived from the color. |
-| `permission` | `string \| Action` | Action of the page, relative to its permission id (`"export"` on `pages.sales` → `pages.sales.export`), or an `Action` of any component, the user must hold to see the button. |
-| `permissionId` | `string` | Absolute permission id the user must hold to see the button; wins over `permission`. |
-| `availability` | `CustomButtonAvailability` | Disables the button for a request it answers `{ reason }` with, the reason shown in a tooltip; leaves it out of the header for one it answers `{ hidden: true }`. Receives the page URL's query as `context.query`. |
-| `order` | `number` | Place among the header's buttons, smallest first; defaults to `0`. See [Ordering the header](#ordering-the-header). |
-
-#### Buttons that follow the page URL
-
-A page scoped by its URL — `?workspace=web`, a record id in the path — declares its buttons once and lets them follow the URL. A target's URL (`page`, `external`, `download`, `api`, `exportJob`) takes the tokens of a block's `fetchUrl`: `{{params.X}}` is filled with the route parameter `X` of the page, `{{query.X}}` with its query parameter `X`, percent-encoded, again whenever the URL changes. A query pair whose value is a token the page has no value for is left out (`?workspace={{query.workspace}}` on a page without `?workspace=` leads to the target's default), and any other token without a value is left empty. A `download` target's `filename` takes the same tokens, written as they are; while one has no value, the file is saved under the server's name:
-
-```ts
-{
-  id: "download-language",
-  label: "$lang.queue.download", // "Download {locale}.json"
-  icon: "i-ph-download-simple",
-  target: {
-    type: "download",
-    url: "/api/lang/translations/export?workspace={{query.workspace}}&locale={{query.locale}}",
-    filename: "{{query.locale}}.json",
-  },
-}
-```
-
-A label's translation takes the page's route and query parameters as its own (a query parameter wins over a route parameter of the same name), so `"Download {locale}.json"` names the language of `?locale=fr` and follows it as the URL changes.
-
-An `availability` receives the page URL's query as `context.query` (one value per name; caller-supplied, so check it like any input), its route parameters as `context.params` (`/projects/project/p1` on a page registered at `/projects/project/:id` is `{ id: "p1" }`), and the record the layout read as `context.record` ([Buttons acting on the page's record](#buttons-acting-on-the-pages-record)). The header asks again whenever the query or the route parameters change, and once a write refreshed the page — only when one of its buttons declares an `availability` or the layout reads a `record` — and keeps the buttons it has until the answer lands. The keys the DMS writes for the view itself never cause a request: `record` (the row open in a side panel), `live` (the paused live mode) and a period selector's `<id>.period`, `<id>.compare`, `<id>.from`, `<id>.to`, `<id>.compareFrom` and `<id>.compareTo`. A query key may carry dots, so `{{query.api.period}}` reads a period selector's choice.
-
-```typescript
-DefaultLayout({
-  headerActions: [
-    {
-      id: "matrix",
-      label: "$lang.queue.open_matrix",
-      icon: "i-ph-table",
-      target: { type: "page", url: "/modules/lang/translations?workspace={{query.workspace}}&missingIn={{params.locale}}" },
-    },
-    {
-      id: "download",
-      label: "$lang.queue.download",
-      target: { type: "api", url: "/api/lang/export?workspace={{query.workspace}}", successMessage: "$lang.exported" },
-      availability: async ({ query }) =>
-        (await workspaceExists(query?.workspace)) ? undefined : { reason: "$lang.workspace.unknown" },
-    },
-  ],
-});
-```
-
-A table view of the page places its own buttons in the header with `placement: "header"` — a custom button, or its built-in add (`rowActions: { add: { placement: "header" } }`): the server adds them after the layout's own buttons, served as the table view was (left out without its permission or when its `availability` hides it, disabled with the reason its `availability` gives), and the table view runs them, in place. They take the order `0`.
-
-Who sees a button is settled on the server when the layout is served: a button whose `permission` or `permissionId` the user lacks is left out of the layout, and a quick-action button only shows to the users the quick action is served to — that is, the users its page admits. A page drawn by a Vue page component can add its own buttons next to these with `usePageHeaderActions`; call it before the first `await` of the component's setup, so the server renders the buttons with the page and they never pop in. A page whose changes save as soon as they are made shows the shared **Saved instantly** pill there with `useInstantSaveHeader` ([Instant save or a save bar](/docs/components/lists-and-settings/section#instant-save-or-a-save-bar)).
-
-#### Buttons acting on the page's record
-
-A page about one record (a site, an invoice) reads it with its layout: `record` is a function the server calls each time it serves the layout, with the request's context — the page URL's `params` and `query`, the `user` and the `tenantId` — and answers the record, or `undefined` when there is none to show. A button's target names its fields as `{{record.X}}`, filled in by the server and percent-encoded: a maps link to the site's address, an API call on its own id. A button acting on the record — one whose target names `{{record.X}}`, or declaring `requiresRecord: true` (an "Edit" link that only needs `{{params.id}}`) — is left out of a page whose record was not found, or whose `record` threw (logged). Every `availability` of the page reads the record as `context.record`, so a button can be disabled on the record's state without reading it again:
-
-```typescript
-DefaultLayout({
-  record: ({ params }) => GetModel(SiteModel).get(params?.id ?? ""),
-  headerActions: [
-    {
-      label: "$sites.directions",
-      icon: "i-ph-map-pin",
-      target: { type: "external", url: "https://www.google.com/maps/search/?api=1&query={{record.address}}", newTab: true },
-    },
-    { label: "$sites.edit", requiresRecord: true, target: { type: "page", url: "/sites/{{params.id}}/edit" } },
-    {
-      label: "$sites.close",
-      target: { type: "api", url: "/api/sites/close?id={{params.id}}" },
-      availability: ({ record }) => (record?.closed ? { reason: "$sites.already_closed" } : undefined),
-    },
-  ],
-});
-```
-
-The record travels with the layout, so the header is drawn with it, on the server too, and never waits for it. Like an `availability`, it follows the page URL: the header asks for its buttons again when the route parameters or the query change, and once a write refreshed the page (`refreshPageBlocks()`, which a header button calls after a change, and a form once it saved). Its fields only shape the buttons; the route behind each one still checks the record on its own.
-
-#### A record deleted under the page
-
-A page reading a `record` leaves it once it is deleted, in every tab and for every member on it, with no code of the module. On each event of one of the page's realtime topics (its table views' rows, a `realtimeTopic`, a topic bound with `RegisterPageTopic`), the page asks its layout again: a record the server found before and now finds none of (its `record` answers `undefined`) was deleted. A toast says so, and the page opens the list it is a detail of (`MenuOptions.parent`); without one, it stays, on the "not found" state of its blocks. A `record` that throws counts as unknown, never as deleted, and a page opened on a record that never existed shows its blocks' "not found" state without a toast. Publish on one of the page's topics when the record is deleted: a table view's delete does it on its own.
-
-#### Hidden or disabled
-
-An `availability` has three answers. `undefined` leaves the button as declared, `{ reason }` disables it with the reason in a tooltip — for something the user can change ("No seat left: upgrade the plan") — and `{ hidden: true }` leaves it out of the header, as a missing permission does — for a button that makes no sense in the scope the page shows. Like a disabled one, a hidden button follows the page URL: the header asks again when the query changes, so a button can disappear on one `?workspace=` and come back on another, and the server-rendered header already carries the answer for the URL it was rendered for.
-
-```typescript
-DefaultLayout({
-  headerActions: [
-    {
-      id: "add-key",
-      label: "$lang.keys.add",
-      color: "primary",
-      target: { type: "drawer", component: AddKeyForm() },
-      availability: async ({ query }) =>
-        (await workspaceOf(query?.workspace))?.readOnly ? { hidden: true } : undefined,
-    },
-  ],
-});
-```
-
-A detail page reads its record from `context.params`, and hides the buttons that act on it when the record does not exist — the page then shows its "not found" state with no "Edit" or "Delete" beside the title:
-
-```typescript
-DefaultLayout({
-  headerActions: [
-    {
-      id: "edit",
-      label: "$projects.edit",
-      target: { type: "page", url: "/projects/project/{{params.id}}/edit" },
-      availability: async ({ params }) =>
-        (await projectExists(params?.id)) ? undefined : { hidden: true },
-    },
-  ],
-});
-```
-
-Hiding only shapes the UI: the route behind the button must still refuse the operation on its own.
-
-#### Ordering the header
-
-The header shows, left to right, the buttons the layout declares, the buttons a table view places there (`placement: "header"`), then the actions a Vue component of the page adds with `usePageHeaderActions` ([UI toolkit](/docs/frontend-composables/ui-toolkit#page-header-actions-usepageheaderactions)). To interleave them, give a button an `order` and the component's actions one too (`usePageHeaderActions(render, { order })`): the header sorts everything by `order`, smallest first, `0` when none is given, and at an equal order keeps the served buttons first, in the order above. So `{ order: -1 }` on a component's actions puts them before every served button left at the default:
-
-```typescript
-// The served "Add key" stays at the default order, 0.
-DefaultLayout({ headerActions: [{ id: "add-key", label: "$lang.keys.add", color: "primary", target }] });
-```
-
-```vue [app/components/TranslationMatrix.vue]
-<script setup lang="ts">
-import { usePageHeaderActions } from "#dms-layout/app/composables/layout/usePageHeaderActions";
-
-// Export, built in the browser, goes before the served "Add key".
-usePageHeaderActions(() => h(UButton, { label: t("lang.export"), icon: "i-ph-download-simple", onClick: exportCsv }), { order: -1 });
-</script>
-```
-
-### Pages that fill the panel
-
-A page built around one tool — a file explorer, a data grid, a graph canvas — usually wants that tool to take the height of the panel and scroll inside itself, rather than make the whole page scroll. Set `fillHeight` on its layout:
-
-```typescript
-DefaultLayout({ fillHeight: true })
-```
-
-The layout then lays the page out as a flex column the height of the panel. The page header keeps its own height and the height left under it goes to the **last component** of the page; the components above it keep theirs. Give the root of that component `flex-1 min-h-0`, and let an element inside it scroll:
-
-```vue [app/components/MyExplorer.vue]
-<template>
-  <div class="flex min-h-0 flex-1 flex-col gap-4">
-    <MyToolbar />
-    <div class="min-h-0 flex-1 overflow-y-auto">
-      <!-- the rows -->
-    </div>
-  </div>
-</template>
-```
-
-A custom page — a page component your frontend layer registers under the page's slug — sits straight in the layout, so its own root takes `flex-1 min-h-0` the same way.
-
-Do not size the tool from the viewport, with `h-[calc(100vh-…)]` or an offset measured in the browser. The dashboard header, the [layout banners](/docs/interfaces/core/layout-banners), the page header and the panel padding all take height above the page, and that height changes: a banner shows up or is dismissed, a description wraps. The layout accounts for all of it.
-
-- **Minimum height.** The page area, header included, never gets shorter than 30rem: on a shorter panel it stops shrinking and the panel scrolls again. The floor sits on the page area rather than on the tool, because a `min-h-*` set inside the page overflows the column, and the panel then scrolls past its own bottom padding. A tool that needs more room than what is left to it at that floor — one that shares its component with a card of figures, say — can still set its own `min-h-*`, at that cost.
-- **Every width.** The page fills the panel on a phone too: the panel is the part of the dashboard that scrolls at every width. A page whose panes stack on a narrow screen (`grid-cols-1 lg:grid-cols-[…]`) decides how they share the height there, or lets its own root scroll below that breakpoint (`max-lg:overflow-y-auto`).
-- **Several components.** Only the last one fills. Put the tool last, under whatever summarizes it, or keep both in one component that lays them out itself.
-
 ## Guard
 
 `Guard` is a container that renders its children unchanged unless a route says there is nothing for them; then it renders one `EmptyState`, its `fallback`, in their place. Several children stack with the spacing the page puts between its blocks.
 
-```typescript
+```typescript fragment
 import { Guard } from "@antelopejs/interface-dms/base/guard";
 
 static statistics = Guard({
@@ -451,7 +200,7 @@ An `emptyState` object in the answer, or in the body of the 404, is laid over `f
 
 `Placeholder` renders a labelled box. It exists so a layout can be assembled and reviewed before the real components are written. It takes `PlaceholderOptions`:
 
-```typescript
+```typescript fragment
 import { Placeholder } from "@antelopejs/interface-dms/base/placeholder";
 
 static preview = Placeholder({ label: "Chart goes here", height: "200px" });
@@ -463,11 +212,11 @@ static preview = Placeholder({ label: "Chart goes here", height: "200px" });
 | `height` | `string` | CSS height. Defaults to `"120px"`. |
 | `width` | `string` | CSS width. Auto by default. |
 
-## CustomComponent
+## `CustomComponent`
 
 `CustomComponent(componentName)` returns a bare `ComponentBuilder` for a frontend component resolved by name. Nothing else in the `base` domain is involved: the options you pass with `.options()` are handed to that component as-is, and the component itself comes from a frontend module registered with `AddFrontendModule`.
 
-```typescript
+```typescript fragment
 import { CustomComponent } from "@antelopejs/interface-dms/base/custom";
 
 static activity = CustomComponent("DmsAiActivityView").meta({
@@ -478,6 +227,8 @@ static activity = CustomComponent("DmsAiActivityView").meta({
 
 Since the return value is an ordinary builder, `.options()`, `.child()`, `.meta()`, `.watch()`, `.onCreated()` and `.onFilter()` all apply, and the component can hold `base` components as children.
 
-`CustomComponent` is also how a table view's `formContainer.pages.*.customPage` option is used: you register your own page carrying a custom component at the slug the table view would otherwise generate — declare that slug as the entry's `urlSlug`, which is taken relative to the page as it stands — see [Tables](/docs/interfaces/base/tables).
+`CustomComponent` is also how a table view's `formContainer.pages.*.customPage` option is used: you register your own page carrying a custom component at the slug the table view would otherwise generate. Declare that slug as the entry's `urlSlug`, which is taken relative to the page as it stands. See [Tables](/docs/interfaces/base/tables).
+
+## Next steps
 
-## Next Steps
+- [Page layouts](/docs/interfaces/base/page-layouts): The layouts a page renders in, its header actions, and pages that fill the panel.