@antelopejs/interface-dms-builder 0.3.1 → 0.4.0

package/docs/2.addressing-and-structure.md

@@ -1,10 +1,14 @@
-# Addressing and Structure
+---
+title: "Addressing and structure"
+description: "The refs that name a page, a block and a category, and the page, block and listing shapes the builder reads back."
+mode: reference
+---
 
 ## Overview
 
 Every builder operation identifies its target with a string ref. This page covers `PageRef` for a page, `BlockPath` for a block inside it, and `CategoryRef` for a menu category. [Resources](./5.resources.md) and [Queries](./6.queries.md) define their own refs.
 
-Alongside the refs, this page describes the read shapes the builder hands back: the page metadata it can read and patch, the block tree it resolves from source, and the lightweight summaries the listing operations return. The operations that produce and consume these shapes live in [Page Operations](./4.page-operations.md).
+This page also describes the shapes the builder reads back. Those are the page metadata it can read and patch, the block tree it resolves from source, and the summaries the listing operations return. [Page operations](./4.page-operations.md) documents the operations that produce and take these shapes.
 
 ```typescript
 import type {
@@ -18,9 +22,9 @@ const block: BlockPath = "/dashboard#kpis/row/revenue";
 const category: CategoryRef = "pages.reports";
 ```
 
-## Address a Page
+## Address a page
 
-`PageRef` is a page's route string, built from its category's slug and the page's own name — a page named `revenue` under the root `pages` category is `/revenue`. `CreatePage` returns the ref it assigned, and every page operation takes it as its first argument.
+`PageRef` is the route string of a page. The builder joins the slug of the category with the page's own `urlSlug`, which defaults to its name. A page named `revenue` under the root `pages` category is `/revenue`. `CreatePage` returns the ref it assigned, and every page operation takes it as its first argument.
 
 ```typescript
 import {
@@ -38,9 +42,9 @@ if (created.ok) {
 }
 ```
 
-## Address a Block
+## Address a block
 
-`BlockPath` addresses one block inside a page: `<pageRef>#<name>` for a top-level block, then `/<childId>` for each nesting level below it.
+`BlockPath` addresses one block inside a page. A top-level block is `<pageRef>#<name>`, and each nesting level below it adds `/<childId>`.
 
 | Path | What it addresses |
 | --- | --- |
