@antelopejs/interface-dms-builder 0.3.1 → 0.4.1

package/docs/6.queries.md

@@ -1,8 +1,12 @@
-# Queries
+---
+title: "Queries"
+description: "The operations that add, configure, read back and remove a query, a page route that answers a count, an aggregate or a series of points computed from a resource."
+mode: reference
+---
 
-## Count rows without writing a route
+## Overview
 
-A query gives a page data to display: a count, a total or a series of points. With an existing `/books` page and a `book` resource, this example creates a route that counts the books:
+A query gives a page a count, a total or a series of points to display. This example adds a query to an existing `/books` page that counts the rows of the `book` resource:
 
 ```typescript
 import { AddQuery } from "@antelopejs/interface-dms-builder";
@@ -19,21 +23,17 @@ if (result.ok) {
 }
 ```
 
-After the backend reloads, a signed-in user with access to `/books` can request that URL through the frontend. It returns `{ "value": N }`, where `N` is the number of rows. The operation writes a model method and a page route; it does not add a visible block. Use the returned `route` as the block's `fetchUrl`.
+`AddQuery` writes a model method and a page route. It adds no visible block. After the backend reloads, a signed-in user with access to `/books` can request the route through the frontend, and the route answers `{ "value": N }`, where `N` is the number of rows. A block reads the answer through the returned `route`, as its `fetchUrl`. An editor that previews before it saves uses [PreviewQuery and page drafts](./9.drafts-and-preview.md) instead of a call to `AddQuery` on each change.
 
-Choose an unused query name. For an editor that must preview before saving, use [PreviewQuery and page drafts](./9.drafts-and-preview.md) instead of calling `AddQuery` on each change.
+The route carries the page's own permission, through a parameter decorator on that route alone. A user who can open the page can read what the query derives, and no other route on the controller changes.
 
-## Query reference
+A query is addressed by a `QueryRef`, lives on a page, and reads from a resource. A template decides what a query can compute. You pick one by id and fill in its parameters, and the builder emits the database chain.
 
-The route is guarded with the page's own permission, as a parameter decorator on that route alone: whoever may open the page may read what it derives, and no other route on the controller is affected.
+`GetPageStructure` reports the queries it finds on a page in `PageStructure.queries`, whether the builder wrote them or a person did.
 
-A query is addressed by a `QueryRef`, lives on a page, and reads from a resource. Templates decide what a query can compute; you pick one by id, fill in its parameters, and the builder emits the chain.
+## Address a query
 
-Queries read back structurally: `GetPageStructure` reports the queries it finds on a page in `PageStructure.queries`, whether the builder wrote them or a human did.
-
-## Address a Query
-
-`QueryRef` is `<pageRef>@<name>`, e.g. `/books@inStockCount`. The page part says where the route lives; the resource the query reads is recorded in the query itself, not in its ref.
+`QueryRef` is `<pageRef>@<name>`, for example `/books@inStockCount`. The page part says where the route lives. The query itself records the resource it reads, and the ref does not.
 
 ```typescript
 import type { QueryRef } from "@antelopejs/interface-dms-builder";
@@ -41,9 +41,9 @@ import type { QueryRef } from "@antelopejs/interface-dms-builder";
 const query: QueryRef = "/books@inStockCount";
 ```
 
-## List the Templates
+## List the templates
 
-`ListQueryTemplates(resourceType?)` returns the templates currently registered. It is a plain read, and the registry is live, so call it rather than hard-coding ids.
+`ListQueryTemplates(resourceType?)` returns the templates registered now. It is a plain read of a live registry, so the ids it returns are the ones to use.
 
 ```typescript
 import { ListQueryTemplates } from "@antelopejs/interface-dms-builder";
@@ -54,32 +54,29 @@ for (const template of templates) {
 }
 ```
 
-`QueryTemplateDescriptor`:
+`QueryTemplateDescriptor` has these fields:
 
 | Field | Type | Description |
 | --- | --- | --- |
-| `id` | `string` | The template id, e.g. `count` or `aggregate`. This is `AddQueryInput.template`. |
+| `id` | `string` | The template id, such as `count` or `aggregate`. `AddQueryInput.template` takes it. |
 | `resourceType` | `"database-table"` | The kind of resource the template reads. |
 | `title` | `string` | A human-readable title. |
-| `description` | `string` | What the template computes. |
-| `output` | `QueryOutputKind` | The shape the query's route responds with. |
+| `description` | `string` | What the template computes. Optional. |
+| `output` | `QueryOutputKind` | The shape the query's route answers with. |
 | `params` | `ConfigSchema` | The template's parameter schema, in the same vocabulary as the block catalog. |
 
