@antelopejs/interface-dms-builder 0.3.1 → 0.4.0

package/docs/4.page-operations.md

@@ -1,14 +1,18 @@
-# Page Operations
+---
+title: "Page operations"
+description: "The operations that list, create, configure, move and delete pages, categories and the blocks of a page, with their inputs and refusals."
+mode: reference
+---
 
 ## Overview
 
-Page operations cover everything that lives in a page file: the pages themselves, the categories they hang from, and the block tree inside each page. Reads (`ListPages`, `ListCategories`, `GetPageStructure`) tell you what is there; mutations (`CreatePage`, `AddBlock`, `MoveBlock`, …) rewrite the source and return the staged `FileChange` list.
+Page operations cover the pages, the categories that hold them, and the block tree inside each page. The reads are `ListPages`, `ListCategories` and `GetPageStructure`. The mutations, such as `CreatePage`, `AddBlock` and `MoveBlock`, rewrite the source and return the list of `FileChange` entries they wrote.
 
-Every mutation returns an `OpResult`, so branch on `ok` before touching `data`. The refs and shapes these operations trade in are described in [Addressing and Structure](./2.addressing-and-structure.md); the errors and warnings they return are described in [Results and Errors](./8.results-and-errors.md).
+Every mutation returns an `OpResult`, so branch on `ok` before you read `data`. [Addressing and structure](./2.addressing-and-structure.md) describes the refs and shapes these operations take and return. [Results and errors](./8.results-and-errors.md) describes their errors and warnings.
 
-## List Pages and Categories
+## List pages and categories
 
-`ListPages` and `ListCategories` are plain reads: they return arrays, not an `OpResult`.
+`ListPages` and `ListCategories` are plain reads. They return arrays, not an `OpResult`.
 
 ```typescript
 import {
@@ -24,9 +28,9 @@ for (const page of pages) {
 }
 ```
 
-## Read a Page's Structure
+## Read a page's structure
 
-`GetPageStructure(ref)` returns the page's metadata, its block tree and its queries, wrapped in an `OpResult<PageStructure>`. Being a read, its `changes` array is empty.
+`GetPageStructure(ref)` returns the metadata, the block tree and the queries of the page in an `OpResult<PageStructure>`. Its `changes` array is empty, because the operation is a read.
 
 ```typescript
 import { GetPageStructure } from "@antelopejs/interface-dms-builder";
@@ -39,11 +43,11 @@ if (!result.ok) {
 const { page, blocks, queries, version } = result.data;
 ```
 
-Keep `version`: passing it as `expectedVersion` on the next mutation turns the write into a conditional one.
+Keep `version`. Passed as `expectedVersion` on the next mutation, it makes the write conditional.
 
-## Refresh the Source Index
+## Refresh the source index
 
-The builder keeps an index of the project's source. Mutations invalidate it themselves, so you only need `RefreshSourceIndex` after something *else* changed the files — a hand edit, a checkout, a generator run.
+The builder keeps an index of the project's source and a cached catalog. Every mutation drops the index after it writes. A read also rescans by itself when a file the index read has changed or disappeared since the scan, after a hand edit or a checkout for example. The index does not see a new file until a file it already read changes, such as the barrel that imports the new file. It never drops the catalog. Call `RefreshSourceIndex` after such a change, and after a change to the components the catalog describes.
 
 ```typescript
 import { RefreshSourceIndex } from "@antelopejs/interface-dms-builder";
@@ -56,15 +60,15 @@ await RefreshSourceIndex({ page: "/dashboard" }); // source index only
 
 | Option | Type | Description |
 | --- | --- | --- |
-| `page` | `PageRef` | Keep the cached catalog. Omit the scope entirely to drop the catalog as well. |
+| `page` | `PageRef` | Keep the cached catalog. Without `page`, the call drops the catalog as well. |
 
-The scope does not narrow the source index: it is invalidated in full either way, and naming a page only spares the catalog cache. Pass a page when you know the change was confined to page source and left the component catalog alone — it saves rescanning the catalog, not the project.
+The scope does not narrow the source index. The call drops the whole index either way, and a `page` only spares the catalog cache. Pass a page when the change touched page source and left the component catalog alone. It saves a rebuild of the catalog, not a rescan of the project.
 
-Invalidating is not rescanning. The call only drops the cache; the cost lands on the next read, which rescans the project in full and memoizes the result. Two refreshes in a row therefore cost nothing extra, but refreshing before every read costs a full scan every time. The operation returns `void`, not an `OpResult`.
+The call only drops the caches. The next read pays the cost, because it rescans the project in full and keeps the result. Two refreshes in a row cost nothing extra, and a refresh before every read costs a full scan every time. The operation returns `void`, not an `OpResult`.
 
-## Create a Page
+## Create a page
 
-`CreatePage(input)` writes a new page file, wires it into the nearest barrel, and returns the ref it assigned along with the file it created.
+`CreatePage(input)` writes a new page file and wires it into the nearest barrel. It returns the ref it assigned and the file it created. The new page uses `DefaultLayout({ fullWidth: true })`.
 
 ```typescript
 import { CreatePage } from "@antelopejs/interface-dms-builder";
