@antelopejs/interface-dms 0.10.4 → 0.13.0

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

@@ -1,10 +1,9 @@
 ---
-title: "Data Types"
+title: "Data types"
 description: "A data type is the single object that answers everything the DMS needs to know about one value: which input component edits it, which Zod schema validates it, which comparison modes its filter offers, and whether the…"
+mode: reference
 ---
 
-# Data Types
-
 ## Overview
 
 A data type is the single object that answers everything the DMS needs to know about one value: which input component edits it, which Zod schema validates it, which comparison modes its filter offers, and whether the field it sits on needs extra decorators. `FormField.type` and `ColumnOptions.type` both take one, which is why a form field and a table column of the same type behave identically.
@@ -20,11 +19,11 @@ import {
 } from "@antelopejs/interface-dms/base/data-types";
 ```
 
-The `data-types` subpath re-exports the built-in catalogues, so `DefaultDataTypes`, `DefaultDataCompareTypes` and `StatusType` are all reachable from it. They also have their own modules — `data-types/default-types`, `data-types/compare-types` and `data-types/status-type` — which is how much of the DMS imports them.
+The `data-types` subpath re-exports the built-in catalogues, so `DefaultDataTypes`, `DefaultDataCompareTypes` and `StatusType` are all reachable from it. They also have their own modules, `data-types/default-types`, `data-types/compare-types` and `data-types/status-type`, and much of the DMS imports them from there.
 
-Note that the data types are **not** re-exported from the `base` barrel — always import them from the `data-types` subpath.
+The `base` barrel does **not** re-export the data types. Import them from the `data-types` subpath.
 
-## Use a Data Type
+## Use a data type
 
 Instantiate the type with its options and hand the instance to the field or the column.
 
@@ -57,9 +56,9 @@ const form = Form({
 
 An instance is reusable: the same object can back a form field and a table column, since it holds only its configuration.
 
-## The DataType Contract
+## The `DataType` contract
 
-```typescript
+```typescript fragment
 abstract class DataType {
   constructor(
     readonly compareModes: Class<DataCompareMode>[] = [],
@@ -89,9 +88,9 @@ abstract class DataType {
 | `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. |
+| `decorateField()` | Optional. Called by the `@Column` decorator so the type can add further decorators to the field. The relation types install their join this way. |
 
-### Write a Custom Type
+### Write a custom type
 
 `StatusType` is the smallest complete example: a boolean rendered as an online/offline indicator whose labels and colours are configurable.
 
@@ -122,13 +121,13 @@ export class StatusType extends DataType {
     super(
       [DefaultDataCompareTypes.Is, DefaultDataCompareTypes.IsNot],
       DefaultDataCompareTypes.Is,
-      options as Record<string, unknown>,
+      options,
     );
   }
 
   protected defaultInputComponent() {
     const component = FormComponents.InputCheckbox();
-    component.options = this.options;
+    component.options = { label: this.options.onlineLabel };
     return component;
   }
 
@@ -138,32 +137,32 @@ export class StatusType extends DataType {
 }
 ```
 
-Three pieces make it a type: the `@RegisterDataType("status")` decorator puts it in the registry under an id, the `super()` call declares the compare modes and stores the options, and the two abstract members supply the input and the schema. `StatusType` itself is exported by the `data-types` subpath and is one of the three column types a kanban board can group by — see [Tables](/docs/interfaces/base/tables).
+Three pieces make it a type: the `@RegisterDataType("status")` decorator puts it in the registry under an id, the `super()` call declares the compare modes and stores the options, and the two abstract members supply the input and the schema. `StatusType` itself is exported by the `data-types` subpath and is one of the three column types a kanban board can group by. See [Tables](/docs/interfaces/base/tables).
 
-## The Registry
+## The registry
 
-### RegisterDataType
+### `RegisterDataType`
 
-```typescript
+```typescript fragment
 const RegisterDataType: (id: string) => ClassDecorator<Class<DataType>>;
 ```
 
-Registers the decorated class under `id`, in both directions: `CreateDataType` looks up the class by id, and `getDataTypeId` recovers the id from an instance. An id must be unique — registering twice under the same string replaces the earlier class.
+Registers the decorated class under `id`, in both directions: `CreateDataType` looks up the class by id, and `getDataTypeId` recovers the id from an instance. An id must be unique. Registering twice under the same string replaces the earlier class.
 
-### RegisterDataCompareMode
+### `RegisterDataCompareMode`
 