-`QueryOutputKind` says what the route responds with:
+`QueryOutputKind` names what the route answers with:
 
 | Kind | Response | Templates |
 | --- | --- | --- |
-| `"scalar"` | `{ value }` — one number | `count`, `aggregate` |
-| `"series"` | `{ series }` — one point per group, each `{ x, y }` | `series` |
+| `"scalar"` | `{ value }`, one number | `count`, `aggregate` |
+| `"series"` | `{ series }`, one `{ x, y }` point per group | `series` |
 
-A series point carries its group as `x` and what was measured as `y`. A bucketed
-group is a number that sorts — `2026`, `202601`, `20260114` — rather than a label:
-the group is also what the points are ordered by, and a label belongs to a
-response that knows the reader's locale.
+A series point carries its group as `x` and the measure as `y`. A bucketed group is a number that sorts, such as `2026`, `202601` or `20260114`, and not a label. The points are ordered by the group, and a label would need the reader's locale, which the route does not know.
 
-Read `params` the way you read a block's `config` schema, described in [Catalog](./3.catalog.md) — it tells you which keys `AddQueryInput.params` accepts, and a key the template does not declare fails with `invalid_config`.
+`params` reads like a block's `config` schema, described in [Catalog](./3.catalog.md). It lists the keys that `AddQueryInput.params` accepts. A key the template does not declare fails with `invalid_config`, and so does an unknown template id.
 
-## Add a Query
+## Add a query
 
 ```typescript
 import { AddQuery } from "@antelopejs/interface-dms-builder";
@@ -98,7 +95,7 @@ if (result.ok) {
 }
 ```
 
-`AddQueryInput`:
+`AddQueryInput` has these options:
 
 | Option | Type | Description |
 | --- | --- | --- |
