@antelopejs/interface-dms 0.7.1 → 0.7.2

package/docs/2.auth/4.users.md

@@ -0,0 +1,256 @@
+---
+title: "Users"
+description: "The `User` table is the identity record every other part of this interface points at: the authentication decorators resolve a request to one, the token generators sign for one, and `Session` rows reference one."
+---
+
+# Users
+
+## Overview
+
+The `User` table is the identity record every other part of this interface points at: the authentication decorators resolve a request to one, the token generators sign for one, and `Session` rows reference one. The table, its constant and its model live on the `/db` subpath; the sanitizer and the mail entry points live on the root subpath.
+
+```typescript
+import { sanitizeUser } from "@antelopejs/interface-dms/auth";
+import {
+  USERS_TABLE_NAME,
+  User,
+  UserModel,
+} from "@antelopejs/interface-dms/auth/db";
+```
+
+## The User Table
+
+`User` extends `Table.with(HashModifier)` and is registered as the `users` table under the DMS core schema, so its rows are shared across tenants and its model is retrieved without a tenant instance. `USERS_TABLE_NAME` holds the table name, `"users"`.
+
+| Field | Type | Description |
+| ----- | ---- | ----------- |
+| `_id` | `string` | Primary key. |
+| `createdAt` | `Date` | Set on insert by the creation-time decorator. Indexed. |
+| `updatedAt` | `Date` | Set on write by the update-time decorator. Indexed. |
+| `email` | `string` | Login identifier. Indexed. |
+| `name` | `string` | Display name. |
+| `avatar` | `DefaultDataTypes.ImageValue \| null` | Profile picture as an image value (`{ key, alt? }`) in the default storage, downscaled client-side to a square of at most 100×100 pixels. |
+| `language` | `string` | Preferred language or locale, for example `"en"` or `"fr"`. Indexed. |
+| `password` | `string \| null` | Hashed by the `HashModifier`; reads back as the hash, not the plaintext. `null` for accounts with no password. |
+| `authKey` | `string` | Per-user secret that takes part in JWT signing. Rotating it invalidates every token already issued to the user. |
+| `isValidated` | `boolean` | Whether the email address has been validated. Indexed. |
+| `validationToken` | `string \| null` | Current email-validation code. Indexed. |
+| `validationRequestedAt` | `Date \| null` | When the validation code was issued, for expiry and rate limiting. |
+| `forgotPasswordToken` | `string \| null` | Current password-reset code. Indexed. |
+| `forgotPasswordRequestedAt` | `Date \| null` | When the reset code was issued, for expiry and rate limiting. |
+| `owner` | `boolean` | Platform owner flag. This is what `AuthOwnerOnly` checks — see [Authentication](/docs/interfaces/auth/authentication). |
+| `twoFactorMethods` | `string[]` | Second factors enabled on the account. |
+| `twoFactorSecret` | `string \| null` | Active TOTP secret. |
+| `twoFactorPendingSecret` | `string \| null` | TOTP secret awaiting confirmation during enrolment. |
+| `twoFactorTotpLastStep` | `number \| null` | 30-second time step of the last TOTP code accepted; a code from that step or an earlier one is refused, so each code works once. Unset until one is accepted. |
+| `twoFactorBackupCodes` | `string[]` | Remaining single-use backup codes. |
+| `twoFactorEmailCode` | `string \| null` | Hash of the current emailed second-factor code — hex SHA-256 of `JSON.stringify([userId, code])` — never the code itself. |
+| `twoFactorEmailCodeRequestedAt` | `Date \| null` | When the emailed code was issued, for expiry and rate limiting. |
+
+The indexed fields — `createdAt`, `updatedAt`, `email`, `language`, `isValidated`, `validationToken`, `forgotPasswordToken` — are the ones you can look up through `getAll` on the underlying table or `getBy` on the model, which is how `UserModel.getByEmail` works.
+
+## Store and Check a Password
+
+`password` carries the `@Hashed` decorator, and the table composes `HashModifier`. Assign a plaintext value on write and it is hashed on the way into the database; read it back and you get the hash, not the original.
+
+```typescript
+import type { UserModel } from "@antelopejs/interface-dms/auth/db";
+import randomstring from "randomstring";
+
+const AUTH_KEY_LENGTH = 64;
+
+export async function createUser(
+  userModel: UserModel,
+  name: string,
+  email: string,
+  password: string,
+) {
+  const ids = await userModel.insert({
+    createdAt: new Date(),
+    updatedAt: new Date(),
+    name,
+    email: email.toLowerCase(),
+    password, // hashed by the modifier on insert
+    authKey: randomstring.generate({ length: AUTH_KEY_LENGTH }),
+    owner: false,
+    language: "en",
+  });
+  return ids[0];
+}
+```
+
+To check a candidate password, call `testHash` on the loaded row. The mixin hashes the candidate with the stored salt and compares it against the stored hash.
+
+```typescript
+import { HTTPResult } from "@antelopejs/interface-api";
+import type { UserModel } from "@antelopejs/interface-dms/auth/db";
+
+const UNAUTHORIZED = 401;
+
+export async function checkCredentials(
+  userModel: UserModel,
+  email: string,
+  password: string,
+) {
+  const user = await userModel.getByEmail(email.toLowerCase());
+  if (!user || !user.testHash("password", password)) {
+    throw new HTTPResult(UNAUTHORIZED, "error.invalid_credentials");
+  }
+  return user;
+}
+```
+
+Emails are stored trimmed and lowercased. `getByEmail` normalizes its argument itself; normalize with `normalizeEmail` (exported alongside `UserModel`) before writing one.
+
+## Query Users with UserModel
+
+`UserModel` extends `BasicDataModel(User, USERS_TABLE_NAME)`, so it has the standard `get`, `getBy`, `getAll`, `insert`, `update` and `delete` operations, plus three lookups of its own.
+
+| Method | Signature | Description |
+| ------ | --------- | ----------- |
+| `getByEmail` | `(email: string) => Promise<User \| undefined>` | The user with this email, trimmed and lowercased before the lookup through the `email` index, or `undefined`. |
+| `getOwners` | `() => Promise<User[]>` | Every user with `owner === true`. |
+| `countOwnersExcluding` | `(excludedIds: string[]) => Promise<number>` | How many owners remain once the given user ids are set aside. Pass an empty array to count all owners. |
+
+`countOwnersExcluding` exists for the last-owner check: before removing the owner flag from a set of users, count who would be left and refuse the operation if the answer is zero.
+
+```typescript
+import { HTTPResult } from "@antelopejs/interface-api";
+import type { UserModel } from "@antelopejs/interface-dms/auth/db";
+
+const CONFLICT = 409;
+
+export async function demoteOwners(userModel: UserModel, userIds: string[]) {
+  const remaining = await userModel.countOwnersExcluding(userIds);
+  if (remaining === 0) {
+    throw new HTTPResult(CONFLICT, "error.last_owner");
+  }
+
+  for (const id of userIds) {
+    await userModel.update(id, { owner: false });
+  }
+}
+```
+
+## Invalidate Every Token for a User
+
+`authKey` takes part in the signing secret of every token issued for the user, so replacing it makes all outstanding access, refresh, two-factor and tenant-assignment tokens fail validation at once. Combine it with `SessionModel.deleteByUserId` from [Tokens and Sessions](/docs/interfaces/auth/tokens-and-sessions) to sign a user out everywhere.
+
+```typescript
+import type {
+  SessionModel,
+  User,
+  UserModel,
+} from "@antelopejs/interface-dms/auth/db";
+import randomstring from "randomstring";
+
+const AUTH_KEY_LENGTH = 64;
+
+export async function signOutEverywhere(
+  userModel: UserModel,
+  sessionModel: SessionModel,
+  user: User,
+) {
+  await sessionModel.deleteByUserId(user._id);
+  user.authKey = randomstring.generate({ length: AUTH_KEY_LENGTH });
+  await userModel.update(user);
+}
+```
+
+`userModel.update(user)` takes the primary key from the object; the two-argument form `update(id, partial)` updates a subset of fields instead.
+
+## Strip Secrets Before Responding
+
+A `User` loaded from the database carries authentication secrets. `sanitizeUser` returns a copy without them, and is what you return over HTTP.
+
+```typescript
+sanitizeUser(user: User): Promise<Partial<User>>
+```
+
+It removes the account's secret material — the `authKey`, the email-validation and password-reset tokens with their timestamps, and the two-factor secret, the secret of an enrolment in progress, backup codes and email code with its timestamp — along with any additional keys the deployment lists in its authentication configuration. Because the removed set is configurable, the return type is `Partial<User>`: treat every field as possibly absent rather than assuming a fixed shape.
+
+```typescript
+import { Controller, Get } from "@antelopejs/interface-api";
+import {
+  AuthRawUser,
+  sanitizeUser,
+} from "@antelopejs/interface-dms/auth";
+import type { User } from "@antelopejs/interface-dms/auth/db";
+
+export class MeController extends Controller("/api/me") {
+  @Get("")
+  me(@AuthRawUser() user: User): Promise<Partial<User>> {
+    return sanitizeUser(user);
+  }
+}
+```
+
+## Send Account Emails
+
+Four entry points send the account emails the authentication flows depend on. Each returns a promise that resolves once the message has been accepted and rejects when the mail provider reports a failure, so decide per call site whether to await it or dispatch it in the background.
+
+| Function | Signature | Sends |
+| -------- | --------- | ----- |
+| `send2FAEmail` | `(user: User, code: string) => Promise<void>` | The emailed second-factor code, to `user.email`. |
+| `sendEmailValidationEmail` | `(user: User) => Promise<void>` | The email-validation message, using the `validationToken` currently stored on the user. |
+| `sendEmailForgotEmail` | `(user: User) => Promise<void>` | The password-reset message, using the `forgotPasswordToken` currently stored on the user. |
+| `sendAdminInviteEmail` | `(email: string, token: string, inviteeName?: string) => Promise<void>` | An invite carrying a signup link built from `token`, to an address that has no user row yet. `inviteeName` addresses the invitee by name when the invite carried one. |
+
+`sendEmailValidationEmail` and `sendEmailForgotEmail` read the code off the user, so generate it, persist it, and only then send.
+
+```typescript
+import { sendEmailForgotEmail } from "@antelopejs/interface-dms/auth";
+import type { UserModel } from "@antelopejs/interface-dms/auth/db";
+import randomstring from "randomstring";
+
+const RESET_CODE_LENGTH = 6;
+
+export async function requestPasswordReset(
+  userModel: UserModel,
+  email: string,
+) {
+  const user = await userModel.getByEmail(email.toLowerCase());
+  if (!user) return; // answer identically whether or not the address exists
+
+  user.forgotPasswordToken = randomstring.generate({
+    length: RESET_CODE_LENGTH,
+    capitalization: "uppercase",
+  });
+  user.forgotPasswordRequestedAt = new Date();
+  await userModel.update(user);
+
+  await sendEmailForgotEmail(user);
+}
+```
+
+`sendAdminInviteEmail` takes a bare address and a token instead of a `User`, because an invitee has no user row until they sign up. The invite record itself, its token and its expiry belong to the [Core](/docs/interfaces/core/introduction) domain, whose invite helper dispatches this mail for you.
+
+## Password Policy
+
+`@antelopejs/interface-dms/auth/password` exports the policy every DMS flow applies when a password is set: at least `PASSWORD_MIN_LENGTH` (8) characters, with at least one uppercase letter, one digit and one of `@$!%*?&`, and no character outside ASCII letters, digits and those special characters. `PASSWORD_PATTERN` holds the character rules without the length.
+
+```typescript
+isPasswordCompliant(password: string): boolean
+```
+
+It is a pure function, not an interface call, so it works without the DMS loaded. Call it from any flow you own that stores a password — a public signup, for instance — before hashing it, so your module accepts exactly the passwords the DMS accepts.
+
+## Announce a Registration
+
+`announceRegistration` runs everything that must happen once an account has really joined a tenant: the welcome notification, the collaborator notification to the platform owners, and then the `USER_REGISTERED` hook.
+
+```typescript
+announceRegistration(
+  userModel: UserModel,
+  user: User,
+  tenantId: string,
+): Promise<void>
+```
+
+Call it from any registration flow you own — a module with its own signup, a SaaS transactional flow calling it once provisioning has committed. The DMS password signup and a provider login consuming an invitation both go through it, which is what keeps notifications and automations independent of which door the account came through.
+
+The hook is observational: registration is already complete when it runs, so a failing subscriber is logged rather than allowed to fail the request and strand a user whose account exists but whose retry token is gone. The same is true of the notifications — they are dispatched in the background and a failure there is logged, not propagated.
+
+## Next Steps
+
+[External Identities](/docs/interfaces/auth/external-identities) covers binding a user to the accounts they own on a login provider.