-```typescript
+```typescript fragment
 const RegisterDataCompareMode: (
   id: string,
   noInput?: boolean,
 ) => ClassDecorator<Class<DataCompareMode>>;
 ```
 
-Registers a compare mode. The decorator instantiates the class immediately and keeps that single instance, so a compare mode is stateless. `noInput` marks a mode that needs no value from the viewer — `serializeType` replaces its filter component with the literal `"noInput"`.
+Registers a compare mode. The decorator instantiates the class immediately and keeps that single instance, so a compare mode is stateless. `noInput` marks a mode that needs no value from the viewer. `serializeType` replaces its filter component with the literal `"noInput"`.
 
 `DataCompareMode` is the interface a mode implements:
 
-```typescript
+```typescript fragment
 interface DataCompareMode {
   filter(
     context: RequestContext,
@@ -177,17 +176,17 @@ interface DataCompareMode {
 
 `proxy` is the database value proxy for the field being filtered and `row` the proxy for the whole row, both from `@antelopejs/interface-database`, so a mode builds a database-side predicate rather than filtering in memory.
 
-### CreateDataType
+### `CreateDataType`
 
-```typescript
+```typescript fragment
 function CreateDataType(id: string, options?: unknown): DataType;
 ```
 
-Instantiates a registered type by id, forwarding `options` to its constructor. It asserts on an unknown id with the message `Unknown type <id>`. Use it when the type is chosen at runtime — from configuration, or from a description produced by another module — rather than written in the source.
+Instantiates a registered type by id, forwarding `options` to its constructor. It asserts on an unknown id with the message `Unknown type <id>`. Use it when the type is chosen at runtime, from configuration or from a description another module produced, rather than written in the source.
 
-### getDataTypeId
+### `getDataTypeId`
 
-```typescript
+```typescript fragment
 function getDataTypeId(instance: DataType): string | undefined;
 ```
 
@@ -195,7 +194,7 @@ Returns the id an instance's class was registered under, or `undefined` when the
 
 ## Serialization
 
-```typescript
+```typescript fragment
 function serializeType(instance?: DataType): DataTypeSerialized | undefined;
 ```
 
@@ -211,9 +210,9 @@ function serializeType(instance?: DataType): DataTypeSerialized | undefined;
 | `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 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).
+`FilterComponent` is `ComponentInfoSerialized | "noInput"`. The value-level counterpart, `ComponentOrNoInput`, is described in [Shared types](/docs/interfaces/base/types).
 
-## Compare Modes
+## Compare modes
 
 `DefaultDataCompareTypes` holds the built-in modes. Each entry is a class; you reference the class in a type's `compareModes`, and the string id is what appears in a serialized type and in a filter query.
 
@@ -238,7 +237,7 @@ The ordering modes and `is_between` send a date value to the value proxy as epoc
 
 `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
+## The default types
 
 `DefaultDataTypes` is the built-in catalogue. Every class takes its options object as its only constructor argument, and most of them accept a `fallback` string used in place of an empty value.
 
@@ -264,7 +263,7 @@ The ordering modes and `is_between` send a date value to the value proxy as epoc
 | `FileType` | `file` | none | file upload |
 | `ImageType` | `image` | none | image upload |
 
-### Scalar Types
+### Scalar types
 
 | Options interface | Fields |
 | --- | --- |
@@ -293,13 +292,13 @@ Notes on the ones whose behaviour is not obvious from the options:
 - `PercentageType` is a `NumberType` whose options default to `min: 0`, `max: 1` and `step: 0.01`; the stored value is a fraction while the input works in whole percent.
 - `PhoneType` only validates the E.164 pattern when `requiredPrefix` is set; otherwise any string passes.
 - `ColorType` validates a six-digit `#RRGGBB` string.
-- `StringTimeType` validates a **number** — a time of day expressed as a number, bounded by `min` and `max`.
+- `StringTimeType` validates a **number**: a time of day expressed as a number, bounded by `min` and `max`.
 
 ### Relations
 
-`RelationType<T>` points a field at another data controller. Its input is a searchable picker whose `searchUrl` is the target controller's `select` endpoint, and — unless `filterOnly` is set — its `decorateField` installs a data-api `Foreign` join so list rows carry the resolved related row instead of the raw foreign key.
+`RelationType<T>` points a field at another data controller. Its input is a searchable picker whose `searchUrl` is the target controller's `select` endpoint. Unless `filterOnly` is set, its `decorateField` installs a data-api `Foreign` join so list rows carry the resolved related row instead of the raw foreign key.
 
-```typescript
+```typescript fragment
 import { DefaultDataTypes } from "@antelopejs/interface-dms/base/data-types";
 import { Column } from "@antelopejs/interface-dms/base/table-view";
 