@@ -85,16 +89,17 @@ if (result.ok) {
 
 | Option | Type | Description |
 | --- | --- | --- |
-| `name` | `string` | The page's route id/slug. Required. A duplicate fails with `duplicate_name`. |
+| `name` | `string` | The page id and route segment. Required. It must be lowercase letters, digits and single dashes, or the call fails with `invalid_config`. A duplicate fails with `duplicate_name`. |
 | `displayName` | `string` | The label shown in the menu. Required. |
-| `category` | `CategoryRef` | The category to attach to. Required, and it must already exist. |
-| `icon` | `string` | Icon name. |
+| `category` | `CategoryRef` | The category to attach to. Required. An unknown category fails with `not_found`. |
+| `icon` | `string` | The icon name. |
 | `order` | `number` | Sort order within the category. |
 | `description` | `string` | The page's description. |
 | `permission` | `PagePermission` | The permission guarding the page. |
-| `dir` | `string` | Explicit folder, relative to the src root, overriding the default category-relative placement. |
+| `dir` | `string` | A folder relative to the `src` root, which replaces the placement beside the category. |
+| `module` | `string` | The project module to write into, by its id in the project configuration. Without it, the builder writes into the project's own module. The module must be a local module with an `src/index.ts`, and the page may only use declarations from that same module. A category declared in another module fails with `invalid_config`. |
 
-Without `dir`, the page lands at `<category-folder>/<name>/page.ts` when the category is declared in the project's source and has a barrel beside it, and at `src/<name>.ts` otherwise. With `dir`, it lands at `src/<dir>/<name>/page.ts`. Either way the nearest barrel above the file is wired, keeping a relative import chain up to `src/index.ts`. `dir` must stay inside the src tree; a `dir` that escapes it, or a project with no barrel to wire, fails with `unsupported`.
+Without `dir`, the page goes to `<category-folder>/<name>/page.ts` when the project's source declares the category and an `index.ts` barrel sits beside it. Otherwise it goes to `src/<name>.ts`, next to the root barrel. With `dir`, it goes to `src/<dir>/<name>/page.ts`. In each case the builder wires the nearest barrel above the file, which keeps a relative import chain up to `src/index.ts`. `dir` must stay inside the `src` tree. A `dir` that leaves it, or a project with no barrel to wire, fails with `unsupported`.
 
 ```typescript
 import { CreatePage } from "@antelopejs/interface-dms-builder";
@@ -107,9 +112,9 @@ await CreatePage({
 });
 ```
 
-## Configure a Page
+## Configure a page
 
-`ConfigurePage(ref, patch, opts?)` patches the page's metadata in place. The patch is a `Partial<EditablePageMeta>`; keys you leave out are untouched, and a key set to `undefined` is removed from the page's options.
+`ConfigurePage(ref, patch, opts?)` patches the metadata of the page in place and returns its ref. The patch is a `Partial<EditablePageMeta>`. Keys left out stay untouched, and a key set to `undefined` or `null` is removed from the options of the page. A page whose options are not a plain object literal fails with `unsupported`, because the builder needs a literal to rewrite.
 
 ```typescript
 import { ConfigurePage } from "@antelopejs/interface-dms-builder";
@@ -121,11 +126,11 @@ const result = await ConfigurePage("/revenue", {
 });
 ```
 
-### Move a Page Between Categories
+### Move a page between categories
 
-A page's category decides its route, so patching `category` moves the page rather than editing a field. `ConfigurePage` rewrites the `category` option and its import, moves the file to the directory beside the new category — where `CreatePage` would have put it — and moves the registration with it, so each directory's barrel still lists what it holds. Relative imports inside the page are re-anchored to its new location.
+The category of a page decides its route, so a patch of `category` moves the page. `ConfigurePage` rewrites the `category` option and its import. When the new category has an `index.ts` barrel beside it, the builder also moves the file to the folder where `CreatePage` would have put it, and moves the registration with it, so each barrel still lists what its folder holds. The builder rewrites the relative imports inside the page for its new location.
 
-The result carries the page's new `ref`, and a `route_changed` warning naming the old one. **Nothing redirects the old route**: links and bookmarks to it break.
+The result carries the new `ref` of the page, and a `route_changed` warning names the old one. Nothing redirects the old route, so links and bookmarks to it break.
 
 ```typescript
 import { ConfigurePage } from "@antelopejs/interface-dms-builder";
@@ -134,20 +139,24 @@ const moved = await ConfigurePage("/form/revenue", { category: "pages.reports" }
 if (moved.ok) {
   console.log(moved.data.ref); // "/reports/revenue"
   for (const warning of moved.warnings ?? []) {
-    console.log(warning.code, warning.message); // "route_changed", …
+    console.log(warning.code, warning.message); // "route_changed" and its message
   }
 }
 ```
 
-The move is refused when the target category is unknown (`not_found`), when it is built-in or not declared in source so a page cannot reference it (`unsupported`), or when the destination already holds a page of that name (`duplicate_name`). A page whose options are not a plain object literal fails with `unsupported` too — the builder rewrites source, so it needs a literal to rewrite.
+The builder refuses the move in three cases:
+
+- The target category is unknown. The call fails with `not_found`.
+- The target category is built in or not declared in source, so a page cannot reference it. The call fails with `unsupported`.
+- The destination already holds a page of that name. The call fails with `duplicate_name`.
 
 `opts` is a `MutationOpts`, so `expectedVersion` makes the write conditional.
 
-## Delete a Page
+## Delete a page
 
-`DeletePage(ref, opts?)` removes the page file and unwires every import of it.
+`DeletePage(ref, opts?)` removes the page class, with the constants, imports and generated model methods that only the page used. The builder deletes the file and removes its barrel import only when nothing but imports is left in it, because a hand-written page file can also declare a category that other pages import. `opts` is a `MutationOpts`.
 
-```typescript
+```typescript fragment
 import { DeletePage } from "@antelopejs/interface-dms-builder";
 
 const result = await DeletePage("/revenue", { expectedVersion: version });
@@ -156,9 +165,9 @@ if (!result.ok && result.error.code === "stale") {
 }
 ```
 
-## Create a Category
+## Create a category
 
-`CreateCategory(input)` declares a new category and registers it in the root barrel.
+`CreateCategory(input)` writes the new category to `<name>.category.ts` beside the root barrel and imports that file from the barrel. A project with no root barrel fails with `unsupported`.
 
 ```typescript
 import { CreateCategory } from "@antelopejs/interface-dms-builder";
@@ -177,15 +186,16 @@ const result = await CreateCategory({
 
 | Option | Type | Description |
 | --- | --- | --- |
-| `name` | `string` | The category's id segment. Required. A duplicate fails with `duplicate_name`. |
+| `name` | `string` | The id segment of the category. Required. It must be lowercase letters, digits and single dashes, or the call fails with `invalid_config`. A duplicate fails with `duplicate_name`. |
 | `displayName` | `string` | The label shown in the menu. Required. |
 | `parent` | `CategoryRef` | The parent category. Omit for a category under the root `pages`. |
-| `icon` | `string` | Icon name. |
+| `icon` | `string` | The icon name. |
 | `order` | `number` | Sort order among siblings. |
+| `module` | `string` | The project module to write into, as `CreatePageInput.module`. |
 
 A `parent` that does not exist fails with `not_found`.
 
-## Configure a Category
+## Configure a category
 
 `ConfigureCategory(ref, patch)` patches an existing category. It takes no options argument.
 
@@ -198,11 +208,15 @@ await ConfigureCategory("pages.reports", {
 });
 ```
 
-Two refusals, both `unsupported`: re-parenting (a patch carrying `parent`), and a category that is built in or otherwise not declared in editable source.
+An unknown category fails with `not_found`. Three refusals fail with `unsupported`:
+
+- a patch that carries `parent`,
+- a category that is built in or not declared in editable source,
+- a category whose options are not a plain object literal.
 
-## Delete a Category
+## Delete a category
 
-`DeleteCategory(ref)` removes the category declaration, and deletes its file when nothing but imports is left in it.
+`DeleteCategory(ref)` removes the category declaration. When nothing but imports is left in its file, the builder deletes the file and the imports of it.
 
 ```typescript
 import { DeleteCategory } from "@antelopejs/interface-dms-builder";
@@ -213,11 +227,11 @@ if (!result.ok && result.error.code === "referential_integrity") {
 }
 ```
 
-A category that still holds pages or child categories fails with `referential_integrity`, and `blockedBy` lists the refs standing in the way. Empty it first.
+A category that still holds pages, directly or through its subcategories, or that has child categories, fails with `referential_integrity`. `blockedBy` lists the refs of those pages and child categories. A built-in category, or one not declared in editable source, fails with `unsupported`.
 
-## Add a Block
+## Add a block
 
-`AddBlock(input, opts?)` emits a factory call into the page and returns the `BlockPath` of the new block.
+`AddBlock(input, opts?)` writes a factory call into the page and returns the `BlockPath` of the new block.
 
 ```typescript
 import { AddBlock } from "@antelopejs/interface-dms-builder";
@@ -243,18 +257,18 @@ if (result.ok) {
 | `page` | `PageRef` | The page to add to. Required. |
 | `name` | `string` | The block's name, unique among its siblings. Required. A duplicate fails with `duplicate_name`. |
 | `type` | `string` | A `BlockTypeDescriptor.type` from the catalog. Required. An unknown type fails with `unsupported`. |
-| `config` | `Record<string, unknown>` | The factory's options object. Required. |
+| `config` | `ConfigObject` | The factory's options object. Required. |
 | `parent` | `BlockPath` | The container to nest under. Omit to add a top-level block. |
 | `slot` | `string` | The slot within the parent container. |
 | `index` | `number` | Position among siblings. Defaults to appending. |
-| `meta` | `Record<string, unknown>` | Child metadata emitted alongside `slot` in the third argument of `.child()`, such as `{ colSpan: 2 }`. Ignored for top-level blocks. |
+| `meta` | `ConfigObject` | Child metadata emitted alongside `slot` in the third argument of `.child()`, such as `{ colSpan: 2 }`. Ignored for top-level blocks. |
 | `controller` | `ResourceRef` | The resource whose DataAPI class is the leading argument, for controller-leading block types. |
 
-`config` is plain JSON by default; values that are not literals — a DataType instance, a reference to a generated class — use the sentinel encodings in [Value Encodings](./7.values.md).
+`config` is plain JSON by default. A value that is not a literal, such as a DataType instance or a reference to a generated class, uses the encodings in [Value encodings](./7.values.md).
 
-Nesting requires an editable container: a `parent` that resolves to an opaque block fails with `opaque_target`, and one that does not resolve at all fails with `not_found`. An out-of-range `index` is clamped, and the result carries an `index_clamped` warning.
+A nested block needs an editable container. A `parent` that resolves to an opaque block fails with `opaque_target`, and a `parent` that does not resolve fails with `not_found`. The builder clamps an `index` out of range, and the result carries an `index_clamped` warning.
 
-Controller-leading types (catalog `controllerArg: true`, e.g. `TableView`) require `controller`; passing it for any other type is rejected. Both mismatches fail with `invalid_config`.
+A block type whose catalog entry has `controllerArg: true`, such as `TableView`, requires `controller`. Any other type refuses it. Both mismatches fail with `invalid_config`.
 
 ```typescript
 import { AddBlock } from "@antelopejs/interface-dms-builder";
@@ -268,9 +282,9 @@ await AddBlock({
 });
 ```
 
-## Configure a Block
+## Configure a block
 
-`ConfigureBlock(path, patch, opts?)` rewrites a block's options object. By default the patch merges: listed keys are replaced, unlisted keys survive, and a key set to `undefined` is removed.
+`ConfigureBlock(path, patch, opts?)` rewrites the options object of a block. By default the patch merges. Listed keys are replaced, other keys stay, and a key set to `undefined` is removed.
 
 ```typescript
 import { ConfigureBlock } from "@antelopejs/interface-dms-builder";
@@ -287,9 +301,9 @@ await ConfigureBlock("/revenue#total", {
 | --- | --- | --- |
 | `replace` | `boolean` | Replace the whole options object instead of merging into it. |
 | `expectedVersion` | `string` | The `PageStructure.version` you last read. A mismatch fails with `stale`. |
-| `meta` | `Record<string, unknown>` | Patch child metadata (`slot`, `colSpan`, …). A key set to `undefined` is removed. Rejected for a top-level block, which has no `.child()` call. |
+| `meta` | `ConfigObject` | A patch of the child metadata, such as `slot` or `colSpan`. A key set to `undefined` is removed. A top-level block has no `.child()` call to carry it, so it fails with `unsupported`. |
 
-Read the version before changing an existing child. Here `/revenue#grid/total` must already be a child of the page's grid:
+The following example reads the version before it changes an existing child. `/revenue#grid/total` must already be a child of the grid of the page.
 
 ```ts docs-check
 import { ConfigureBlock, GetPageStructure } from "@antelopejs/interface-dms-builder";
@@ -306,9 +320,9 @@ export async function resizeRevenueCard() {
 }
 ```
 
-An opaque block fails with `opaque_target`: the builder can read it but not rewrite it.
+An opaque block fails with `opaque_target`, because the builder can read it but cannot rewrite it.
 
-## Move a Block
+## Move a block
 
 `MoveBlock(path, dest, opts?)` moves a child block within its container or into another one.
 
@@ -325,15 +339,15 @@ await MoveBlock("/revenue#grid/row/total", {
 
 | Option | Type | Description |
 | --- | --- | --- |
-| `parent` | `BlockPath` | The destination container. |
-| `slot` | `string` | The slot within the destination container. |
+| `parent` | `BlockPath` | The destination container. Optional in the type, and required by the operation. |
+| `slot` | `string` | Declared in the type, but `MoveBlock` does not read it. The block lands among the destination's children. |
 | `index` | `number` | Position among the destination's children. Required. |
 
-The move is a child-into-container operation: the path must address a nested block, and `dest.parent` must name a container. Anything else — a top-level block, a destination without a `parent` — fails with `unsupported`. An out-of-range `index` is clamped with an `index_clamped` warning, and a destination that is opaque or missing fails with `opaque_target` or `not_found`.
+The path must address a nested block. A top-level block, or a destination without a `parent`, fails with `unsupported`. The builder clamps an `index` out of range and adds an `index_clamped` warning. An opaque destination fails with `opaque_target`, and a missing one fails with `not_found`.
 
-## Remove a Block
+## Remove a block
 
-`RemoveBlock(path, opts?)` deletes a block. A top-level block is removed as a static member; a nested one is dropped from its parent's `.child()` chain.
+`RemoveBlock(path, opts?)` deletes a block. The builder removes a top-level block as a static member, and drops a nested one from the `.child()` chain of its parent.
 
 ```typescript
 import { RemoveBlock } from "@antelopejs/interface-dms-builder";
@@ -344,7 +358,7 @@ if (result.ok) {
 }
 ```
 
-## Next Steps
+## Next steps
 
-- [Resources](./5.resources.md) - Generate the tables and DataAPI controllers a page reads from
-- [Drafts and Preview](./9.drafts-and-preview.md) - Write a page's whole block tree in one transaction
+- [Resources](./5.resources.md) generates the tables and DataAPI controllers a page reads from.
+- [Drafts and preview](./9.drafts-and-preview.md) writes the whole block tree of a page in one transaction.