package/docs/2.auth/5.external-identities.md

@@ -0,0 +1,122 @@
+---
+title: "External Identities"
+description: "An external identity binds an account a user owns on a login provider — GitHub, Google, whichever the deployment configures — to a `User` row, so that signing in through that provider resolves to the same account…"
+---
+
+# External Identities
+
+## Overview
+
+An external identity binds an account a user owns on a login provider — GitHub, Google, whichever the deployment configures — to a `User` row, so that signing in through that provider resolves to the same account every time. The binding is what the provider login flow reads; the provider account id, not the email, is what identifies it.
+
+The two functions live on the root subpath, the table and its model on `/db`.
+
+```typescript
+import {
+  getExternalIdentities,
+  linkExternalIdentity,
+} from "@antelopejs/interface-dms/auth";
+import {
+  USER_EXTERNAL_IDENTITIES_TABLE_NAME,
+  UserExternalIdentity,
+  UserExternalIdentityModel,
+  buildExternalIdentityId,
+} from "@antelopejs/interface-dms/auth/db";
+```
+
+This surface is scoped to authentication. A provider connection that powers a product feature — repository access, deployments — owns its own storage and must never be derived from these rows: they say who the user is, not what the deployment may do on their behalf.
+
+## Bind a Provider Account
+
+```typescript
+linkExternalIdentity(
+  userId: string,
+  identity: ExternalIdentityInput,
+): Promise<ExternalIdentityLinkResult>
+```
+
+```typescript
+interface ExternalIdentityInput {
+  provider: string;
+  providerAccountId: string;
+  email: string;
+}
+
+interface ExternalIdentityLinkResult {
+  wasCreated: boolean;
+}
+```
+
+| Field | Description |
+| ----- | ----------- |
+| `provider` | Provider identifier, as declared in the instance's OAuth configuration. |
+| `providerAccountId` | Immutable account identifier on the provider side. Never the email: users change their provider email without changing account. |
+| `email` | Email the provider reported, stored lowercased for support and audit only. |
+
+`wasCreated` distinguishes a first binding from a refresh, which is what a login flow needs to decide whether the user just connected a new provider or simply signed in again.
+
+```typescript
+import { linkExternalIdentity } from "@antelopejs/interface-dms/auth";
+
+const { wasCreated } = await linkExternalIdentity(user._id, {
+  provider: "github",
+  providerAccountId: profile.id,
+  email: profile.email,
+});
+```
+
+The call is idempotent for the owning user: re-linking the same provider account only refreshes its `email` and `lastLoginAt`. Binding an account already owned by another user throws `409` with the message `error.oauth.identity_already_linked` — a provider account is a single-user credential.
+
+Uniqueness is enforced by the row's deterministic primary key rather than by a secondary index, so two concurrent bindings of the same provider account collide instead of duplicating; the loser re-reads the row and either refreshes it or gets the `409`.
+
+## List a User's Identities
+
+```typescript
+getExternalIdentities(userId: string): Promise<UserExternalIdentity[]>
+```
+
+Returns an empty array for a user who only signs in with a password, which is how an account-settings screen decides whether to offer disconnecting a provider.
+
+## The `UserExternalIdentity` Table
+
+Table `user_external_identities` in the DMS core schema, so its rows are shared across tenants like `users`. `USER_EXTERNAL_IDENTITIES_TABLE_NAME` holds the name.
+
+| Field | Type | Description |
+| ----- | ---- | ----------- |
+| `_id` | `string` | `<provider>:<providerAccountId>`. Being the primary key is what makes the binding unique. |
+| `userId` | `string` | Owning user. Indexed, related to `User`. |
+| `provider` | `string` | Provider identifier. |
+| `providerAccountId` | `string` | Account identifier on the provider side. |
+| `email` | `string` | Email reported at the last successful login. Account resolution never reads it back. |
+| `createdAt` | `Date` | Set on insert. Indexed. |
+| `lastLoginAt` | `Date` | Refreshed on every successful login through this identity. |
+
+`buildExternalIdentityId(provider, providerAccountId)` composes the id. Use it rather than formatting the string yourself, so a lookup by id keeps matching what `linkExternalIdentity` writes.
+
+## `UserExternalIdentityModel`
+
+`UserExternalIdentityModel` extends `BasicDataModel(UserExternalIdentity, USER_EXTERNAL_IDENTITIES_TABLE_NAME)` and adds three methods:
+
+| Method | Signature | Description |
+| ------ | --------- | ----------- |
+| `getByProviderAccount` | `(provider: string, providerAccountId: string) => Promise<UserExternalIdentity \| undefined>` | The identity a provider account is bound to, or `undefined` when the account is unknown. |
+| `getByUserId` | `(userId: string) => Promise<UserExternalIdentity[]>` | Every identity bound to a user, read through the `userId` index. |
+| `deleteByUserId` | `(userId: string) => Promise<void>` | Drop every identity of a user. |
+
+`getByProviderAccount` is the login-side lookup: resolve the provider profile to an identity, and its `userId` to the account to sign in.
+
+```typescript
+import { GetModel } from "@antelopejs/interface-database-decorators";
+import {
+  UserExternalIdentityModel,
+  UserModel,
+} from "@antelopejs/interface-dms/auth/db";
+
+const identities = GetModel(UserExternalIdentityModel);
+const identity = await identities.getByProviderAccount("github", profile.id);
+const user = identity
+  ? await GetModel(UserModel).get(identity.userId)
+  : undefined;
+```
+
+An unknown provider account means no account exists for it yet — hand the flow to signup or to invite redemption rather than creating one implicitly. `deleteByUserId` belongs to account deletion: leaving identities behind would let a recycled provider account resolve to a user row that is gone.