@@ -329,9 +328,9 @@ declare customerId: string;
 
 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.
 
-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.
+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 (the target's fields, its validation schema, its own relations' add forms) is the bulk of the component, 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`.
+`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
 
@@ -358,14 +357,14 @@ The type's options are `placeholder` (one string per address component), `autoco
 | `limit` | `number` | Maximum number of suggestions. Defaults to `5`. |
 | `placeholder` | `string` | Search field placeholder. |
 
-### Files and Images
+### Files and images
 
 `FileTypeOptions` has `multiple?`, `constraints?: UploadConstraints`, `path?`, `storage?` and `fallback?`. `ImageTypeOptions` has `multiple?`, `max?`, `constraints?`, `path?`, `storage?` and `resize?`, the `FormComponents.ImageResizeOptions` the input applies client-side before uploading ([Forms](/docs/interfaces/base/forms)). Both accept `attachmentField?` for a stable native field identity and `visibility?: "private" | "public"`, defaulting to private. `constraints` is the `UploadConstraints` type from `@antelopejs/interface-file-storage`; `storage` names the storage backend and `path` the prefix uploads land under.
 
-A file value is the resource key as a string. Metadata-based validation checks configured constraints, matching `allowedMimetypes` patterns including the `type/*` form. A native field's save integration also validates upload provenance and canonical metadata before persistence. Existing unclassified legacy values may be retained, but cannot be introduced as new native attachments or read through the native metadata endpoint. A storage outage propagates as a server error rather than becoming a field validation error. An image value is an `ImageValue` — `{ key: string; alt?: string; principal?: boolean }` — and `ImageType` defaults `allowedMimetypes` to `["image/*"]`, caps the array at `max` when `multiple` is set, and rejects a list with more than one `principal` image.
+A file value is the resource key as a string. Metadata-based validation checks configured constraints, matching `allowedMimetypes` patterns including the `type/*` form. A native field's save integration also validates upload provenance and canonical metadata before persistence. Existing unclassified legacy values may be retained, but cannot be introduced as new native attachments or read through the native metadata endpoint. A storage outage propagates as a server error rather than becoming a field validation error. An image value is an `ImageValue`, `{ key: string; alt?: string; principal?: boolean }`, and `ImageType` defaults `allowedMimetypes` to `["image/*"]`, caps the array at `max` when `multiple` is set, and rejects a list with more than one `principal` image.
 
 Both types enable the table view's native file handling: authorized saves promote staging keys, and successful edits or deletes clean removed native references. Failed saves retain promoted objects; cleanup is not reference-counted across records. See [File storage](/docs/components/file-storage) for authorization, visibility, retries, and custom save routes, and [Helpers](/docs/interfaces/base/helpers) for comparing references within records.
 
-## Next Steps
+## Next steps
 
-- [Helpers](/docs/interfaces/base/helpers) - Search, export jobs, file references and the archive-mode defaults.
+- [Helpers](/docs/interfaces/base/helpers): Search, export jobs, file references and the archive-mode defaults.

package/docs/3.base/9.helpers.md

@@ -1,13 +1,12 @@
 ---
 title: "Helpers"
 description: "A few small surfaces sit beside the components and support them: the `@Searchable` decorator that tells a list route which columns free-text search covers, the export-job runner behind every long download, the…"
+mode: reference
 ---
 
-# Helpers
-
 ## Overview
 
