@antelopejs/interface-dms 0.7.4 → 0.9.0

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

@@ -89,12 +89,12 @@ export class NotesPage extends PageController(
 | `redirectOnSuccess` | `string` | Path to navigate to after a successful submit. Accepts `{{params.X}}` and `{{query.X}}` tokens like `submitUrl`, plus `{{response.X}}` which resolves against the JSON body of the submit response. |
 | `submitDefaults` | `Record<string, unknown>` | Values merged into the submit payload even when the field is absent from the form. String values accept `{{params.X}}` and `{{query.X}}` tokens resolved against the form's route at submit time; entries whose tokens do not resolve are dropped. |
 | `saveMode` | `FormSaveMode` | How the form offers to save. `"bar"` (default): a sticky bar shown while there are unsaved changes, naming them, with Discard and Save; on a page it floats over the form, taking no space while hidden. `"footer"`: buttons in the form's footer. `"none"`: no buttons. `"instant"`: each change saves on its own, the changed field alone sent to `submitUrl` (so the endpoint must accept a partial body), a pick at once and a text once typing pauses; a refused save is put back to the last confirmed value, with a Retry; an `"action"` form ignores it. In a drawer or modal, `"bar"` and `"footer"` both use the container's footer. |
-| `kind` | `FormKind` | What the form edits. `"record"` (default): keeps its values once saved, and offers Cancel while clean only when it has somewhere to go back to (the drawer or modal it sits in, or `backTo` on a page). `"action"`: a send, invite or run form; its `submitLabel` always shows in its footer, ready, so a pre-filled form sends its defaults as they are (a form with no field to fill in included); Reset joins it once a value changes (in a drawer or a modal, Cancel before that), and it empties after a successful submit (each field back to its `defaultValue`, or what `fetchUrl` loaded). |
+| `kind` | `FormKind` | What the form edits. `"record"` (default): keeps its values once saved, and offers Cancel while clean only when it has somewhere to go back to (the drawer or modal it sits in, or `backTo` on a page). `"create"`: a form making a new record (a table view's add form and its duplicate, a relation's add form, set by `TableView` and `RelationType`); its submit, "Create" by default, shows from the start and it lists no changes. Declared, never inferred from `submitUrlMethod`. `"action"`: a send, invite or run form; its `submitLabel` always shows in its footer, ready, so a pre-filled form sends its defaults as they are (a form with no field to fill in included); Reset joins it once a value changes (in a drawer or a modal, Cancel before that), and it empties after a successful submit (each field back to its `defaultValue`, or what `fetchUrl` loaded). |
 | `backTo` | `string` | Where Cancel leads a `"record"` form on a page; without it the form offers no Cancel there. `TableView` sets it on its form pages, to the list. |
 | `labelKey` | `string` | Field of the loaded record that names it: on a page, the breadcrumb ends with its value once the form has loaded. `TableView` sets it on its edit and details pages from its own `labelKey`. Also in the page editor's Form schema, as an advanced option. |
 | `requiresRecord` | `boolean` | The form is about the record `fetchUrl` loads: while a route value that URL names is missing (a page reached without its `?id=`), it shows "No entry selected" instead of its fields, and cannot be saved. `ResourceForm` sets it in `edit` and `view`. |
 
-A form on a page that sets neither `saveMode` nor `kind` saves with the save bar, as a record: declare `kind: "action"` on a form that sends something new each time. `FORM_SAVE_MODES` and `FORM_KINDS` list the accepted values.
+A form on a page that sets neither `saveMode` nor `kind` saves with the save bar, as a record: declare `kind: "create"` on a form that makes a new record and `kind: "action"` on a form that sends something new each time. `FORM_SAVE_MODES` and `FORM_KINDS` list the accepted values.
 
 An `"action"` form resets after a successful submit, a `"record"` keeps its values; `labelKey` names the field labelling the record.
 
@@ -112,9 +112,16 @@ A `FormField` describes one input.
 | `description` | `string` | Help text. |
 | `inputComponent` | `ComponentInfoSerialized` | Overrides the input component the data type would provide. |
 | `disabled` | `boolean` | Render the input non-editable. |
+| `showEmptyOnCreate` | `boolean` | On a `"create"` form, keep this read-only field while it holds nothing; left out, an empty read-only field is hidden there. |
 | `required` | `boolean` | Whether a value must be supplied. Drives the schema, see below. |
 | `defaultValue` | `DefaultValue` | Initial value. |
+| `offersDefault` | `boolean` | `defaultValue` is the module's default for a setting: while the field holds something else, it shows "Module default: X" with "Use default", which puts it back. Off unless set, so a record form never presents a column's initial value as a default. |
 | `localized` | `boolean` | The value is a per-locale record rather than a single value. |
+| `fallbackLocale` | `string` | A localized field's fallback language: a value in any language requires one in this one. Set by a table view from `@Localized({ fallbackLocale })`. |
+| `visibleWhen` | `FieldCondition` | `{ field, in }`: shown only while the field `field` holds one of the values `in` lists (`null` for an empty one), from the moment the form opens; hidden, it is neither required nor sent. |
+| `disabledWhen` | `FieldCondition` | Same shape: read-only while the condition holds; its value is not sent. |
+
+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.
 
@@ -211,13 +218,13 @@ function buildFormSchema(
 ```typescript
 function adaptFieldValidationSchema(
   baseSchema: z.ZodTypeAny,
-  options: { localized?: boolean; required?: boolean },
+  options: FieldValidationOptions, // { localized?, required?, fallbackLocale? }
 ): z.ZodTypeAny;
 ```
 
 `adaptFieldValidationSchema` turns the schema a data type returns from `getValidation()` into the schema for one particular field:
 
-- With `localized: true` the schema is wrapped in `z.record(z.string(), schema)`, so the value becomes a map of locale to value.
+- With `localized: true` the schema is wrapped in `z.record(z.string(), schema)`, so the value becomes a map of locale to value. With a `fallbackLocale` as well, a map filling any language must fill that one, else it fails with `$dms.field_errors.required` on `[fallbackLocale]`.
 - 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.
 
@@ -275,6 +282,8 @@ const priority = FormComponents.InputSelect({
 | `File(options?)` | `FileOptions` |
 | `Image(options?)` | `ImageOptions` |
 
+`InputWidth` is `"compact" | "full"`: how wide a single-line text, number or percentage input sits in its row. `"compact"` sizes it for a short value (11rem) from the `sm` breakpoint up, while a phone keeps the full row; `"full"` fills the row. Left out, the input is compact when its bounds keep the value short -- `min` / `max` within 6 digits, `maxLength` of 16 or less -- and fills the row otherwise.
+
 The option interfaces live in the same namespace. The ones with more than a placeholder:
 
 | Interface | Fields |
@@ -282,9 +291,9 @@ The option interfaces live in the same namespace. The ones with more than a plac
 | `SelectOption` | `label: string`, `value: string \| number`, `disabled?`, `icon?`, `iconColor?`, `textColor?` |
 | `SelectOptions` | `items: SelectOption[]`, `placeholder?`, `multiple?`, `deselectable?` |
 | `RadioGroupOptions` | `items: SelectOption[]`, `orientation?: AxeOrientation` |
-| `InputTextOptions` | `placeholder?`, `maxLength?`, `minLength?`, `showCount?` |
+| `InputTextOptions` | `placeholder?`, `maxLength?`, `minLength?`, `showCount?`, `width?: InputWidth` |
 | `TextareaOptions` | `placeholder?`, `rows?`, `maxLength?`, `showCount?` |
-| `InputNumberOptions` | `min?`, `max?`, `step?`, `placeholder?`, `suffix?`, `clamp?` (`InputNumber` only: `false` keeps a value outside `min` / `max` as typed and reports it under the field instead of clamping it on blur) |
+| `InputNumberOptions` | `min?`, `max?`, `step?`, `placeholder?`, `suffix?`, `clamp?` (`InputNumber` only: `false` keeps a value outside `min` / `max` as typed and reports it under the field instead of clamping it on blur), `width?: InputWidth` |
 | `InputTimeOptions` | `min?`, `max?`, `placeholder?` |
 | `InputPhoneOptions` | `placeholder?`, `requiredPrefix?` |
 | `InputPasswordOptions` | `placeholder?`, `minLength?`, `confirmPassword?`, `confirmPlaceholder?` |
@@ -316,14 +325,16 @@ The option interfaces live in the same namespace. The ones with more than a plac
 | `FormFunctions.SET_FIELD_DISABLED` | `"DmsComponent.Form.SetFieldDisabled"` |
 | `FormFunctions.SET_FIELD_HIDDEN` | `"DmsComponent.Form.SetFieldHidden"` |
 | `FormFunctions.SET_FIELD_REQUIRED` | `"DmsComponent.Form.SetFieldRequired"` |
+| `FormFunctions.SET_FIELD_VALUE` | `"DmsComponent.Form.SetFieldValue"` |
 
-Both functions register their parameter shape in `WatchFunctionParamMap`, so `.watch()` type-checks the `params` object:
+Each function registers their parameter shape in `WatchFunctionParamMap`, so `.watch()` type-checks the `params` object:
 
 | Function | Params |
 | --- | --- |
 | `SET_FIELD_DISABLED` | `{ targetField: string; setDisabled: boolean }` |
 | `SET_FIELD_HIDDEN` | `{ targetField: string; setHidden: boolean }` |
 | `SET_FIELD_REQUIRED` | `{ targetField: string; setRequired: boolean }` |
+| `SET_FIELD_VALUE` | `SetFieldValueParams`: `{ targetField: string; value?: unknown; valueMap?: Record<string, unknown> }` |
 
 ```typescript
 import { Form, FormEvents, FormFunctions } from "@antelopejs/interface-dms/base/form";
@@ -340,7 +351,16 @@ const form = Form({
 });
 ```
 
-`FIELD_CHANGE` carries `{ fieldId, value }` and fires once per field with the values the form starts from (its defaults, or the record it loaded), then on each change: the watch above, which names no condition, hides `vatNumber` as soon as the form opens. Add a `value` condition to `onParam` for a watch that applies only when the field holds that value, whether it opened with it or the user picked it.
+`FIELD_CHANGE` carries `{ fieldId, value, initial }` and fires once per field with the values the form starts from (its defaults, or the record it loaded), then on each change: the watch above, which names no condition, hides `vatNumber` as soon as the form opens. Add a `value` condition to `onParam` for a watch that applies only when the field holds that value, whether it opened with it or the user picked it. `initial` is `true` while the field still holds the value it started from and never held another.
+
+`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
+form.watch(FormEvents.FIELD_CHANGE, FormFunctions.SET_FIELD_VALUE, {
+  params: { targetField: "probability", valueMap: { won: 100, lost: 0 } },
+  onParam: { key: "fieldId", value: "stage" },
+});
+```
 
 `.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`.
 

package/docs/3.base/4.tables.md

@@ -102,7 +102,7 @@ export class roleDataAPI extends DataController(
 | --- | --- |
 | `Get` | Read one row. |
 | `List` | Paginated list with search, filters and sorting. |
-| `Select` | List with the `select` pluck mode, used by relation pickers. |
+| `Select` | List with the `select` pluck mode, used by relation pickers. `?ids=a&ids=b` (with `idKey` when the value is another field) answers those rows alone, as `List` does: a picker and a filter chip name the ids they hold this way. |
 | `Count` | Row count for the current query. |
 | `CountBatch` | One count per query, in a single `POST /count/batch` (tab, view and group counters). |
 | `Summary` | `GET /summary?ids=…`: the footer summaries a table view declared, over every row the request's filters list. |
@@ -137,9 +137,22 @@ These are not the plain data-api defaults. Every route asserts tenant access and
 | `group` | `string` | Identifier of the `ColumnGroup` this column belongs to in the generated forms. |
 | `cellWrap` | `boolean` | Wrap the grid cell without a line limit. |
 | `size` | `number` | Default width of the grid column in px (150 when omitted). |
+| `visibleWhen` | `FieldCondition` | `{ field, in }`: the form field shows only while the column `field` holds one of the values `in` lists (`null` for an empty one). The data routes hold to it too: hidden, the field is not mandatory, the value sent for it is ignored, and an edit clears the value it stored. |
+| `disabledWhen` | `FieldCondition` | Same shape: the form field is read-only while the condition holds, and the data routes ignore the value sent for it. |
 | `display` | `ColumnDisplay` | A display class instance (`new DefaultDisplays.IdentityDisplay({ … })`, or a module's own `@RegisterDisplay("<module>:<id>")` class) the grid cells (and expanded-row fields) render with, its options typed by the class. `type` keeps driving forms, filters, validation and exports; the formatter also receives the row. Serialized as `{ type, options? }`. |
 
-A read-only field whose `readonlyBehavior` resolves to `hidden` for a mode is dropped from that mode's form; a field whose data type has no input component is dropped from every form.
+A field is read-only in a form when its `@Access` for the action that form runs is `AccessMode.ReadOnly`: the per-action override (`@Access(AccessMode.ReadWrite, { new: AccessMode.ReadOnly })`, keyed `new`, `edit` and `get` for the view form) where it declares one, else its default access — the access the data API applies to the value it writes. Such a field is disabled in that form, or dropped from it when its `readonlyBehavior` resolves to `hidden` for the mode; a field whose data type has no input component is dropped from every form.
+
+`visibleWhen` and `disabledWhen` make a field depend on the value of another column, with no watch: the generated forms apply them from the values they open with, and the `new` and `edit` routes (`TableViewRoutes.New`, `Edit`, `EditWith`) apply them to what they write, read on the row as it will be stored — an edit's stored row under its body. A hidden or disabled field leaves the body before the guard runs, and an edit clears the value a hidden field stored (a disabled one keeps its own); `@Mandatory` binds a field with `visibleWhen` only while it shows, and there an edit must leave it filled (a deal moved to `lost` without its reason is refused with `400 { code: "missing_mandatory_fields", fields: ["lostReason"] }`, as the data API refuses any mandatory field). A condition naming an unknown column, the column itself or no value throws at registration.
+
+```ts
+@Mandatory("new", "edit")
+@Column({ name: "Loss reason", type: reasonType, visibleWhen: { field: "stage", in: ["lost"] } })
+declare lostReason: string;
+
+@Column({ name: "Probability", type: percentType, disabledWhen: { field: "stage", in: ["won", "lost"] } })
+declare probability: number;
+```
 
 ### Column Groups
 
@@ -230,7 +243,7 @@ Typing `TableViewOptions` by `InstanceType<T>` is what makes row-action rules fi
 | `layout` | `TableViewLayout` | `"full"` (default): the dashboard grid; `"compact"`: the list of a settings page (tabs, open search, quick filters, the footer's page size picker; no caption, refresh, ⋯ menu nor column menus). Either way, search shows only with `@Searchable` fields, filters only with a `filterable` column, the caption only when `caption` is set. |
 | `searchPlaceholder` | `string` | Placeholder of the search field, also its accessible name. |
 | `searchShortcut` | `string` | Key opening and focusing the search, in Nuxt UI `defineShortcuts` notation (`"/"`, `"shift_f"`): `"shift_f"` (⇧F) by default. It does not fire while the user types in a field. |
-| `quickFilters` | `TableViewQuickFilter[]` | `{ field, label?, icon?, allLabel?, mode? }` dropdown filters over a filterable column's values, `mode` a `TableViewQuickFilterMode`. The picked value is the column's own filter: kept with the table state, counted, cleared by "Clear filters"; in the `compact` layout the button reads "Role: Admin" with a clear button. Unknown or non-filterable columns throw. |
+| `quickFilters` | `TableViewQuickFilter[]` | `{ field, label?, icon?, allLabel?, mode? }` dropdown filters over a filterable column's values, `mode` a `TableViewQuickFilterMode`. The picked value is the column's own filter: kept with the table state, counted, cleared by "Clear filters"; in the `compact` layout the button reads "Role: Admin" with a clear button. Unknown or non-filterable columns throw. The column needs values to list (a select with `items`, a boolean, a status, a relation, or an input declaring `items` or a `searchUrl`): on any other — a free-text string, say — the toolbar leaves it out and registration logs a warning. |
 | `pageSize` | `number` | Rows per page while the user picked none (default 10), 1 to 50: registration throws above. A size other than 10, 25 and 50 joins them in the table's page size picker. |
 | `pagination` | `TableViewPaginationMode` | `"pages"` (default): a pager; `"loadMore"`: a "Load more" button; `"infinite"`: the next page loads as the footer scrolls into view. The last two ask for every page loaded so far, from the first row, so a refresh re-reads them. |
 | `footer` | `TableViewFooterOptions` | `{ countLabel?, hint?, summary?, legend? }`: the footer's row count (`$` key pluralized on `{ count }`) and hint; `summary` figures (`TableViewFooterSummary`: `label`, `field?`, `op: "sum" \| "count"`, `where?` row rule, `format?` `TableViewSummaryFormat`) computed by the `Summary` route over every listed row; `legend`, a `SelectType` column. Serialized as `TableViewFooterSerialized`: each summary gets an `id`, its `where` stays server-side (`TableViewMeta.footerSummary(id)`). A sum without `field`, an unknown column or a legend that is no select column throws. |
@@ -241,8 +254,10 @@ Typing `TableViewOptions` by `InstanceType<T>` is what makes row-action rules fi
 | `rowActions` | `TableViewRowActionOptions<T>` | Built-in and custom row actions. |
 | `columns` | `TableViewColumnsOptions` | The controller's columns as this table view shows them: `hidden` lists the ones it opens hidden, as `isVisible: false` does on the `@Column`, for this table view only (they stay in the column menu, filterable and in the forms). A name the controller has no column for throws at registration. |
 | `customButtons` | `CustomButton[]` | Toolbar buttons; see [Shared Types](/docs/interfaces/base/types). |
+| `forms` | `Partial<Record<"new" \| "edit" \| "view", TableViewFormSetup>>` | A callback per generated form, `(form: FormBuilder) => void`, receiving its builder before the table view embeds it, for input comfort only: what it declares (`.watch()`, a value filled in from another, a field one table's forms leave out) holds in a drawer, a modal or a form page alike. No data rule here, the routes never see it: a field shown, required or locked by another's value is a column's `visibleWhen` / `disabledWhen`. |
 | `formContainer` | `FormContainer` | Where the `new` / `edit` / `view` forms open. |
 | `archiveMode` | `boolean` | Replace delete with archive/restore. Requires `@ArchiveField`. |
+| `archivedCountLabel` | `string` | How the footer counts the archived rows: an i18n key with `$` receiving `{ count }` and pluralized on it, or a text with `{count}`. Defaults to "Archived: {count}", which agrees with no noun. |
 | `defaultFilters` | `Array<{ accessorKey: string; value?: string; mode: string }>` | Filters applied when the table opens. |
 | `defaultSort` | `{ field: string; desc?: boolean }` | Sort applied when the viewer has no stored preference, and the one a cleared sort goes back to. |
 | `pinnedRows` | `RowActionRule<T>` | Rows listed first whatever the sort, in the sort's order among themselves: within the list the route answers (a source without `paginate` answers every row, so its pinned rows open the first page; a paging route's open their page). The `grouped` display pins nothing; registration throws beside `reorder`. |
@@ -252,14 +267,15 @@ Typing `TableViewOptions` by `InstanceType<T>` is what makes row-action rules fi
 | `tabs` | `TableViewTab[]` | Tabs above the table, each applying a hidden filter on one column (`filter` optional). A tab may link to another page instead (`to`: page controller or path, `countFrom`: data controller or location for its counter); a tab with id `"all"` replaces the implicit one; `permission` (an action of the table) or `permissionId` (an absolute id) gates it; `navBadge` (`true`, or `{ tone }`) publishes its counter as the page's nav badge. Serialized as `TableViewTabSerialized` (`to` resolved per request, `toPage`). |
 | `realtime` | `boolean` | Set to `false` to disable realtime broadcast and presence for this resource. Realtime is on by default. |
 | `realtimeTopic` | `string \| string[]` | Topics the backend publishes on when rows change outside the table's routes: the table reads its rows again on each event. Registered against the page from `onCreated`; also offered by `TableView.fromSource`. |
-| `liveHold` | `boolean \| TableViewLiveHoldOptions` | On a page declared with `live`, keeps the rows while the page is paused and shows a "N new · Show" strip; Show reads them once without leaving the pause. `{ whileRowOpen?, whileScrolled?, whileSearching?, whileSorted? }` (all default `false`) also holds the table alone, the page staying live, while a row is open in the side panel, its first row is scrolled out of view, the user's search narrows the rows or they are sorted otherwise than by `defaultSort`; the strip then names the reason ("Table on hold · search active"). `missedLabel` words the strip's count, given `{count}` ("12 new requests"); while the page is paused the strip adds the page's `setMissedDetail` breakdown. A `TableView.fromSource` route receives `liveHeldAt` (ISO 8601) on every request made while held. Also offered by `TableView.fromSource`. |
+| `liveHold` | `boolean \| TableViewLiveHoldOptions` | On a page declared with `live`, keeps the rows while the page is paused, and in Direct while they are on screen or scrolled past (a new row at the top would push them down), and shows a "N new · Show" pill over the rows, which moves nothing, counting the rows its tab, search and filters match now beyond those it holds (asked of its count route), not the events; Show reads them once without leaving the pause. `{ whileRowOpen?, whileScrolled?, whileSearching?, whileSorted? }` (all default `false`) also holds the table alone, the page staying live, while a row is open in the side panel, its first row is scrolled out of view, the user's search narrows the rows or they are sorted otherwise than by `defaultSort`; the strip then names the reason ("Table on hold · search active"). `missedLabel` words the strip's count, given `{count}` ("12 new requests"); while the page is paused the strip adds the page's `setMissedDetail` breakdown. A `TableView.fromSource` route receives `liveHeldAt` (ISO 8601) on every request made while held. Also offered by `TableView.fromSource`. |
 | `reorder` | `TableViewReorderOptions` | `{ field }`: rows ordered by hand with a drag handle, on the grid and on the `cards` display. `field` must be a `@Sortable()`, writable `NumberType` column, and the edit action on: registration throws otherwise. The rows are listed sorted on it, and a move saves only the rows whose value changed. |
 | `kanban` | `KanbanOptions` | Enable the kanban display. |
 | `grouped` | `GroupedOptions` | `{ groupByField, by?: "value" \| "day" \| "week", collapsible?, count? }`: offer the `grouped` display, the grid's columns under a header row per group. `groupByField` must be a `@Sortable()` column, a `DateType` one to group by day or week. |
 | `views` | `TableViewViewsOptions` | `{ items: TableViewView[], layout?: "tabs" \| "strip" \| "menu", defaultView?, userViews? }`. A `TableViewView` is a `TableViewViewState` (`filters`, `search`, `sort`, `columns: { visible?, hidden?, order? }`, `display`, `density`) with `id`, `label`, `icon`, `tone`, `dot`, `count`, `permission` (an action of the table by name, or an `Action`) and `permissionId` (an absolute permission id, which wins); a view the caller fails it for is left out when the layout is served. Filter values may hold `{{user.id}}`, `{{now}}` and `{{now±Nd}}`, resolved by the server. Serialized as `TableViewViewsSerialized` (no `permission` nor `permissionId`). |
-| `card` | `TableViewCardOptions` | The card the `kanban` and `cards` displays draw: `fields` it shows, or a `component` drawing it whole. |
+| `card` | `TableViewCardOptions` | The card the `kanban` and `cards` displays draw: `fields` it shows, or a `component` drawing it whole; `minWidth` (a CSS length, `"230px"` by default) is the narrowest a card of the `cards` grid gets. |
 | `displays` | `TableViewDisplayOption[]` | The displays offered, in order: a built-in id (`"table"`, `"cards"`) without a component, or a module display named `<module>:<id>`; registration throws otherwise. Left out, the built-in `table` alone; listed, exactly these, so the grid is kept by listing `{ id: "table" }`. |
 | `defaultDisplay` | `string` | Display shown when the viewer has no stored preference. Defaults to `"table"`. |
+| `mobileDisplay` | `string` | Display a phone (narrower than 768px) opens on when the viewer has no stored preference, e.g. `"cards"`. Registration throws when it is not among the displays offered. |
 | `guards` | `TableViewGuards<T>` | Server-side guards run before mutating actions. |
 | `bypassTenantAccessGate` | `boolean` | Skip the tenant access gate on every data route of this table view. |
 
@@ -269,7 +285,7 @@ Typing `TableViewOptions` by `InstanceType<T>` is what makes row-action rules fi
 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}}`. There is no export, realtime nor footer summary.
+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.
 
 ### Reaching a Table Behind a Tenant Gate
 
@@ -358,7 +374,7 @@ A `new` or `edit` `ResourceForm` block over the controller submits to the same r
 
 `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 —, `?<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, 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`).
+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.
 
@@ -442,7 +458,7 @@ static table = TableView(invoiceDataAPI, {
 
 `KanbanOptionsSerialized` is `KanbanOptions` plus the serialized `card` (`TableViewCardOptionsSerialized`).
 
-`card` (`TableViewCardOptions`: `{ fields?: string[]; component?: Component }`) 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).
+`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
 
@@ -516,7 +532,9 @@ 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 — a background job updating rows, for instance — builds the name with `tableViewRowTopic` rather than spelling out the prefix.
+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 — a background job updating rows, for instance — 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:
 

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

@@ -313,10 +313,11 @@ const card = ChartCard({
 | `currencyCode` | `string` | Currency for `valueFormat: "currency"`. |
 | `valuePrecision` | `ValuePrecision` | Fixed fraction digits or `"native"` Intl defaults; omitted keeps legacy formatting. Also applies to the previous value and nested chart's value axis and tooltip. |
 | `showDelta` | `boolean` | Show the change against the comparison period. |
+| `invert` | `boolean` | Treat an increase as bad — for metrics where lower is better. |
 | `showLegend` | `boolean` | Show the primary / comparison legend. Defaults to `true`. |
 | `showSeriesLegend` | `boolean` | Show the nested chart's legend, naming each series. Defaults to `false`. |
 | `primaryLabel` | `string` | Label of the primary series. |
-| `comparisonLabel` | `string` | Label of the comparison series. |
+| `comparisonLabel` | `string` | Label of the comparison series. Without it, a card with a `periodScope` names the selected comparison ("Previous year"). |
 
 ## KpiCard
 
@@ -345,17 +346,20 @@ const denied = KpiCard({
 | `icon` | `string` | Card icon. Defaults to `"i-ph-trend-up"` for the component metadata. |
 | `fetchUrl` | `string` | URL the card loads its value from. |
 | `fetchUrlMethod` | `HttpMethod` | Method for `fetchUrl`. |
-| `periodScope` | `string` | Id of the `PeriodSelector` to follow. |
+| `periodScope` | `string` | Id of the `PeriodSelector` to follow. Its comparison names the change; "No comparison" hides the change, the comparison value and the label. |
+| `realtimeTopic` | `string \| string[]` | Topics whose events make the card read `fetchUrl` again, through the page's `live` gate. The builder registers them on the page. |
 | `valueFormat` | `ValueFormat` | How the value is formatted. |
 | `currencyCode` | `string` | Currency for `valueFormat: "currency"`. |
 | `valuePrecision` | `ValuePrecision` | Fixed fraction digits or `"native"` Intl defaults; omitted keeps legacy formatting. |
 | `showDelta` | `boolean` | Show the change against the comparison period. |
+| `showPreviousValue` | `boolean` | Show the route's `previousValue` next to the change ("vs €42,900"), formatted as the value. Defaults to `true`. |
 | `showSparkline` | `boolean` | Show the sparkline. |
 | `sparklineAccent` | `ChartColorValue \| "auto"` | Sparkline colour. |
 | `invert` | `boolean` | Treat an increase as bad — for metrics where lower is better. |
-| `compareLabel` | `string` | Label next to the delta. |
+| `compareLabel` | `string` | Label next to the delta. Without it (and without `description`), a card with a `periodScope` names the selected comparison ("vs previous year"). Shown with the delta only: with no comparison, the `description` shows instead. |
 | `staticValue` | `number` | Inline value, as an alternative to `fetchUrl`. |
 | `staticDelta` | `number` | Inline delta, in percent (`12.5` reads +12.5 %). |
+| `staticPreviousValue` | `number` | Inline value compared against, as a fetched `previousValue`. |
 | `staticSparkline` | `number[]` | Inline sparkline points. |
 
 ## TopListCard
@@ -450,7 +454,7 @@ const selector = PeriodSelector({
 | `size` | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | Control size. |
 | `showRangeLabel` | `boolean` | Show the resolved date range as text. |
 | `rangeLabel` | `PeriodRangeLabel` | `"absolute"` (default): both bounds. `"relative"`: the start of a window reaching now, "since yesterday 11:52". |
-| `comparisonControl` | `PeriodComparisonControl` | `"menu"`, `"toggle"` (one inline button switching a comparison on and off) or `"hidden"` (nothing drawn, the comparison kept on). Defaults to `"toggle"` when `comparisons` offers a single comparison besides `"none"`, `"menu"` otherwise. |
+| `comparisonControl` | `PeriodComparisonControl` | `"menu"`, `"toggle"` (one inline button switching a comparison on and off) or `"hidden"` (nothing drawn, the comparison kept on). Defaults to `"toggle"` when `comparisons` offers a single comparison besides `"none"`, `"menu"` otherwise. The menu's trigger names the compared window ("vs 16 – 17 Oct", the option's name in its tooltip and its list), so the range label beside it keeps the current window only. |
 | `rememberKey` | `string` | Selectors carrying the same key share the remembered last choice, on any page. |
 | `variant` | `PeriodSelectorVariant` | `"default"` or `"segmented"`. |
 | `maxDays` | `number` | The longest custom range, in days (both ends included), the user can pick in the calendar or the date fields. Presets and a range given by the URL are not limited. |

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

@@ -195,6 +195,7 @@ export class OverviewPage extends PageController(
 | `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:
 
@@ -275,7 +276,7 @@ A page scoped by its URL — `?workspace=web`, a record id in the path — decla
 
 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). The header asks again whenever the query changes — only when one of its buttons declares an `availability` — 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.
+An `availability` receives the page URL's query as `context.query` (one value per name; caller-supplied, so check it like any input), its route parameters as `context.params` (`/projects/project/p1` on a page registered at `/projects/project/:id` is `{ id: "p1" }`), and the record the layout read as `context.record` ([Buttons acting on the page's record](#buttons-acting-on-the-pages-record)). The header asks again whenever the query or the route parameters change, and once a write refreshed the page — only when one of its buttons declares an `availability` or the layout reads a `record` — and keeps the buttons it has until the answer lands. The keys the DMS writes for the view itself never cause a request: `record` (the row open in a side panel), `live` (the paused live mode) and a period selector's `<id>.period`, `<id>.compare`, `<id>.from`, `<id>.to`, `<id>.compareFrom` and `<id>.compareTo`. A query key may carry dots, so `{{query.api.period}}` reads a period selector's choice.
 
 ```typescript
 DefaultLayout({
@@ -301,6 +302,35 @@ A table view of the page places its own buttons in the header with `placement: "
 
 Who sees a button is settled on the server when the layout is served: a button whose `permission` or `permissionId` the user lacks is left out of the layout, and a quick-action button only shows to the users the quick action is served to — that is, the users its page admits. A page drawn by a Vue page component can add its own buttons next to these with `usePageHeaderActions`; call it before the first `await` of the component's setup, so the server renders the buttons with the page and they never pop in. A page whose changes save as soon as they are made shows the shared **Saved instantly** pill there with `useInstantSaveHeader` ([Instant save or a save bar](/docs/components/lists-and-settings/section#instant-save-or-a-save-bar)).
 
+#### Buttons acting on the page's record
+
+A page about one record (a site, an invoice) reads it with its layout: `record` is a function the server calls each time it serves the layout, with the request's context — the page URL's `params` and `query`, the `user` and the `tenantId` — and answers the record, or `undefined` when there is none to show. A button's target names its fields as `{{record.X}}`, filled in by the server and percent-encoded: a maps link to the site's address, an API call on its own id. A button acting on the record — one whose target names `{{record.X}}`, or declaring `requiresRecord: true` (an "Edit" link that only needs `{{params.id}}`) — is left out of a page whose record was not found, or whose `record` threw (logged). Every `availability` of the page reads the record as `context.record`, so a button can be disabled on the record's state without reading it again:
+
+```typescript
+DefaultLayout({
+  record: ({ params }) => GetModel(SiteModel).get(params?.id ?? ""),
+  headerActions: [
+    {
+      label: "$sites.directions",
+      icon: "i-ph-map-pin",
+      target: { type: "external", url: "https://www.google.com/maps/search/?api=1&query={{record.address}}", newTab: true },
+    },
+    { label: "$sites.edit", requiresRecord: true, target: { type: "page", url: "/sites/{{params.id}}/edit" } },
+    {
+      label: "$sites.close",
+      target: { type: "api", url: "/api/sites/close?id={{params.id}}" },
+      availability: ({ record }) => (record?.closed ? { reason: "$sites.already_closed" } : undefined),
+    },
+  ],
+});
+```
+
+The record travels with the layout, so the header is drawn with it, on the server too, and never waits for it. Like an `availability`, it follows the page URL: the header asks for its buttons again when the route parameters or the query change, and once a write refreshed the page (`refreshPageBlocks()`, which a header button calls after a change, and a form once it saved). Its fields only shape the buttons; the route behind each one still checks the record on its own.
+
+#### A record deleted under the page
+
+A page reading a `record` leaves it once it is deleted, in every tab and for every member on it, with no code of the module. On each event of one of the page's realtime topics (its table views' rows, a `realtimeTopic`, a topic bound with `RegisterPageTopic`), the page asks its layout again: a record the server found before and now finds none of (its `record` answers `undefined`) was deleted. A toast says so, and the page opens the list it is a detail of (`MenuOptions.parent`); without one, it stays, on the "not found" state of its blocks. A `record` that throws counts as unknown, never as deleted, and a page opened on a record that never existed shows its blocks' "not found" state without a toast. Publish on one of the page's topics when the record is deleted: a table view's delete does it on its own.
+
 #### Hidden or disabled
 
 An `availability` has three answers. `undefined` leaves the button as declared, `{ reason }` disables it with the reason in a tooltip — for something the user can change ("No seat left: upgrade the plan") — and `{ hidden: true }` leaves it out of the header, as a missing permission does — for a button that makes no sense in the scope the page shows. Like a disabled one, a hidden button follows the page URL: the header asks again when the query changes, so a button can disappear on one `?workspace=` and come back on another, and the server-rendered header already carries the answer for the URL it was rendered for.
@@ -320,6 +350,22 @@ DefaultLayout({
 });
 ```
 
+A detail page reads its record from `context.params`, and hides the buttons that act on it when the record does not exist — the page then shows its "not found" state with no "Edit" or "Delete" beside the title:
+
+```typescript
+DefaultLayout({
+  headerActions: [
+    {
+      id: "edit",
+      label: "$projects.edit",
+      target: { type: "page", url: "/projects/project/{{params.id}}/edit" },
+      availability: async ({ params }) =>
+        (await projectExists(params?.id)) ? undefined : { hidden: true },
+    },
+  ],
+});
+```
+
 Hiding only shapes the UI: the route behind the button must still refuse the operation on its own.
 
 #### Ordering the header

package/docs/3.base/8.data-types.md

@@ -73,6 +73,7 @@ abstract class DataType {
   filter(context, proxy, key, value, mode, row): ValueProxyOrValue<boolean>;
   filterComponents(): Record<string, ComponentInfoSerialized> & { default: ComponentInfoSerialized };
   inputComponent(): ComponentInfoSerialized;
+  describedInputComponent(): ComponentInfoSerialized;
   decorateField?(target: unknown, key: PropertyKey, descriptor?: PropertyDescriptor): void;
 }
 ```
@@ -85,6 +86,7 @@ abstract class DataType {
 | `defaultInputComponent()` | Abstract. Returns the input component the type renders. Implemented by every concrete type. |
 | `getValidation()` | Abstract. Returns the Zod schema for one value of this type, before the field-level adaptation described in [Forms](/docs/interfaces/base/forms). |
 | `inputComponent()` | The form input. Defaults to `defaultInputComponent()`. |
+| `describedInputComponent()` | The input as it is described where nothing is entered through it: a table column's type (its cells, cards and quick filters read the options) and a read-only form field. Defaults to `inputComponent()`; a type leaves out what only an editable control uses, as a relation leaves out its add form. |
 | `filterComponents()` | The filter inputs, keyed by compare-mode id with a mandatory `default`. Defaults to `{ default: defaultInputComponent() }`. |
 | `filter()` | Applies a filter for one compare mode. The base implementation looks the mode up in the compare-mode registry and delegates to it; a type overrides it when a mode needs different semantics. |
 | `decorateField()` | Optional. Called by the `@Column` decorator so the type can add further decorators to the field — this is how the relation types install their join. |
@@ -207,7 +209,7 @@ function serializeType(instance?: DataType): DataTypeSerialized | undefined;
 | `compareModes` | `string[]` | Ids of the type's compare modes; unregistered ones are dropped. |
 | `defaultCompareMode` | `string` | Id of the default mode. |
 | `filterComponents` | `Record<string, FilterComponent>` | Filter inputs by mode id, from `filterComponents()`, with every `noInput` mode's entry replaced by the literal `"noInput"`. |
-| `inputComponent` | `ComponentInfoSerialized` | The form input, from `inputComponent()`. |
+| `inputComponent` | `ComponentInfoSerialized` | The input the column's cells and quick filters read the options of, from `describedInputComponent()`. |
 
 `FilterComponent` is `ComponentInfoSerialized | "noInput"`. The value-level counterpart, `ComponentOrNoInput`, is described in [Shared Types](/docs/interfaces/base/types).
 
@@ -232,7 +234,7 @@ function serializeType(instance?: DataType): DataTypeSerialized | undefined;
 | `NotContains` | `not_contains` | value |
 | `ArrayContainsString` | `array_contains_string` | value |
 
-`IsEmpty` and `IsNotEmpty` are the two registered with `noInput`. The namespace also exports `escapeRegex(str: string): string`, the helper the substring modes use to make a viewer-supplied value safe inside a pattern.
+`IsEmpty` and `IsNotEmpty` are the two registered with `noInput`. `Include`, `Exclude` and `ArrayContainsString` read a `null` or missing list as an empty one, so a row saved without a value never fails the query: it is left out by `include` and `array_contains_string`, and kept by `exclude`. The namespace also exports `escapeRegex(str: string): string`, the helper the substring modes use to make a viewer-supplied value safe inside a pattern.
 
 ## The Default Types
 
@@ -264,12 +266,13 @@ function serializeType(instance?: DataType): DataTypeSerialized | undefined;
 
 | Options interface | Fields |
 | --- | --- |
-| `StringTypeOptions` | `placeholder?`, `maxLength?`, `minLength?`, `showCount?`, `textarea?`, `rows?`, `fallback?` |
-| `NumberTypeOptions` | `min?`, `max?`, `step?`, `placeholder?`, `suffix?`, `fallback?` |
+| `StringTypeOptions` | `placeholder?`, `maxLength?`, `minLength?`, `showCount?`, `textarea?`, `rows?`, `width?`, `fallback?` |
+| `NumberTypeOptions` | `min?`, `max?`, `step?`, `placeholder?`, `suffix?`, `width?`, `fallback?` |
 | `DateTypeOptions` | `range?`, `multiple?`, `minDate?`, `maxDate?`, `fallback?` |
 | `BooleanTypeOptions` | `fallback?` |
 | `SelectTypeOptions` | `items: FormComponents.SelectOption[]`, `placeholder?`, `multiple?`, `deselectable?`, `display?`, `columns?` (cards per row of the `cards` display, 2 by default), `fallback?` |
-| `EmailTypeOptions`, `ColorTypeOptions`, `UrlTypeOptions`, `RichTextTypeOptions` | `placeholder?`, `fallback?` |
+| `EmailTypeOptions`, `ColorTypeOptions`, `RichTextTypeOptions` | `placeholder?`, `fallback?` |
+| `UrlTypeOptions` | `placeholder?`, `preview?` (`"avatar"` \| `"image"`: shown read-only, the URL is drawn as the image it points to; the form still edits it as text), `fallback?` |
 | `PasswordTypeOptions` | `placeholder?`, `minLength?`, `confirmPassword?`, `confirmPlaceholder?`, `fallback?` |
 | `PhoneTypeOptions` | `placeholder?`, `requiredPrefix?`, `fallback?` |
 | `StringTimeTypeOptions` | `placeholder?`, `min?`, `max?`, `fallback?` |
@@ -279,6 +282,7 @@ Notes on the ones whose behaviour is not obvious from the options:
 - `StringType` renders a textarea instead of a single-line input when `textarea` is set, and passes `rows` to it.
 - `StringType` with `showCount` shows the characters typed, out of `maxLength` when set ("4 / 60"), in its input or under its textarea.
 - `NumberType` hands `suffix` (an i18n key with `$`, or a literal) to its input, which writes it after the field; the value stays a number. `PriceType` inherits it; `PercentageType` keeps its own `%`.
+- `NumberType` (and the types extending it) and a single-line `StringType` hand `width` (`FormComponents.InputWidth`) to their input: `"compact"` sizes it for a short value from `sm` up, `"full"` fills the row, and left out the input is compact when `min` / `max` fit in 6 digits or `maxLength` is 16 or less.
 - `DateType` overrides `filter` so `is`, `is_not` and `is_between` compare whole UTC days rather than instants, and adds a range picker as the filter component for `is_between`. Its schema accepts a `Date` or an ISO-shaped string and transforms it to a `Date`; with `multiple` the value becomes an array, and with `range` it becomes `{ start, end }`, `end` on or after `start` (a pair `[start, end]` is still read and validates to the same object).
 - `BooleanType` uses a two-option select as its filter component, so a viewer picks "checked"/"unchecked" rather than typing a value.
 - `SelectType` validates against the `value`s of its `items`, as an enum or an array of that enum when `multiple` is set.
@@ -315,13 +319,16 @@ declare customerId: string;
 | `placeholder` | `string` | Picker placeholder. |
 | `multiple` | `boolean` | Allow more than one related row. |
 | `deselectable` | `boolean` | Allow clearing the selection. |
-| `filterOnly` | `boolean` | Skip the join entirely: the raw scalar id stays in the list output and the funnel filter runs equality on it. |
+| `filterOnly` | `boolean` | Skip the join entirely: the raw scalar id stays in the list output and the funnel filter runs equality on it. A table cell, a card or a kanban card of that column then shows the id: lists draw the joined row only, they never read the ids by `?ids=`. |
 | `addForm` | `{ displayName?: string; description?: string }` | Title and description of the drawer the picker's "add" entry opens ("New customer"). `$`-prefixed: i18n keys. Default to "New entry". |
+| `filterBy` | `{ field, from }` | List only the target rows whose `field` equals the form's current value of the field `from`, e.g. `{ field: "customerId", from: "customerId" }` for a site among its customer's sites. `field` must be filterable on the target (`filterable: true` or `@Filter`); `decorateField` throws otherwise. |
 | `fallback` | `string` | Text used in place of an empty value. |
 
-When the target controller exposes a `new` endpoint and has form fields, the picker also carries an inline "add" form built from the target's `new` fields, plus the permission id of the target's `add` action.
+With `filterBy`, the picker sends the table filter syntax to the `select` endpoint (`filter_<field>=is:<value>`), which honors only the filters the target controller declares. It searches again when `from` changes and clears a pick made for its previous value; the pair a record loaded with is kept, and while `from` is empty every row is offered. It narrows what is offered only: a rule that must hold on save belongs to the module's routes.
 
-`CascaderRelationType<T>` is the same idea for a self-referencing table: the target's `select` endpoint returns a flat list, and the widget rebuilds the tree client-side. Its `keyMapping` is required and adds `parent` — the field pointing at the parent row, which must itself carry `@Select()` — alongside the required `label` and `value`. It adds `maxDepth` and `leafOnly` to the relation options, and supports the same `filterOnly` behaviour. In a table cell it shows the path of the picked node ("Electronics / Audio"); a `multiple` one shows a badge per picked node, named by its own label with its path on hover, and folds those past three into `+N`.
+When the target controller exposes a `new` endpoint and has form fields, the picker of an editable form field also carries an inline "add" form built from the target's `new` fields, plus the permission id of the target's `add` action. That form is the bulk of the component — the target's fields, its validation schema, its own relations' add forms — so a table column's type, its filter and a read-only field leave it out: they read the related rows through the `select` route, and a filter only picks among them.
+
+`CascaderRelationType<T>` is the same idea for a self-referencing table: the target's `select` endpoint returns a flat list, and the widget rebuilds the tree client-side. Its cell and its field name the picked row by its path, read by `?ids=` for the picked rows and then each level of their ancestors. Its `keyMapping` is required and adds `parent` — the field pointing at the parent row, which must itself carry `@Select()` — alongside the required `label` and `value`. It adds `maxDepth` and `leafOnly` to the relation options, and supports the same `filterOnly` behaviour. In a table cell it shows the path of the picked node ("Electronics / Audio"); a `multiple` one shows a badge per picked node, named by its own label with its path on hover, and folds those past three into `+N`.
 
 ### Address
 
@@ -338,7 +345,7 @@ When the target controller exposes a `new` endpoint and has form fields, the pic
 | `addressLine2` | no | Supplementary delivery information. |
 | `countrySubdivision` | no | Region, state or province. |
 
-The type's options are `placeholder` (one string per address component), `autocomplete`, an optional `dataApiController` with a `keyMapping` of `label` / `value` for picking an existing address, and `fallback`. `AddressAutocomplete` configures the geocoder:
+The type's options are `placeholder` (one string per address component), `autocomplete`, `defaultCountry` (the ISO 3166-1 alpha-2 country shown while the address has none and whose places the street suggestions list first, written with the first part typed: an address left empty stays empty), an optional `dataApiController` with a `keyMapping` of `label` / `value` for picking an existing address, and `fallback`. `AddressAutocomplete` configures the geocoder:
 
 | Option | Type | Description |
 | --- | --- | --- |

package/docs/4.notifications/3.sending.md

@@ -33,7 +33,7 @@ A `SendableNotification` is immutable and holds no recipient, so you can build o
 | `toUser` | `(userId: string, options?: SendOptions) => Promise<void>` | Send to one user. |
 | `toUsers` | `(userIds: string[], options?: SendOptions) => Promise<void>` | Send to a list of users. |
 | `toUsersIdempotently` | `(userIds: string[], idempotencyKey: string, options?: SendOptions) => Promise<void>` | Send a durable event once per recipient, including after dismissal. |
-| `toRoles` | `(roleIds: string[], options?: SendOptions) => Promise<void>` | Send to every user holding at least one of the roles. |
+| `toRoles` | `(roleIds: string[], options?: RoleSendOptions) => Promise<void>` | Send to every user holding at least one of the roles, in `options.tenantId` when set. |
 | `broadcast` | `(options?: SendOptions) => Promise<void>` | Send to every user. |
 
 ## Building a Notification
@@ -146,10 +146,10 @@ await shipped.toUsers([ownerId, managerId], { readScope: "shared" });
 `toRoles(roleIds, options?)` resolves the users that hold any of the given roles and sends to them. An empty `roleIds` array sends nothing, and so does a set of roles nobody holds.
 
 ```typescript
-await shipped.toRoles([adminRoleId], { readScope: "shared" });
+await shipped.toRoles([adminRoleId], { readScope: "shared", tenantId });
 ```
 
-Role ids are the DMS role identifiers described in the DMS tenancy and permissions guide; membership is resolved across tenants, so a user holding the role in any tenant is included.
+Role ids are the DMS role identifiers described in the DMS tenancy and permissions guide, and they belong to a tenant. `tenantId` (`RoleSendOptions`) restricts the recipients to that tenant's members; without it, membership is resolved across tenants, so a user holding the role in any tenant is included.
 
 ## Broadcasting
 
@@ -168,6 +168,7 @@ Every dispatch method accepts an optional `SendOptions` object.
 | `readScope` | `ReadScope` (optional) | Read-state grouping for a multi-recipient send. Defaults to `"individual"` — see [Read Scope](/docs/interfaces/notifications/categories-and-subjects#read-scope). |
 | `idempotencyKey` | `string` (optional) | Stable event key, unique across producers: prefix it with your module ID. Reusing it for a recipient preserves the original notification and dismissal state. |
 | `dedupe` | `boolean` (optional) | `false` stores every unkeyed send, even one identical to a notification the recipient got less than 10 seconds earlier. Defaults to `true`; see below. |
+| `tenantId` | `string` (optional, `toRoles` only: `RoleSendOptions`) | Only the members of this tenant holding the roles; every tenant when unset. |
 
 Pick `"shared"` for alerts that only need one person to act on them, and `"individual"` for anything each recipient has to see for themselves.
 

package/docs/5.html-render/1.introduction.md

@@ -255,7 +255,7 @@ Types the `htmlRender` block of the DMS module configuration in `antelope.config
 | Option | Type | Description |
 | ------ | ---- | ----------- |
 | `renderEndpoint` | `string` | Absolute URL `GenerateHtml` posts to. Default `http://localhost:3001/api/html/render`. |
-| `serviceSecret` | `string` | Secret used to sign the service token that authenticates the render call. Default `"dev"` — set a strong value in production. |
+| `serviceSecret` | `string` | Secret used to sign the service token that authenticates the render call. Default `"dev"`, which the DMS refuses in production. |
 | `serviceTokenLifetime` | `number` | Lifetime of that service token, in milliseconds. The frontend render server rejects a token valid for more than five minutes. Default `300000` (5 minutes). |
 
 The DMS merges the block you supply over those defaults, so a configuration only needs the keys it changes:
@@ -263,13 +263,12 @@ The DMS merges the block you supply over those defaults, so a configuration only
 ```typescript
 import { defineConfig } from "@antelopejs/interface-core/config";
 
-const renderSecret = process.env.DMS_HTML_RENDER_SECRET;
-if (!renderSecret) {
-  throw new Error("DMS_HTML_RENDER_SECRET is not set");
-}
-
 export default defineConfig({
   name: "acme-admin",
+  // Read at start; a production start without it is refused by the DMS.
+  envOverrides: {
+    DMS_HTML_RENDER_SECRET: "modules.dms.config.htmlRender.serviceSecret",
+  },
   modules: {
     dms: {
       source: {
@@ -280,7 +279,6 @@ export default defineConfig({
       config: {
         htmlRender: {
           renderEndpoint: "https://admin.example.com/api/html/render",
-          serviceSecret: renderSecret,
         },
       },
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/interface-dms",
-  "version": "0.7.4",
+  "version": "0.9.0",
   "description": "Public AntelopeJS interfaces of the DMS: pages, components, permissions, tenancy, auth, notifications and HTML rendering.",
   "keywords": [
     "antelopejs",
@@ -45,7 +45,6 @@
     "knip:all": "knip"
   },
   "dependencies": {
-    "jsonwebtoken": "^9.0.3",
     "randomstring": "^1.3.1",
     "zod": "~3.24.2",
     "zod-to-json-schema": "~3.24.6"
@@ -53,23 +52,20 @@
   "peerDependencies": {
     "@antelopejs/interface-api": ">=0.0.15 <1.0.0",
     "@antelopejs/interface-api-util": ">=0.1.3 <1.0.0",
-    "@antelopejs/interface-auth": ">=0.0.7 <1.0.0",
     "@antelopejs/interface-core": ">=0.2.4 <1.0.0",
-    "@antelopejs/interface-data-api": ">=0.2.2 <1.0.0",
-    "@antelopejs/interface-database": ">=0.1.10 <1.0.0",
-    "@antelopejs/interface-database-decorators": ">=0.1.9 <1.0.0",
+    "@antelopejs/interface-data-api": ">=0.4.0 <1.0.0",
+    "@antelopejs/interface-database": ">=0.1.11 <1.0.0",
+    "@antelopejs/interface-database-decorators": ">=0.1.10 <1.0.0",
     "@antelopejs/interface-file-storage": ">=0.1.4 <1.0.0"
   },
   "devDependencies": {
     "@antelopejs/interface-api": ">=0.0.15 <1.0.0",
     "@antelopejs/interface-api-util": ">=0.1.3 <1.0.0",
-    "@antelopejs/interface-auth": ">=0.0.7 <1.0.0",
     "@antelopejs/interface-core": ">=0.2.4 <1.0.0",
-    "@antelopejs/interface-data-api": ">=0.2.2 <1.0.0",
-    "@antelopejs/interface-database": ">=0.1.10 <1.0.0",
-    "@antelopejs/interface-database-decorators": ">=0.1.9 <1.0.0",
+    "@antelopejs/interface-data-api": ">=0.4.0 <1.0.0",
+    "@antelopejs/interface-database": ">=0.1.11 <1.0.0",
+    "@antelopejs/interface-database-decorators": ">=0.1.10 <1.0.0",
     "@antelopejs/interface-file-storage": ">=0.1.4 <1.0.0",
-    "@types/jsonwebtoken": "^9.0.10",
     "@types/node": "^24.0.0",
     "@types/randomstring": "^1.3.0",
     "knip": "^6.34.0",