@@ -48,11 +52,11 @@ if (created.ok) {
 | `/dashboard#kpis/row` | The `.child("row", …)` of that block |
 | `/dashboard#kpis/row/revenue` | The `.child("revenue", …)` of `row` |
 
-The first segment after `#` is the static class member the block is declared as; every further segment is the id passed to `.child()`. `AddBlock` returns the path of the block it added, so you rarely build one by hand.
+The first segment after `#` is the static class member that declares the block. Every further segment is the id passed to `.child()`. `AddBlock` returns the path of the block it added.
 
-## Address a Category
+## Address a category
 
-`CategoryRef` is a category's stable id. The three roots are `pages`, `modules` and `settings`; a category created under a parent is addressed by joining them with a dot, so a `reports` category under `pages` is `pages.reports`.
+`CategoryRef` is the stable id of a category. The three roots are `pages`, `modules` and `settings`. The ref of a category under a parent joins the parent ref and the category id with a dot, so a `reports` category under `pages` is `pages.reports`. The root category of a module is `modules.<moduleId>`.
 
 ```typescript
 import { CreateCategory } from "@antelopejs/interface-dms-builder";
@@ -65,27 +69,27 @@ const category = await CreateCategory({
 // category.data.ref === "pages.reports"
 ```
 
-## Read a Page's Metadata
+## Read a page's metadata
 
-`PageMeta` is what the builder knows about a page. It comes back inside `PageStructure`, which `GetPageStructure` returns.
+`PageMeta` holds what the builder knows about a page. It comes back inside the `PageStructure` that `GetPageStructure` returns.
 
 | Field | Type | Description |
 | --- | --- | --- |
 | `ref` | `PageRef` | The page's route string. |
 | `id` | `string` | The page id, the first argument of its `PageController`. |
 | `displayName` | `string` | The label shown in the menu. |
-| `icon` | `string` | Icon name, when the page declares one. |
+| `icon` | `string` | The icon name, when the page declares one. |
 | `category` | `CategoryRef` | The category the page belongs to. |
 | `order` | `number` | Sort order within the category. |
 | `description` | `string` | The page's description. |
 | `hidden` | `boolean` | Whether the page is hidden from the menu. |
 | `permission` | `PagePermission` | The permission guarding the page. |
-| `live` | `PageLive` | The page's Direct / Pause options, when it is live. |
-| `filepath` | `string` | The file the page is declared in, resolved by the builder's source index rather than by the runtime registry. |
+| `live` | `PageLive` | The Direct and Pause options of the page, when it is live. |
+| `filepath` | `string` | The file that declares the page. The builder's source index resolves it, not the runtime registry. |
 
-`hidden`, `permission` and `live` read back like any other field, as long as the page declares them literally. A `permission` built from a call or a reference — an `Action`, say — reads back as `undefined`: the builder reports only what it can also rewrite.
+`hidden`, `permission` and `live` read back like any other field when the page declares them as literals. A `permission` built from a call or a reference, such as an `Action`, reads back as `undefined`. The builder reports only what it can also rewrite.
 
-`PagePermission` mirrors the DMS `MenuOptions.permission`: a partial permission spec, whose fields are `id`, `title`, `icon`, `description`, `dependencies` and `defaultGranted`. A bare action id is *not* accepted — the DMS types the option as `Partial<Permission> | Action`, so a string would be written and then refused by the typecheck gate.
+`PagePermission` mirrors the DMS `MenuOptions.permission`. It is a partial permission spec with the fields `id`, `title`, `icon`, `description`, `dependencies` and `defaultGranted`. Its type is `ConfigObject`, an object of plain data, so the compiler refuses a function or a class instance. A bare action id is not accepted. The DMS types the option as `Partial<Permission> | Action`, so the builder would write a string and the typecheck gate would then refuse it.
 
 ```typescript
 import type { PagePermission } from "@antelopejs/interface-dms-builder";
@@ -96,15 +100,15 @@ const permission: PagePermission = {
 };
 ```
 
-The DMS also accepts an `Action` there. That is a live object rather than data, so it has no encoding in the builder: a page declaring one reads its permission back as `undefined`.
+The DMS also accepts an `Action` there. An `Action` is a live object and not data, so the builder has no encoding for it. A page that declares one reads its permission back as `undefined`.
 
-`PageLive` mirrors the DMS `MenuOptions.live`: `maxRate`, `slowRateAfter`, `rememberKey`. Present, even empty (`{}`), the page is live — its blocks refetch through a Direct / Pause valve its `LiveToggle` switches; absent, they refetch on every event. Sent as `null` in a patch, it is taken off.
+`PageLive` mirrors the DMS `MenuOptions.live`, with the fields `maxRate`, `slowRateAfter` and `rememberKey`. It is a `ConfigObject` as well. When `live` is present, even as `{}`, the page is live. Its blocks then refetch through a Direct and Pause valve that its `LiveToggle` switches. When `live` is absent, the blocks refetch on every event. A patch that sends `live` as `null` removes it.
 
-## Patch a Page's Metadata
+## Patch a page's metadata
 
-`EditablePageMeta` is the subset of `PageMeta` that `ConfigurePage` accepts as a patch: `displayName`, `icon`, `category`, `order`, `description`, `hidden`, `permission` and `live`. `ref`, `id` and `filepath` are not patchable — they follow from where the page lives.
+`EditablePageMeta` is the subset of `PageMeta` that `ConfigurePage` accepts as a patch. Its fields are `displayName`, `icon`, `category`, `order`, `description`, `hidden`, `permission` and `live`. `ref`, `id` and `filepath` are not patchable, because they follow from where the page lives.
 
-Patching `category` moves the page, which changes its `ref`: the result carries the new one, and a `route_changed` warning says what the old route was. See [Page Operations](./4.page-operations.md).
+A patch of `category` moves the page and changes its `ref`. The result carries the new ref, and a `route_changed` warning names the old route. [Move a page between categories](./4.page-operations.md#move-a-page-between-categories) describes the move.
 
 ```typescript
 import type { EditablePageMeta } from "@antelopejs/interface-dms-builder";
@@ -115,24 +119,25 @@ const patch: Partial<EditablePageMeta> = {
 };
 ```
 
-## Read the Block Tree
+## Read the block tree
 
-`BlockNode` is one block in a page's tree. The builder resolves each static member and each `.child()` call it can parse; anything it cannot parse still appears as a node, marked not editable.
+`BlockNode` is one block in the tree of a page. The builder resolves each static member and each `.child()` call it can parse. A block it cannot parse still appears as a node, marked not editable.
 
 | Field | Type | Description |
 | --- | --- | --- |
 | `path` | `BlockPath` | The block's address. |
 | `name` | `string` | Static key for a top-level block, `.child()` id for a nested one. |
 | `type` | `string \| null` | The factory name, or `null` when it does not resolve. |
-| `editable` | `boolean` | `false` marks an opaque, non-canonical block. |
+| `editable` | `boolean` | Whether the builder can edit the options it understands. `false` marks an opaque block. |
 | `opaqueReason` | `string` | Why the block is opaque. Set when `editable === false`. |
 | `slot` | `string` | The slot the block sits in, when its parent declares slots. |
-| `meta` | `Record<string, unknown>` | Child metadata beyond `slot`, such as `{ colSpan: 2 }`. Keep it when constructing a draft from the tree. |
-| `config` | `Record<string, unknown>` | The block's options object. Present only when the block is editable. |
-| `controller` | `ResourceRef` | For a controller-leading block such as `TableView`, the resource its leading argument resolves to, when it is a known generated resource. |
+| `meta` | `ConfigObject` | Child metadata beyond `slot`, as declared in the third argument of `.child()`, such as `{ colSpan: 2 }`. Nested blocks only. Keep it when you build a draft from the tree. |
+| `config` | `ConfigObject` | The options of the block that are literals. Present only when the block is editable. |
+| `lockedOptions` | `Record<string, string>` | The top-level options defined by an expression in code, each with the reason it is locked. A save keeps them unchanged. |
+| `controller` | `ResourceRef` | For a block whose factory takes a controller first, such as `TableView`, the resource that the leading argument resolves to, when it is a known generated resource. |
 | `children` | `BlockNode[]` | Container blocks only, in `.child()` order. |
 
-An opaque block is one the builder can see but not rewrite — a block behind an unresolved reference, or one produced by a computed expression rather than a direct factory call. Reading it is fine; `ConfigureBlock`, `AddBlock` under it and `MoveBlock` onto it fail with `opaque_target`, described in [Results and Errors](./8.results-and-errors.md).
+The builder can read an opaque block but cannot rewrite it. A block behind an unresolved reference is opaque, and so is a block that a computed expression produces instead of a direct factory call. `ConfigureBlock` on it, `AddBlock` under it and `MoveBlock` onto it fail with `opaque_target`, which [Results and errors](./8.results-and-errors.md) describes.
 
 ```typescript
 import { GetPageStructure } from "@antelopejs/interface-dms-builder";
@@ -147,22 +152,22 @@ if (result.ok) {
 }
 ```
 
-## Read a Page's Structure
+## Read a page's structure
 
 `PageStructure` is the whole page as the builder sees it.
 
 | Field | Type | Description |
 | --- | --- | --- |
-| `page` | `PageMeta` | The page's metadata. |
+| `page` | `PageMeta` | The metadata of the page. |
 | `blocks` | `BlockNode[]` | The top-level blocks, each carrying its own children. |
-| `queries` | `QueryStructure[]` | The query routes declared on the page, found by shape. See [Queries](./6.queries.md). |
+| `queries` | `QueryStructure[]` | The query routes declared on the page, found by shape. [Queries](./6.queries.md) describes them. |
 | `version` | `string` | A content hash of the page file. |
 
-`version` is what makes a write conditional: pass it back as `expectedVersion` on the next mutation and the operation fails with `stale` if the file changed in between. See [Results and Errors](./8.results-and-errors.md).
+`version` makes a write conditional. Pass it back as `expectedVersion` on the next mutation, and the operation fails with `stale` if the file changed in between. [Results and errors](./8.results-and-errors.md) describes `stale`.
 
-## Read the Listings
+## Read the listings
 
-`ListPages` and `ListCategories` return summaries rather than full structures, so you can survey a project without parsing every page.
+`ListPages` and `ListCategories` return summaries instead of full structures, so a caller can survey a project without the structure of every page.
 
 `PageSummary`:
 
@@ -172,11 +177,12 @@ if (result.ok) {
 | `id` | `string` | The page id. |
 | `displayName` | `string` | The label shown in the menu. |
 | `category` | `CategoryRef` | The category the page belongs to. |
-| `moduleId` | `string` | The module the page comes from, for pages declared inside a module. |
+| `moduleId` | `string` | The `module` option of the page, for a page that declares one. |
 | `filepath` | `string` | The file the page is declared in. |
 | `icon` | `string` | The icon the menu shows beside the page, when it declares one. |
 | `order` | `number` | Sorts the page among the others of its category, when it declares one. |
-| `hidden` | `boolean` | Whether the menu leaves the page out; its route still answers. |
+| `hidden` | `boolean` | Whether the menu leaves the page out. Its route still answers. |
+| `sourceModule` | `string` | The project module the page lives in, when it is not the project's own module. |
 
 `CategorySummary`:
 
@@ -185,6 +191,8 @@ if (result.ok) {
 | `ref` | `CategoryRef` | The category's id. |
 | `displayName` | `string` | The label shown in the menu. |
 | `parent` | `CategoryRef` | The parent category, absent for a root. |
+| `icon` | `string` | The icon name, when the category declares one. |
+| `order` | `number` | Its place among its siblings in the menu, lowest first, when the category declares one. |
 
 ```typescript
 import {
@@ -199,9 +207,9 @@ const [pages, categories] = await Promise.all([
 const rootPages = pages.filter((page) => page.category === "pages");
 ```
 
-## Patch a Category's Metadata
+## Patch a category's metadata
 
-`EditableCategoryMeta` is what `ConfigureCategory` accepts: `displayName`, `parent`, `icon` and `order`. Re-parenting a category is refused — every page beneath it would change route at once; see [Page Operations](./4.page-operations.md).
+`EditableCategoryMeta` is what `ConfigureCategory` accepts. Its fields are `displayName`, `parent`, `icon` and `order`. `ConfigureCategory` refuses a new `parent` with `unsupported`, because every page beneath the category would change route at once. [Configure a category](./4.page-operations.md#configure-a-category) lists the refusals.
 
 ```typescript
 import type { EditableCategoryMeta } from "@antelopejs/interface-dms-builder";
@@ -209,6 +217,6 @@ import type { EditableCategoryMeta } from "@antelopejs/interface-dms-builder";
 const patch: Partial<EditableCategoryMeta> = { displayName: "Reports", order: 2 };
 ```
 
-## Next Steps
+## Next steps
 
-- [Catalog](./3.catalog.md) - Discover the block types and DataTypes you can emit
+- [Catalog](./3.catalog.md) lists the block types and DataTypes the builder can write.

package/docs/3.catalog.md

@@ -1,12 +1,16 @@
-# Catalog
+---
+title: "Catalog"
+description: "The block types, DataTypes, reserved field names and declared data sources the builder reports, with the schema of each option."
+mode: reference
+---
 
 ## Overview
 
-The catalog is the builder's answer to "what can I put on a page?". `GetCatalog` returns a `BlockCatalog`: every block factory the builder knows how to emit, every DataType a form field can use, and the field names a resource may not take. Each entry carries the import the emitter will add and a schema for the options the factory accepts, so you can validate a configuration before you write it.
+The catalog lists what the builder can put on a page. `GetCatalog` returns a `BlockCatalog` with every block factory the builder can write, every DataType a form field can use, and the field names a resource may not take. Each entry carries the import the emitter adds and a schema for the options the factory accepts, so a caller can validate a configuration before it writes one.
 
-Read the catalog before `AddBlock`: the `type` you pass is a catalog key, and `AddBlock` rejects a type that is not in it.
+The `type` passed to `AddBlock` is a catalog key. `AddBlock` fails with `unsupported` for a type the catalog does not list.
 
-## Read the Catalog
+## Read the catalog
 
 ```typescript
 import { GetCatalog } from "@antelopejs/interface-dms-builder";
@@ -17,57 +21,76 @@ const containers = catalog.blocks.filter((block) => block.container);
 const dataTypeIds = catalog.dataTypes.map((dataType) => dataType.id);
 ```
 
-`GetCatalog` is a read: it returns a `BlockCatalog` directly, not an `OpResult`.
+`GetCatalog` is a read. It returns a `BlockCatalog` directly, not an `OpResult`.
 
 | Field | Type | Description |
 | --- | --- | --- |
-| `blocks` | `BlockTypeDescriptor[]` | Every block factory the builder can emit and configure. |
+| `blocks` | `BlockTypeDescriptor[]` | Every block factory the builder can write and configure. |
 | `dataTypes` | `DataTypeDescriptor[]` | Every DataType usable as a form field's `type`. |
 | `reservedFieldNames` | `string[]` | Names a resource field may not take. |
-| `generatedAt` | `string` | Cache key, invalidated when the module source changes. |
+| `generatedAt` | `string` | The ISO time at which the builder built the cached catalog. It is also the cache key. |
 
-The catalog is cached. `RefreshSourceIndex` with no scope drops that cache; see [Page Operations](./4.page-operations.md).
+The builder caches the catalog. `RefreshSourceIndex` without a `page` in its scope drops that cache, as [Refresh the source index](./4.page-operations.md#refresh-the-source-index) describes.
 
-## Describe a Block Type
+## Describe a block type
 
-`BlockTypeDescriptor` is keyed on `type`, the factory's export name.
+`BlockTypeDescriptor` is keyed on `type`, the export name of the factory.
 
 | Field | Type | Description |
 | --- | --- | --- |
-| `type` | `string` | The factory export name, e.g. `KpiCard`. This is the catalog key and the value of `AddBlockInput.type`. |
+| `type` | `string` | The export name of the factory, such as `KpiCard`. It is the catalog key and the value of `AddBlockInput.type`. |
 | `import` | `ImportRef` | The import the emitter adds for the factory. |
+| `componentName` | `string` | The frontend component the factory emits, such as `dms-kpi-card`. |
+| `label` | `string` | The label for the palette. A consumer falls back to `type` when it is absent. |
+| `icon` | `string` | The icon name for the palette. |
+| `group` | `BlockGroup` | The palette section: `layout`, `content`, `data`, `visualization`, or another name a DMS declares. |
 | `container` | `boolean` | Whether the block accepts `.child(...)`. |
-| `slots` | `SlotDescriptor[]` | The named regions the block exposes, when it has any. |
-| `config` | `ConfigSchema` | A description of the factory's options object. |
-| `shapeSource` | `ShapeSource` | How the emit shape was determined. |
+| `allowedChildren` | `string[]` | The block types accepted as children. Any type is accepted when it is absent. |
+| `slots` | `SlotDescriptor[]` | The fixed named regions the block exposes, when it has any. |
+| `dynamicSlots` | `DynamicSlots` | Where the block's own options name its regions, for a container such as `Tab`. |
+| `config` | `ConfigSchema` | A description of the options object of the factory. |
+| `defaults` | `ConfigObject` | The option values the factory applies when the caller omits them. |
+| `childMeta` | `ConfigSchema` | The schema of the metadata a child carries, such as `{ colSpan }`. |
+| `fixedOptions` | `ConfigObject` | The options the factory sets itself whatever the caller passes, such as the `type` of a chart. |
+| `configOrigin` | `ConfigOrigin` | How the builder determined the shape of `config`. |
 | `description` | `string` | A human-readable description of the block. |
-| `controllerArg` | `boolean` | `true` when the factory takes a leading controller-class argument before its options object. |
-| `initialChildren` | `BlockInitialChild[]` | The children a new block of this type starts with, as the DMS's own helper places them in code (a `PageToolbar`'s `LiveToggle` and `PeriodSelector`, with the options of `pageToolbar()`). Each has an `id` (the child id roles name it by), a `type` (a catalog key) and its `options`. Absent for most types. |
+| `controllerArg` | `boolean` | `true` when the factory takes a controller class as its first argument, before its options object. |
+| `initialChildren` | `BlockInitialChild[]` | The children a new block of this type starts with, as the DMS's own helper places them in code. A `PageToolbar` starts with a `LiveToggle` and a `PeriodSelector`, with the options of `pageToolbar()`. Each child has an `id` (the child id that roles name it by), a `type` (a catalog key) and its `options`. Absent for most types. |
 
-Only a `container` block can hold children, so it is the check to make before passing a block's path as `AddBlockInput.parent`.
+Only a `container` block can hold children. Check `container` before you pass the path of a block as `AddBlockInput.parent`.
 
-## Place a Block in a Slot
+## Place a block in a slot
 
-A container block may declare named regions. `SlotDescriptor` describes one:
+A container block can declare named regions. `SlotDescriptor` describes one fixed region.
 
 | Field | Type | Description |
 | --- | --- | --- |
 | `id` | `string` | The slot id, passed as `AddBlockInput.slot`. |
+| `label` | `string` | The name of the slot for a person. |
 | `description` | `string` | What the slot is for. |
 
 ```typescript
 import { GetCatalog } from "@antelopejs/interface-dms-builder";
 
 const catalog = await GetCatalog();
-const descriptor = catalog.blocks.find((block) => block.type === "Tab");
+const descriptor = catalog.blocks.find((block) => block.type === "Card");
 const slotIds = descriptor?.slots?.map((slot) => slot.id) ?? [];
+// ["actions", "footer"]
 ```
 
-## Handle a Controller-Leading Block
+Some containers take their regions from their own options instead. `Tab` names one region per entry of its `items` option. Its descriptor has no `slots` and carries `dynamicSlots` instead.
 
-Some factories take a controller class before their options — `TableView(controller, options)` is the common case. Those descriptors carry `controllerArg: true`, and their `config` describes the *second* argument, the options object.
+| Field | Type | Description |
+| --- | --- | --- |
+| `optionPath` | `string` | The option of the block config that lists the regions, such as `items`. |
+| `idKey` | `string` | The key of each entry that holds the slot id, such as `slot`. |
+| `labelKey` | `string` | The key of each entry that holds its label, such as `label`. |
+
+## Handle a block that takes a controller
+
+Some factories take a controller class before their options, as in `TableView(controller, options)`. Those descriptors carry `controllerArg: true`, and their `config` describes the second argument, the options object.
 
-A block type with `controllerArg: true` requires `AddBlockInput.controller`, naming the resource whose DataAPI class becomes the leading argument; passing `controller` for any other block type is rejected with `invalid_config`. Both rules are covered in [Page Operations](./4.page-operations.md).
+A block type with `controllerArg: true` requires `AddBlockInput.controller`, which names the resource whose DataAPI class becomes the first argument. `AddBlock` fails with `invalid_config` when that `controller` is missing, and when a `controller` is passed for any other block type. [Add a block](./4.page-operations.md#add-a-block) covers both rules.
 
 ```typescript
 import { GetCatalog } from "@antelopejs/interface-dms-builder";
@@ -79,17 +102,26 @@ if (tableView?.controllerArg) {
 }
 ```
 
-## Read a Config Schema
+## Read a config schema
 
-`ConfigSchema` is a `Record<string, unknown>` holding a JSON-Schema-shaped description of a block's or DataType's options, generated from its TypeScript type. Keys are option names; each value describes that option — `type`, `enum` for a literal union, `properties` for a nested object, `items` for an array, `oneOf` for a union of object shapes.
+`ConfigSchema` is a `Record<string, OptionSchema>`. It describes the options of a block or a DataType in a shape close to JSON Schema. The keys are option names. Each `OptionSchema` describes one option with these fields:
 
-On top of the standard keys, the schema carries DMS extensions in the `x-` namespace. The one you act on is `x-dataType`:
+- `type` is one of `string`, `number`, `boolean`, `object`, `array`, `record`, `union` or `unknown`.
+- `optional`, `nullable`, `description` and `default` describe the value.
+- `enum` lists the values of a literal union.
+- `properties` describes a nested object, `items` the element of an array, and `values` and `keys` a record.
+- `oneOf` lists the branches of a union, and `discriminator` names the property that tags each branch.
+- `prefixItems` lists the element shapes of a tuple, and `allOf` the shapes of an intersection.
+- `truncated` is `true` when the value has more structure than the catalog describes.
+- `ui` tells a builder UI how to present the option, with fields such as `label`, `widget`, `group` and `advanced`.
+
+On top of these keys, the schema carries DMS extensions in the `x-` namespace.
 
 | Key | Meaning |
 | --- | --- |
-| `x-dataType: true` | The value is a DataType instance (`new <DataType>(...)`), such as a Form field's `type`. Pass a `DataTypeValue`, described in [Value Encodings](./7.values.md). |
-
-An option whose value holds a nested block is marked the same way, with its own `x-` key. That is rare: most nesting goes through `.child`, which you express with `AddBlockInput.parent` rather than through config.
+| `x-dataType: true` | The value is a DataType instance (`new <DataType>(...)`), such as the `type` of a Form field. Pass a `DataTypeValue`, described in [Value encodings](./7.values.md). |
+| `x-component: true` | The value holds a nested block. Most nesting goes through `.child()`, which `AddBlockInput.parent` expresses instead of config. |
+| `x-controller: true` | The option receives the DataAPI class of a table, such as the `dataApiController` of a relation. Its value is a `$ref` to a resource. |
 
 ```typescript
 import { GetCatalog } from "@antelopejs/interface-dms-builder";
@@ -99,39 +131,39 @@ const form = catalog.blocks.find((block) => block.type === "Form");
 const fieldsOption = form?.config.fields; // schema for the `fields` option
 ```
 
-## Resolve an Import
+## Resolve an import
 
-`ImportRef` is the import the emitter adds when it writes a factory call, a DataType instantiation or a class reference.
+`ImportRef` is the import the emitter adds when it writes a factory call, a DataType instance or a class reference.
 
 | Field | Type | Description |
 | --- | --- | --- |
-| `name` | `string` | The imported symbol, e.g. `KpiCard` or `DefaultDataTypes.StringType`. |
+| `name` | `string` | The imported symbol, such as `KpiCard` or `DefaultDataTypes.StringType`. |
 | `module` | `string` | A package specifier, fixed and independent of the emitting file. |
-| `targetFile` | `string` | An absolute path, resolved to a specifier relative to the file being written — used for a reference to a local class such as a generated resource. |
+| `targetFile` | `string` | An absolute path that the emitter turns into a specifier relative to the file it writes. The emitter uses it for a reference to a local class, such as a generated resource. |
 
-A descriptor carries one or the other: `module` for a symbol that comes from a package, `targetFile` for one that lives in the project's own source.
+An `ImportRef` carries one of the two. `module` names a symbol from a package, and `targetFile` points at a symbol in the project's own source.
 
-## Know Where a Shape Came From
+## Know where a shape came from
 
-`ShapeSource` is `"inferred" | "annotated"`, and a `BlockTypeDescriptor` reports which applies to its `config`:
+`ConfigOrigin` is `"inferred" | "annotated"`. A `BlockTypeDescriptor` reports which one applies to its `config`.
 
-- **`inferred`** — the shape was read off the factory's TypeScript signature. It is as good as the types are: a well-typed options interface yields a precise schema, while a wide or generic option yields a loose one.
-- **`annotated`** — the shape was declared for the builder rather than derived from the signature.
+- `annotated` means that the DMS declared the block type for the builder. Its schema carries labels, defaults and widgets. A declared block type replaces the inferred one of the same name.
+- `inferred` means that the builder read the shape off the TypeScript signature of the factory, for a factory the DMS has not declared. A precise options interface gives a precise schema, and a wide or generic option gives a loose one.
 
-Use `shapeSource` when deciding how much to trust `config`. An empty or shallow `config` on an `inferred` descriptor means the type could not be described further, not that the factory takes no options.
+An empty or shallow `config` on an `inferred` descriptor means that the builder could not describe the type further. It does not mean that the factory takes no options.
 
-## Choose a DataType
+## Choose a data type
 
-`DataTypeDescriptor` describes a DataType a form field's `type` (or a table column's `type`) can use.
+`DataTypeDescriptor` describes a DataType that the `type` of a form field or of a table column can use.
 
 | Field | Type | Description |
 | --- | --- | --- |
-| `id` | `string` | The registered id, e.g. `string`, `number`, `select`. |
+| `id` | `string` | The registered id, such as `string`, `number` or `select`. |
 | `import` | `ImportRef` | The import the emitter adds for the DataType class. |
-| `config` | `ConfigSchema` | A description of the DataType's options. |
+| `config` | `ConfigSchema` | A description of the options of the DataType. |
 | `description` | `string` | A human-readable description. |
 
-The `id` is what you pass as `$dataType` when writing a value; see [Value Encodings](./7.values.md). A `$dataType` the catalog does not list is rejected with `invalid_config`.
+Pass the `id` as `$dataType` to write a DataType value, as [Value encodings](./7.values.md) describes. A `$dataType` that the catalog does not list fails with `invalid_config`.
 
 ```typescript
 import {
@@ -158,9 +190,9 @@ await AddBlock({
 });
 ```
 
-## Avoid a Reserved Field Name
+## Avoid a reserved field name
 
-`reservedFieldNames` lists the names a resource field may not take: they collide with a generated DataController route or a Model member, and `CreateResource` or `AddField` rejects them with `invalid_config`. Reading them from the catalog saves you carrying your own copy of the list.
+`reservedFieldNames` lists the names a resource field may not take. They collide with a route of the generated DataController or a member of the model, and `CreateResource` and `AddField` fail with `invalid_config` on them. The list is `_id`, `model`, `get`, `list`, `select`, `count`, `new`, `edit`, `delete`, `archive`, `restore`, `exportStart`, `exportStatus` and `exportDownload`. Read it from the catalog instead of keeping a copy.
 
 ```typescript
 import { GetCatalog } from "@antelopejs/interface-dms-builder";
@@ -170,8 +202,32 @@ const reserved = new Set(catalog.reservedFieldNames);
 const fieldName = reserved.has("status") ? "state" : "status";
 ```
 
-Resource fields are covered in [Resources](./5.resources.md).
+[Resources](./5.resources.md) covers resource fields.
+
+## List the declared data sources
+
+`ListDataSources(response?)` returns the routes that developers declared beside their own code as something a block may read. It is separate from the catalog, because these sources come and go as modules load. With `response`, it returns only the sources whose `responseKind` equals it. It returns a `DataSourceDescriptor[]` directly, not an `OpResult`.
+
+```typescript
+import { ListDataSources } from "@antelopejs/interface-dms-builder";
+
+const sources = await ListDataSources();
+const paths = sources.map((source) => source.path);
+```
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | The id of the source. |
+| `title` | `string` | The title of the source. |
+| `description` | `string` | A description of the source. |
+| `responseKind` | `string` | The shape the source answers with, matched against what a block can read. |
+| `path` | `string` | The path a block fetches, as declared. |
+| `method` | `string` | The HTTP method, when the source declares one. |
+| `params` | `ConfigSchema` | The parameters the source takes, described like block options. |
+| `period` | `{ from: string; to: string }` | The query parameters that carry a period, when the source takes one. |
+
+The builder never reads or rewrites the code behind a declared source. It knows only what the declaration says.
 
-## Next Steps
+## Next steps
 
-- [Page Operations](./4.page-operations.md) - Create pages and categories, and edit a page's block tree
+- [Page operations](./4.page-operations.md) creates pages and categories, and edits the block tree of a page.