@antelopejs/interface-dms 0.10.4 → 0.13.0

package/docs/3.base/14.table-events-and-helpers.md

@@ -0,0 +1,114 @@
+---
+title: "Table events and helpers"
+description: Exports, realtime updates, the metadata, the route helpers and the events of a table view.
+mode: reference
+---
+
+These are the parts of a [table view](/docs/interfaces/base/tables) that run around its rows: exports, realtime updates, the metadata it registers, the route helpers and its events.
+
+## Exports
+
+The export action is offered only when the controller registered all three `ExportRoutes`. Pressing it starts a background export job, polls its status, and downloads the result; the job machinery itself is shared with any other long export and is documented in [Helpers](/docs/interfaces/base/helpers). Which columns land in the file is decided by `@Exported`.
+
+## Realtime
+
+Unless `realtime: false` is set, a table view registers two realtime topics for its page (and for each generated sub-page), and its routes publish every create, update and delete on the first and track who has a row open on the second. Both are named after the controller's location:
+
+```typescript
+import {
+  tableViewPresenceTopic,
+  tableViewRowTopic,
+} from "@antelopejs/interface-dms/base/table-view";
+
+tableViewRowTopic("/api/orders"); // "tableview:row:/api/orders"
+tableViewPresenceTopic("/api/orders"); // "tableview:presence:/api/orders"
+```
+
+The topics are registered with `RegisterPageTopic` from the table view's `onCreated`, so they belong to the module whose page it is, as described in [Realtime](/docs/interfaces/core/realtime). A module that publishes on a table's row topic itself, such as a background job updating rows, builds the name with `tableViewRowTopic` rather than spelling out the prefix, and passes the tenant of the rows as `tenantId`.
+
+The topics are the same for every tenant, but what is published on them is not: the routes publish each change, and each presence, for the tenant the request was made in, so the sessions of the other tenants neither refetch nor see who has a row open. The DMS decides who else receives them, with no option on the table: a table whose rows live in the schema every tenant shares (`CORE_SCHEMA_NAME`) publishes to every tenant, and a session on a platform page (a module's page) receives the changes of every tenant, as such a page lists the data of all of them. `RealtimeMutationContext` and `RealtimePresenceContext` carry the tenant as `tenantId`, absent on a table of the shared schema.
+
+Two functions let other modules observe those mutations:
+
+```typescript
+import {
+  registerRealtimeMutationListener,
+  unregisterRealtimeMutationListener,
+  type RealtimeMutationContext,
+} from "@antelopejs/interface-dms/base/table-view";
+
+const listener = (context: RealtimeMutationContext) => {
+  // context.controllerLocation, context.eventType, context.ids, …
+};
+
+registerRealtimeMutationListener(listener);
+```
+
+Listeners are additive side observers: they run after the DMS has published the mutation, and a listener that throws is logged, never propagated to the mutating request. A listener is released with the module that registered it, including when that module reloads in development; `unregisterRealtimeMutationListener` is for a module that stops listening while it stays loaded.
+
+| Type | Shape |
+| --- | --- |
+| `RealtimeMutationEventType` | `"created" \| "updated" \| "deleted"` |
+| `RealtimeMutationContext` | `controllerLocation`, `rowIdKey`, `eventType`, `ids: string[]`, `sessionId?`, `actor?: RealtimePresenceActor` |
+| `RealtimePresenceActor` | `id`, `displayName?`, `avatarUrl?` |
+| `RealtimePresenceContext` | `controllerLocation`, `rowIdKey`, `sessionId`, `rowId`, `actor` |
+
+The routes reach the DMS through two interface functions it implements, `internal.PublishMutation` and `internal.AcquirePresence`. They are internal: nothing outside the DMS implements them, and the core binds them to each generation of the DMS module, so a mutation made while the DMS reloads waits for the next generation instead of reaching the one being torn down.
+
+## Metadata
+
+`TableViewMeta` is the metadata object the decorators write to and the builder reads from. Retrieve it with `GetMetadata(controller, TableViewMeta)`.
+
+| Member | Description |
+| --- | --- |
+| `columns` | `Record<string, ColumnOptions>` keyed by field name. |
+| `groups` | `Record<string, ColumnGroupConfig>` keyed by group id. |
+| `options` | The `TableViewOptions` of the writing `TableView`, or of the last one built while none writes. |
+| `archiveField` | Field name recorded by `@ArchiveField`. |
+| `controllerRowActionRules` | The rules the write routes enforce: the writing table view's `rowActions`, archive-mode defaults included. |
+| `controllerGuards` | Guards promoted to controller-wide guards. |
+| `componentBuilders` | Every live `TableView` builder built on the controller, in build order. |
+| `writingComponentBuilders` | The live builders of `componentBuilders` that write through the data routes. |
+| `actionPermissionIds(actionId)` | The permission id the action carries on each mounted table view of the controller, on the writing one only for a write action. |
+| `addComponentBuilder(builder, access?)` | Writer the builder calls to record itself, with its `TableViewAccess` (`"read"` or `"write"`, the default). A custom component standing in for a table view (the roles editor) records itself the same way. |
+| `resourceFormBuilders` | Every live `new` / `edit` form built over the controller, in build order: the `ResourceForm` blocks and the forms each table view opens. |
+| `addResourceFormBuilder` | Writer the form builder calls to record a form that submits to the controller. |
+| `writingComponents` | Every live component that submits to the controller's write routes: its writing table view and its `new` / `edit` forms, including the ones a page-mode table view mounts on its form sub-pages. A native file staged by any of them is accepted on save; one staged by any other component is refused. |
+| `inherit(parent)` | Called by `GetMetadata` for a derived controller: copies the parent's `columns` (each with its own copy of its data type), `groups`, `options` and `archiveField`, never its table views or forms. |
+| `config` | Getter returning `{ location, columns }`, the serialized column list plus the controller's route location. |
+| `getFormFields(mode)` | Builds the `FormFieldOrGroup[]` for `"view"`, `"edit"` or `"new"`. |
+| `setColumn`, `setGroup`, `setOptions`, `setArchiveField`, `setControllerRowActionRules`, `setControllerGuards` | Writers used by the decorators and the builder. |
+
+Each entry of `config.columns` carries `id`, `header`, `isVisible`, `type` (the serialized data type), `accessorKey`, `listable`, `enableSorting`, `enableColumnFilter`, `defaultValue`, `accessMode` and `readonlyBehavior`.
+
+## Route helpers
+
+`table-view` also exports the interface functions the wrapped routes call. They are the seam between the interface and its implementation. A consumer wires them by declaring `TableViewRoutes`, and does not normally call them directly.
+
+| Function | Role |
+| --- | --- |
+| `listWithSearch` | Runs the list query with search, filters, sorting and pagination; returns `{ results, total, offset, limit }`. |
+| `countWithSearch` | Same query, count only; returns `{ total }`. |
+| `startExport` | Queues an export job; returns `{ jobId, format, extension }`. |
+| `getExportStatus` | Returns `{ status, progress, error? }` for a job. |
+| `downloadExport` | Streams a completed job's file to the response. |
+| `archiveRows` | Sets the archive field on the given ids; returns `{ success, archivedCount }`. |
+| `restoreRows` | Clears it; returns `{ success, restoredCount }`. |
+| `validateRowsAgainstRule` | Splits ids into `{ eligibleIds, rejectedIds }` against a `RowActionRule`. |
+| `fetchRowForGuard` | Loads one row by id field, for the `edit` guard and the file-cleanup passes. |
+
+## Events and functions
+
+| Namespace member | Value |
+| --- | --- |
+| `TableViewEvents.ROW_CLICK` | `"DmsComponent.TableView.RowClick"` |
+| `TableViewEvents.ROW_SELECT` | `"DmsComponent.TableView.RowSelect"` |
+| `TableViewEvents.ROW_DELETE` | `"DmsComponent.TableView.RowDelete"` |
+| `TableViewEvents.ROW_ADD` | `"DmsComponent.TableView.RowAdd"` |
+| `TableViewEvents.ROW_EDIT` | `"DmsComponent.TableView.RowEdit"` |
+| `TableViewEvents.FILTER_CHANGE` | `"DmsComponent.TableView.FilterChange"` |
+| `TableViewEvents.SORT_CHANGE` | `"DmsComponent.TableView.SortChange"` |
+| `TableViewEvents.EXPORT` | `"DmsComponent.TableView.Export"` |
+| `TableViewFunctions.CUSTOM_PAGE_FORM_SUCCESS` | `"DmsComponent.TableView.CustomPageFormSuccess"` |
+
+`CUSTOM_PAGE_FORM_SUCCESS` registers `{ url: string; preserveQuery?: string[] }` in `WatchFunctionParamMap`. The builder uses it itself: the generated `new` and `edit` page forms watch `FormEvents.SUBMIT_SUCCESS` and navigate back to the table, preserving the query parameters named in `queryParamFilters`. The handler resolves `{{params.X}}` / `{{query.X}}` tokens in `url` against the route being left before navigating; the generated forms rely on it to send the user back to a page whose slug carries parameters: each placeholder of the page's slug becomes the token reading it on the form route (`/workspaces/:id` becomes `/workspaces/{{params.id:1}}` from `/workspaces/:id/invoiceTable/:id/edit`, `/workspaces/{{params.id}}` from `/workspaces/:id/invoiceTable/new`). A slug without parameters is used as is. The `view` form submits nothing and carries no such watch. All three generated pages are registered with `FormPageLayout()`, the constrained-column layout ([Layout and containers](/docs/interfaces/base/layout)).

package/docs/3.base/15.table-sources-and-gates.md

@@ -0,0 +1,24 @@
+---
+title: "Table sources and tenant gates"
+description: Table views over a module's own route, and table views that stay readable behind a tenant access gate.
+mode: reference
+---
+
+A [table view](/docs/interfaces/base/tables) usually reads a data controller. These two cases differ: a table view over a module's own route, and a table view that stays readable while a tenant access gate denies the tenant.
+
+## Tables over a module's route
+
+```typescript fragment
+TableView.fromSource(options: TableViewSourceOptions): ComponentBuilder<TableViewOptionsSerialized>;
+```
+
+A read-only table view with no data controller (`tableViewFromSource`). `TableViewSourceOptions` takes `columns` (a record of `TableViewSourceColumn`, a `@Column`'s options plus `sortable`), `fetchUrl` (its `{{params.X}}` / `{{query.X}}` tokens are filled from the page URL, percent-encoded; the table and its tab counters list again when they change and request nothing while one has no value), `fetchRowUrl?` (a route answering one row by id, `{{row.id}}` its percent-encoded id, with the same tokens: a deep link to a row the table does not list opens through it; serialized on `TableViewSourceSerialized`), `rowIdKey?`, `periodScope?` (the id of a `PeriodSelector`: every request carries its `from`, `to`, `preset` and `comparison`, the table lists again when the period changes, and nothing is requested until the selector is on the page), `capabilities?` (`TableViewSourceCapabilities`: `search`, `sort`, `paginate`, `filter`), `queryParamFilters?` (URL query parameters sent to the route as hidden `filter_<field>` filters), custom row actions and buttons only, and the presentation options of a table view (`caption`, `layout`, `pagination`, `tabs`, `quickFilters`, `displays`, `card`, `emptyStates`, `footer` texts and legend…). The route answers `{ results, total }` and is sent the part of the list query its capabilities name, nothing else; the browser does the rest over the rows it answered, except that a paging route's rows are neither searched nor sorted by the browser. Registration runs the checks of `TableView()` that apply (page size, display ids, tab targets) and throws when tabs, quick filters or `queryParamFilters` lack `capabilities.filter`, or when a key they, `labelKey`, `card.fields` or `expandable` name is not a column, or when `expandable` sets `lazyLoad` (a source has no `get` route), or when `fetchRowUrl` lacks `{{row.id}}`; it warns about a quick filter on a column with no values to pick. There is no export, realtime nor footer summary.
+
+## Reach a table behind a tenant gate
+
+`bypassTenantAccessGate` is the table-view mirror of the guard option of the same name. Reserve it for tables that must stay readable while a gate denies the tenant, such as the invoices on the billing page of a suspended tenant, so it can regularize its situation. Permission checks still apply.
+
+Data routes are registered against the controller, not against a page, so the opt-out is controller-level and **latched**: once any `TableView()` call on a controller declares it, the controller's routes bypass the gate wherever they are rendered. A later registration of the same controller without the flag cannot re-gate them, and gets a warning saying so. Two consequences worth designing around:
+
+- Declaring the flag on a controller opens its routes for every table view built on it, including one mounted on an ordinary page.
+- Actions that carry no permission id, such as a plain list on a component that was never mounted, are then served to any member of a denied tenant. That is the escape hatch working as intended, so keep every action of a flagged controller stamped with a permission.

package/docs/3.base/2.types.md

@@ -1,10 +1,9 @@
 ---
-title: "Shared Types"
+title: "Shared types"
 description: "The `types` subpath holds the vocabulary every other part of the `base` domain is built from: the base props interface every component's props extend, the colour and size scales, the action targets a button or a row…"
+mode: reference
 ---
 
-# Shared Types
-
 ## Overview
 
 The `types` subpath holds the vocabulary every other part of the `base` domain is built from: the base props interface every component's props extend, the colour and size scales, the action targets a button or a row action can point at, the rule algebra that decides whether a row action applies to a row, the guard signatures a table view runs before a mutation, and a handful of small enums and value unions.
@@ -30,7 +29,7 @@ Four modules are not re-exported by that barrel and are imported from their own
 | `FIELD_OPERATORS`, `FIELD_KEY`, `FieldOperatorKey`, `FieldRule`, `AnyFieldRule`, `LOGICAL_OPERATOR_KEYS`, `LogicalOperatorKey` | `@antelopejs/interface-dms/base/types/row-action-operators` |
 | `EditGuardArgs`, `DeleteGuardArgs`, `BulkGuardArgs`, `NewGuardArgs`, `GuardFn`, `AfterWrite`, `TableViewGuards` | `@antelopejs/interface-dms/base/types/guards` |
 
-## Base Component Props
+## Base component props
 
 `BaseComponentProps` is the one field every component props interface inherits.
 
@@ -48,9 +47,9 @@ interface BaseComponentProps {
 }
 ```
 
-`FormProps`, `TreeProps`, `TabProps`, `KpiCardProps`, `ChartCardProps`, `TopListCardProps`, `PeriodSelectorProps` and the chart props all extend it. The `ComponentBuilder` from `@antelopejs/interface-dms/component` strips a caller-supplied `watchActions` from the options it receives and fills the field itself from `.watch()` / `.watchOn()` calls, so the property is the transport rather than something you set by hand.
+`FormProps`, `TabProps`, `KpiCardProps`, `ChartCardProps`, `TopListCardProps`, `PeriodSelectorProps` and the chart props all extend it. The `ComponentBuilder` from `@antelopejs/interface-dms/component` strips a caller-supplied `watchActions` from the options it receives and fills the field itself from `.watch()` / `.watchOn()` calls, so the property is the transport rather than something you set by hand.
 
-### Watch Actions
+### Watch actions
 
 A `WatchAction` binds an event emitted by a component to a function exposed by a component.
 
@@ -66,13 +65,13 @@ import type {
 | `component` | `string` | Identifier of the component that emits the event. `ComponentId.SELF` (`"$component:self"`) refers to the declaring component. |
 | `event` | `string` | Event name, e.g. `FormEvents.SUBMIT_SUCCESS`. |
 | `functionId` | `string` | Identifier of the function to invoke, e.g. `FormFunctions.SET_FIELD_HIDDEN`. |
-| `params` | `Record<string, unknown>` | Arguments passed to the function. |
+| `params` | `object` | Arguments passed to the function. Read a member after checking it (`"targetField" in params`), or read the shape the function registers through `WatchFunctionParams`. |
 | `onParam` | `WatchActionCondition \| WatchActionCondition[]` | Only run when the event payload matches these `{ key, value }` pairs. |
 | `requirePermission` | `string` | Permission id the viewer must hold for the action to be kept. |
 
-`WatchFunctionParamMap` is an interface extended by declaration merging: each module that exposes a watch function adds its `functionId` and the exact parameter shape to the map. `WatchFunctionId` is `keyof WatchFunctionParamMap & string`, and `WatchFunctionParams<F>` resolves to the registered parameter shape for `F`, falling back to `Record<string, unknown> | undefined` for ids that are not in the map. `Form` and `TableView` both register their functions in this map — see [Forms](/docs/interfaces/base/forms) and [Tables](/docs/interfaces/base/tables).
+`WatchFunctionParamMap` is an interface extended by declaration merging: each module that exposes a watch function adds its `functionId` and the exact parameter shape to the map. `WatchFunctionId` is `keyof WatchFunctionParamMap & string`, and `WatchFunctionParams<F>` resolves to the registered parameter shape for `F`, falling back to `Record<string, unknown> | undefined` for ids that are not in the map. `Form` and `TableView` both register their functions in this map, as [Forms](/docs/interfaces/base/forms) and [Tables](/docs/interfaces/base/tables) describe.
 
-## Colors and Sizes
+## Colors and sizes
 
 ```typescript
 import {
@@ -86,7 +85,7 @@ import {
 
 `Color` is an enum of the semantic palette names: `primary`, `secondary`, `success`, `info`, `warning`, `error`, `neutral`. `ColorValue` is `Color | (string & {})`, so a component that accepts a `ColorValue` takes either an enum member or an arbitrary string while keeping the enum members in editor completion.
 
-`TONES` (`Tone`, from `types/tone`) is `neutral`, `primary`, `secondary`, `success`, `warning`, `error`, `info`; `ICON_TONES` (`IconTone`) adds `muted`. `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); see [Display Blocks](/docs/interfaces/base/display-blocks).
+`TONES` (`Tone`, from `types/tone`) is `neutral`, `primary`, `secondary`, `success`, `warning`, `error`, `info`; `ICON_TONES` (`IconTone`) adds `muted`. `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); see [Display blocks](/docs/interfaces/base/display-blocks).
 
 `Size` maps readable names onto the scale tokens: `tiny` → `"xs"`, `small` → `"sm"`, `medium` → `"md"`, `large` → `"lg"`, `huge` → `"xl"`. `SizeValue` widens it the same way `ColorValue` widens `Color`.
 
@@ -94,7 +93,7 @@ import {
 
 ## Buttons
 
-`ButtonVariant` is an enum with `solid`, `outline`, `soft`, `ghost` and `link`. `ButtonColor` is a plain string union — `"primary" | "secondary" | "success" | "error" | "warning" | "info" | "neutral"` — used by `CustomButton` in place of the `Color` enum.
+`ButtonVariant` is an enum with `solid`, `outline`, `soft`, `ghost` and `link`. `ButtonColor` is a plain string union, `"primary" | "secondary" | "success" | "error" | "warning" | "info" | "neutral"`, used by `CustomButton` in place of the `Color` enum.
 
 `CustomButton` describes a toolbar button; it is what `TableViewOptions.customButtons` takes.
 
@@ -123,7 +122,7 @@ const inviteButton: CustomButton = {
 | `permissionId` | `string` | Absolute permission id the button requires; wins over `permission`. |
 | `availability` | `CustomButtonAvailability` | Disable the button, with a reason, for a request it refuses. |
 
-`permission` takes either form: a string names one of the owner's actions, relative to its permission id — the table's for a toolbar button (`"add"` → `<table permission id>.add`), the page's for a header button (`DefaultLayout({ headerActions })`) — and an `Action` references any component's action — another table's `add`, for instance. `permissionId` takes an absolute permission id (`"settings.workspace.invites"`) and wins when both are set. A button the caller lacks the permission for is stripped from the serialized options rather than disabled, so it never reaches the browser. A declared permission that cannot be resolved to an id — an action on a page that never registered — fails closed and strips the button too.
+`permission` takes either form: a string names one of the owner's actions, relative to its permission id: the table's for a toolbar button (`"add"` → `<table permission id>.add`), the page's for a header button (`DefaultLayout({ headerActions })`). An `Action` references any component's action, such as another table's `add`. `permissionId` takes an absolute permission id (`"settings.workspace.invites"`) and wins when both are set. A button the caller lacks the permission for is stripped from the serialized options rather than disabled, so it never reaches the browser. A declared permission that cannot be resolved to an id, such as an action on a page that never registered, fails closed and strips the button too.
 
 A button with an `id` can be exposed as a [quick action](/docs/interfaces/core/quick-actions) with a `"button"` target. The quick action opens what the button opens and inherits the button's `permission`: it is listed for exactly the callers the button is shown to.
 
@@ -135,7 +134,7 @@ A button with an `id` can be exposed as a [quick action](/docs/interfaces/core/q
 
 `PermissionGate`, imported from `@antelopejs/interface-dms/permission-gate`, names the shared optional `permission?: ButtonPermission` and `permissionId?: string` fields described above. `ButtonPermission` is `string | Action`; `permissionId` takes precedence. The shape is shared by permission-filtered buttons, row actions, table tabs and views. It does not authorize the route that a control calls: protect that route with a guard too.
 
-## Action Targets
+## Action targets
 
 `ActionTarget` is a discriminated union on `type`. It is what a custom button or a custom row action points at.
 
@@ -147,7 +146,7 @@ import type { ActionTarget } from "@antelopejs/interface-dms/base/types/action-t
 | --- | --- |
 | `"drawer"` | `component: Component`, `title?`, `description?`, `direction?: DrawerDirection`, plus `DrawerTargetOptions`: `size?: ModalSize`, `rowHeader?`, `rowTitle?`, `positionLabel?`, `deepLink?`, `notFound?` |
 | `"modal"` | `component: Component`, `size?: ModalSize`, `title?`, `description?` |
-| `"sidePanel"` | `component: Component`, plus `SidePanelTargetOptions`: `title?`, `rowTitle?`, `positionLabel?`, `deepLink?`, `notFound?` — for global, page-independent panels; a detail panel is a `drawer` |
+| `"sidePanel"` | `component: Component`, plus `SidePanelTargetOptions`: `title?`, `rowTitle?`, `positionLabel?`, `deepLink?`, `notFound?`. For global, page-independent panels. A detail panel is a `drawer`. |
 | `"page"` | `url: string`: the page URL's `{{params.X}}` / `{{query.X}}` (a query pair without a value left out), then on a row action the row's `{{row.field}}`; see [Template tokens](/docs/building/pages-and-components#template-tokens) |
 | `"external"` | `url: string`, `newTab?: boolean`; the same tokens as `page` |
 | `"download"` | `url: string`, `filename?: string` (`DownloadActionTarget`); the same tokens as `page`, the file name taking them as written. Fetched with the user's session and saved under `filename`, else the server's `Content-Disposition` name, else the URL's last segment; a failure is toasted |
@@ -155,15 +154,17 @@ import type { ActionTarget } from "@antelopejs/interface-dms/base/types/action-t
 | `"api"` | `url: string`, `method?: "GET" \| "POST" \| "PUT" \| "DELETE" \| "PATCH"`, `body?`, `copy?`, `successMessage: string`; the same tokens as `page` |
 | `"exportJob"` | `url: string`, `method?: "GET" \| "POST"`, `statusUrl?`, `downloadUrl?`, `labels?`; the same tokens as `page`, plus `{{job.id}}` in `statusUrl` and `downloadUrl` |
 
-`SidePanelTargetOptions` sets the header the DMS draws above a `sidePanel` target's component: `title` (the action's label by default; `$`: an i18n key), `rowTitle`, the title while a row is open, an i18n key or a literal receiving the row's fields (`"{method} {path}"`), `positionLabel`, an i18n key receiving `{ index }` (from 1) and `{ total }` for the row's position among all the rows the table lists, its count rather than the page loaded (the DMS's "{index} of {total}" by default), and `deepLink`, which keeps the open row in the URL like the action's own `deepLink` — on by default for a side panel, `false` opting out (the action's own `deepLink` wins when set), and `notFound` (`SidePanelNotFoundTexts`: `title?`, `description?`), the state the panel draws with a close button when the row a link names answers 404. The panel is non-modal and docked on the right, one at a time with a module's side panels. It is meant for global, page-independent panels (an assistant dock): a detail or record panel opens in a `drawer`.
+`SidePanelTargetOptions` sets the header the DMS draws above a `sidePanel` target's component: `title` (the action's label by default; `$`: an i18n key), `rowTitle`, the title while a row is open, an i18n key or a literal receiving the row's fields (`"{method} {path}"`), `positionLabel`, an i18n key receiving `{ index }` (from 1) and `{ total }` for the row's position among all the rows the table lists, its count rather than the page loaded (the DMS's "{index} of {total}" by default), and `deepLink`, which keeps the open row in the URL like the action's own `deepLink`. It is on by default for a side panel, `false` opting out (the action's own `deepLink` wins when set), and `notFound` (`SidePanelNotFoundTexts`: `title?`, `description?`), the state the panel draws with a close button when the row a link names answers 404. The panel is non-modal and docked on the right, one at a time with a module's side panels. It is meant for global, page-independent panels (an assistant dock): a detail or record panel opens in a `drawer`.
 
-`DrawerTargetOptions` gives a `drawer` target opened on a row the same options, so a detail panel moves from `sidePanel` to `drawer` without losing any: `rowTitle`, `positionLabel` and `notFound` as above; `rowHeader`, the DMS drawing the row header (the title naming the row, its position, previous and next buttons next to the close button) — on when `rowTitle` or `positionLabel` is set, `false` leaving the drawer's own title, `true` drawing it with the defaults; `deepLink`, off by default for a drawer (the action's own `deepLink` wins when set); and `size` (`ModalSize`), the width a `left` / `right` drawer opens at from `lg`, a modal's width at that size. J and K step through the rows in place whatever the header. A drawer shows its not-found state only once its target sets `notFound`; otherwise a deep link to a missing row is a toast, as before.
+`DrawerTargetOptions` gives a `drawer` target opened on a row the same options, so a detail panel moves from `sidePanel` to `drawer` without losing any: `rowTitle`, `positionLabel` and `notFound` as above; `rowHeader`, the DMS drawing the row header (the title naming the row, its position, previous and next buttons next to the close button), on when `rowTitle` or `positionLabel` is set, `false` leaving the drawer's own title, `true` drawing it with the defaults; `deepLink`, off by default for a drawer (the action's own `deepLink` wins when set); and `size` (`ModalSize`), the width a `left` / `right` drawer opens at from `lg`, a modal's width at that size. J and K step through the rows in place whatever the header. A drawer shows its not-found state only once its target sets `notFound`; otherwise a deep link to a missing row is a toast, as before.
 
 `DrawerDirection` is `"top" | "right" | "bottom" | "left"`, the edge the drawer slides in from: `bottom` by default, while `left` and `right` open a side sheet spanning the window's height, 600px wide from `lg` without a `size` (capped to the window) and 440px below it. From `lg` the user resizes every drawer by its inner edge (width or height), and the drawer opens again at the size it was left at.
 
 A target carries no confirmation: the action does (`CustomButton.confirm`, `CustomRowAction.confirm`, `RowActionConfig.confirm`), with one type, `ActionConfirm = ConfirmDialog | ConfirmDialogFrom` (see below). The `labels` object on `exportJob` accepts `title`, `exporting`, `downloading`, `successTitle`, `successMessage`, `errorTitle` and `retry`, all optional strings.
 
 ```typescript
+import { ActionTarget } from "@antelopejs/interface-dms/base/types/action-target";
+
 const validateEmail: ActionTarget = {
   type: "api",
   url: "/settings/workspace/members/{{row._id}}/validate-email",
@@ -181,15 +182,15 @@ import type {
 } from "@antelopejs/interface-dms/base/types/confirm-dialog";
 ```
 
-`ConfirmDialog` is the one confirmation every action asks in: `title`, `description?`, `params?` (interpolated into the texts, besides a row action's row fields; a numeric `count` pluralizes them), `icon?`, `color?` (`ButtonColor`), `confirmLabel?`, `cancelLabel?`, `impact?: ConfirmDialogImpact[]` (`{ icon, label, count? }`), `secondaryAction?: ConfirmDialogSecondaryAction` (`{ label, icon?, target }`, a button next to cancel and confirm that leaves the dialog open; its `target` is an `external` link or `{ type: "download", url, filename? }`, fetched with the user's session), `blocked?` (the dialog only explains why the action cannot run), `confirmText?` (type-to-confirm), `confirmTextCaseInsensitive?` (the typed text compared ignoring case), `fields?: FormField[]` and `component?: Component`. The values of `fields` are sent with the action's request — merged into an `api` target's `body`, the input winning — and a field error the server answers shows under its field. `ConfirmDialogFrom` is `{ from: string }`: a URL (on a row action, built-in or custom, the row's fields filled in, such as `{{row._id}}`, plus `{{row.id}}`, the row's id) answering a `ConfirmDialogSerialized`, which `serializeConfirmDialog(dialog)` builds. `ActionConfirm` is either.
+`ConfirmDialog` is the one confirmation every action asks in: `title`, `description?`, `params?` (interpolated into the texts, besides a row action's row fields; a numeric `count` pluralizes them), `icon?`, `color?` (`ButtonColor`), `confirmLabel?`, `cancelLabel?`, `impact?: ConfirmDialogImpact[]` (`{ icon, label, count? }`), `secondaryAction?: ConfirmDialogSecondaryAction` (`{ label, icon?, target }`, a button next to cancel and confirm that leaves the dialog open; its `target` is an `external` link or `{ type: "download", url, filename? }`, fetched with the user's session), `blocked?` (the dialog only explains why the action cannot run), `confirmText?` (type-to-confirm), `confirmTextCaseInsensitive?` (the typed text compared ignoring case), `fields?: FormField[]` and `component?: Component`. The values of `fields` are sent with the action's request, merged into an `api` target's `body` with the input winning. A field error the server answers shows under its field. `ConfirmDialogFrom` is `{ from: string }`: a URL (on a row action, built-in or custom, the row's fields filled in, such as `{{row._id}}`, plus `{{row.id}}`, the row's id) answering a `ConfirmDialogSerialized`, which `serializeConfirmDialog(dialog)` builds. `ActionConfirm` is either.
 
 `ActionTargetSerialized` mirrors the union exactly, with `component` on the `drawer`, `modal` and `sidePanel` variants replaced by `ComponentInfoSerialized`.
 
-## Row Action Rules
+## Row action rules
 
 A row action rule decides, per row, whether an action applies. The same rule value is sent to the frontend so the row's menu matches what the backend will accept, and evaluated on the backend before an `edit`, `delete`, `archive` or `restore` runs.
 
-### Field Operators
+### Field operators
 
 `FIELD_OPERATORS` is the catalogue of leaf comparisons. Each entry declares whether the rule value is an array and carries the comparison itself.
 
@@ -210,9 +211,9 @@ import {
 
 `FieldOperatorKey` is `keyof typeof FIELD_OPERATORS`. `FIELD_KEY` is the literal `"field"`, the property name that carries the field name inside a leaf rule. `LOGICAL_OPERATOR_KEYS` is the tuple `["and", "or", "not"]` and `LogicalOperatorKey` is its element type.
 
-### Rule Shapes
+### Rule shapes
 
-A leaf rule is `{ field: K }` plus the operator key. `FieldRule<T, Op>` builds that shape for one operator over the keys of `T`, choosing `T[K][]` for the array operators and `T[K]` for the others. `AnyFieldRule<T>` is the union over all four operators.
+A leaf rule is `{ field: K }` plus the operator key. `FieldRule<T, Op>` builds that shape for one operator over the keys of `T`, choosing `Awaited<T[K]>[]` for the array operators and `Awaited<T[K]>` for the others: a getter answering a promise is compared by the value it resolves to, as the served row holds it. `AnyFieldRule<T>` is the union over all four operators.
 
 ```typescript
 import type {
@@ -235,7 +236,7 @@ const editable: AndRule<Invoice> = {
 
 The four named leaf aliases are `FieldEqualsRule<T>`, `FieldNotEqualsRule<T>`, `FieldInRule<T>` and `FieldNotInRule<T>`, each an alias of `FieldRule<T, Op>` for the matching operator. The three combinators are `AndRule<T>` (`{ and: RowActionRule<T>[] }`), `OrRule<T>` (`{ or: RowActionRule<T>[] }`) and `NotRule<T>` (`{ not: RowActionRule<T> }`); `LogicalRule<T>` is their union. `RowActionRule<T>` is `AnyFieldRule<T> | LogicalRule<T>`, so rules nest to any depth.
 
-### Attaching a Rule
+### Attach a rule
 
 `RowActionConfig<T>` is the object form of a built-in row action.
 
@@ -258,7 +259,7 @@ The four named leaf aliases are `FieldEqualsRule<T>`, `FieldNotEqualsRule<T>`, `
 
 `CustomRowActionSerialized` is the same shape with `target: ActionTargetSerialized` and an untyped `RowActionRule`.
 
-Where these are consumed — `TableViewOptions.rowActions`, and the archive-mode defaults — is covered in [Tables](/docs/interfaces/base/tables).
+[Tables](/docs/interfaces/base/tables) covers where these are consumed: `TableViewOptions.rowActions` and the archive-mode defaults.
 
 ## Guards
 
@@ -309,13 +310,13 @@ A mutating guard may return an `AfterWrite`: the table view runs it once the wri
 
 `T` is the data controller instance `TableView()` infers from its controller; it defaults to `Record<string, unknown>` on every one of them. How guards are attached and when each one fires is documented in [Tables](/docs/interfaces/base/tables).
 
-## Form and Field Types
+## Form and field types
 
-### FormMode
+### `FormMode`
 
 `FormMode` is the enum `new`, `edit`, `view`. It selects which variant of a form the table view generates and which readonly behaviour applies.
 
-### ReadonlyBehavior
+### `ReadonlyBehavior`
 
 `ReadonlyBehaviorType` is an enum with `disabled`, `hidden` and `default`. `ReadonlyBehaviorConfig` gives one value per mode:
 
@@ -331,7 +332,7 @@ const createdAtBehavior = {
 
 `ReadonlyBehavior` is `ReadonlyBehaviorType | ReadonlyBehaviorConfig`, so a column may pass a single value that applies to every mode or a per-mode object. It is read by `ColumnOptions.readonlyBehavior`.
 
-### ListableConfig and FieldMetadata
+### `ListableConfig` and `FieldMetadata`
 
 `FieldMetadata` is the slice of a field's data-api metadata the table view reads when it builds a column or a form field.
 
@@ -342,35 +343,37 @@ const createdAtBehavior = {
 | `listable` | `ListableConfig` | Which pluck modes include the field. |
 | `sortable` | `boolean` | Whether the field can be sorted on. |
 
-`ListableConfig` is `{ list?: boolean; select?: boolean; export?: boolean }` — one flag per pluck mode.
+`ListableConfig` is `{ list?: boolean; select?: boolean; export?: boolean }`, one flag per pluck mode.
 
-### Field Values
+### Field values
 
 `DefaultValue` and `FormFieldValue` are the same recursive union: `string | number | boolean | Date | null` and arrays of themselves. `DefaultValue` types `FormField.defaultValue` and `ColumnOptions.defaultValue`; `FormFieldValue` types a value held by a form field.
 
-### ComponentOrNoInput
+### `ComponentOrNoInput`
 
 ```typescript
+import { Component } from "vue";
+
 type ComponentOrNoInput<T = undefined> = Component<T> | "noInput";
 ```
 
-The literal `"noInput"` stands for a compare mode that takes no value — `is_empty` and `is_not_empty` are registered that way, and `serializeType` substitutes the literal for their filter component. The serialized counterpart used by data types is `FilterComponent`, documented in [Data Types](/docs/interfaces/base/data-types).
+The literal `"noInput"` stands for a compare mode that takes no value. `is_empty` and `is_not_empty` are registered that way, and `serializeType` substitutes the literal for their filter component. The serialized counterpart used by data types is `FilterComponent`, documented in [Data types](/docs/interfaces/base/data-types).
 
-## Transport and Miscellaneous
+## Transport and other types
 
-### HttpMethod
+### `HttpMethod`
 
 `HttpMethod` is an enum of `GET`, `POST`, `PUT`, `DELETE`, `PATCH`, `HEAD`, `OPTIONS`, keyed by the lowercase name (`HttpMethod.get`, `HttpMethod.post`, …). Every component with a `fetchUrl` also accepts a `fetchUrlMethod` of this type.
 
-### AxeOrientation
+### `AxeOrientation`
 
 `AxeOrientation` is the enum `horizontal` / `vertical`. `TabProps.orientation`, `BarChartProps.orientation` and `FormComponents.RadioGroupOptions.orientation` take it.
 
-### ExportStatus
+### `ExportStatus`
 
-`ExportStatus` is the enum `pending`, `completed`, `failed`. It is the status stored on an export job and returned by the export-status route — see [Helpers](/docs/interfaces/base/helpers).
+`ExportStatus` is the enum `pending`, `completed`, `failed`. It is the status stored on an export job and returned by the export-status route, as [Helpers](/docs/interfaces/base/helpers) describes.
 
-### Json Values
+### JSON values
 
 ```typescript
 type JsonPrimitive = string | number | boolean | null;
@@ -379,9 +382,9 @@ type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue };
 
 `JsonValue` describes anything that survives a JSON round trip.
 
-### Error Helpers
+### Error helpers
 
-```typescript
+```typescript fragment
 import {
   getErrorMessage,
   isErrorWithMessage,
@@ -399,6 +402,6 @@ try {
 
 `ErrorWithMessage` is `{ message: string }`. `isErrorWithMessage` is a type guard that accepts any object carrying a `message` property. `getErrorMessage` returns that message, or the string `"Unknown error"` for anything else, including an object whose `message` is not a string.
 
-## Next Steps
+## Next steps
 
-- [Forms](/docs/interfaces/base/forms) - Build a form, its fields, and its validation schema.
+- [Forms](/docs/interfaces/base/forms): Build a form, its fields, and its validation schema.

package/docs/3.base/3.forms.md

@@ -1,13 +1,12 @@
 ---
 title: "Forms"
 description: "The Form builder, its fields and field groups, sections, validation and the save modes."
+mode: reference
 ---
 
-# Forms
-
 ## Overview
 
-`Form` builds a form component from a list of fields. Each field names a [data type](/docs/interfaces/base/data-types), and the data type supplies both the input component the frontend renders and the Zod schema the value is validated against. The builder does three things when you call it: it serializes every field, it compiles the field list into a single Zod object schema, and it attaches the JSON Schema form of that schema to the component options — so the description shipped to the frontend already carries its own validation contract.
+`Form` builds a form component from a list of fields. Each field names a [data type](/docs/interfaces/base/data-types), and the data type supplies both the input component the frontend renders and the Zod schema the value is validated against. The builder does three things when you call it: it serializes every field, it compiles the field list into a single Zod object schema, and it attaches the JSON Schema form of that schema to the component options. The description shipped to the frontend already carries its own validation contract.
 
 Everything on this page is exported from the `form` module, reachable either from the package root or from its own subpath:
 
@@ -23,7 +22,7 @@ import { Form, FormComponents } from "@antelopejs/interface-dms/base/form";
 
 `Form` returns a `FormBuilder`, which is a `ComponentBuilder<FormPropsSerialized>` with one extra readonly property, `fields`, carrying the original unserialized `FormFieldOrGroup[]`. That property is what lets `formSchema` derive a schema straight from a builder.
 
-## Declare a Form
+## Declare a form
 
 Assign the builder to a static field of a page class. The form fetches its initial values from `fetchUrl` and posts back to `submitUrl`.
 
@@ -67,7 +66,7 @@ export class NotesPage extends PageController(
 }
 ```
 
-### FormProps
+### `FormProps`
 
 `FormProps` extends [`BaseComponentProps`](/docs/interfaces/base/types).
 
@@ -98,7 +97,7 @@ A form on a page that sets neither `saveMode` nor `kind` saves with the save bar
 
 An `"action"` form resets after a successful submit, a `"record"` keeps its values; `labelKey` names the field labelling the record.
 
-`FormPropsSerialized` is `FormProps` with `fields` replaced by `FormFieldOrGroupSerialized[]` — every entry of the form, its own then each section's (`formEntries`) — `sections` by `FormSectionSerialized[]` (each section with the `fieldIds` of the entries it holds), and one added property, `schema`, holding the JSON Schema produced from the compiled Zod object. A required boolean field whose input is a checkbox validates as `z.literal(true)` (`isAcceptanceField`).
+`FormPropsSerialized` is `FormProps` with `fields` replaced by `FormFieldOrGroupSerialized[]` (every entry of the form, its own then each section's, `formEntries`), `sections` by `FormSectionSerialized[]` (each section with the `fieldIds` of the entries it holds), and one added property, `schema`, holding the JSON Schema produced from the compiled Zod object. A required boolean field whose input is a checkbox validates as `z.literal(true)` (`isAcceptanceField`).
 
 ## Fields
 
@@ -123,9 +122,9 @@ A `FormField` describes one input.
 
 A module's own form applies `visibleWhen` and `disabledWhen` in the browser; its submit handler enforces what it needs. A table view's columns carry them to its forms and its data routes enforce them as well (see [Tables](/docs/interfaces/base/tables)).
 
-`FormFieldSerialized` replaces `type` with the data type's registered id string and `inputComponent` with a mandatory `component: ComponentInfoSerialized` — the resolved input component, taken from `inputComponent` when set and from `type.inputComponent()` otherwise.
+`FormFieldSerialized` replaces `type` with the data type's registered id string and `inputComponent` with a mandatory `component: ComponentInfoSerialized`: the resolved input component, taken from `inputComponent` when set and from `type.inputComponent()` otherwise.
 
-## Group Fields
+## Group fields
 
 A `FieldGroup` nests fields under a common heading. It is an alternative member of the `fields` array, not a wrapper around it.
 
@@ -158,7 +157,7 @@ const contact: FieldGroup = {
 
 `FormFieldOrGroup` is `FormField | FieldGroup`, and `FormFieldOrGroupSerialized` is `FormFieldSerialized | FieldGroupSerialized`. Two guards discriminate them, both by checking for an array-valued `fields` property:
 
-```typescript
+```typescript fragment
 import {
   isFieldGroup,
   isFieldGroupSerialized,
@@ -171,11 +170,11 @@ for (const item of formProps.fields) {
 }
 ```
 
-## Validate a Submission
+## Validate a submission
 
 The schema the form ships to the frontend is also available on the backend, so the route that receives the submission validates against exactly the same rules.
 
-```typescript
+```typescript fragment
 import { Controller, HTTPResult, JSONBody, Post } from "@antelopejs/interface-api";
 import { formSchema } from "@antelopejs/interface-dms/base";
 
@@ -193,9 +192,9 @@ export class NotesController extends Controller("/playground/notes") {
 }
 ```
 
-### formSchema
+### `formSchema`
 
-```typescript
+```typescript fragment
 function formSchema(
   source: FormSchemaSource,
 ): z.ZodObject<Record<string, z.ZodTypeAny>>;
@@ -203,9 +202,9 @@ function formSchema(
 
 `FormSchemaSource` is `FormFieldOrGroup[] | FormProps | FormBuilder`. `formSchema` accepts any of the three: an array is compiled directly, a `FormBuilder` and a `FormProps` object are compiled from their `fields`. Anything else throws `Error("formSchema: unsupported source")`.
 
-### buildFormSchema
+### `buildFormSchema`
 
-```typescript
+```typescript fragment
 function buildFormSchema(
   fields: FormFieldOrGroup[],
 ): z.ZodObject<Record<string, z.ZodTypeAny>>;
@@ -213,9 +212,9 @@ function buildFormSchema(
 
 `buildFormSchema` is the field-list form of the same operation and is what `Form` itself calls. It walks the list, flattens groups so a grouped field lands in the object under its own `id`, and adapts every field's base schema. The resulting object is flat: grouping affects layout, not the payload shape.
 
-### adaptFieldValidationSchema
+### `adaptFieldValidationSchema`
 
-```typescript
+```typescript fragment
 function adaptFieldValidationSchema(
   baseSchema: z.ZodTypeAny,
   options: FieldValidationOptions, // { localized?, required?, fallbackLocale? }
@@ -228,11 +227,11 @@ function adaptFieldValidationSchema(
 - When `required` is falsy the schema becomes `.nullable().optional()`.
 - When `required` is true and the schema is a `ZodString` or a `ZodArray`, a `.min(1)` is added so an empty string or empty array does not satisfy the requirement.
 
-It is exported because the same adaptation is applied outside forms — the `Column` decorator uses it to register a field validator on a data controller.
+It is exported because the same adaptation is applied outside forms. The `Column` decorator uses it to register a field validator on a data controller.
 
-### serializeFormFields
+### `serializeFormFields`
 
-```typescript
+```typescript fragment
 function serializeFormFields(
   fields: FormFieldOrGroup[],
 ): FormFieldOrGroupSerialized[];
@@ -240,7 +239,7 @@ function serializeFormFields(
 
 `serializeFormFields` produces the serialized field list: for each field it resolves the input component (`inputComponent` if given, otherwise `type.inputComponent()`) and replaces the data type instance with its registered id, falling back to the string `"unknown"` when the type is not registered. Groups keep their metadata and have their `fields` serialized in place.
 
-## Input Components
+## Input components
 
 `FormComponents` is a namespace of factory functions, each returning a `ComponentInfoSerialized` for one input widget. Data types call them to produce their default input; you call them directly when a field needs a widget other than its type's default, via `FormField.inputComponent` or `ColumnOptions.inputComponent`.
 
@@ -258,7 +257,7 @@ const priority = FormComponents.InputSelect({
 
 | Function | Options interface |
 | --- | --- |
-| `InputCheckbox()` | — |
+| `InputCheckbox()` | None |
 | `InputText(options?)` | `InputTextOptions` |
 | `InputTextarea(options?)` | `TextareaOptions` |
 | `InputEmail(options?)` | `InputEmailOptions` |
@@ -269,7 +268,7 @@ const priority = FormComponents.InputSelect({
 | `InputTime(options?)` | `InputTimeOptions` |
 | `InputPhone(options?)` | `InputPhoneOptions` |
 | `InputSlider(options?)` | `SliderOptions` |
-| `InputSwitch()` | — |
+| `InputSwitch()` | None |
 | `InputRadioGroup(options)` | `RadioGroupOptions` |
 | `InputSelect(options)` | `SelectOptions` |
 | `InputRelation(options)` | `RelationOptions` |
@@ -309,9 +308,9 @@ The option interfaces live in the same namespace. The ones with more than a plac
 | `ImageResizeOptions` | `maxWidth: number`, `maxHeight: number`, `fit?: "cover" \| "contain"` |
 | `InputEmailOptions`, `InputColorOptions`, `RichTextOptions` | `placeholder?` |
 
-`ImageResizeOptions` downscales client-side before upload. `contain` (the default) scales down while preserving the source ratio; `cover` crops the image centred to the `maxWidth`/`maxHeight` ratio first, then scales down. An image already within bounds is uploaded untouched. This is a UX-level bound, not a server-enforced guarantee — keep `constraints.maxSize` for the latter.
+`ImageResizeOptions` downscales client-side before upload. `contain` (the default) scales down while preserving the source ratio; `cover` crops the image centred to the `maxWidth`/`maxHeight` ratio first, then scales down. An image already within bounds is uploaded untouched. This is a UX-level bound, not a server-enforced guarantee. Keep `constraints.maxSize` for that.
 
-## Events and Functions
+## Events and functions
 
 `FormEvents` names the events a form emits, `FormFunctions` the functions it exposes to watch actions.
 
@@ -355,7 +354,7 @@ const form = Form({
 
 `SET_FIELD_VALUE` writes a field from another one's change: `value` writes a fixed value, `valueMap` the entry named by the value of the field the event names, and a value the map has no entry for writes nothing. It skips the `initial` events, so a record opens with what it stored and a field nobody edited is never submitted as changed; a field it writes on a change counts as changed, like one typed in. A field it writes fires `FIELD_CHANGE` in turn, so two watches writing each other loop.
 
-```typescript
+```typescript fragment
 form.watch(FormEvents.FIELD_CHANGE, FormFunctions.SET_FIELD_VALUE, {
   params: { targetField: "probability", valueMap: { won: 100, lost: 0 } },
   onParam: { key: "fieldId", value: "stage" },
@@ -364,6 +363,6 @@ form.watch(FormEvents.FIELD_CHANGE, FormFunctions.SET_FIELD_VALUE, {
 
 `.watch()` records the watch on the component itself; `.watchOn(childId, …)` records it on a child declared with `.child()`. Both come from `ComponentBuilder` in `@antelopejs/interface-dms/component`.
 
-## Next Steps
+## Next steps
 
-- [Tables](/docs/interfaces/base/tables) - Turn a data controller into a table view with columns, row actions and guards.
+- [Tables](/docs/interfaces/base/tables): Turn a data controller into a table view with columns, row actions and guards.