@antelopejs/interface-dms 0.7.1 → 0.7.3

package/dist/db/models/tenants.model.d.ts

@@ -12,6 +12,7 @@ declare const TenantModel_base: {
         delete(id: string): Promise<number>;
     };
     readonly schemaName: string;
+    readonly tableClass: import("@antelopejs/interface-database-decorators").Constructible<Tenant>;
     fromPlainData(obj: any): Tenant;
     fromDatabase(obj: any): Tenant | undefined;
     toDatabase(obj: any): Record<string, any>;

package/dist/db/models/user_invites.model.d.ts

@@ -16,6 +16,7 @@ declare const UserInviteModel_base: {
         delete(id: string): Promise<number>;
     };
     readonly schemaName: string;
+    readonly tableClass: import("@antelopejs/interface-database-decorators").Constructible<UserInvite>;
     fromPlainData(obj: any): UserInvite;
     fromDatabase(obj: any): UserInvite | undefined;
     toDatabase(obj: any): Record<string, any>;

package/docs/.navigation.yml

@@ -0,0 +1,2 @@
+title: Interfaces
+icon: i-lucide-file-code-2

package/docs/1.core/.navigation.yml

@@ -0,0 +1,2 @@
+title: Core
+icon: i-lucide-cpu

package/docs/1.core/1.introduction.md