-A few small surfaces sit beside the components and support them: the `@Searchable` decorator that tells a list route which columns free-text search covers, the export-job runner behind every long download, the tenant-export archive built on top of it, and two helper modules — file references and archive-mode defaults — that the table view uses internally and that are available when you build equivalent routes yourself.
+A few small surfaces sit beside the components and support them: the `@Searchable` decorator that tells a list route which columns free-text search covers, the export-job runner behind every long download, the tenant-export archive built on top of it, and two helper modules, file references and archive-mode defaults, that the table view uses internally and that are available when you build equivalent routes yourself.
 
 ```typescript
 import { Searchable, SearchableMeta } from "@antelopejs/interface-dms/base/searchable";
@@ -19,11 +18,11 @@ import { startTenantExportJob } from "@antelopejs/interface-dms/base/tenant-expo
 
 `Searchable`, `SearchableMeta` and everything in `export-jobs` and `tenant-export-archive` are also exported from the package root, `@antelopejs/interface-dms/base`. The two `helpers/*` modules are not in that barrel and are imported from their own subpath.
 
-## Make Columns Searchable
+## Make columns searchable
 
 `@Searchable(compareMode?)` is a property decorator on a data controller field. It records the field, and the compare mode used to match it, on the controller's `SearchableMeta`. The list route reads that record when the request carries a `search` query parameter and ORs one condition per recorded field into the query. A field does not have to be `filterable` to be searched: it is matched with its data-api filter when it has one, and otherwise with the filter of its `@Column` type. A controller with no searchable field ignores the parameter.
 
-```typescript
+```typescript fragment
 import { Listable } from "@antelopejs/interface-data-api/metadata";
 import { DefaultDataTypes } from "@antelopejs/interface-dms/base/data-types";
 import { Searchable } from "@antelopejs/interface-dms/base/searchable";
@@ -50,9 +49,9 @@ export class customerDataAPI extends DataController(/* … */) {
 | --- | --- |
 | `compareMode` | Id of a registered `DataCompareMode` used to match this field. Defaults to `"contains"`. |
 
-The id is the one the mode was registered under with `@RegisterDataCompareMode` — `"contains"`, `"is"`, `"array_contains_string"` and the rest of the catalogue are listed in [Data Types](/docs/interfaces/base/data-types).
+The id is the one the mode was registered under with `@RegisterDataCompareMode`. `"contains"`, `"is"`, `"array_contains_string"` and the rest of the catalog are listed in [Data types](/docs/interfaces/base/data-types).
 
-### SearchableMeta
+### `SearchableMeta`
 
 `SearchableMeta` is the metadata object the decorator writes to. Read it with `GetMetadata(controller, SearchableMeta)` from `@antelopejs/interface-core`.
 
@@ -62,7 +61,7 @@ The id is the one the mode was registered under with `@RegisterDataCompareMode`
 | `setSearchableField(key, compareMode)` | Records one field. Called by the decorator. |
 | `getSearchableFields()` | Returns the same record. |
 
-## Run an Export Job
+## Run an export job
 
 `runExportJob` starts a background job, hands you a ticket immediately, and leaves the generation running. The pattern is three routes: one that starts the job, one that reports its progress, one that streams the finished file. The table view's export action is built on exactly these three, and any route of your own can reuse them.
 
@@ -133,9 +132,9 @@ export class ReportPage extends PageController("report", {
 }
 ```
 
-### RunExportJobOptions
+### `RunExportJobOptions`
 
-```typescript
+```typescript fragment
 function runExportJob<TContext = unknown>(
   opts: RunExportJobOptions<TContext>,
 ): Promise<ExportJobTicket>;
@@ -172,7 +171,7 @@ interface ExportJobFailure {
 }
 ```
 
-The summary is stored on the job and surfaced on its status, so a consumer can tell a complete export from one that succeeded with holes. `source` names the part that failed — a contributing module id, typically.
+The summary is stored on the job and surfaced on its status, so a consumer can tell a complete export from one that succeeded with holes. `source` names the part that failed, usually a contributing module id.
 
 By default a job is deleted once it has been downloaded. Set `retainUntilExpiry` for a scope whose jobs outlive their first download: one that surfaces a job history, or one whose result is reached through a delivered link.
 
@@ -182,7 +181,7 @@ By default a job is deleted once it has been downloaded. Set `retainUntilExpiry`
 | `extension` | `string` | Echo of the requested extension. |
 | `filename` | `string` | Echo of the requested base name. |
 
-### ExportJobGenerateContext
+### `ExportJobGenerateContext`
 
 | Field | Type | Description |
 | --- | --- | --- |
@@ -190,12 +189,12 @@ By default a job is deleted once it has been downloaded. Set `retainUntilExpiry`
 | `tenantId` | `string` | Tenant the job belongs to. |
 | `localPath` | `string` | Path your generator writes the file to. |
 | `context` | `TContext` | The payload passed as `context` to `runExportJob`. |
-| `reportProgress` | `(progress: number) => Promise<void>` | Records progress. The value is floored and clamped to `0`–`99`; repeating the last value writes nothing. Throws once the job is aborted. |
+| `reportProgress` | `(progress: number) => Promise<void>` | Records progress. The value is floored and clamped to `0` through `99`; repeating the last value writes nothing. Throws once the job is aborted. |
 | `signal` | `AbortSignal` | Aborted when the job exceeds `maxExecutionTimeMs`. |
 
-### Status and Download
+### Status and download
 
-```typescript
+```typescript fragment
 function getExportJobStatus<TContext = unknown>(
   ctx: RequestContext,
   user: User,
@@ -211,19 +210,19 @@ function downloadExportJob<TContext = unknown>(
 ): Promise<void>;
 ```
 
-`ExportJobStatus` carries `status: ExportStatus`, `progress: number`, and the optional `error`, `filename`, `extension`, `result` and `expiresAt`. `ExportStatus` is the `pending` / `completed` / `failed` enum from [Shared Types](/docs/interfaces/base/types). `result` is the `ExportJobResultSummary` the generator returned, present once the job completed; `expiresAt` is when the sweep will drop the record and its stored file.
+`ExportJobStatus` carries `status: ExportStatus`, `progress: number`, and the optional `error`, `filename`, `extension`, `result` and `expiresAt`. `ExportStatus` is the `pending` / `completed` / `failed` enum from [Shared types](/docs/interfaces/base/types). `result` is the `ExportJobResultSummary` the generator returned, present once the job completed; `expiresAt` is when the sweep will drop the record and its stored file.
 
-`getExportJobExpiry(record)` computes that moment from a record directly — `updatedAt` plus `EXPORT_TTL_MS`, which is one day.
+`getExportJobExpiry(record)` computes that moment from a record directly: `updatedAt` plus `EXPORT_TTL_MS`, which is one day.
 
-`downloadExportJob` requires a completed job with a stored result — anything else fails with `400` or `500`. It sets `Content-Disposition` (with a filename built by `buildExportFilename`), `Content-Length` when the size is known, and `Access-Control-Expose-Headers`, then pipes the stored object to the response. The function returns as soon as the pipe is set up rather than awaiting it; once the response stream closes, the stored object and the job record are both deleted.
+`downloadExportJob` requires a completed job with a stored result. Anything else fails with `400` or `500`. It sets `Content-Disposition` (with a filename built by `buildExportFilename`), `Content-Length` when the size is known, and `Access-Control-Expose-Headers`, then pipes the stored object to the response. The function returns as soon as the pipe is set up rather than awaiting it; once the response stream closes, the stored object and the job record are both deleted.
 
 `loadExportJobForUser(ctx, user, jobId, access?)` is the shared step underneath both: it resolves the tenant, loads the record, runs the access checks, and returns the model, the record and the parsed context. Use it when you need the record itself rather than its status.
 
-`downloadExportJob` deletes the stored object and the job record once the response stream closes — unless the job was started with `retainUntilExpiry`, in which case both survive until the sweep.
+`downloadExportJob` deletes the stored object and the job record once the response stream closes, unless the job was started with `retainUntilExpiry`, in which case both survive until the sweep.
 
-### List a Caller's Jobs
+### List a caller's jobs
 
-```typescript
+```typescript fragment
 function listExportJobs(
   ctx: RequestContext,
   user: User,
@@ -231,11 +230,11 @@ function listExportJobs(
 ): Promise<ExportJobSummary[]>;
 ```
 
-Returns the caller's own jobs, most recent first — the history a scope such as a tenant data export surfaces next to its request action. `ListExportJobsOptions` narrows it: `scope` restricts to one scope, `limit` caps the count and defaults to 20.
+Returns the caller's own jobs, most recent first: the history a scope such as a tenant data export surfaces next to its request action. `ListExportJobsOptions` narrows it: `scope` restricts to one scope, `limit` caps the count and defaults to 20.
 
 `ExportJobSummary` extends `ExportJobStatus` with `jobId`, `scope` and `createdAt`. Listing is scoped to the caller, so it needs no access options: another user's jobs are never returned.
 
-### Access Checks
+### Access checks
 
 | Option | Type | Description |
 | --- | --- | --- |
@@ -244,19 +243,18 @@ Returns the caller's own jobs, most recent first — the history a scope such as
 
 `ExportJobOwnership<TContext>` carries only `isOwnedBy`; `ExportJobAccessOptions<TContext>` extends it with `scope`. The job's `userId` is always compared against the caller regardless of what you pass, and every failed check answers `403`.
 
-### Formats and Delivery
+### Formats and delivery
 
 An export format is an `Exporter`, and a delivery mode is a `Deliverer`. Both are looked up by id.
 
 ```typescript
 import {
-  DEFAULT_DELIVERY,
   DEFAULT_EXPORT_FORMAT,
-  getDeliverer,
   getExporter,
 } from "@antelopejs/interface-dms/base/export-jobs";
 
-const exporter = getExporter(DEFAULT_EXPORT_FORMAT); // "csv"
+const localPath = "/tmp/export.csv";
+const exporter = await getExporter(DEFAULT_EXPORT_FORMAT); // "csv"
 const writer = exporter.createWriter(localPath);
 writer.writeHeaders(["id", "name"]);
 writer.appendRow(["id", "name"], { id: "1", name: "Ada" });
@@ -269,8 +267,8 @@ writer.close();
 | `ExportWriter` | `{ writeHeaders(headers), appendRow(headers, row), close() }` | Incremental writer for one file. |
 | `Deliverer` | `{ validate?(options: ExportJobDeliveryOptions): void; deliver(exportRecord, resultPath): Promise<void> }` | One delivery mode. `validate` runs when the job is created, so an unusable delivery fails fast rather than after generation. |
 | `ExportJobDeliveryOptions` | `{ delivery: string; deliveryPath?: string }` | What `validate` is given. |
-| `getExporter(format)` | `Exporter` | Throws `400` for an unknown format. |
-| `getDeliverer(delivery)` | `Deliverer` | Throws `400` for an unknown delivery mode. |
+| `getExporter(format)` | `Promise<Exporter>` | Resolves to the format's exporter. Rejects with `400` for an unknown format. |
+| `getDeliverer(delivery)` | `Promise<Deliverer>` | Resolves to the delivery mode's deliverer. Rejects with `400` for an unknown delivery mode. |
 | `DEFAULT_EXPORT_FORMAT` | `"csv"` | The format `csv` writes a BOM-prefixed comma-separated file; array values are joined with `;` and dates written as ISO strings. |
 | `DEFAULT_DELIVERY` | `"download"` | Keeps the result in storage for the download route. |
 | `EMAIL_DELIVERY` | `"email"` | Mails the recipient a link instead. Requires `deliveryPath`: the link is that path with `?exportJob=<jobId>` appended. |
@@ -279,7 +277,7 @@ writer.close();
 
 `buildExportFilename(base, extension)` produces the name sent to the browser: the base and an ISO timestamp, both stripped of anything outside `[a-zA-Z0-9._-]`, joined by `-` and suffixed with the extension.
 
-### Storage and Maintenance
+### Storage and maintenance
 
 | Function | Signature | Description |
 | --- | --- | --- |
@@ -290,7 +288,7 @@ writer.close();
 | `sweepStaleExportsAllTenants` | `(ttlMs) => Promise<void>` | Deletes every job whose `updatedAt` is older than `ttlMs`, in every tenant, along with its stored file. |
 | `deleteAllExportsForTenant` | `(tenantId) => Promise<void>` | Deletes every job of one tenant and its stored files. |
 
-## Export a Tenant's Data
+## Export a tenant's data
 
 `startTenantExportJob` runs the tenant data export as a background job: it asks every registered contributor for its slice, assembles the answers into one ZIP, and hands you the same ticket `runExportJob` does.
 
@@ -334,17 +332,17 @@ export class ExportsPage extends PageController("exports", {
 }
 ```
 
-`StartTenantExportJobOptions` is `ctx`, `user`, `scope`, `filename`, and the optional `delivery`, `deliveryPath` and `maxExecutionTimeMs` — the same fields `runExportJob` takes, minus the ones the archive fixes itself: the extension is `TENANT_EXPORT_EXTENSION` (`"zip"`), the content type `TENANT_EXPORT_CONTENT_TYPE` (`"application/zip"`), and `retainUntilExpiry` is always on, since the archive is reachable from a delivered link and from the job history long after the first download.
+`StartTenantExportJobOptions` is `ctx`, `user`, `scope`, `filename`, and the optional `delivery`, `deliveryPath` and `maxExecutionTimeMs`: the same fields `runExportJob` takes, minus the ones the archive fixes itself: the extension is `TENANT_EXPORT_EXTENSION` (`"zip"`), the content type `TENANT_EXPORT_CONTENT_TYPE` (`"application/zip"`), and `retainUntilExpiry` is always on, since the archive is reachable from a delivered link and from the job history long after the first download.
 
 `buildTenantExportArchive(options)` is the step underneath, for a caller that runs the archive outside a job. Its `BuildTenantExportArchiveOptions` are `tenantId`, the `localPath` to write the ZIP to, an `AbortSignal`, and an optional `reportProgress`; it resolves to the `ExportJobResultSummary` describing which contributors failed.
 
 Contributing to the archive is the other side of this: a module registers a handler on the `TENANT_DATA_EXPORT` hook of the [Core](/docs/interfaces/core/introduction) domain, and that hook's page covers the archive sink, the manifest and what a failing contributor does to the result.
 
-## Track File References
+## Track file references
 
 A `file` or `image` column stores keys into file storage, not the bytes. The helpers in `helpers/file-refs` compare or remap references in the supplied records. They do not authorize access, validate upload provenance, or determine whether another record still references an object. Use the [native save integration](/docs/components/file-storage#custom-save-routes) for promotion and cleanup in custom write routes.
 
-```typescript
+```typescript fragment
 import {
   collectFileRefs,
   dedupeRefs,
@@ -379,7 +377,7 @@ The three functions that inspect columns take the column map first. An entry onl
 
 `FileRef` is `{ key: string; storage?: string }`. The `storage` is read from the data type's `storage` option when it declares one, and left undefined otherwise, so a ref always carries the storage its key belongs to.
 
-## Archive-Mode Defaults
+## Archive mode defaults
 
 `applyArchiveModeDefaultRules(rowActions, archiveField)` derives the row-action rules that make archive mode coherent: archived rows offer restore and delete, live rows offer edit, duplicate and archive. `TableView` calls it for you when `archiveMode` is set; call it directly only when you assemble `TableViewRowActionOptions` yourself.
 
@@ -401,7 +399,7 @@ const rowActions = applyArchiveModeDefaultRules(
 | `restore` | `{ field: archiveField, equals: true }` |
 | `delete` | `{ field: archiveField, equals: true }` |
 
-The function returns a new options object and never rewrites a decision you made explicitly:
+The function returns a new options object; it skips only actions you turned off:
 
 | Value you passed | Result |
 | --- | --- |
@@ -409,6 +407,6 @@ The function returns a new options object and never rewrites a decision you made
 | `true` | `{ isEnabled: true, rule: <default> }` |
 | `false`, or a config with `isEnabled: false` | Left as is; no rule added. |
 | A config without a `rule` | The config, plus the default rule. |
-| A config with a `rule` | Left as is. |
+| A config with a `rule` | The config, with its rule ANDed with the default rule. |
 
-Passing `undefined` as `rowActions` yields an object carrying only the five defaults. The rule shapes themselves are documented in [Shared Types](/docs/interfaces/base/types), and how the table view consumes them in [Tables](/docs/interfaces/base/tables).
+Passing `undefined` as `rowActions` yields an object carrying only the five defaults. The rule shapes themselves are documented in [Shared types](/docs/interfaces/base/types), and how the table view consumes them in [Tables](/docs/interfaces/base/tables).

package/docs/4.notifications/1.introduction.md

@@ -1,41 +1,38 @@
 ---
 title: "Introduction"
 description: "How backend code puts a message in a user's notification list: categories, subjects and sending."
+mode: explanation
 ---
 
-# Introduction
+The `notifications` domain of `@antelopejs/interface-dms` is how backend code puts a message in a user's notification list. It has two halves. You declare a taxonomy once, and you use a builder every time you send.
 
-## Overview
+The taxonomy is two levels deep. A **category** groups related notifications. A **subject** sits under a category and names one kind of message. Every notification is filed under a subject. Users choose what they receive per subject in their notification settings, so the subject you pick decides how the user sees the message grouped and whether the DMS delivers it at all.
 
-The `notifications` domain of `@antelopejs/interface-dms` is how backend code puts a message in a user's notification list. It has two halves: a taxonomy you declare once, and a builder you use every time you send.
+You declare both levels at import time, with `NotificationCategory()` first and then the `NotificationSubject()` calls under it. Sending is a chain of calls. `Notification()` opens a builder, the setters fill in the icon, title, description and subject, and `.build()` returns an immutable `SendableNotification`. You dispatch that to one user, a list of users, the holders of a set of roles, or every user.
 
-The taxonomy is two levels deep. A **category** groups related notifications, a **subject** sits under a category and names one kind of message, and every notification is filed under a subject. Users manage what they receive per subject from their notification settings, so the subject you pick decides how the message is grouped for the user and whether it is delivered at all.
+The [Read notifications](/docs/auth-and-tenancy/authentication#read-notifications) walkthrough shows the open notification bell with one unread message, and describes how a click marks a message read and how a new message reaches every open session of its recipient. The [Notification preferences](/docs/auth-and-tenancy/authentication#notification-preferences) walkthrough shows the System category expanded to its subjects.
 
-Both levels are declared at import time: `NotificationCategory()` first, then the `NotificationSubject()` calls that sit under it. Sending is a fluent chain: `Notification()` opens a builder, the setters fill in the icon, title, description and subject, and `.build()` returns an immutable `SendableNotification` you dispatch to one user, a list of users, the holders of a set of roles, or everyone.
+## What the domain gives you
 
-See the [notification bell before and after reading](/docs/auth-and-tenancy/authentication#read-notifications) and the [category and subject preferences](/docs/auth-and-tenancy/authentication#notification-preferences) for real dashboard examples. The demonstration sends to one disposable account and checks a second session of that account; it does not broadcast or send email.
-
-## Key Features
-
-- **Two-level taxonomy** — Categories group subjects, and subjects classify notifications; the `categoryId:subjectId` pair is the key a user's preferences are stored under.
-- **Declarative registration** — `NotificationCategory()` and `NotificationSubject()` register at import time and return plain info objects you keep as constants and pass around.
-- **Built-in system subjects** — `GeneralSubject`, `SecuritySubject`, `AccountSubject`, `CollaborationSubject` and `AutomationSubject` cover the common platform messages without declaring anything.
-- **Type-checked builder** — The builder tracks which fields have been supplied in its type parameter, so `.build()` does not compile until icon, title, description and subject are all set.
-- **Four dispatch targets** — Send to one user, a list of users, every user holding at least one of a set of roles, or every user.
-- **Shared or individual read state** — A multi-recipient send can give each recipient their own read state, or group the copies so one recipient reading it clears it for all of them.
-- **Preference-aware delivery** — Sends are silently skipped for users who turned the subject off, and `togglePermission` marks the subjects users may not turn off.
+- **A two-level taxonomy.** Categories group subjects, and subjects classify notifications. The DMS stores a user's preferences under the `categoryId:subjectId` pair.
+- **Declarative registration.** `NotificationCategory()` and `NotificationSubject()` register at import time and return plain info objects that you keep as constants and pass around.
+- **Built-in system subjects.** `GeneralSubject`, `SecuritySubject`, `AccountSubject`, `CollaborationSubject` and `AutomationSubject` cover the common platform messages, so you declare nothing for them.
+- **A type-checked builder.** The builder tracks the fields you have supplied in its type parameter, so `.build()` does not compile until the icon, the title, the description and the subject are all set.
+- **Four dispatch targets.** You send to one user, to a list of users, to every user holding at least one of a set of roles, or to every user.
+- **Shared or individual read state.** A multi-recipient send can give each recipient their own read state. It can also group the copies, so that one recipient reading the notification marks it read for all of them.
+- **Preference-aware delivery.** The DMS skips a send without an error for a user who turned the subject off. `togglePermission` marks the subjects that users may not turn off.
 
 ## Dependencies
 
-This interface relies on the following AntelopeJS packages:
+This interface relies on the following AntelopeJS package:
 
-- [@antelopejs/interface-core](https://github.com/AntelopeJS/interface-core) - Interface function and registration proxies used to reach the DMS implementation.
+- [`@antelopejs/interface-core`](https://github.com/AntelopeJS/interface-core) provides the interface functions and registration proxies that reach the DMS implementation.
 
-The implementation lives in the DMS module, so the interface only works in a project that loads `@antelopejs/dms`. Sending to users and roles uses the DMS user and role identifiers described in the DMS auth and tenancy guide.
+The implementation lives in the DMS module, so the interface only works in a project that loads `@antelopejs/dms`. Sending to users and roles uses the DMS user and role identifiers that the DMS auth and tenancy guide describes.
 
-## Quick Start
+## A first notification
 
-The following example declares a category with one subject and sends a notification against it.
+The following example declares a category with one subject and sends a notification under it.
 
 ```typescript
 import {
@@ -44,7 +41,6 @@ import {
   NotificationSubject,
 } from "@antelopejs/interface-dms/notifications";
 
-// Declared at import time — the category first, then its subjects
 export const shopCategory = NotificationCategory("shop", {
   labelKey: "shop.notifications.categories.shop",
   descriptionKey: "shop.notifications.categories.shop_desc",
@@ -73,9 +69,9 @@ export async function notifyOrderShipped(
 }
 ```
 
-The user sees the notification in the dashboard, and finds an `orders` toggle under a `shop` group in their notification settings.
+The category comes first in the file because the DMS refuses a subject whose category it has not registered yet. The user sees the notification in the dashboard, and finds an `orders` switch under a `shop` group in their notification settings.
 
-## Documentation Sections
+## Pages in this section
 
-- [Categories and Subjects](/docs/interfaces/notifications/categories-and-subjects) - Declare categories and subjects, control what users may toggle, and use the built-in system subjects
-- [Sending Notifications](/docs/interfaces/notifications/sending) - Build a notification, dispatch it to users, roles or everyone, and understand what gates delivery
+- [Categories and subjects](/docs/interfaces/notifications/categories-and-subjects) covers declaring categories and subjects, controlling what users may turn off, and the built-in system subjects.
+- [Sending notifications](/docs/interfaces/notifications/sending) covers building a notification, dispatching it to users, roles or everyone, and the rules that decide delivery.