@@ -107,30 +104,30 @@ if (result.ok) {
 | `template` | `string` | A `QueryTemplateDescriptor.id`. Required. |
 | `params` | `Record<string, QueryParamValue>` | The template's parameters. |
 | `endpoint` | `string` | The route path relative to the page, served at `/dms/pages<pageRef><endpoint>`. Defaults to `/stats/<kebab-name>`. |
-| `response` | `QueryResponseShape` | How the answer is arranged for the block reading it. Defaults to what the calculation computes. |
+| `response` | `QueryArrangement` | How the answer is arranged for the block that reads it. Defaults to what the template computes. |
 | `compare` | `boolean` | Also answer the preceding period, so a card can show a variation. |
 
-The result carries both addresses: `query` is the `QueryRef` to configure or remove it by, `route` is the URL a block fetches from: the endpoint under the page, at `/dms/pages<pageRef><endpoint>` (`pageRoutePath(pageRef, endpoint)` from `@antelopejs/interface-dms/page`). The DMS serves the routes of a page controller under its own `/dms/pages` prefix, since the page's own path is the page.
+The result carries two addresses. `query` is the `QueryRef` that configures or removes the query. `route` is the URL a block fetches from, the endpoint under the page at `/dms/pages<pageRef><endpoint>`, which `pageRoutePath(pageRef, endpoint)` from `@antelopejs/interface-dms/page` also builds. The DMS serves the routes of a page controller under its own `/dms/pages` prefix, because the page's own path is the page.
 
-A few rules the operation enforces:
+The operation enforces these rules:
 
-- `name` must be a camelCase identifier, and must not collide with a member the page or the model already has. A collision fails with `duplicate_name` in the `query` scope.
-- `endpoint` must start with `/`, and must not collide with another route on the page. Any path is allowed otherwise, because read-back identifies a query by its shape rather than by its URL.
-- When a model method of that name already exists compiling a *different* chain, the model method is emitted under a free suffixed name, so the queries already sharing the original keep their behavior.
+- `name` must be a camelCase identifier, or the operation fails with `invalid_config`. A name that matches a member of the page or of the model fails with `duplicate_name` in the `query` scope.
+- `endpoint` must start with `/`, or the operation fails with `invalid_config`. An endpoint that another route on the page already uses fails with `duplicate_name`. Any other path is allowed, because read-back identifies a query by its shape and not by its URL.
+- A model method of that name may already exist and compile a different chain. The builder then emits the model method under a free suffixed name, so the queries that share the original keep their behavior.
 
-## Filter the Rows
+## Filter the rows
 
-`QueryFilter` is one conjunct of a template's `where`. Filters combine with AND.
+`QueryFilter` is one condition of a template's `where`. Filters combine with AND.
 
 | Field | Type | Description |
 | --- | --- | --- |
 | `field` | `string` | A field of the resource. It must exist and must not be opaque. |
 | `op` | `FilterOp` | The comparison. |
-| `value` | `QueryParamValue` | A plain scalar baked into the chain, or a `QueryParamBinding`. |
+| `value` | `QueryParamValue` | A plain scalar written into the chain, or a `QueryParamBinding`. A scalar must match the field's type. |
 
-`FilterOp` is `"eq" | "ne" | "gt" | "ge" | "lt" | "le"`. The ordering operators (`gt`, `ge`, `lt`, `le`) are rejected on `boolean` and `select` fields.
+`FilterOp` is `"eq" | "ne" | "gt" | "ge" | "lt" | "le"`. The ordering operators (`gt`, `ge`, `lt` and `le`) fail with `invalid_config` on `boolean` and `select` fields.
 
-`QueryParamValue` is `unknown`, and a query's values are data: an `ExprValue` anywhere in a query's params is refused with `invalid_config`, since a raw expression would put uncheckable code inside a model body. The other sentinels are described in [Value Encodings](./7.values.md).
+`QueryParamValue` is a `ConfigValue`, which is plain data. An `ExprValue` anywhere in a query's params fails with `invalid_config`, because a raw expression would put code the builder cannot check inside a model body. [Value encodings](./7.values.md) describes the other sentinels.
 
 ```typescript
 import { AddQuery } from "@antelopejs/interface-dms-builder";
@@ -147,9 +144,9 @@ await AddQuery("/books", {
 });
 ```
 
-## Bind a Value at Request Time
+## Bind a value at request time
 
-`QueryParamBinding` replaces a baked-in filter value with one supplied per request. It becomes a parameter of the model method and a declared parameter on the route.
+`QueryParamBinding` replaces a fixed filter value with a value each request supplies. It becomes a parameter of the model method and a declared `@Parameter` on the route.
 
 ```typescript
 import { AddQuery } from "@antelopejs/interface-dms-builder";
@@ -172,12 +169,12 @@ await AddQuery("/books", {
 | `$param.name` | `string` | A camelCase identifier. The route exposes the value under this name. |
 | `$param.in` | `"query" \| "param"` | Where the route reads the value from. Defaults to `"query"`. |
 
-`name` and `in` describe the route, not the model: the route reads the value from that source, coerces it, and passes it positionally to the model method, whose own parameter is named from the template.
+`name` and `in` describe the route, not the model. The route reads the value from that source, converts it with `Number(...)`, `new Date(...)` or a comparison with `"true"` for the field's type, and passes it by position to the model method. The model method names its own parameter from the template.
 
-Two rules to plan for:
+Two rules apply:
 
-- `in: "param"` reads a path segment, so the endpoint must declare a matching `:name`. The default `/stats/…` endpoint has none, so a path-bound value forces you to supply an endpoint that does. A mismatch fails with `invalid_config` rather than emitting a route whose value never binds.
-- Two filters may bind the same parameter name, but only when they agree on its type and source.
+- `in: "param"` reads a path segment, so the endpoint must declare a matching `:name`. The default `/stats/...` endpoint has no segment, so a path-bound value needs an endpoint that declares one. A mismatch fails with `invalid_config`, and the builder emits no route.
+- Two filters can bind the same parameter name only when they agree on its type and its source.
 
 ```typescript
 import { AddQuery } from "@antelopejs/interface-dms-builder";
@@ -199,9 +196,9 @@ await AddQuery("/books", {
 });
 ```
 
-## Measure per Group
+## Measure per group
 
-The `series` template answers one point per group rather than one number, which is what a chart, a ranking or any other multi-point block reads. Group by a field's own value, or by a period of a date field.
+The `series` template answers one point per group instead of one number. A chart, a ranking and the other blocks that show several points read it. A series groups by a field's own value, or by a period of a date field.
 
 ```typescript
 import { AddQuery } from "@antelopejs/interface-dms-builder";
@@ -226,44 +223,44 @@ await AddQuery("/dashboard", {
 | Option | Type | Description |
 | --- | --- | --- |
 | `op` | `"count" \| "sum" \| "avg" \| "min" \| "max"` | What to measure in each group. Defaults to `count`. |
-| `field` | `string` | The numeric field the measure reads. Required for every op but `count`. |
-| `groupBy` | `string` | The field the rows are grouped by. Required. |
-| `bucket` | `"day" \| "week" \| "month" \| "quarter" \| "year"` | Groups a date field by period instead of by exact value. A week runs Monday to Sunday. Only for a date field. |
-| `timezone` | `string` | IANA zone the period is computed in. |
-| `orderBy` | `"group" \| "measure"` | Order the points by their group (a timeline) or by what was measured (a ranking). Defaults to `group`. |
+| `field` | `string` | The numeric field the measure reads. Required for every op except `count`. |
+| `groupBy` | `string` | The field that groups the rows. Required. Without a `bucket`, it must be a text or numeric field. |
+| `bucket` | `"day" \| "week" \| "month" \| "quarter" \| "year"` | Groups a date field by period instead of by exact value. A week runs from Monday to Sunday. Only valid on a date field. |
+| `timezone` | `string` | The IANA zone the period is computed in. |
+| `orderBy` | `"group" \| "measure"` | Orders the points by their group, for a timeline, or by the measure, for a ranking. Defaults to `group`. |
 | `direction` | `"asc" \| "desc"` | Defaults to `asc`. |
-| `limit` | `number` | Keep only the first N points after ordering — a top N. At most 1000. |
+| `limit` | `number` | Keeps only the first N points after ordering, for a top N. A whole number from 1 to 1000. |
 | `where` | `QueryFilter[]` | As for every other template. |
 
-Three rules worth planning for:
+These rules apply to a series:
 
-- **A series is always ordered.** Databases return groups in no particular order — MongoDB scrambles them — so an ordering is emitted whether or not you ask for one. Omitting `orderBy` gives a timeline: the group, ascending.
-- **Omitting `timezone` buckets in UTC.** A row near a period boundary may belong to a different bucket in the reader's local time. Pass the zone the reader uses for reporting.
-- **A top N is an ordering plus a limit**, not a separate template: `orderBy: "measure"`, `direction: "desc"`, `limit: 5`.
+- **A series is always ordered.** A database returns groups in its own order, and MongoDB returns them unordered, so the builder always emits an ordering. Without `orderBy` and `direction`, the points come as a timeline, by group, ascending.
+- **Without `timezone`, periods are computed in UTC.** A row near a period boundary can then fall in a different bucket than in the reader's local time.
+- **A top N is an ordering plus a limit,** such as `orderBy: "measure"`, `direction: "desc"` and `limit: 5`. It has no template of its own.
 
-There is no week bucket. Neither database adapter exposes an ISO week, and deriving one from the day of the year puts the first days of January in the previous year's week — a wrong week being worse than a missing one.
+A week runs from Monday to Sunday, like an ISO week, and a week that straddles New Year stays one week. `AddQuery` refuses `bucket: "week"` with `invalid_config` when the installed `@antelopejs/interface-dms` cannot name a week for a reader. Bucket by day or month then, or update it.
 
-A series reads back like any other query: `GetPageStructure` reports its `template` and the parameters that produced it, including the ordering the engine applies when you omit one. Editing and removing it work as they do for a scalar query — the model method goes with the route.
+A series reads back like any other query. `GetPageStructure` reports its `template` and the parameters that produced it, including the ordering the engine applies when you omit one. Configuring and removing it work as for a scalar query, and the model method goes with the route.
 
-A chain edited past what the grammar accepts is the exception, and the rule is the same as everywhere else: it reads as `opaque`, keeps its `endpoint`, `resource`, `modelMethod` and `output`, and the builder will list and remove it but never rewrite it.
+A chain edited past what the templates accept reads as `opaque`, as everywhere else. It keeps its `endpoint`, `resource`, `modelMethod` and `output`. The builder lists and removes it, but never rewrites it.
 
-## Arrange the Answer
+## Arrange the answer
 
-One calculation feeds several kinds of block, so `response` says how its answer is dressed rather than making you describe it more than once.
+One calculation feeds several kinds of block. `response` says how the route arranges its answer, so you describe the calculation only once.
 
 | Shape | Answer | Read by |
 | --- | --- | --- |
-| `series` | `{ series }` — the points | A bare chart |
-| `card` | `{ value, series, previousValue?, delta?, comparisonSeries? }` | A chart card |
-| `value` | `{ value, previousValue?, delta?, sparkline? }` | A KPI card |
-| `items` | `{ items }` — the points as ranked entries | A ranked list |
+| `series` | `{ series }`, the points | A bare chart |
+| `card` | `{ value?, series, previousValue?, delta?, comparisonSeries? }` | A chart card |
+| `value` | `{ value?, previousValue?, delta?, sparkline? }` | A KPI card |
+| `items` | `{ items }`, the points as ranked entries | A ranked list |
 
-The arrangements that need more than a property name are built by helpers `@antelopejs/interface-dms/base` publishes, which the generated route imports. That keeps the route to one expression, and is why a query whose answer is arranged still reads back as the parameters that produced it.
+The `card`, `value` and `items` shapes come from the `chartCardData`, `kpiCardData` and `topListData` helpers that `@antelopejs/interface-dms/base` publishes. The generated route imports them. The route stays one expression, so a query with an arranged answer still reads back as the parameters that produced it.
 
-Two rules worth planning for:
+Two rules apply:
 
-- **The headline figure is taken from the points.** Counts and sums add up, a min or max is the min or max of the group figures — but an average is the average of the group averages, which is not the average over all the rows whenever the groups are uneven.
-- **`compare` needs a period the route supplies.** It re-asks the same model method with the `compareFrom` / `compareTo` bounds the request carried. A calculation whose dates are baked in has nothing to shift, so it is not compared and no second call is emitted.
+- **The headline figure comes from the points.** Counts and sums add up, and a min or a max is the min or the max of the group figures. An average is the average of the group averages. When the groups differ in size, that is not the average over all the rows.
+- **`compare` needs a period that the route supplies.** The route calls the same model method again with the `compareFrom` and `compareTo` bounds of the request. The query must bind exactly two date values. A calculation with fixed dates has nothing to shift, so the builder emits no second call.
 
 ```typescript
 import { AddQuery } from "@antelopejs/interface-dms-builder";
@@ -285,13 +282,13 @@ await AddQuery("/dashboard", {
   response: "card",
   compare: true,
 });
-// GET /dms/pages/dashboard/stats/revenue?from=…&to=…&compareFrom=…&compareTo=…
+// GET /dms/pages/dashboard/stats/revenue?from=...&to=...&compareFrom=...&compareTo=...
 // { value, series, previousValue, delta, comparisonSeries }
 ```
 
-## Configure a Query
+## Configure a query
 
-`ConfigureQuery(query, patch, opts?)` recompiles the query from the merged patch and replaces both emitted members. Fields you leave out keep their current value, read back off disk.
+`ConfigureQuery(query, patch, opts?)` compiles the query again from the merged patch and replaces the route and the model method. A field you leave out keeps the value read back from the file.
 
 ```typescript
 import { ConfigureQuery } from "@antelopejs/interface-dms-builder";
@@ -301,13 +298,13 @@ await ConfigureQuery("/books@inStockCount", {
 });
 ```
 
-The patch is a `Partial<AddQueryInput>`, so `resource`, `template`, `params` and `endpoint` are all patchable. The query keeps the name in its `QueryRef`: a `name` in the patch is not applied.
+The patch is a `Partial<AddQueryInput>`. The operation applies its `resource`, `template`, `params` and `endpoint`. The query keeps the name in its `QueryRef`, so a `name` in the patch has no effect. `response` and `compare` in the patch also have no effect, and the route the operation writes has neither an arrangement nor a comparison.
 
-A query that no longer reads back as an editable template fails with `opaque_target`. That is deliberate — an opaque chain means a human owns it now, and regenerating it from a template it no longer matches would revert their edit. Remove it and add a new one if you need to.
+A query that no longer reads back as an editable template fails with `opaque_target`. An opaque chain belongs to a person now, and a chain generated again from a template it no longer matches would undo their edit. To change such a query, remove it and add a new one.
 
-## Remove a Query
+## Remove a query
 
-`RemoveQuery(query, opts?)` deletes the query's route from the page, and drops the model method it called once nothing else calls it — a method shared with another query stays. It works on an opaque query too.
+`RemoveQuery(query, opts?)` deletes the query's route from the page. It deletes the model method too once nothing else calls it, and keeps a method that another query shares. It works on an opaque query as well.
 
 ```typescript
 import { RemoveQuery } from "@antelopejs/interface-dms-builder";
@@ -315,31 +312,33 @@ import { RemoveQuery } from "@antelopejs/interface-dms-builder";
 await RemoveQuery("/books@cheaperThan");
 ```
 
-## Read a Query Back
+## Read a query back
 
-`QueryStructure` is a query as found on disk. Read-back is purely structural: a route reads as a query when its shape and the chain it calls both parse, so a hand-written route matching the grammar is as editable as a generated one, and any edit that keeps the chain in-grammar is simply re-read.
+`QueryStructure` is a query as found on disk. Read-back is structural. A route reads as a query when its shape and the chain it calls both parse. A hand-written route that matches the grammar is as editable as a generated one, and an edit that keeps the chain inside the grammar reads back again.
 
 | Field | Type | Description |
 | --- | --- | --- |
 | `name` | `string` | The query name. Always present. |
-| `endpoint` | `string` | The route path relative to the page's slug, as `AddQueryInput.endpoint` takes it. Always present. |
-| `resource` | `ResourceRef` | The resource the route's model parameter points at. |
-| `modelMethod` | `string` | The model method the route calls. Sharing is driven by the query's *name*: a query looks for its own name and numbered forks of it, so two differently-named queries never share a method however identical their chains. |
-| `output` | `QueryOutputKind` | The output shape, read from the property the route's response carries — so a query whose chain no longer parses still reports what it answers. |
+| `endpoint` | `string` | The route path relative to the page's slug, in the form `AddQueryInput.endpoint` takes. Always present. |
+| `resource` | `ResourceRef` | The resource that the route's model parameter points at. |
+| `modelMethod` | `string` | The model method the route calls. A query looks for a method with its own name or a numbered fork of it, so two queries with different names never share a method, even when their chains match. |
+| `output` | `QueryOutputKind` | The output shape, read from the property the route's response carries. A query whose chain no longer parses still reports what it answers. |
+| `response` | `QueryArrangement` | How the answer is arranged, when the route wraps the calculation in a helper. |
+| `compare` | `boolean` | `true` when the route also answers the preceding period. |
 | `template` | `string` | The template the chain was compiled from. |
-| `params` | `Record<string, unknown>` | The parameters that produced the chain. |
-| `routeParams` | `{ name: string; in: "query" \| "param" \| "header" }[]` | The route's declared parameters — the source of truth for a bound value's `name` and `in`. `header` appears only on hand-written routes. |
-| `opaque` | `boolean` | `true` when the query could not be reversed to an editable template. |
-| `opaqueReason` | `"unparseable_route" \| "unparseable_chain"` | Why it is opaque. Set when `opaque === true`. |
+| `params` | `Record<string, QueryParamValue>` | The parameters that produced the chain. |
+| `routeParams` | `{ name: string; in: "query" \| "param" \| "header" }[]` | The route's declared parameters. They are what a bound value's `name` and `in` are read from. `header` appears only on hand-written routes. |
+| `opaque` | `boolean` | `true` when the query does not read back as an editable template. |
+| `opaqueReason` | `"unparseable_route" \| "unparseable_chain"` | Why the query is opaque. Set when `opaque` is `true`. |
 
-The two opaque reasons say which half failed:
+Each opaque reason names the half that failed:
 
-- **`unparseable_route`** — the GET wrapper is not the recognized `return { value: await model.m(...) }` shape.
-- **`unparseable_chain`** — the model method it calls is not a chain any registered template accepts: hand-written, edited out of grammar, or emitted by a newer builder.
+- **`unparseable_route`.** The GET method is not the `return { value: await model.m(...) }` shape the builder recognizes.
+- **`unparseable_chain`.** The model method it calls is not a chain that any registered template accepts. It was hand-written, edited outside the grammar, or emitted by a newer builder.
 
-A query that no longer parses still reports its `endpoint`, `resource` and `modelMethod`; only `template` and `params` go missing. The builder can therefore always see and remove what it cannot edit.
+A query that no longer parses still reports its `endpoint`, `resource` and `modelMethod`. Only `template` and `params` are missing. The builder can always see and remove what it cannot edit.
 
-```typescript
+```typescript fragment
 import { GetPageStructure } from "@antelopejs/interface-dms-builder";
 import { pageRoutePath } from "@antelopejs/interface-dms/page";
 
@@ -350,6 +349,6 @@ if (result.ok) {
 }
 ```
 
-## Next Steps
+## Next steps
 
-- [Value Encodings](./7.values.md) - Write configuration values that are not plain literals
+- [Value encodings](./7.values.md) shows how to write configuration values that are not plain literals.

package/docs/7.values.md

@@ -1,10 +1,16 @@
-# Value Encodings
+---
+title: "Value encodings"
+description: "How the builder writes a configuration value to source: plain JSON as a literal, and the $dataType, $ref, $expr and $block sentinels for values that must reach the source as TypeScript."
+mode: reference
+---
 
 ## Overview
 
-Configuration values are plain JSON by default. `AddBlockInput.config`, a `ConfigureBlock` patch, a page's `permission` — all of it is written to source exactly as you pass it, as a literal.
+Configuration values are plain JSON by default. The builder writes `AddBlockInput.config`, a `ConfigureBlock` patch and a page's `permission` to source exactly as you pass them, as literals.
 
-Some options need TypeScript values rather than JSON literals. A form field needs a DataType instance, a relation needs a controller class, and a chart card needs a nested chart. The structured encodings below let the builder write those values and their imports. Use a raw `$expr` only as an escape hatch; drafts and query parameters reject it.
+The type of such a value is `ConfigValue`. It is a string, a number, a boolean, `null`, `undefined`, an array of `ConfigValue` items, or a `ConfigObject`, an object whose members are `ConfigValue` items. The compiler refuses a function or a class instance. `undefined` stands for an absent member. The builder skips it when it writes, and a `ConfigureBlock` patch reads it as "remove this key". The four encodings below are `ConfigObject` values.
+
+Some options need TypeScript values instead of JSON literals. A form field needs a DataType instance, a relation needs a controller class, and a chart card needs a nested chart. The structured encodings below let the builder write those values and their imports. A raw `$expr` is the fallback for anything else, and page drafts and query parameters refuse it.
 
 ```typescript
 import type {
@@ -15,26 +21,26 @@ import type {
 } from "@antelopejs/interface-dms-builder";
 ```
 
-## Choose an Encoding
+## Choose an encoding
 
 | You are writing | Encoding |
 | --- | --- |
 | A string, number, boolean, array or object | The value itself, as JSON. |
 | A value the catalog marks `x-dataType` | `DataTypeValue` |
-| A reference to a builder-generated resource class | `RefValue` |
-| A nested component in an option marked `x-component` | `BlockValue` |
+| A reference to a class of a builder-generated resource | `RefValue` |
+| A nested component in an option the catalog marks `x-component` | `BlockValue` |
 | Anything else that must reach the source as code | `ExprValue` |
 
-The catalog is what tells you which option needs which: an option marked `x-dataType` in a block's `ConfigSchema` takes a `DataTypeValue`, and nothing else. See [Catalog](./3.catalog.md).
+The catalog says which option needs which encoding. An option marked `x-dataType` in a block's `ConfigSchema` takes a `DataTypeValue` and nothing else. See [Catalog](./3.catalog.md).
 
-## Write a DataType
+## Write a `DataTypeValue`
 
-`DataTypeValue` emits `new <DataType>(<config>)` and adds the import for you.
+`DataTypeValue` emits `new <DataType>(<config>)` and adds the import.
 
 | Field | Type | Description |
 | --- | --- | --- |
-| `$dataType` | `string` | A `DataTypeDescriptor.id` from the catalog, e.g. `"string"` or `"select"`. |
-| `config` | `Record<string, unknown>` | The DataType's options. Omit for a no-arg `new <DataType>()`. |
+| `$dataType` | `string` | A `DataTypeDescriptor.id` from the catalog, such as `"string"` or `"select"`. |
+| `config` | `ConfigObject` | The DataType's options. Omit it for `new <DataType>()` with no argument. |
 
 ```typescript
 import { AddBlock } from "@antelopejs/interface-dms-builder";
@@ -56,17 +62,17 @@ await AddBlock({
 // emits:  type: new DefaultDataTypes.StringType({ placeholder: "Name" })
 ```
 
-The same encoding is what a resource field's `dataType` takes, described in [Resources](./5.resources.md).
+A resource field's `dataType` takes the same encoding, as [Resources](./5.resources.md) describes.
 
-A `$dataType` id the catalog does not list fails with `invalid_config`, and the message points you at `GetCatalog` for the valid ids.
+A `$dataType` id that the catalog does not list fails with `invalid_config`. The message names `GetCatalog` as the source of the valid ids.
 
-## Reference a Generated Class
+## Reference a generated class
 
-`RefValue` emits the bare class identifier of a builder-generated resource, with its import added. It is the structured, validated alternative to `ExprValue` for a class reference — a `RelationType`'s `dataApiController`, for instance.
+`RefValue` emits the bare class name of a builder-generated resource and adds its import. It is the checked alternative to `ExprValue` for a class reference, such as the `dataApiController` of a `RelationType`.
 
 | Field | Type | Description |
 | --- | --- | --- |
-| `$ref.resource` | `string` | A `ResourceRef` — the resource's name, e.g. `"product"`. |
+| `$ref.resource` | `string` | A `ResourceRef`, the resource's name, such as `"product"`. |
 | `$ref.as` | `"dataApi" \| "table" \| "model"` | Which of the resource's classes to reference. Defaults to `"dataApi"`. |
 
 ```typescript
@@ -83,17 +89,17 @@ await AddField("order-line", {
 // emits:  dataApiController: productDataAPI   (imported from the resource's data-api.ts)
 ```
 
-`as` selects among the three classes a resource generates: `"dataApi"` for the `DataController`, `"table"` for the `Table`, `"model"` for the `BasicDataModel`. An unknown resource fails with `invalid_config`, and the message points you at `ListResources`.
+`as` picks one of the three classes a resource generates. `"dataApi"` is the `DataController`, `"table"` is the `Table` and `"model"` is the `BasicDataModel`. An unknown resource fails with `invalid_config`, and the message names `ListResources` as the source of the valid refs.
 
-`AddBlockInput.controller` is the same reference in a dedicated field: a controller-leading block type takes a `ResourceRef` there rather than a `RefValue` in its config. See [Page Operations](./4.page-operations.md).
+`AddBlockInput.controller` holds the same reference in a field of its own. A block type that leads with a controller takes a `ResourceRef` there, not a `RefValue` in its config. See [Page operations](./4.page-operations.md).
 
-## Write a Raw Expression
+## Write a raw expression
 
-`ExprValue` is emitted verbatim. Reach for it only when the builder cannot model the value structurally.
+The builder emits an `ExprValue` as written. It is for a value the builder cannot model as structure.
 
 | Field | Type | Description |
 | --- | --- | --- |
-| `$expr` | `string` | TypeScript source, spliced into the emitted file as written. |
+| `$expr` | `string` | TypeScript source, inserted into the emitted file as written. |
 
 ```typescript
 import { ConfigureBlock } from "@antelopejs/interface-dms-builder";
@@ -103,16 +109,16 @@ await ConfigureBlock("/revenue#total", {
 });
 ```
 
-Two constraints come with it:
+Two constraints apply:
 
-- The referenced symbol must already be in scope in the target file. `$expr` adds no import.
-- `$expr` is refused inside a query's parameters — a query's values are data, and a raw expression would put uncheckable code inside a model body. See [Queries](./6.queries.md).
+- The symbol the expression names must already be in scope in the target file. `$expr` adds no import.
+- A query's parameters refuse `$expr`, because a query's values are data and a raw expression would put code the builder cannot check inside a model body. See [Queries](./6.queries.md).
 
-Consumers that run the builder in a restricted mode may refuse `$expr` outright, since arbitrary code defeats the structured guarantees the rest of the surface provides. `RefValue` is allowed in that mode precisely because it is validated; prefer it whenever the value you need is a generated class.
+A consumer that runs the builder in a restricted mode can refuse `$expr` entirely, because arbitrary code removes the checks that the structured encodings give. `RefValue` and `BlockValue` stay allowed in that mode, because the builder checks them. For a generated class, `RefValue` is the encoding to use.
 
-## Nest a Block in a Config Value
+## Nest a block in a config value
 
-A few options hold a component rather than data — a `ChartCard`'s `chart`, marked `x-component` in the catalog. `BlockValue` is how you write one: the builder emits the nested factory call and adds its import.
+A few options hold a component instead of data, such as the `chart` of a `ChartCard`, which the catalog marks `x-component`. `BlockValue` writes such a component. The builder emits the nested factory call and adds its import.
 
 ```typescript
 import type { BlockValue } from "@antelopejs/interface-dms-builder";
@@ -120,13 +126,13 @@ import type { BlockValue } from "@antelopejs/interface-dms-builder";
 const chart: BlockValue = {
   $block: { type: "ChartArea", config: { xaxisType: "datetime" } },
 };
-// → chart: ChartArea({ xaxisType: "datetime" })
+// emits:  chart: ChartArea({ xaxisType: "datetime" })
 ```
 
-`type` is a catalog key, like `AddBlockInput.type`; an unknown one is rejected with `invalid_config`. Read-back is symmetrical: a nested factory call whose callee is a known block type comes back as a `$block` sentinel rather than as `$expr`, so the value stays editable.
+`type` is a catalog key, like `AddBlockInput.type`. In a page draft, an unknown type fails with `invalid_config`. `AddBlock` and `ConfigureBlock` do not turn it into a result, and the call rejects with an `unknown block type` error. Read-back mirrors the write. A nested factory call whose callee is a known block type reads back as a `$block` sentinel, not as `$expr`, so the value stays editable.
 
-Most nesting does *not* go through config — it goes through `.child`, which you express with `AddBlockInput.parent` or with `BlockDraft.children`. Reach for `$block` only where the catalog marks an option `x-component`.
+Most nesting does not go through config. It goes through `.child`, which `AddBlockInput.parent` or `BlockDraft.children` express. `$block` is only for an option that the catalog marks `x-component`.
 
-## Next Steps
+## Next steps
 
-- [Results and Errors](./8.results-and-errors.md) - Branch on an operation's result and read its diagnostics
+- [Results and errors](./8.results-and-errors.md) shows how to branch on an operation's result and read its diagnostics.