@@ -0,0 +1,169 @@
+---
+title: "Introduction"
+description: "The core contract of the DMS: pages and modules, components, permissions, tenancy, invites, hooks, realtime, quick actions and layout banners."
+---
+
+# Introduction
+
+## Overview
+
+The root export of `@antelopejs/interface-dms` and the subpaths listed below are the core contract of the AntelopeJS DMS. It encodes one inversion: the backend declares the screen, as serializable data. A page is a controller class, its components are static fields holding builders, and the page's layout route returns the description a shared frontend renders. Adding an admin screen is a backend change.
+
+Around that core the interface carries what an admin backend needs to be more than a renderer: hierarchical permissions derived from the page tree, multi-tenant data access scoped by the model handle, lifecycle hooks, realtime topics, and command-palette entries.
+
+Everything here is imported from a subpath of `@antelopejs/interface-dms`. Two other domains of the same package complete the picture and are referenced throughout these pages: [Auth](/docs/interfaces/auth/introduction) (`/auth`) for authentication and the `User` table, and [Base](/docs/interfaces/base/introduction) (`/base`) for the concrete component vocabulary (`Form`, `TableView`, `Grid`, the chart family) built on the component types documented here.
+
+## Key Features
+
+- **Pages as controllers** — `PageController` builds a controller class bound to a URL; `@RegisterPage()` records it, registers its permissions, and serves its layout.
+- **Components that serialize** — a `ComponentBuilder` produces data, not a live component, so one frontend renders every module's screens.
+- **Categories and modules** — a sidebar tree of nested categories, plus modules that own a whole branch under `/modules`.
+- **Dynamic navigation** — providers that resolve extra menu entries per request, so one page can back an entry per project or workspace.
+- **Page extensions** — inject components into a page owned by another module, permissioned in that page's own tree.
+- **Hierarchical permissions** — ids derived from page, component and action, with a base set from roles and an effective set shaped by registered resolvers.
+- **Route guards** — permission, tenant-member and tenant-owner decorators usable as parameter or property decorators.
+- **Tenancy in the handle** — per-tenant schemas and model handles bound to one tenant, rather than a tenant column filtered on every query.
+- **Tenant access gates** — one binary check that denies a tenant at every authorization surface at once.
+- **Invites** — one call that either grants membership to an existing user or issues a token-bearing invite.
+- **Lifecycle hooks** — typed events for tenants, members, invites and registrations, dispatched either to notify or to collect contributions.
+- **Realtime topics** — bind a topic to a page, publish to whoever is on it, and subscribe from the backend to what others publish.
+- **Quick actions** — contribute grouped, permission-gated entries to the command palette.
+
+## Dependencies
+
+This interface relies on the following AntelopeJS packages:
+
+- [@antelopejs/interface-api](https://github.com/AntelopeJS/interface-api) - Controllers, route registration and request context.
+- [@antelopejs/interface-auth](https://github.com/AntelopeJS/interface-auth) - The authentication decorator machinery the guards build on.
+- [@antelopejs/interface-core](https://github.com/AntelopeJS/interface-core) - Interface functions, registering proxies and decorator helpers.
+- [@antelopejs/interface-database-decorators](https://github.com/AntelopeJS/interface-database-decorators) - Table definitions, data models and model injection.
+- [@antelopejs/interface-data-api](https://github.com/AntelopeJS/interface-data-api) - Used by the `/data-controllers` subpath for the built-in members and roles controllers.
+
+## Quick Start
+
+Declare the application's table and model first. `BookModel` is not a DMS export; this example defines it with the stock flag used by the KPI query.
+
+```typescript [db.ts]
+import {
+  BasicDataModel,
+  Field,
+  RegisterTable,
+  Table,
+} from "@antelopejs/interface-database-decorators";
+
+export const CATALOG_SCHEMA = "example_catalog";
+
+@RegisterTable("books", CATALOG_SCHEMA)
+export class Book extends Table {
+  @Field("string") declare _id: string;
+  @Field("string") declare title: string;
+  @Field("boolean") declare inStock: boolean;
+}
+
+export class BookModel extends BasicDataModel(Book, "books") {}
+```
+
+Then declare a category, a page with a component, and the route that component fetches from:
+
+```typescript [books-page.ts]
+import { Get } from "@antelopejs/interface-api";
+import { GetModel } from "@antelopejs/interface-database-decorators";
+import {
+  Category,
+  PageController,
+  RegisterPage,
+  pagesCategory,
+} from "@antelopejs/interface-dms/page";
+import { KpiCard } from "@antelopejs/interface-dms/base";
+import { BookModel } from "./db";
+
+export const catalog = Category("catalog", {
+  displayName: "Catalog",
+  icon: "i-ph-books",
+  category: pagesCategory,
+});
+
+@RegisterPage()
+export class BooksPage extends PageController("books", {
+  displayName: "Books",
+  description: "Everything currently in the catalog",
+  icon: "i-ph-book-open",
+  category: catalog,
+  order: 1,
+}) {
+  static inStockKpi = KpiCard({
+    title: "In stock",
+    icon: "i-ph-package",
+    fetchUrl: "/catalog/books/stats/in-stock",
+    valueFormat: "number",
+  });
+
+  @Get("/stats/in-stock")
+  async inStock() {
+    const value = await GetModel(BookModel).table
+      .filter((book) => book.key("inStock").eq(true)).count().run();
+    return { value };
+  }
+}
+```
+
+Import the page and register the schema from your module's entry file, merging this into an existing `start()` if necessary:
+
+```typescript [index.ts]
+import "./books-page";
+import { RegisterSchema } from "@antelopejs/interface-database-decorators";
+import { CATALOG_SCHEMA } from "./db";
+
+export async function start(): Promise<void> {
+  await RegisterSchema(CATALOG_SCHEMA);
+}
+```
+
+The page resolves at `/catalog/books` and its layout at `/dms/pages/catalog/books/pagelayout`: a page controller's routes live under `/dms/pages` (`pageRoutePath`), a prefix the frontend server proxies to the backend, since the page's own path is the page. Its permission id is the chain of ids down from the root category — `pages.catalog.books` — with `pages.catalog.books.inStockKpi` registered underneath it.
+
+## Subpath Map
+
+| Subpath | Contains | Documented in |
+| ------- | -------- | ------------- |
+| `/page` | Pages, categories, modules, layouts, page extensions, dynamic menus, frontend modules | [Pages and Modules](/docs/interfaces/core/pages-and-modules) |
+| `/component` | `Component`, `ComponentBuilder`, actions, watches | [Components](/docs/interfaces/core/components) |
+| `/component-slots` | `RegisterComponentSlot`, `ComponentSlotResolver`, `SlotOptions` | [Components](/docs/interfaces/core/components#registercomponentslot) |
+| `/attachments` | `SaveComponentFiles` and its request, field and result types | [Pages and Modules](/docs/interfaces/core/pages-and-modules#savecomponentfiles) |
+| `/permission-gate` | Shared `PermissionGate` fields | [Base types](/docs/interfaces/base/types#permissiongate) |
+| `/permissions` | The permission registry and the permission computation | [Permissions](/docs/interfaces/core/permissions) |
+| `/permissions-resolver` | Registering and running permission resolvers | [Permissions](/docs/interfaces/core/permissions) |
+| `/guards` | `AuthUserWithPermission`, `AuthTenantOwner`, `AuthTenantMember` | [Permissions](/docs/interfaces/core/permissions) |
+| `/constants` | Schema names and the default tenant | [Tenancy](/docs/interfaces/core/tenancy) |
+| `/db` | The `Tenant`, `TenantMember`, `Role` and `UserInvite` tables and models | [Tenancy](/docs/interfaces/core/tenancy), [Invites](/docs/interfaces/core/invites) |
+| `/request-tenant` | `getRequestTenantId` | [Tenancy](/docs/interfaces/core/tenancy) |
+| `/tenant-scoped-model` | `TenantScopedModel` | [Tenancy](/docs/interfaces/core/tenancy) |
+| `/tenant-access` | Tenant access gates | [Tenancy](/docs/interfaces/core/tenancy) |
+| `/tenant-ownership` | Membership and ownership writes | [Tenancy](/docs/interfaces/core/tenancy) |
+| `/tenant-lifecycle` | Producer admission and closure before tenant deletion | [Tenancy](/docs/interfaces/core/tenancy#tenant-lifecycle-admission) |
+| `/data-controllers` | The built-in members and roles data controllers | [Tenancy](/docs/interfaces/core/tenancy) |
+| `/invites` | Inviting a user into a tenant | [Invites](/docs/interfaces/core/invites) |
+| `/invite-extensions` | Invite form contributions, callbacks and availability | [Invites](/docs/interfaces/core/invites#registerinviteextension) |
+| `/invite-resolution` | Durable terminal decisions and retryable effects | [Invites](/docs/interfaces/core/invites#durable-invite-resolution) |
+| `/hooks` | The `Hook` enum, handlers and dispatch | [Hooks](/docs/interfaces/core/hooks) |
+| `/tenant-export` | The tenant data export archive, contribution and manifest types, re-exported from `/hooks` | [Hooks](/docs/interfaces/core/hooks) |
+| `/realtime` | Page topics, publishing and backend subscription | [Realtime](/docs/interfaces/core/realtime) |
+| `/quick-actions` | Command-palette entries | [Quick Actions](/docs/interfaces/core/quick-actions) |
+| `/layout-banners` | Global banners under the dashboard header | [Layout Banners](/docs/interfaces/core/layout-banners) |
+| `/uploads` | Signed upload tokens for the file and image fields of a serialized component | [Pages and Modules](/docs/interfaces/core/pages-and-modules) |
+| `/types` | `MaybePromise`, the one shared type alias | [Pages and Modules](/docs/interfaces/core/pages-and-modules) |
+| `/api-base-url`, `/client-base-url` | `GetApiBaseUrl`, `GetClientBaseUrl`: the public origins of the API and the dashboard | [Pages and Modules](/docs/interfaces/core/pages-and-modules#public-urls) |
+| `/client-ip` | `getClientIp`, `ResolveClientIp`: a request's client address behind the trusted proxies | [Pages and Modules](/docs/interfaces/core/pages-and-modules#client-address) |
+
+Paths under `internal/`, symbols tagged `@internal`, and `internal` namespaces are implementation wiring, not supported consumer APIs. The wildcard export does not change that boundary.
+
+## Documentation Sections
+
+- [Pages and Modules](/docs/interfaces/core/pages-and-modules) - Declare pages, group them into categories, own a branch of the sidebar with a module, and extend a page from another one
+- [Components](/docs/interfaces/core/components) - Build serializable components, declare actions and watches
+- [Permissions](/docs/interfaces/core/permissions) - Register permissions, compute a user's effective set, guard routes
+- [Tenancy](/docs/interfaces/core/tenancy) - Schemas, the tenancy tables, tenant-scoped models and access gates
+- [Invites](/docs/interfaces/core/invites) - Bring a user into a tenant by email
+- [Hooks](/docs/interfaces/core/hooks) - React to platform events and contribute to the tenant data export
+- [Realtime](/docs/interfaces/core/realtime) - Bind topics to pages, publish messages and subscribe to them
+- [Quick Actions](/docs/interfaces/core/quick-actions) - Contribute entries to the command palette
+- [Layout Banners](/docs/interfaces/core/layout-banners) - Show a global banner under the dashboard header, decided per request

package/docs/1.core/10.layout-banners.md

@@ -0,0 +1,133 @@
+---
+title: "Layout Banners"
+description: "A layout banner is a global message the backend adds under the dashboard header: a colored strip carrying a line of text and its link buttons, or a component of your frontend layer."
+---
+
+# Layout Banners
+
+## Overview
+
+A layout banner is a global message the backend adds under the dashboard header: a colored strip carrying a line of text and its link buttons, or a component of your frontend layer. It renders on every page of the dashboard layout — tenant pages and the module back-office pages under `/modules` alike — and banners stack by `order`.
+
+Whether a banner shows is decided per request, on the server, while the site layout is built. The answer is part of the server-rendered page, so a banner never flashes in or out after hydration.
+
+Everything lives in `@antelopejs/interface-dms/layout-banners`.
+
+## Register a Banner
+
+`RegisterLayoutBanner(info)` registers the banner and returns a function removing it. Register at import time, next to the state the banner reports on; the registration is dropped automatically when your module stops.
+
+```typescript
+import {
+  LayoutBannerVariant,
+  RegisterLayoutBanner,
+} from "@antelopejs/interface-dms/layout-banners";
+import { isMaintenanceScheduled } from "./maintenance";
+
+RegisterLayoutBanner({
+  key: "my-app:maintenance",
+  variant: LayoutBannerVariant.WARNING,
+  text: "$my_app.banners.maintenance",
+  order: 10,
+  dismissible: true,
+  visible: async ({ tenantId }) => isMaintenanceScheduled(tenantId),
+});
+```
+
+The text can be a [composed text](/docs/components/block-fundamentals#composed-texts) — an i18n key and the raw values it names, written in the reader's language — and `actions` adds link buttons after it, the last one leading:
+
+```typescript
+RegisterLayoutBanner({
+  key: "my-app:maintenance",
+  variant: LayoutBannerVariant.WARNING,
+  text: {
+    key: "my_app.banners.maintenance_at", // "Maintenance {date}"
+    params: { date: { type: "datetime", value: "2026-10-12T22:00:00Z" } },
+  },
+  actions: [{ label: "$my_app.banners.status", to: "https://status.example.com" }],
+});
+```
+
+## Resolve the Content per Request
+
+When the message names the state that makes the banner show — the invoice that failed, its amount, the day the workspace is suspended — `resolve(context)` builds the text and the buttons for each request, or answers `undefined` to hide the banner. It replaces `visible`: one read decides both.
+
+```typescript
+RegisterLayoutBanner({
+  key: "saas:past-due",
+  variant: LayoutBannerVariant.ERROR,
+  resolve: async ({ tenantId }) => {
+    const invoice = await openInvoice(tenantId);
+    if (!invoice) return undefined;
+    return {
+      text: {
+        key: "saas.banner.past_due", // "Invoice {invoice} of {amount} failed, retry {date}"
+        params: {
+          invoice: invoice.number,
+          amount: { type: "money", value: invoice.amountDue, currency: invoice.currency },
+          date: { type: "date", value: invoice.nextAttemptAt, format: "day" },
+        },
+      },
+      actions: [{ label: "$saas.banner.pay", to: "/settings/workspace/billing?pay=1" }],
+    };
+  },
+});
+```
+
+The server sends the raw values; the browser formats them for the reader's language, time zone and clock, so the resolver never formats text. A banner like this one needs no frontend component.
+
+## Mount a Component
+
+A banner can mount a global component of your [frontend layer](/docs/building/frontend-layer) instead of a text. The DMS still draws the chrome around it — color, icon, close button and ARIA role — and passes `props` to the component:
+
+```typescript
+RegisterLayoutBanner({
+  key: "my-app:trial",
+  variant: LayoutBannerVariant.INFO,
+  component: "MyAppTrialBanner",
+  props: { upgradeUrl: "/settings/billing" },
+  visible: ({ isOwner }) => isOwner,
+});
+```
+
+Re-registering a `key` replaces the banner.
+
+## `LayoutBannerInfo`
+
+| Field | Type | Description |
+| ----- | ---- | ----------- |
+| `key` | `string` | Unique across the deployment. Required. Also what a dismissal remembers: give a banner a new key when it must show again to users who dismissed it. |
+| `variant` | `LayoutBannerVariant` | `"info"`, `"warning"` or `"error"`. Required. Picks the color, the default icon and the ARIA role. |
+| `text` | `string \| ComposedText` | The message. A `$`-prefixed value resolves as an i18n key; a `ComposedText` is written in the reader's language. Exclusive with `component` and `resolve`; one of the three is required. |
+| `actions` | `BlockLinkAction[]` | Link buttons after `text`, the last one leading. Labels follow the `$` convention. |
+| `component` | `string` | Name of a global component rendered as the banner's content. Exclusive with `text` and `resolve`. |
+| `props` | `Record<string, unknown>` | Props passed to `component`. Must be serializable. |
+| `order` | `number` | Stack order, ascending from the top. Defaults to `0`; ties keep the registration order. |
+| `icon` | `string` | Leading icon. Defaults to one matching the variant. |
+| `dismissible` | `boolean` | Whether the user can close the banner. Defaults to `false`. |
+| `visible` | `LayoutBannerVisibility` | Decides per request whether a `text` or `component` banner shows. Absent means always. |
+| `resolve` | `LayoutBannerResolver` | Builds `{ text, actions? }` per request, or `undefined` to hide the banner. Exclusive with `text`, `component` and `visible`. |
+
+## Visibility
+
+`visible(context)` returns a boolean, or a promise of one; `resolve(context)` returns a `LayoutBannerContent` (`{ text, actions? }`), `undefined`, or a promise of either. They run server-side for every site layout request, all resolvers together, so the request waits for the slowest one rather than for their sum. A resolver that throws or does not answer within two seconds hides its banner for that request, as does a `visible` returning anything but `true` or a `resolve` answering no text; the other banners are unaffected.
+
+### `LayoutBannerContext`
+
+| Field | Type | Description |
+| ----- | ---- | ----------- |
+| `user` | `User \| undefined` | The caller; `undefined` for an unauthenticated request. |
+| `tenantId` | `string` | The tenant the site layout is built for. |
+| `permissions` | `Set<string>` | The caller's effective permissions in the tenant. |
+| `isOwner` | `boolean` | Whether the caller holds the wildcard permission. |
+| `isTenantAccessDenied` | `boolean` | Whether a [tenant access gate](/docs/interfaces/core/tenancy) currently refuses the caller. |
+
+Unlike product surfaces, a banner reads the permissions a denying access gate would hide: telling a suspended or past-due workspace why is exactly what a banner is for. Check `isTenantAccessDenied` when the two situations call for different banners.
+
+The resolvers run whenever a client fetches its site layout — on a full page load and after a menu invalidation. When the state a resolver reads changes, call `NotifyMenuChanged(tenantId)` from `@antelopejs/interface-dms/page` so the connected clients of that tenant re-fetch it and the banner appears or goes without a reload.
+
+## Rendering
+
+Banners render under the header of the dashboard layout, full width, in `order`, a text banner's `actions` on its right. Each one is its own live region: `error` banners carry `role="alert"`, `info` and `warning` banners `role="status"`.
+
+A dismissible banner shows a close button. The dismissal lasts for the browser session and is kept in the `dms-dismissed-banners` cookie, which the server reads too, so a dismissed banner is already absent from the server-rendered page. A banner that is not dismissible ignores any dismissal recorded under its key.