@antelopejs/interface-dms 0.10.3 → 0.12.0

package/docs/3.base/10.display-blocks.md

@@ -1,10 +1,9 @@
 ---
-title: "Display Blocks"
+title: "Display blocks"
 description: "Seven builders cover the summaries and notices around a page's data: `StatGroup`, `KeyValueList`, `NavCardGrid`, `EmptyState`, `Banner`, `Card` and `CodeBlock`."
+mode: reference
 ---
 
-# Display Blocks
-
 ## Overview
 
 Seven builders cover the summaries and notices around a page's data: `StatGroup`, `KeyValueList`, `NavCardGrid`, `EmptyState`, `Banner`, `Card` and `CodeBlock`. Each returns a `ComponentBuilder` and registers its block type with an options schema, so `ListBlockTypes()` describes it to a page builder. `Card` is a container; the others are leaves. The task-shaped chapter is [Display blocks](/docs/components/display-blocks).
@@ -33,7 +32,7 @@ import {
 
 Every factory but `EmptyState` takes its options as optional, so a block placed before it is configured is the bare call `StatGroup()`. `EmptyState(options)` requires its options, `title` included.
 
-## Shared Vocabulary
+## Shared vocabulary
 
 `display` holds what the six share; the tones come from `types/tone`, also re-exported by the `base` barrel. `color` is for what is clicked (buttons, row actions, header actions, tabs), `tone` for what shows a state (pills, icon wells, banners, meters, notifications, blocks).
 
@@ -52,9 +51,9 @@ Every factory but `EmptyState` takes its options as optional, so a block placed
 
 A block that can drop its frame does so with `card?: boolean` (`KeyValueList`, `EmptyState`, and the `ActivityFeed`, `Meter` and `Section` of [Lists & settings](/docs/components/lists-and-settings)); `Card` itself has `padded`. In the page editor a `fetchUrl` is picked in the data-source picker (widget `dataSource`).
 
-## List Blocks
+## List blocks
 
-`StatGroupProps`, `KeyValueListProps` and `NavCardGridProps` — and `ActivityFeedProps` ([Lists & settings](/docs/components/lists-and-settings)) — extend `BaseComponentProps` and `BlockItemsSource`. Their `items` are static; a `fetchUrl` replaces them with the `items` of its answer, `{ items: T[] }`, in the same item shape. An `ActivityFeed`'s answer may add a `count` (`ActivityFeedResponse`), drawn beside its title in place of its `count` option. When there is nothing to list, the block shows `empty`.
+`StatGroupProps`, `KeyValueListProps` and `NavCardGridProps`, and `ActivityFeedProps` ([Lists and settings](/docs/components/lists-and-settings)), extend `BaseComponentProps` and `BlockItemsSource`. Their `items` are static; a `fetchUrl` replaces them with the `items` of its answer, `{ items: T[] }`, in the same item shape. An `ActivityFeed`'s answer may add a `count` (`ActivityFeedResponse`), drawn beside its title in place of its `count` option. When there is nothing to list, the block shows `empty`.
 
 `fetchUrl` may name the record of the page it is on: `{{params.X}}` is filled with the route parameter `X` of the page URL (`{{params.id:n}}` for the n-th of a repeated name), `{{query.X}}` with its query parameter `X`, as in a form's `fetchUrl`. The block reads it again when they change and requests nothing while a token has no value. The same holds for the `fetchUrl` of `KpiCard`, `TopListCard`, `Meter`, `ChartCard` and the charts, and for `TabProps.badgesUrl`.
 
@@ -80,7 +79,7 @@ A block that can drop its frame does so with `card?: boolean` (`KeyValueList`, `
 
 `STAT_GROUP_LAYOUTS` is `joined`, `cards`; `KEY_VALUE_TYPES` is `text`, `status`, `money`, `date`, `link`, `mono`.
 
-## Composed Texts
+## Composed texts
 
 `StatGroupItem.eyebrow`, `.value` and `.detail`, `KeyValueListItem.label`, `.value` and `.detail`, `NavCardItem.title`, `.description`, `.state`, `.tag` and `.readout` lines, `ActivityFeedItem.title`, `.meta` entries, `.detail` and `.time`, `ActivityFeedProps.badge`, `MeterProps.hint` and `.valueLabel`, `MeterSegment.label`, `TopListItem.title`, `.description` and `.valueLabel`, `BannerProps.title` and `.description`, and a layout banner's `text` are typed `BlockText`: a plain string as before, or a `ComposedText` the frontend writes in the reader's locale. The block schemas accept both (`ValidateBlockOptions` refuses a parameter of an unknown `type`) and describe the field with the `text` widget. The task-shaped guide is [Composed texts](/docs/components/block-fundamentals#composed-texts).
 
@@ -99,7 +98,7 @@ A block that can drop its frame does so with `card?: boolean` (`KeyValueList`, `
 | `COMPOSED_TEXT_DATE_FORMATS`    | constant  | `day`, `short`, `medium`, `long` (`ComposedTextDateFormat`).                                |
 | `COMPOSED_TEXT_NUMBER_FORMATS`  | constant  | `decimal`, `percent`, `compact` (`ComposedTextNumberFormat`).                               |
 
-## Static Blocks
+## Static blocks
 
 | Props             | Options                                                                                               |
 | ----------------- | ----------------------------------------------------------------------------------------------------- |
@@ -111,37 +110,37 @@ A block that can drop its frame does so with `card?: boolean` (`KeyValueList`, `
 
 `EMPTY_STATE_VARIANTS` is `no-data`, `no-result`, `no-access`, `error`; `EMPTY_STATE_SIZES` is `sm`, `md`, `lg`. `BANNER_TONES` is `info`, `success`, `warning`, `error`, `primary`; `BANNER_SIZES` is `md`, `sm`. `CARD_VARIANTS` is `default`, `elevated`. The three props extend `BaseComponentProps` (`watchActions`) like the list blocks. `BannerTone` is `Extract<Tone, …>` over `BANNER_TONES`. A banner's `dismissKey` defaults to the block's id on its page (`welcome` for `.child("welcome", Banner(…))`), which holds when blocks are added or moved. A banner's `fetchUrl` answers a `BannerContent` (the content fields of `BannerProps`, its `actions` being `BannerAction[]`: a `BlockLinkAction` or a `BannerButtonAction`, the `label`, `icon`, `variant`, `color`, `target` and `confirm` of a `CustomButtonSerialized`), or `null`, `{}` or a 204 for no banner; its fields override the options one by one. `realtimeTopic` registers each topic on the page the banner is placed on, as a chart's does.
 
-## Code Block
+## Code block
 
 `CodeBlockProps` extends `BaseComponentProps`: `code`, `language` (`CodeBlockLanguage`, default `text`), `copy` (default `true`), `title` (`BlockText`), `maxLines`, `wrap`, `fetchUrl` and `fetchUrlMethod`. `CODE_BLOCK_LANGUAGES` is `json`, `javascript`, `typescript`, `html`, `sql`, `shell`, `text`. A `fetchUrl` answers a `CodeBlockResponse`, `{ code, language? }`, which replaces `code` and `language`; it takes the `{{params.X}}` / `{{query.X}}` tokens and `BlockFunctions.REFRESH_PAGE` like the list blocks. `CodeBlock(options?)` takes its options as optional.
 
-## Card Slots
+## Card slots
 
 `Card` registers `container: true` and two slots, `CARD_ACTIONS_SLOT` (`"actions"`, next to the head's link buttons) and `CARD_FOOTER_SLOT` (`"footer"`, the foot band). Children without a slot render in the body; each slot holds one child.
 
-```typescript
+```typescript fragment
 Card({ title: "Connectors", count: 4 })
   .child("list", KeyValueList({ card: false, items }))
   .child("foot", HStack(), { slot: CARD_FOOTER_SLOT });
 ```
 
-## Live Toggle
+## Live toggle
 
 `LiveToggle(options?)` (subpath `live-toggle`, block type `LiveToggle`, component `dms-live-toggle-block`, group `data`) is the Live / Pause switch of a page declared with `live` (`PageLiveOptions` from `@antelopejs/interface-dms/page`). `LiveToggleProps` extends `BaseComponentProps`: `align` (`LIVE_TOGGLE_ALIGNS`: `left`, `center`, `right`; default `right`) `showUpdatedAt` (default `true`), the time since the page last read its data, counted in the browser, `variant` (`LIVE_TOGGLE_VARIANTS`: `segmented`, `pill`; default `segmented`), `size` (`LIVE_TOGGLE_SIZES`: `xs`, `sm`, `md`; default the holding `PageToolbar`'s, else `sm`) and `missedLabel`, an i18n key or text given `{count}` naming the missed events while paused. The state belongs to the page, not to the block; on a page without `live` the block renders nothing.
 
-```typescript
+```typescript fragment
 import { LiveToggle } from "@antelopejs/interface-dms/base/live-toggle";
 
 static toolbar = HStack().child("spacer", Spacer()).child("live", LiveToggle());
 ```
 
-## Page Toolbar
+## Page toolbar
 
-`PageToolbar(options?)` (subpath `page-toolbar`, block type `PageToolbar`, component `dms-page-toolbar-block`, group `data`, a container) is the context bar of a page with a period or live data, first in its body. `PageToolbarProps` extends `BaseComponentProps`: `size` (`PAGE_TOOLBAR_SIZES`: `xs`, `sm`, `md`; default `sm`), the size of the `LiveToggle` and `PeriodSelector` it holds unless they set one, and `showUpdatedAt` and `refresh` (both default `true`), the "updated N s ago" label and the refresh button it shows where no `LiveToggle` is on screen — a page without `live` — counted from the page's last read. Its children render in one order whatever order they were added in: the other blocks, a spacer, the updated label or the `LiveToggle`, then the `PeriodSelector`.
+`PageToolbar(options?)` (subpath `page-toolbar`, block type `PageToolbar`, component `dms-page-toolbar-block`, group `data`, a container) is the context bar of a page with a period or live data, first in its body. `PageToolbarProps` extends `BaseComponentProps`: `size` (`PAGE_TOOLBAR_SIZES`: `xs`, `sm`, `md`; default `sm`), the size of the `LiveToggle` and `PeriodSelector` it holds unless they set one, and `showUpdatedAt` and `refresh` (both default `true`), the "updated N s ago" label and the refresh button it shows where no `LiveToggle` is on screen (a page without `live`), counted from the page's last read. Its children render in one order whatever order they were added in: the other blocks, a spacer, the updated label or the `LiveToggle`, then the `PeriodSelector`.
 
 `pageToolbar(options?)` builds one: `PageToolbarOptions` extends `PageToolbarProps` with `leading` (`Record<string, Component>`, the blocks on the left by child id), `live` (`LiveToggleProps | false`, child `live`, over `PAGE_TOOLBAR_LIVE_DEFAULTS`) and `period` (`PeriodSelectorProps | false`, child `period`, over `PAGE_TOOLBAR_PERIOD_DEFAULTS`: segmented `last-hour` / `last-24h` / `last-7-days` / `last-30-days`, `defaultPreset: "last-24h"`, `rangeLabel: "relative"`, right aligned). Unless `period` sets `comparisonControl`, it is `"menu"` when the period offers more than one comparison (`none` included; the selector's default list when `comparisons` is unset), on `defaultComparison` or else the first one besides `none`, and `"hidden"` with a single comparison or none.
 
-```typescript
+```typescript fragment
 import { pageToolbar } from "@antelopejs/interface-dms/base/page-toolbar";
 
 static toolbar = pageToolbar({

package/docs/3.base/11.page-layouts.md

@@ -0,0 +1,273 @@
+---
+title: "Page layouts"
+description: The layouts a page renders in, the buttons of its header, and pages that fill the panel.
+mode: reference
+---
+
+A page renders its components inside a layout. This page covers the layouts `interface-dms` exports, the header actions a page declares, and pages that fill the panel. The containers that arrange components inside a page are in [Layout and containers](/docs/interfaces/base/layout).
+
+## 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 fragment
+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, such as sign-in and onboarding screens.
+
+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, such as a primary "New invoice", an "Export" or 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, such as `?workspace=web` or 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 fragment
+{
+  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 fragment
+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, which are 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
+import { BasicDataModel, Field, GetModel, RegisterTable, Table } from "@antelopejs/interface-database-decorators";
+import { DefaultLayout } from "@antelopejs/interface-dms/base/layouts";
+
+@RegisterTable("sites", "example_sites")
+class Site extends Table {
+  @Field("string") declare address: string;
+  @Field("boolean") declare closed: boolean;
+}
+
+class SiteModel extends BasicDataModel(Site, "sites") {}
+
+DefaultLayout({
+  record: async ({ params }) => {
+    const site = await GetModel(SiteModel).get(params?.id ?? "");
+    return site && { ...site };
+  },
+  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}}", successMessage: "$sites.closed" },
+      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"). `{ 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 fragment
+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 fragment
+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 fragment
+// 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, such as a file explorer, a data grid or 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
+import { DefaultLayout } from "@antelopejs/interface-dms/base/layouts";
+
+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, such as one that shares its component with a card of figures, 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.

package/docs/3.base/12.table-row-actions.md

@@ -0,0 +1,122 @@
+---
+title: "Table row actions"
+description: The row actions of a table view, archive mode, and the guards that run before each write.
+mode: reference
+---
+
+These are the options of a [table view](/docs/interfaces/base/tables) that act on its rows: row actions and their extras, archive mode, and the guards its routes run before each write.
+
+## Row actions
+
+`TableViewRowActionOptions<T>` configures the row menu. Every built-in action takes `true`, `false`, or a `RowActionConfig<T>` carrying a rule.
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `add` | `boolean \| RowActionConfig<T>` | Create a row. |
+| `edit` | `boolean \| RowActionConfig<T>` | Edit a row. |
+| `details` | `boolean \| RowActionConfig<T>` | Open the read-only view. |
+| `duplicate` | `boolean \| RowActionConfig<T>` | Open the `new` form pre-filled from the row. |
+| `delete` | `boolean \| RowActionConfig<T>` | Delete a row. |
+| `archive` | `boolean \| RowActionConfig<T>` | Archive a row. |
+| `restore` | `boolean \| RowActionConfig<T>` | Restore an archived row. |
+| `copyLink` | `boolean \| RowActionConfig<T>` | Copy a link to the row. |
+| `hasSelection` | `boolean` | Enable row selection. |
+| `custom` | `CustomRowAction<T>[]` | Extra actions pointing at an `ActionTarget`. |
+
+```typescript fragment
+static table = TableView(memberDataAPI, {
+  rowActions: {
+    add: false,
+    edit: { isEnabled: true, isVisible: true },
+    delete: { isEnabled: true, rule: { field: "isTenantOwner", notEquals: true } },
+    hasSelection: true,
+    custom: [
+      {
+        label: "Validate email",
+        icon: "i-ph-check-circle",
+        target: {
+          type: "api",
+          url: "/settings/workspace/members/{{row._id}}/validate-email",
+          method: "POST",
+          successMessage: "Email validated",
+        },
+        rule: { field: "isValidated", notEquals: true },
+      },
+    ],
+  },
+});
+```
+
+A double-click on a row opens `edit`, or `details` when edit is off. It is a single click on a table declaring `rowClick: "single"` (`TableViewRowClick`), which leaves a click on a control of the row (a button, a link, a checkbox) or one ending a text selection to them. A custom action flagged `isDefault` takes that slot instead. The first flagged action whose `rule` accepts the row wins, and the click opens its `ActionTarget` like the menu entry does. This is how a table whose detail view is a custom drawer keeps the row affordance: without a click target the row is inert and no longer lights up on hover.
+
+```typescript fragment
+custom: [
+  {
+    label: "Details",
+    icon: "i-ph-info",
+    isDefault: true,
+    target: { type: "drawer", component: CustomComponent("SendDetailDrawer"), title: "Details" },
+  },
+],
+```
+
+Rules are enforced on both sides. A data controller has one **writing** table view: a `TableView` enabling at least one write action (add, duplicate, edit, delete, archive or restore) that the controller offers. Its `rowActions` (archive-mode defaults included) become the controller's `controllerRowActionRules`, along with its `rowIdKey` and `strictRuleValidation`. The `edit`, `delete`, `archive` and `restore` routes validate the affected ids against those rules before running. Rows that fail the rule are dropped from the operation; with `strictRuleValidation` the whole request is rejected instead.
+
+A second writing table view over the same controller fails the registration of its page with a `WritingTableViewConflictError` (a `PageDeclarationConflictError`, rethrown even from a nested component) naming both table views. Read-only table views, with every write action set to `false` and no `archiveMode`, may share the controller: they open no `new` / `edit` form and leave its rules and options alone. A page re-registering (a hot reload) re-claims the controller; a page that went away releases it. To give the same data a second writing screen, derive a controller (see [Show the same data in two writing screens](/docs/components/derived-controller)).
+
+Permissions are applied on top. The table view registers `list` and `select` as component actions always, `add`, `edit` and `view` when the matching generated form exists, `delete` when the controller declares the delete endpoint, `archive`, `restore` and `viewArchived` under `archiveMode`, and `export` when the three export endpoints are registered. Each action carries a permission id of the form `<component-permission>.<action>`. When the viewer lacks the permission the corresponding row action is forced to `false` and the corresponding generated form is withheld. The rule algebra itself (leaf operators, `and`, `or`, `not`, and `RowActionConfig`) is documented in [Shared types](/docs/interfaces/base/types).
+
+Several pages may each mount their own `TableView` over one data controller, and they all share its data routes. A read action (`list`, `select`, `view`, `export`, `viewArchived`) accepts the permission from any table view a page mounts on that controller; a write action (`add`, `edit`, `delete`, `archive`, `restore`) accepts only the writing table view's, so a user granted `add` on a read-only table view cannot create rows. A read-only table view still declares the write actions the controller offers: while no table view writes through the controller, they keep its write routes behind permission ids nobody is granted by default. The inline add button of a relation field pointing at the controller follows the same rule (`addPermissionIds`).
+
+A `new` or `edit` `ResourceForm` block over the controller submits to the same routes, so the native files staged from its fields are accepted on save as well, alongside those of the writing table view. It adds no permission of its own to the union: the routes still require the action's permission from a table view of the controller when one is mounted, exactly as for the block's other fields. The `new` and `edit` forms a page-mode table view mounts on its form sub-pages count the same way: each is a component of its own sub-page, so the files staged from it are accepted on save, under the same table view permissions.
+
+`TableViewRowActionOptionsSerialized` is the transported shape: rules and flags untyped, `custom` as `CustomRowActionSerialized[]`, plus a `showArchived?: boolean` field the builder fills from the `viewArchived` permission.
+
+### Row action extras
+
+`TableViewRowActionOptions` also takes `menuLabel`: the accessible name of a row's ⋯ menu button, its `{field}` braces filled from the row (a `$` key's translation receives the row's fields), "Actions for <label>" by default with `labelKey`, "Row actions" without. A `CustomRowAction`'s `label` fills its `{field}` braces from the row the same way.
+
+`RowActionConfig` (built-in actions) also takes `label`, `icon` and `confirm` (an `ActionConfirm`: a `ConfirmDialog`, or `{ from }`, a URL answering one for the row, on delete, archive and restore, for a single row); `BulkRowActionConfig` (delete, archive, restore) adds `successMessage`. `CustomRowAction` also takes `confirm`, `permission` (`ButtonPermission`: an action of the table by name, or an `Action`), `permissionId` (an absolute permission id, which wins over `permission`), `color`, `variant`, `showLabel`, `bulk` (`true` or `{ allMatching: true }`: offered on the selection bar, see below) and `deepLink` (a drawer, modal or side panel it opens is kept in the URL as `?record=<id>` (by default for a side panel, which `false` opts out of), or `?<tableId>.record=<id>` on a page with several table views). An action the caller fails the permission for is stripped per request like a custom button; it is only hidden, so the route its target calls must check the permission itself.
+
+A bulk custom action sends the selected ids as a repeated `ids` query parameter, or `allMatching=true` with the table's filters, search and archive view after "Select all N matching". `resolveBulkRowIds(this, ctx, user)`, called from a route of the table's data controller, or `resolveBulkRowIds({ model, tableView }, ctx, user)` (`BulkRowSource`: the model the calling route is given, and the table's `TableViewMeta`) from any other route, a page's included, answers the ids the action covers: the selected ones, or every matching row read like the list reads them, refusing more than `MAX_BULK_MATCHING_ROWS` (413). Either way the caller needs the table's `list` permission (403 otherwise). `BULK_ALL_MATCHING_KEY` is the query flag. The `api` action target also takes `body` (the confirmation's field values merged in) and `copy` (response field copied to the clipboard). `CustomButton` takes `placement` (`"toolbar"`, the default, or `"header"`: drawn in the page header, which the server adds it to); `rowActions.add` takes it too (`AddRowActionConfig`).
+
+When several table views share a data controller, each read action of its routes is guarded by the permission ids of every mounted table view, each write action by the writing table view's (`TableViewMeta.actionPermissionIds(action)`; any one suffices). `TableViewMeta.componentBuilders` lists them, `writingComponentBuilders` the ones that write.
+
+## Archive mode
+
+With `archiveMode: true`, the archive and restore actions replace deletion. The builder calls `applyArchiveModeDefaultRules` (see [Helpers](/docs/interfaces/base/helpers)) to give every relevant action a default rule against the `@ArchiveField` column, so archived rows offer restore and delete while live rows offer edit, duplicate and archive. Actions you configured keep their other settings; every action not turned off receives the default rule, ANDed with its own rule when it has one.
+
+```typescript fragment
+static table = TableView(articleDataAPI, {
+  archiveMode: true,
+  rowActions: { edit: true, delete: true, archive: true, restore: true },
+});
+```
+
+## Guards
+
+A guard runs before the mutating route and aborts it by throwing. Use `assert` from `@antelopejs/interface-api-util` to fail with an HTTP status and a message key. `this` inside a guard is the data controller instance.
+
+```typescript fragment
+import { assert } from "@antelopejs/interface-api-util";
+import { getRequestTenantId } from "@antelopejs/interface-dms/request-tenant";
+import { GetModel } from "@antelopejs/interface-database-decorators";
+import { TenantMemberModel } from "@antelopejs/interface-dms/db";
+
+static table = TableView(memberDataAPI, {
+  guards: {
+    edit: async (ctx, { current, body }) => {
+      const demoting = current.isTenantOwner && body.isTenantOwner === false;
+      if (!demoting) return;
+      const model = GetModel(TenantMemberModel, getRequestTenantId(ctx));
+      const remaining = await model.countOwnersExcluding([current.userId]);
+      assert(remaining > 0, 409, "$page.settings.members.error.last_owner");
+    },
+    delete: async (ctx, { ids }) => {
+      // ids is the full set of rows the request targets
+    },
+  },
+});
+```
+
+The `edit` guard receives `{ id, body, current }`, where `current` is the row as it stands in the database. The route loads it before calling the guard and answers `404` when it does not exist. The `new` guard receives `{ body }`, parsed from the request body whether it arrived as a buffer, a string or an object. The `delete`, `archive` and `restore` guards receive `{ ids, values }`: `values` is the answer of the action's confirmation `fields`, sent as the request body, and is unset when the request carried none (see [Confirmations](/docs/components/tables/confirmations#what-the-rows-take-with-them)). Like the rules, guards are stored on the controller metadata the first time a table view declares them, so they apply to every table view on that controller. The argument interfaces are documented in [Shared types](/docs/interfaces/base/types).

package/docs/3.base/13.table-filters-and-forms.md

@@ -0,0 +1,104 @@
+---
+title: "Table filters and forms"
+description: The filters, tabs and displays of a table view, and the add, edit and view forms it generates.
+mode: reference
+---
+
+These are the options of a [table view](/docs/interfaces/base/tables) that narrow and show its rows, and the forms it generates from the controller's fields.
+
+## Filters, tabs and displays
+
+`defaultFilters` seeds the visible filter bar. `queryParamFilters` and `routeParamFilters` add hidden filters instead: each is a `Record<string, QueryParamFilter>` / `Record<string, RouteParamFilter>` mapping a URL parameter name onto `{ field: string; mode?: string }`, filtering the table without appearing in the UI or in the viewer's stored preferences. A `QueryParamFilter` also takes `visible?: boolean` and `label?: string`: a visible one shows as a removable chip of the filters row while the URL applies it. `queryParamFilters` reads the page's query string, `routeParamFilters` reads the parameters of the page slug (for example `:id` on a detail page). Both also seed `submitDefaults` on the generated forms, so a row created from a filtered view inherits the filter's value. An active `queryParamFilters` filter makes the table read as filtered (its empty body is the `filtered` state, without a clear action), and a change of its value in the URL lists from page 1.
+
+```typescript fragment
+static table = TableView(invoiceDataAPI, {
+  routeParamFilters: { id: { field: "customerId" } },
+  defaultSort: { field: "createdAt", desc: true },
+  tabs: [
+    { id: "open", label: "Open", filter: { accessorKey: "status", value: "open", mode: "is" } },
+    { id: "paid", label: "Paid", filter: { accessorKey: "status", value: "paid", mode: "is" } },
+  ],
+});
+```
+
+`TableViewTab` is `{ id, label, filter?: TableViewTabFilter, icon?, textColor?: ColorValue, iconColor?: ColorValue }` plus the link fields (`to`, `countFrom`), the gate (`permission`, `permissionId`) and `navBadge?: boolean | TableViewTabNavBadge` (`{ tone?: Tone }`), and `TableViewTabFilter` is `{ accessorKey: string; value?: string; mode: string }`. A tab gives a `filter` or a `to`, never both (registration throws). `permission` is relative to the table view's permission id (`"list"` → `<table permission id>.list`) or an `Action`; `permissionId` is absolute and wins; a link tab to a page controller follows that page's own permission without either. In the page editor, the tab's permission picker sets `permissionId`, and `permission` is the advanced "Action" text field.
+
+`navBadge: true` publishes the tab's counter as the navigation badge of the page it stands for: this table's page for a filter tab, the linked page for a link tab, which then needs a page controller `to` and a data controller `countFrom`; a path or a location logs a warning and publishes nothing. The server counts it on each page visit (the page payload's `navBadges`, never the cached site layout), with the caller's own `list` permission on that table, for the pages the caller can open only; the badge shows in the main and the settings navigation. A count of zero shows no badge, a page's static `MenuOptions.badge` wins over it, and while the table is on screen its own counter keeps it fresh. `TableView.fromSource` tables do not support it. `navBadge: { tone }` draws the badge in that tone instead of neutral; counts landing on one page add up, in the strongest tone. Declaring at least one tab also surfaces an implicit "all" tab that applies no filter.
+
+`displays` declares alternative renderings of the same data:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | Display identifier. Required. |
+| `options` | `Record<string, unknown>` | Options handed to the display. |
+| `component` | `Component` | Frontend component, resolved by name from the global registry. |
+| `selfManagedData` | `boolean` | The display fetches its own data. |
+| `capabilities` | `TableViewDisplayCapabilities` | Which toolbar features the display supports: `columnManagement`, `filters`, `search`, `sorting`, `tabs`, all optional booleans. |
+
+`TableViewDisplayOptionSerialized` is the same with `component` serialized.
+
+`kanban` is a shorthand for one particular display: the builder appends a `displays` entry with id `"kanban"` carrying the kanban options, unless `displays` already places `{ id: "kanban" }`, which then receives them.
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `groupByField` | `string` | Column the cards are grouped by. Must be a non-multiple `SelectType`, a `BooleanType` or a `StatusType` column. Required. |
+| `draggable` | `boolean` | Allow dragging a card to another column to change the group field. Defaults to `true`. |
+| `columnMaxHeight` | `string` | CSS max-height of a column's card list before it scrolls. Defaults to `"60vh"`. |
+
+`KanbanOptionsSerialized` is `KanbanOptions` plus the serialized `card` (`TableViewCardOptionsSerialized`).
+
+`card` (`TableViewCardOptions`: `{ fields?: string[]; component?: Component; minWidth?: string }`) is the card the `kanban` and `cards` displays draw for each row; it joins the options of both display entries. The component receives the same props in both: `row`, `rowId`, `columns`, `labelKey`, `actions`, `selected`, `select(value?)`, `open()`, on the kanban `groupValue`, and on the `cards` display of a table ordered by hand `reorder` (`{ enabled, dragging, handle }`, the card's move handle).
+
+## Generated forms
+
+`TableView` builds up to three forms from the columns, one per `FormMode`, using each column's data type for the input and the controller's mandatory and access metadata for required and disabled state. The `new` form fetches from `<location>/get?id={{query.duplicate}}` and submits to `<location>/new`; the `edit` form fetches from `<location>/get?id={{params.id}}&_presence=1` (the extra parameter makes the `Get` route record the viewer's presence on that row) and submits to `<location>/edit?id={{params.id}}`; the `view` form only fetches, from `<location>/get?id={{params.id}}`. A mode whose column set is empty produces no form and no matching action.
+
+`formContainer` decides where they open:
+
+```typescript fragment
+type FormContainer =
+  | { type: "drawer"; pages?: FormContainerPages<FormContainerPageTexts> }
+  | { type: "modal"; size?: ModalSize; pages?: FormContainerPages<FormContainerPageTexts> }
+  | { type: "page"; pages?: FormContainerPages<FormContainerPageConfig> };
+```
+
+Page mode is the default, used when `formContainer` is omitted. In page mode the builder registers a hidden sub-page per form under the table's page, each guarded by the matching action's permission.
+
+The sub-pages are named after the **table view**, not after the page: their default slugs are `<key>/new`, `<key>/:id/edit` and `<key>/:id/view`, where `<key>` is the key the table view is mounted under, so `static invoices = TableView(...)` on `/billing` gives `/billing/invoices/new`. It is the *simple* key even for a table view nested deep in a layout (`.child("invoiceTable", TableView(...))` gives `invoiceTable`, not `layout/body/main/invoiceTable`), so the URL stays readable and survives the layout being reorganised. That is what lets one page carry several table views, nested or not, each with form pages of its own. The key does not depend on the page declaring a `permission.id` of its own. A table view instance belongs to the first page that mounts it: its form routes cannot be keyed on a second page mounting the same instance in page mode, which is an error, so give each page its own `TableView(...)`.
+
+`pages` (`{ new?, edit?, details? }`) titles the forms in every container: a `FormContainerPageTexts` entry is `{ displayName?, description? }` (`$`-prefixed: i18n keys), falling back to "New entry", "Edit entry" and "Entry details". In page mode an entry is a `FormContainerPageConfig`, which also overrides the sub-page:
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `urlSlug` | `string` | Slug of the sub-page, relative to the page. **No key segment is inserted**, so a declared slug is full control over the URL. The `edit` and `details` slugs must contain `:id`, otherwise `TableView` throws. A slug starting with `/` addresses a page of its own; leading `..` segments each drop one segment of the carrying page. |
+| `displayName` | `string` | Form and sub-page title. |
+| `description` | `string` | Form and sub-page description. |
+| `customPage` | `boolean` | Do not create the sub-page, because you registered your own page at that URL. The slug is still used for navigation. |
+
+Whichever slugs apply, the builder resolves them against the slug of the page
+carrying the table view and serializes the three URLs as `formPages`
+(`{ new, edit, view }`), `:id` placeholder included. The frontend navigates to
+those URLs as they stand, substituting the row id, and the current route
+params for the placeholders the carrying page contributes, rather than
+rebuilding them from the browser path. A `customPage` entry registers no
+sub-page and still gets its URL serialized: it is navigated to all the same.
+
+A page below a `:id` page therefore carries two `:id` placeholders
+(`/workspaces/:id/invoiceTable/:id/view`). The row id takes the **last** one
+and the route params of the carrying page fill the rest, so the form reads the
+row id from `params.id`, the same thing it means on a flat `/customers/:id/edit`,
+which is what the generated `fetchUrl` and `submitUrl` count on.
+
+The id of the page above is not lost to the repetition: when a route repeats a
+placeholder name, every occurrence is also exposed under `<name>:<n>`, numbered
+from 1 in the order they appear in the pattern. On
+`/workspaces/:id/invoiceTable/:id/view` a form reads `{{params.id}}` or
+`{{params.id:2}}` for the row and `{{params.id:1}}` for the workspace carrying
+it. A name that occurs once gets no indexed key. `{{params.id}}` is all there
+is to read on every single-placeholder route.
+
+Two page-mode table views on one page whose form URLs resolve to the same path
+(the same explicit `urlSlug`, or the same key under two different parents)
+**fail the registration** of the page, naming both table views and the path.
+The check covers the page's own components and the table views a page extension
+contributes later. Give one of them a `urlSlug` of its own to resolve it.