package/docs/3.base/.navigation.yml

@@ -0,0 +1,2 @@
+title: Base
+icon: i-lucide-blocks

package/docs/3.base/1.introduction.md

@@ -0,0 +1,202 @@
+---
+title: "Introduction"
+description: "The base domain is the component vocabulary of the DMS: forms, tables, charts and cards, layout containers, data types and shared prop types."
+---
+
+# Introduction
+
+## Overview
+
+The `base` domain of `@antelopejs/interface-dms` is the component vocabulary of the DMS: forms, tables, charts and cards, layout containers, trees, the data types behind every field, and the shared prop types they all draw from.
+
+Every component here is a builder. `Form({...})`, `TableView(controller, {...})` and `ChartLine({...})` do not render anything — they return a `ComponentBuilder` from `@antelopejs/interface-dms/component`, which is a serializable description of a component: its name, its options, and its children. You assign that description to a static field of a page class, and the frontend reads the page's tree and draws it. The options you set are therefore data, and the components that need data are given a `fetchUrl` and a `submitUrl` pointing back at routes you declare on the same page or on a data controller.
+
+Two consequences shape the whole domain. First, a component's contract is its props interface: what you can express is exactly what the props allow, which is why this reference documents them field by field. Second, anything the frontend must receive has to survive serialization, so a builder that accepts a nested `Component` — a modal target, a kanban card, a chart inside a card — stores its serialized form instead.
+
+The DMS documentation carries task-shaped chapters on the same components, organised around what you are building. This folder is the contract behind them: the exact symbol names, option fields and return types.
+
+### Subpath Map
+
+`@antelopejs/interface-dms/base` is the barrel over the modules below, and re-exports most of them. The ones marked as not in the barrel are imported from their own subpath. Every row is a subpath of `@antelopejs/interface-dms/base`.
+
+| Subpath | Holds | In the root barrel | Documented in |
+| --- | --- | --- | --- |
+| `types` | Base props, colours, tones (`TONES`, `Tone`, `ICON_TONES`, `IconTone`), sizes, buttons, action targets, row-action rules, guards, watch actions, enums | yes | [Shared Types](/docs/interfaces/base/types) |
+| `form` | `Form`, the field and group shapes, `FormComponents`, `FormEvents`, the schema helpers | yes | [Forms](/docs/interfaces/base/forms) |
+| `table-view` | `TableView`, `@Column`, `TableViewRoutes`, guards, row actions | yes | [Tables](/docs/interfaces/base/tables) |
+| `chart` | Chart builders, series and point shapes, chart props | yes | [Charts and Widgets](/docs/interfaces/base/charts-and-widgets) |
+| `chart-card` | `ChartCard` | yes | [Charts and Widgets](/docs/interfaces/base/charts-and-widgets) |
+| `kpi-card` | `KpiCard` | yes | [Charts and Widgets](/docs/interfaces/base/charts-and-widgets) |
+| `top-list-card` | `TopListCard` | yes | [Charts and Widgets](/docs/interfaces/base/charts-and-widgets) |
+| `period-selector` | `PeriodSelector` | yes | [Charts and Widgets](/docs/interfaces/base/charts-and-widgets) |
+| `live-toggle` | `LiveToggle` | yes | [Display Blocks](/docs/interfaces/base/display-blocks#live-toggle) |
+| `grid` | `Grid`, `GridRow` | yes | [Layout and Containers](/docs/interfaces/base/layout) |
+| `stack` | `HStack`, `VStack`, `Spacer` | yes | [Layout and Containers](/docs/interfaces/base/layout) |
+| `tab` | `Tab` | yes | [Layout and Containers](/docs/interfaces/base/layout) |
+| `guard` | `Guard` | yes | [Layout and Containers](/docs/interfaces/base/layout#guard) |
+| `layouts` | `DefaultLayout`, `FormPageLayout`, `SettingsLayout`, `EmptyLayout` | yes | [Layout and Containers](/docs/interfaces/base/layout) |
+| `placeholder` | `Placeholder` | yes | [Layout and Containers](/docs/interfaces/base/layout) |
+| `display` | `BlockLinkAction`, `BlockItemsSource`, `BlockEmptyText` | yes | [Display Blocks](/docs/interfaces/base/display-blocks) |
+| `stat-group` | `StatGroup` | yes | [Display Blocks](/docs/interfaces/base/display-blocks) |
+| `key-value-list` | `KeyValueList` | yes | [Display Blocks](/docs/interfaces/base/display-blocks) |
+| `nav-card-grid` | `NavCardGrid` | yes | [Display Blocks](/docs/interfaces/base/display-blocks) |
+| `empty-state` | `EmptyState` | yes | [Display Blocks](/docs/interfaces/base/display-blocks) |
+| `banner` | `Banner` | yes | [Display Blocks](/docs/interfaces/base/display-blocks) |
+| `card` | `Card` | yes | [Display Blocks](/docs/interfaces/base/display-blocks) |
+| `code-block` | `CodeBlock` | yes | [Display Blocks](/docs/interfaces/base/display-blocks) |
+| `custom` | `CustomComponent` | no | [Layout and Containers](/docs/interfaces/base/layout) |
+| `data-types` | `DataType`, the registration decorators, `DefaultDataTypes`, `DefaultDataCompareTypes`, `StatusType` | no | [Data Types](/docs/interfaces/base/data-types) |
+| `searchable` | `Searchable`, `SearchableMeta` | yes | [Helpers](/docs/interfaces/base/helpers) |
+| `export-jobs` | `runExportJob` and the export-job lifecycle | yes | [Helpers](/docs/interfaces/base/helpers) |
+| `tenant-export-archive` | `startTenantExportJob`, `buildTenantExportArchive` | yes | [Helpers](/docs/interfaces/base/helpers) |
+| `helpers/file-refs` | File and image reference tracking | no | [Helpers](/docs/interfaces/base/helpers) |
+| `helpers/archive-mode-helpers` | `applyArchiveModeDefaultRules` | no | [Helpers](/docs/interfaces/base/helpers) |
+
+Within `types`, four modules are outside that subpath's barrel and are imported from `types/action-target`, `types/row-action`, `types/row-action-operators` and `types/guards`; the guard types and `RowActionRule` are also re-exported by `table-view`.
+
+## Key Features
+
+- **Builders that produce data** — Every component function returns a `ComponentBuilder`, so a page's UI is a plain value you can factor, reuse and compose with `.child()`.
+- **Forms from typed fields** — A field names a `DataType`, and the type supplies both the input component and the Zod schema; `Form` compiles the field list into one schema and ships its JSON Schema form with the component.
+- **Tables from data controllers** — `TableView` reads a controller's data-api metadata and its `@Column` declarations to build the columns, the `new` / `edit` / `view` forms, and the permission-carrying actions in one call.
+- **Server-enforced row rules and guards** — Row-action rules are a small algebra evaluated on both sides, and guards run inside the mutating routes, so what the row menu offers is what the server accepts.
+- **A chart and widget set with a shared period scope** — Twelve chart types plus KPI, chart and top-list cards; one `PeriodSelector` id ties them to the same range and comparison.
+- **Layout without a frontend build** — Grids, stacks, tabs and page layouts arrange components, and `CustomComponent` names a Vue component when the vocabulary runs out.
+- **An extensible data-type registry** — `@RegisterDataType` and `@RegisterDataCompareMode` add your own types and filter operators to the catalogue the forms, columns and filters draw from.
+- **Shared prop vocabulary** — Colours, sizes, HTTP methods, action targets, readonly behaviour and watch actions are declared once in `types` and reused by every component.
+
+## Dependencies
+
+This interface relies on the following AntelopeJS packages:
+
+- [@antelopejs/interface-api](https://github.com/AntelopeJS/interface-api) - Request context, controller metadata and route parameters.
+- [@antelopejs/interface-api-util](https://github.com/AntelopeJS/interface-api-util) - `assert` for failing a route with an HTTP status.
+- [@antelopejs/interface-core](https://github.com/AntelopeJS/interface-core) - Metadata storage, decorator factories, interface functions and logging.
+- [@antelopejs/interface-data-api](https://github.com/AntelopeJS/interface-data-api) - Data controllers, default routes, list parameters and field metadata.
+- [@antelopejs/interface-database](https://github.com/AntelopeJS/interface-database) - The value proxies compare modes build their filters from.
+- [@antelopejs/interface-database-decorators](https://github.com/AntelopeJS/interface-database-decorators) - Models and the localization modifier.
+- [@antelopejs/interface-file-storage](https://github.com/AntelopeJS/interface-file-storage) - Upload constraints, staged-key promotion and file deletion behind the file and image types.
+- [zod](https://www.npmjs.com/package/zod) and [zod-to-json-schema](https://www.npmjs.com/package/zod-to-json-schema) - Field validation schemas and their JSON Schema form.
+
+It also builds on other domains of the same package: `/component` for `Component` and `ComponentBuilder`, `/page` for the page a component is registered on, `/permissions` for the action permissions a table view declares, and `/auth` for the authenticated user its routes receive.
+
+## Quick Start
+
+A page declaring one component. The `Form` builder describes the fields; the two routes on the same class serve and accept the values. Define the backing model first; `SettingsModel` is application code, not a DMS export.
+
+```typescript [db.ts]
+import {
+  BasicDataModel,
+  Field,
+  RegisterTable,
+  Table,
+} from "@antelopejs/interface-database-decorators";
+
+export const SETTINGS_SCHEMA = "example_settings";
+export const SETTINGS_ROW_ID = "module";
+
+@RegisterTable("settings", SETTINGS_SCHEMA)
+export class Settings extends Table {
+  @Field("string") declare _id: string;
+  @Field("boolean") declare enabled: boolean;
+  @Field("number") declare retentionDays: number;
+}
+
+export class SettingsModel extends BasicDataModel(Settings, "settings") {}
+```
+
+The page edits one module-wide record, so restrict it to platform owners. It returns defaults before the first save and upserts only `SETTINGS_ROW_ID`, rather than updating every row in the table.
+
+```typescript [settings-page.ts]
+import { Get, JSONBody, Post } from "@antelopejs/interface-api";
+import { assert } from "@antelopejs/interface-api-util";
+import { GetModel } from "@antelopejs/interface-database-decorators";
+import {
+  PageController,
+  pagesCategory,
+  RegisterPage,
+} from "@antelopejs/interface-dms/page";
+import { DefaultDataTypes } from "@antelopejs/interface-dms/base/data-types";
+import { Form, formSchema } from "@antelopejs/interface-dms/base/form";
+import { DefaultLayout } from "@antelopejs/interface-dms/base/layouts";
+import { HttpMethod } from "@antelopejs/interface-dms/base/types";
+import { AuthOwnerOnly } from "@antelopejs/interface-dms/auth";
+import { SettingsModel, SETTINGS_ROW_ID } from "./db";
+
+@RegisterPage()
+@AuthOwnerOnly()
+export class SettingsPage extends PageController(
+  "settings",
+  {
+    urlSlug: "settings",
+    displayName: "Settings",
+    description: "Module configuration",
+    icon: "i-ph-gear",
+    category: pagesCategory,
+  },
+  DefaultLayout(),
+) {
+  static form = Form({
+    title: "Settings",
+    fetchUrl: "/settings/",
+    submitUrl: "/settings/",
+    submitUrlMethod: HttpMethod.post,
+    fields: [
+      {
+        id: "enabled",
+        label: "Enabled",
+        type: new DefaultDataTypes.BooleanType(),
+      },
+      {
+        id: "retentionDays",
+        label: "Retention (days)",
+        type: new DefaultDataTypes.NumberType({ min: 0 }),
+        required: true,
+      },
+    ],
+  });
+
+  settingsModel = GetModel(SettingsModel);
+
+  @Get("/")
+  async read() {
+    return await this.settingsModel.get(SETTINGS_ROW_ID)
+      ?? { enabled: false, retentionDays: 0 };
+  }
+
+  @Post("/")
+  async write(@JSONBody() body: unknown) {
+    const result = formSchema(SettingsPage.form).safeParse(body);
+    assert(result.success, 400, "Invalid settings");
+    await this.settingsModel.table.insert({
+      _id: SETTINGS_ROW_ID,
+      enabled: result.data.enabled ?? false,
+      retentionDays: result.data.retentionDays,
+    }, { conflict: "update" });
+  }
+}
+```
+
+Import the page and provision the schema from your module's entry file. Merge this into an existing `start()` if your module already has one:
+
+```typescript [index.ts]
+import "./settings-page";
+import { RegisterSchema } from "@antelopejs/interface-database-decorators";
+import { SETTINGS_SCHEMA } from "./db";
+
+export async function start(): Promise<void> {
+  await RegisterSchema(SETTINGS_SCHEMA);
+}
+```
+
+The page registers itself at import time, and its routes are mounted under the page's slug — which is why the form fetches from and submits to `/settings/`. `Form` serializes the field descriptions and JSON Schema for the frontend; the custom write route must still validate the request on the server, as the `formSchema` call does here. For per-tenant settings, use a tenant-scoped schema and model instead of this module-wide record.
+
+## Documentation Sections
+
+- [Shared Types](/docs/interfaces/base/types) - Base props, colours, sizes, action targets, row-action rules, guards and the small enums.
+- [Forms](/docs/interfaces/base/forms) - The `Form` builder, fields and groups, input components and the validation schema.
+- [Tables](/docs/interfaces/base/tables) - Table views over a data controller: columns, routes, row actions, guards, displays and generated forms.
+- [Charts and Widgets](/docs/interfaces/base/charts-and-widgets) - Chart types and props, chart cards, KPI cards, top lists and the period selector.
+- [Layout and Containers](/docs/interfaces/base/layout) - Grids, stacks, tabs, the guard, page layouts, the placeholder and the custom-component escape hatch.
+- [Data Types](/docs/interfaces/base/data-types) - The `DataType` contract, the registries, the default catalogue and a custom type.
+- [Helpers](/docs/interfaces/base/helpers) - Searchable columns, export jobs, file references and the archive-mode defaults.