@antelopejs/interface-dms 0.7.2 → 0.7.3

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## v0.7.3
+
+[compare changes](https://github.com/AntelopeJS/dms/compare/interface-v0.7.2...v0.7.3)
+
+### 🚀 Enhancements
+
+- **preview:** Share simple options and document real outcomes ([#339](https://github.com/AntelopeJS/dms/pull/339))
+
+### 🩹 Fixes
+
+- **docs:** Use a sandbox-compatible temporary build database ([#326](https://github.com/AntelopeJS/dms/pull/326))
+- Install DMS frontend with the root workspace ([#322](https://github.com/AntelopeJS/dms/pull/322))
+- **modules:** Top-align card content and place readouts below descriptions ([#328](https://github.com/AntelopeJS/dms/pull/328))
+- **modules:** Reuse registered names in the store ([#330](https://github.com/AntelopeJS/dms/pull/330))
+- **playground:** Use the workspace CLI and compatible core interface ([#331](https://github.com/AntelopeJS/dms/pull/331))
+
+### 📖 Documentation
+
+- Create the DMS demo through the CLI in quickstart ([#327](https://github.com/AntelopeJS/dms/pull/327))
+
+### 🏡 Chore
+
+- **release:** @antelopejs/dms v0.9.3 ([1aaf5404](https://github.com/AntelopeJS/dms/commit/1aaf5404))
+- **docs:** Capture temporary MongoDB startup diagnostics ([#325](https://github.com/AntelopeJS/dms/pull/325))
+- **playground:** Refresh compatible dependencies ([#329](https://github.com/AntelopeJS/dms/pull/329))
+
+### ❤️ Contributors
+
+- Antony Rizzitelli <rizzitelli.antony@pm.me>
+
 ## v0.7.2
 
 [compare changes](https://github.com/AntelopeJS/dms/compare/interface-v0.7.1...v0.7.2)

package/dist/base/block-registry/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./helpers";
+export * from "./presentation";
 export * from "./registry";
 export * from "./types";

package/dist/base/block-registry/index.js

@@ -15,6 +15,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./helpers"), exports);
+__exportStar(require("./presentation"), exports);
 __exportStar(require("./registry"), exports);
 __exportStar(require("./types"), exports);
 //# sourceMappingURL=index.js.map

package/dist/base/block-registry/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/base/block-registry/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,4CAA0B;AAC1B,6CAA2B;AAC3B,0CAAwB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/base/block-registry/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,4CAA0B;AAC1B,iDAA+B;AAC/B,6CAA2B;AAC3B,0CAAwB"}

package/dist/base/block-registry/presentation.d.ts

@@ -0,0 +1,21 @@
+import type { BlockOptionUi, BlockTypeDescriptor } from "./types";
+/** The hints needed to decide whether an editor offers an option in simple mode. */
+export interface SimpleBlockOption {
+    ui?: Pick<BlockOptionUi, "hidden" | "advanced" | "derivedFrom"> & {
+        group?: string;
+    };
+}
+/** Shared simple-mode policy; data binding remains available in the builder. */
+export declare function IsSimpleBlockOption(option: SimpleBlockOption): boolean;
+/**
+ * Dotted paths a standalone preview can edit without replacing data or opaque
+ * values. Objects are descended into, never offered as JSON. Only enum arrays
+ * in presentation/behavior groups and closed-key scalar records are editable
+ * collections; rows, slots and other structural collections remain fixed.
+ * Scalar unions have typed controls; a rich union with an explicit scalar
+ * widget (e.g. translated text or chart color) offers that scalar only.
+ *
+ * Fixed factory options exclude their entire top-level subtree. The returned
+ * paths reference `config`; consumers must not keep another copy of the schema.
+ */
+export declare function BlockPresentationPaths(descriptor: Pick<BlockTypeDescriptor, "config" | "fixedOptions">): string[];

package/dist/base/block-registry/presentation.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IsSimpleBlockOption = IsSimpleBlockOption;
+exports.BlockPresentationPaths = BlockPresentationPaths;
+/** Shared simple-mode policy; data binding remains available in the builder. */
+function IsSimpleBlockOption(option) {
+    const ui = option.ui;
+    return (!ui?.hidden && !ui?.advanced && !ui?.derivedFrom && ui?.group !== "advanced");
+}
+const PRESENTATION_WIDGETS = new Set([
+    "text",
+    "textarea",
+    "number",
+    "range",
+    "switch",
+    "select",
+    "segmented",
+    "icon",
+    "color",
+    "url",
+]);
+function isPresentation(option) {
+    return (IsSimpleBlockOption(option) &&
+        option.ui?.group !== "data" &&
+        !option.truncated &&
+        (!option.ui?.widget || PRESENTATION_WIDGETS.has(option.ui.widget)));
+}
+// A scalar widget can replace a union's structured value, so a restricted
+// descendant in any branch forbids offering that parent too.
+function hasRestrictedHints(option) {
+    if (!IsSimpleBlockOption(option) ||
+        option.ui?.group === "data" ||
+        (option.ui?.widget && !PRESENTATION_WIDGETS.has(option.ui.widget)))
+        return true;
+    const children = [
+        ...Object.values(option.properties ?? {}),
+        ...[option.items, option.values, option.keys].filter((child) => !!child),
+        ...(option.oneOf ?? []),
+        ...(option.allOf ?? []),
+        ...(option.prefixItems ?? []),
+    ];
+    return children.some(hasRestrictedHints);
+}
+function isScalar(option) {
+    if (option.truncated || option.allOf || option.prefixItems)
+        return false;
+    return (["string", "number", "boolean"].includes(option.type) ||
+        (option.type === "union" &&
+            !!option.oneOf?.length &&
+            option.oneOf.every(isScalar)));
+}
+function hasValueEditor(option) {
+    if (hasRestrictedHints(option))
+        return false;
+    if (isScalar(option))
+        return true;
+    if (option.type === "array") {
+        // Content collections can carry demonstration rows even when enum-valued.
+        return (["appearance", "behavior", "layout", "features"].includes(option.ui?.group ?? "") &&
+            !!option.items?.enum?.length &&
+            isScalar(option.items));
+    }
+    if (option.type === "record") {
+        return (!!option.keys?.enum?.length && !!option.values && isScalar(option.values));
+    }
+    // Rich text and palettes can still use the scalar widget their schema declares.
+    return (option.type === "union" &&
+        !!option.ui?.widget &&
+        !!option.oneOf?.some(isScalar));
+}
+/**
+ * Dotted paths a standalone preview can edit without replacing data or opaque
+ * values. Objects are descended into, never offered as JSON. Only enum arrays
+ * in presentation/behavior groups and closed-key scalar records are editable
+ * collections; rows, slots and other structural collections remain fixed.
+ * Scalar unions have typed controls; a rich union with an explicit scalar
+ * widget (e.g. translated text or chart color) offers that scalar only.
+ *
+ * Fixed factory options exclude their entire top-level subtree. The returned
+ * paths reference `config`; consumers must not keep another copy of the schema.
+ */
+function BlockPresentationPaths(descriptor) {
+    const paths = [];
+    const walk = (config, prefix) => {
+        for (const [key, option] of Object.entries(config)) {
+            // Dots and prototype keys cannot be represented safely by path editors.
+            if (key.includes(".") ||
+                ["__proto__", "constructor", "prototype"].includes(key))
+                continue;
+            if (!prefix && Object.hasOwn(descriptor.fixedOptions ?? {}, key))
+                continue;
+            if (!isPresentation(option))
+                continue;
+            const path = prefix ? `${prefix}.${key}` : key;
+            if (option.allOf || option.prefixItems)
+                continue;
+            if (option.type === "object" && option.properties) {
+                walk(option.properties, path);
+                continue;
+            }
+            if (hasValueEditor(option))
+                paths.push(path);
+        }
+    };
+    walk(descriptor.config, "");
+    return paths;
+}
+//# sourceMappingURL=presentation.js.map

package/dist/base/block-registry/presentation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"presentation.js","sourceRoot":"","sources":["../../../src/base/block-registry/presentation.ts"],"names":[],"mappings":"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"}

package/dist/base/placeholder.js

@@ -15,11 +15,11 @@ exports.PlaceholderSchema = zod_1.z.object({
     height: (0, block_registry_1.ui)(zod_1.z
         .string()
         .optional()
-        .describe("How tall the box is, such as 200px; left empty, it fills its place."), { label: "Height", group: "appearance" }),
+        .describe("How tall the box is, such as 200px; left empty, it fills its place."), { label: "Height", group: "appearance", advanced: true }),
     width: (0, block_registry_1.ui)(zod_1.z
         .string()
         .optional()
-        .describe("How wide the box is, such as 300px; left empty, it fills its column."), { label: "Width", group: "appearance" }),
+        .describe("How wide the box is, such as 300px; left empty, it fills its column."), { label: "Width", group: "appearance", advanced: true }),
 });
 /**
  * Placeholder - Development Placeholder Component

package/dist/base/placeholder.js.map

@@ -1 +1 @@
-{"version":3,"file":"placeholder.js","sourceRoot":"","sources":["../../src/base/placeholder.ts"],"names":[],"mappings":";;;AAiEA,kCASC;AA1ED,4CAAgD;AAChD,6BAAwB;AACxB,qDAA+E;AAE/E,MAAM,0BAA0B,GAAG,iBAAiB,CAAC;AAwBrD,yCAAyC;AAC5B,QAAA,iBAAiB,GAAG,OAAC,CAAC,MAAM,CAAC;IACxC,KAAK,EAAE,IAAA,mBAAE,EAAC,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,4BAA4B,CAAC,EAAE;QACtE,KAAK,EAAE,OAAO;QACd,KAAK,EAAE,SAAS;KACjB,CAAC;IACF,MAAM,EAAE,IAAA,mBAAE,EACR,OAAC;SACE,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACP,qEAAqE,CACtE,EACH,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,YAAY,EAAE,CACzC;IACD,KAAK,EAAE,IAAA,mBAAE,EACP,OAAC;SACE,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACP,sEAAsE,CACvE,EACH,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,CACxC;CACF,CAA+C,CAAC;AAEjD;;;;;;;;;;GAUG;AACH,SAAgB,WAAW,CACzB,OAA4B;IAE5B,OAAO,IAAI,4BAAgB,CAAqB,0BAA0B,CAAC;SACxE,OAAO,CAAC,EAAE,GAAG,OAAO,EAAE,CAAC;SACvB,IAAI,CAAC;QACJ,IAAI,EAAE,aAAa;QACnB,IAAI,EAAE,gBAAgB;KACvB,CAAC,CAAC;AACP,CAAC;AAED,IAAA,kCAAiB,EAAC;IAChB,IAAI,EAAE,aAAa;IACnB,aAAa,EAAE,0BAA0B;IACzC,MAAM,EAAE,yBAAiB;IACzB,IAAI,EAAE;QACJ,IAAI,EAAE,aAAa;QACnB,IAAI,EAAE,gBAAgB;QACtB,WAAW,EAAE,kDAAkD;QAC/D,KAAK,EAAE,QAAQ;KAChB;CACF,CAAC,CAAC"}
+{"version":3,"file":"placeholder.js","sourceRoot":"","sources":["../../src/base/placeholder.ts"],"names":[],"mappings":";;;AAiEA,kCASC;AA1ED,4CAAgD;AAChD,6BAAwB;AACxB,qDAA+E;AAE/E,MAAM,0BAA0B,GAAG,iBAAiB,CAAC;AAwBrD,yCAAyC;AAC5B,QAAA,iBAAiB,GAAG,OAAC,CAAC,MAAM,CAAC;IACxC,KAAK,EAAE,IAAA,mBAAE,EAAC,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,4BAA4B,CAAC,EAAE;QACtE,KAAK,EAAE,OAAO;QACd,KAAK,EAAE,SAAS;KACjB,CAAC;IACF,MAAM,EAAE,IAAA,mBAAE,EACR,OAAC;SACE,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACP,qEAAqE,CACtE,EACH,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,IAAI,EAAE,CACzD;IACD,KAAK,EAAE,IAAA,mBAAE,EACP,OAAC;SACE,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACP,sEAAsE,CACvE,EACH,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,IAAI,EAAE,CACxD;CACF,CAA+C,CAAC;AAEjD;;;;;;;;;;GAUG;AACH,SAAgB,WAAW,CACzB,OAA4B;IAE5B,OAAO,IAAI,4BAAgB,CAAqB,0BAA0B,CAAC;SACxE,OAAO,CAAC,EAAE,GAAG,OAAO,EAAE,CAAC;SACvB,IAAI,CAAC;QACJ,IAAI,EAAE,aAAa;QACnB,IAAI,EAAE,gBAAgB;KACvB,CAAC,CAAC;AACP,CAAC;AAED,IAAA,kCAAiB,EAAC;IAChB,IAAI,EAAE,aAAa;IACnB,aAAa,EAAE,0BAA0B;IACzC,MAAM,EAAE,yBAAiB;IACzB,IAAI,EAAE;QACJ,IAAI,EAAE,aAAa;QACnB,IAAI,EAAE,gBAAgB;QACtB,WAAW,EAAE,kDAAkD;QAC/D,KAAK,EAAE,QAAQ;KAChB;CACF,CAAC,CAAC"}

package/docs/1.core/2.pages-and-modules.md

@@ -9,6 +9,8 @@ description: "Pages are controller classes registered into a navigation tree of
 
 A page is a controller class. `PageController(id, options, layout?)` builds a base class bound to a URL, `@RegisterPage()` records it, and the components declared as static fields on the class become the page's serialized layout. Categories group pages into the sidebar tree, and modules group a whole set of pages and categories under their own root.
 
+Building your first screen? Follow [Pages & components](/docs/building/pages-and-components) first. This reference covers registration, identifiers, and lifecycle rules. The guide also shows [page-extension placement](/docs/building/pages-and-components#extending-another-modules-page) in the running playground.
+
 Everything on this page lives in `@antelopejs/interface-dms/page`.
 
 Registration happens at import time: the `@RegisterPage()` decorator runs when the file is loaded, so the order in which you import page files determines the order in which pages, categories and their permissions are registered.

package/docs/1.core/5.tenancy.md

@@ -9,6 +9,8 @@ description: "The DMS serves several tenants from one backend."
 
 The DMS serves several tenants from one backend. Tenant-owned tables live in a per-tenant schema, and a model handle is bound to one tenant when you obtain it: `GetModel(TenantMemberModel, tenantId)` reads and writes that tenant's rows only. No query filters rows by tenant, and no table carries a `tenantId` column — the isolation is in the handle.
 
+For a first implementation, follow [Multi-tenant data](/docs/auth-and-tenancy/multi-tenant): register the table in the tenant schema, protect the route, and inject a tenant-bound model. Use this reference for the schema constants and lifecycle contracts. **Resolving a tenant id is not an authorization check**; `getRequestTenantId` must run behind authentication.
+
 The tenancy surface spans several subpaths:
 
 | Subpath | Contains |

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

@@ -60,7 +60,7 @@ Within `types`, four modules are outside that subpath's barrel and are imported
 - **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.
+- **A chart and widget set with a shared period scope** — Thirteen 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.

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

@@ -9,6 +9,13 @@ description: "Grid, stacks, tabs, guard, placeholder and the page layouts that h
 
 Layout components hold other components. They come in two kinds.
 
+| What you want to change | Use |
+| --- | --- |
+| The frame around a page: dashboard, settings, or no navigation | A page layout (`DefaultLayout`, `SettingsLayout`, `EmptyLayout`). |
+| The arrangement of blocks inside the page | A container builder (`Grid`, stacks, or tabs). |
+
+See the [settings-page screenshot](/docs/building/settings-pages) for the frame and the [container previews](/docs/components/layout-and-containers) for the blocks inside it. The reference below gives their exact contracts.
+
 **Containers** are builders: `Grid`, `GridRow`, `HStack`, `VStack`, `Spacer`, `Tab`, `Guard` and `Placeholder` return a `ComponentBuilder`, and you nest components inside them with `.child(id, component)`. They are assigned to a static field of a page class like any other component.
 
 **Page layouts** are not builders: `DefaultLayout`, `FormPageLayout`, `SettingsLayout` and `EmptyLayout` return a plain `ComponentInfo` and are passed as the third argument of `PageController` — or as the `layout` option of a page or category, the default of everything declared under it — to say how the page's chrome is drawn.
@@ -428,4 +435,3 @@ Since the return value is an ordinary builder, `.options()`, `.child()`, `.meta(
 `CustomComponent` is also how a table view's `formContainer.pages.*.customPage` option is used: you register your own page carrying a custom component at the slug the table view would otherwise generate — declare that slug as the entry's `urlSlug`, which is taken relative to the page as it stands — see [Tables](/docs/interfaces/base/tables).
 
 ## Next Steps
-

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

@@ -13,6 +13,8 @@ The taxonomy is two levels deep. A **category** groups related notifications, a
 
 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.
 
+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.

package/docs/4.notifications/2.categories-and-subjects.md

@@ -13,6 +13,8 @@ You declare categories and subjects by calling `NotificationCategory()` and `Not
 
 Declarations are values, not decorators: they run when the module that contains them is imported. Declare them at the top level of a module that is imported during startup, so the taxonomy is complete before the first notification is sent.
 
+The [notification preferences walkthrough](/docs/auth-and-tenancy/authentication#notification-preferences) shows the System category expanded, its locked General subject, and the Playground category and subject switched off. The Email column is marked Soon: these controls currently manage in-app delivery, not transactional authentication emails.
+
 ## Declaring a Category
 
 `NotificationCategory(id, category)` registers a category and returns the resulting `NotificationCategoryInfo`.

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

@@ -9,6 +9,8 @@ description: "Build a notification, then send it to users, roles or everyone, wi
 
 Sending happens in two steps. `Notification()` starts a builder you fill field by field; `.build()` closes it and gives you a `SendableNotification`, which carries the dispatch methods.
 
+For the visible result, see the [single-recipient notification and second-session update](/docs/auth-and-tenancy/authentication#read-notifications). The walkthrough distinguishes delivery from read state and shows [a disabled subject preventing a new delivery](/docs/auth-and-tenancy/authentication#notification-preferences).
+
 ```typescript
 import {
   GeneralSubject,

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

@@ -332,6 +332,20 @@ The `head` slot adds elements to the document head (a `<title>`, a viewport `<me
 
 The logo is `branding.logo.email.light` from the app config, or `branding.logo.default.light` without an email logo, made absolute against `public.dms.clientBaseUrl` when it starts with `/`. A recipient's mail client fetches it from the internet, and Gmail and Outlook refuse SVG: with `publicLogoOnly`, the layout leaves the logo out when it is an SVG, is not an `http(s)` URL, or is served from a host a mail client cannot reach (`localhost`, `*.local`, `*.internal`, a loopback, private or link-local address), rather than drawing a broken image. Set a PNG logo and a public `clientBaseUrl` for it to show. A `branding.logo.email.dark` goes through the same rules and, when it differs from the light one, is offered to the mail clients in dark mode: the logo is then drawn as `<picture><source media="(prefers-color-scheme: dark)" srcset="…"><img …></picture>`, and a client that ignores the source draws the light image. The same check is exported as `emailLogoUrl(logoPath, clientBaseUrl)` from `#dms-layout/app/emails/components/index`, for a template that draws its own header.
 
+### A rendered custom digest
+
+The playground's `EmailPlaygroundDigest` reuses this layout with a preheader, `divider="false"` and `public-logo-only`. Here is its actual rendered HTML in English, with fictitious activity for Alex Morgan. With the default SVG logo, the header image is intentionally absent.
+
+![Rendered custom playground digest without a logo or footer divider](../images/emails-digest.png)
+
+The same template below uses two demonstration PNG logos supplied through the app config. The light-mode capture selects the teal logo; the dark-mode capture selects the navy logo. The reserved demo hostname is mapped to a local image server for these captures, so they do not establish that a recipient can fetch the logo from the internet.
+
+![Custom digest with the light demonstration logo in browser light mode](../images/emails-digest-logo-light.png)
+
+![Custom digest with the dark demonstration logo in browser dark mode](../images/emails-digest-logo-dark.png)
+
+Dark mode changes the selected logo, not the card: `EmailLayout` keeps its white card and pale background in both browser modes. Without a dark logo source, the unbranded examples look identical in both modes. These captures use the real frontend render endpoint and show the returned HTML directly, not the playground's code viewer. No email is sent. Mail clients may strip `<picture>`, block remote images or transform colors; test delivery and appearance in your target clients separately.
+
 ## Sending Rendered HTML as Email
 
 Rendering and sending are separate steps. Render with `GenerateHtml`, then hand the string to the standard AntelopeJS email interface, which needs an implementing module (such as `@antelopejs/nodemailer`) loaded in your project configuration.

package/docs/5.html-render/2.built-in-emails.md

@@ -39,6 +39,56 @@ What the backend passes to each template. A template that replaces a built-in on
 
 `userName` is the user's name, or their email address when they have none. `expiresInHours` is the lifetime as a number, for the template to word in the recipient's language; `expiresIn` is the same lifetime already worded in English (`24 hours`), kept for templates written before `expiresInHours`.
 
+## Rendered examples
+
+These captures show HTML returned by the DMS frontend's real render endpoint, opened directly in Chromium, rather than the playground's HTML code viewer. All names, codes, addresses and links are fictitious; no email is sent. The default SVG logo is intentionally omitted by `publicLogoOnly`.
+
+### EmailUserValidation
+
+The signup email asks Alex to verify their address with a six-digit code, valid for 24 hours.
+
+![Rendered signup verification email with a six-digit code and a 24-hour expiry](../images/emails-user-validation.png)
+
+### EmailResetPassword
+
+The password-reset email uses a separate code and the configured recovery lifetime: two hours in this example.
+
+![Rendered password-reset email with a two-hour code expiry](../images/emails-reset-password.png)
+
+### EmailTwoFactor
+
+The second-factor email provides a sign-in code. Its footer tells the recipient to ignore the message if they did not attempt to sign in.
+
+![Rendered email second-factor verification code](../images/emails-two-factor.png)
+
+### EmailAdminInvite
+
+The invitation names the inviter, workspace and platform when they are known. Its button uses a fictitious destination here.
+
+![Rendered invitation from Jordan Lee to Northwind Studio on Acme Dashboard](../images/emails-admin-invite.png)
+
+### EmailChangeVerification
+
+The new address receives the code that confirms the sign-in email change.
+
+![Rendered confirmation email naming the new sign-in address and verification code](../images/emails-change-verification.png)
+
+### EmailChangeNotice
+
+The current address receives a notice, not the confirmation code. It tells the recipient what to do if they did not request the change.
+
+![Rendered security notice sent to the current sign-in address](../images/emails-change-notice.png)
+
+### EmailExportReady
+
+A complete export provides a download button and an expiry. A partial export also names the sources that could not be included.
+
+![Rendered complete data-export email with a download button and expiry](../images/emails-export-ready.png)
+
+![Rendered partial data-export email warning that Activity history is missing](../images/emails-export-partial.png)
+
+These are browser previews, not Gmail, Outlook or Apple Mail compatibility tests. See [Email Layout](/docs/interfaces/html-render/introduction#email-layout) for the custom digest, logo variants and the limits of dark-mode support.
+
 ## Language
 
 Each email is written in the recipient's language: the account's `language`, or for an invitation the language it was sent in. English and French are supported; any other language falls back to English.

package/docs/index.md

@@ -19,6 +19,15 @@ The DMS ships one public AntelopeJS interface package, `@antelopejs/interface-dm
 
 This section is the contract reference: the exact symbol names, options and return types, grouped by domain. The DMS guide covers the same ground task by task, organised around what you are building.
 
+If you are learning the DMS, start with the [Quickstart](/docs/getting-started/quickstart) and [Pages & components](/docs/building/pages-and-components). Return here when you need an import path, a signature, or the exact behavior of an option; you do not need to read every domain before building a page.
+
+| Task | Guide with examples | Contract reference |
+| --- | --- | --- |
+| Build a page and choose its layout | [Pages & components](/docs/building/pages-and-components) | [Pages and modules](/docs/interfaces/core/pages-and-modules), [Layout](/docs/interfaces/base/layout) |
+| Add workspace settings | [Settings pages](/docs/building/settings-pages) | [Page access](/docs/interfaces/core/pages-and-modules#page-access) |
+| Protect a route and scope its data | [Auth & tenancy](/docs/auth-and-tenancy/overview) | [Authentication](/docs/interfaces/auth/authentication), [Tenancy](/docs/interfaces/core/tenancy) |
+| Extend another module's screen | [Page extensions](/docs/building/pages-and-components#extending-another-modules-page) | [Extend a page](/docs/interfaces/core/pages-and-modules#extend-a-page-from-another-module) |
+
 Separately published extension interfaces have their own [module interface references](/docs/modules#interface-references), including Builder. This page covers `@antelopejs/interface-dms` itself.
 
 ## One installed copy

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/interface-dms",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "description": "Public AntelopeJS interfaces of the DMS: pages, components, permissions, tenancy, auth, notifications and HTML rendering.",
   "keywords": [
     "antelopejs",
@@ -33,6 +33,7 @@
   "scripts": {
     "build": "rimraf dist && tsc",
     "typecheck": "tsc --noEmit",
+    "test": "pnpm run build && node --test tests/*.test.cjs",
     "lint": "oxlint && oxfmt --check .",
     "lint:fix": "oxlint --fix --max-warnings=1000000 && oxfmt .",
     "format": "oxfmt .",