@antelopejs/interface-dms-builder 0.1.1 → 0.1.3

package/dist/catalog.d.ts

@@ -13,7 +13,7 @@ export interface DynamicSlots {
     idKey: string;
     labelKey?: string;
 }
-export type OptionWidget = "text" | "textarea" | "number" | "range" | "switch" | "select" | "segmented" | "icon" | "color" | "url" | "resource" | "field" | "dataType" | "query" | "permission" | "json" | "block";
+export type OptionWidget = "text" | "textarea" | "number" | "range" | "switch" | "select" | "segmented" | "icon" | "color" | "url" | "resource" | "field" | "dataType" | "query" | "dataSource" | "permission" | "json" | "block";
 export type FieldAspect = "listable" | "searchable" | "sortable" | "filterable";
 export interface OptionUi {
     label?: string;
@@ -27,8 +27,15 @@ export interface OptionUi {
     step?: number;
     scope?: string;
     blockTypes?: string[];
+    supplies?: string[];
     fieldAspect?: FieldAspect | FieldAspect[];
     flatten?: boolean;
+    valueLabels?: Record<string, string>;
+    derivedFrom?: string;
+    optIn?: string;
+    typedBy?: string;
+    advanced?: boolean;
+    initial?: unknown;
 }
 export type OptionType = "string" | "number" | "boolean" | "object" | "array" | "record" | "union" | "unknown";
 export interface OptionSchema {
@@ -41,6 +48,7 @@ export interface OptionSchema {
     properties?: Record<string, OptionSchema>;
     items?: OptionSchema;
     values?: OptionSchema;
+    keys?: OptionSchema;
     oneOf?: OptionSchema[];
     discriminator?: string;
     prefixItems?: OptionSchema[];
@@ -49,6 +57,7 @@ export interface OptionSchema {
     ui?: OptionUi;
     "x-dataType"?: boolean;
     "x-component"?: boolean;
+    "x-controller"?: boolean;
     [key: string]: unknown;
 }
 export type ConfigSchema = Record<string, OptionSchema>;
@@ -85,3 +94,16 @@ export interface BlockCatalog {
     reservedFieldNames: string[];
     generatedAt: string;
 }
+export interface DataSourceDescriptor {
+    id: string;
+    title: string;
+    description?: string;
+    responseShape: string;
+    path: string;
+    method?: string;
+    params?: ConfigSchema;
+    period?: {
+        from: string;
+        to: string;
+    };
+}

package/dist/drafts.d.ts

@@ -1,4 +1,5 @@
 import type { BlockPath } from "./addressing";
+import type { AddQueryInput, QueryPreview } from "./queries";
 import type { ResourceRef } from "./resources";
 import type { MutationOpts, OpResult } from "./results";
 import type { EditablePageMeta } from "./structure";
@@ -15,6 +16,7 @@ export interface BlockDraft {
 export interface PageDraft {
     page?: Partial<EditablePageMeta>;
     blocks: BlockDraft[];
+    queries?: AddQueryInput[];
 }
 export interface ComponentPreview {
     componentName: string;
@@ -35,3 +37,9 @@ export declare const SetPageBlocks: (page: string, draft: PageDraft, opts?: Muta
     version: string;
 }>>;
 export declare const PreviewLayout: (page: string, draft: PageDraft) => Promise<OpResult<PageLayoutPreview>>;
+export declare const PreviewQuery: (request: QueryPreviewRequest) => Promise<OpResult<QueryPreview>>;
+export interface QueryPreviewRequest {
+    query: AddQueryInput;
+    args?: Record<string, unknown>;
+    tenant?: string;
+}

package/dist/drafts.js

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PreviewLayout = exports.SetPageBlocks = void 0;
+exports.PreviewQuery = exports.PreviewLayout = exports.SetPageBlocks = void 0;
 const interface_core_1 = require("@antelopejs/interface-core");
 exports.SetPageBlocks = (0, interface_core_1.InterfaceFunction)();
 exports.PreviewLayout = (0, interface_core_1.InterfaceFunction)();
+exports.PreviewQuery = (0, interface_core_1.InterfaceFunction)();
 //# sourceMappingURL=drafts.js.map

package/dist/drafts.js.map

@@ -1 +1 @@
-{"version":3,"file":"drafts.js","sourceRoot":"","sources":["../src/drafts.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AAwElD,QAAA,aAAa,GACxB,IAAA,kCAAiB,GAMd,CAAC;AAOO,QAAA,aAAa,GACxB,IAAA,kCAAiB,GAEd,CAAC"}
+{"version":3,"file":"drafts.js","sourceRoot":"","sources":["../src/drafts.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AAmFlD,QAAA,aAAa,GACxB,IAAA,kCAAiB,GAMd,CAAC;AAOO,QAAA,aAAa,GACxB,IAAA,kCAAiB,GAEd,CAAC;AAUO,QAAA,YAAY,GACvB,IAAA,kCAAiB,GAEd,CAAC"}

package/dist/operations.d.ts

@@ -1,5 +1,5 @@
 import type { BlockPath, CategoryRef, PageRef } from "./addressing";
-import type { BlockCatalog } from "./catalog";
+import type { BlockCatalog, DataSourceDescriptor } from "./catalog";
 import type { ResourceRef } from "./resources";
 import type { MutationOpts, OpResult } from "./results";
 import type { CategorySummary, EditableCategoryMeta, EditablePageMeta, PagePermission, PageStructure, PageSummary } from "./structure";
@@ -46,6 +46,7 @@ export interface ConfigureBlockOpts extends MutationOpts {
 export declare const ListPages: () => Promise<PageSummary[]>;
 export declare const ListCategories: () => Promise<CategorySummary[]>;
 export declare const GetCatalog: () => Promise<BlockCatalog>;
+export declare const ListDataSources: (responseShape?: string | undefined) => Promise<DataSourceDescriptor[]>;
 export declare const GetPageStructure: (ref: string) => Promise<OpResult<PageStructure>>;
 export declare const RefreshSourceIndex: (scope?: RefreshScope | undefined) => Promise<void>;
 export declare const CreatePage: (input: CreatePageInput) => Promise<OpResult<{

package/dist/operations.js

@@ -1,10 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RemoveBlock = exports.MoveBlock = exports.ConfigureBlock = exports.AddBlock = exports.DeleteCategory = exports.ConfigureCategory = exports.CreateCategory = exports.DeletePage = exports.ConfigurePage = exports.CreatePage = exports.RefreshSourceIndex = exports.GetPageStructure = exports.GetCatalog = exports.ListCategories = exports.ListPages = void 0;
+exports.RemoveBlock = exports.MoveBlock = exports.ConfigureBlock = exports.AddBlock = exports.DeleteCategory = exports.ConfigureCategory = exports.CreateCategory = exports.DeletePage = exports.ConfigurePage = exports.CreatePage = exports.RefreshSourceIndex = exports.GetPageStructure = exports.ListDataSources = exports.GetCatalog = exports.ListCategories = exports.ListPages = void 0;
 const interface_core_1 = require("@antelopejs/interface-core");
 exports.ListPages = (0, interface_core_1.InterfaceFunction)();
 exports.ListCategories = (0, interface_core_1.InterfaceFunction)();
 exports.GetCatalog = (0, interface_core_1.InterfaceFunction)();
+exports.ListDataSources = (0, interface_core_1.InterfaceFunction)();
 exports.GetPageStructure = (0, interface_core_1.InterfaceFunction)();
 exports.RefreshSourceIndex = (0, interface_core_1.InterfaceFunction)();
 exports.CreatePage = (0, interface_core_1.InterfaceFunction)();

package/dist/operations.js.map

@@ -1 +1 @@
-{"version":3,"file":"operations.js","sourceRoot":"","sources":["../src/operations.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AA4FlD,QAAA,SAAS,GAAG,IAAA,kCAAiB,GAAgC,CAAC;AAC9D,QAAA,cAAc,GACzB,IAAA,kCAAiB,GAAoC,CAAC;AAC3C,QAAA,UAAU,GAAG,IAAA,kCAAiB,GAA+B,CAAC;AAC9D,QAAA,gBAAgB,GAC3B,IAAA,kCAAiB,GAAsD,CAAC;AAM7D,QAAA,kBAAkB,GAC7B,IAAA,kCAAiB,GAA2C,CAAC;AAElD,QAAA,UAAU,GACrB,IAAA,kCAAiB,GAId,CAAC;AAOO,QAAA,aAAa,GACxB,IAAA,kCAAiB,GAMd,CAAC;AACO,QAAA,UAAU,GACrB,IAAA,kCAAiB,GAA4D,CAAC;AAEnE,QAAA,cAAc,GACzB,IAAA,kCAAiB,GAEd,CAAC;AACO,QAAA,iBAAiB,GAC5B,IAAA,kCAAiB,GAKd,CAAC;AACO,QAAA,cAAc,GACzB,IAAA,kCAAiB,GAA2C,CAAC;AAElD,QAAA,QAAQ,GACnB,IAAA,kCAAiB,GAKd,CAAC;AACO,QAAA,cAAc,GACzB,IAAA,kCAAiB,GAMd,CAAC;AACO,QAAA,SAAS,GACpB,IAAA,kCAAiB,GAEd,CAAC;AACO,QAAA,WAAW,GACtB,IAAA,kCAAiB,GAEd,CAAC"}
+{"version":3,"file":"operations.js","sourceRoot":"","sources":["../src/operations.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AA4FlD,QAAA,SAAS,GAAG,IAAA,kCAAiB,GAAgC,CAAC;AAC9D,QAAA,cAAc,GACzB,IAAA,kCAAiB,GAAoC,CAAC;AAC3C,QAAA,UAAU,GAAG,IAAA,kCAAiB,GAA+B,CAAC;AAS9D,QAAA,eAAe,GAC1B,IAAA,kCAAiB,GAEd,CAAC;AACO,QAAA,gBAAgB,GAC3B,IAAA,kCAAiB,GAAsD,CAAC;AAM7D,QAAA,kBAAkB,GAC7B,IAAA,kCAAiB,GAA2C,CAAC;AAElD,QAAA,UAAU,GACrB,IAAA,kCAAiB,GAId,CAAC;AAOO,QAAA,aAAa,GACxB,IAAA,kCAAiB,GAMd,CAAC;AACO,QAAA,UAAU,GACrB,IAAA,kCAAiB,GAA4D,CAAC;AAEnE,QAAA,cAAc,GACzB,IAAA,kCAAiB,GAEd,CAAC;AACO,QAAA,iBAAiB,GAC5B,IAAA,kCAAiB,GAKd,CAAC;AACO,QAAA,cAAc,GACzB,IAAA,kCAAiB,GAA2C,CAAC;AAElD,QAAA,QAAQ,GACnB,IAAA,kCAAiB,GAKd,CAAC;AACO,QAAA,cAAc,GACzB,IAAA,kCAAiB,GAMd,CAAC;AACO,QAAA,SAAS,GACpB,IAAA,kCAAiB,GAEd,CAAC;AACO,QAAA,WAAW,GACtB,IAAA,kCAAiB,GAEd,CAAC"}

package/dist/queries.d.ts

@@ -2,7 +2,8 @@ import type { ConfigSchema } from "./catalog";
 import type { ResourceRef } from "./resources";
 import type { MutationOpts, OpResult } from "./results";
 export type QueryRef = string;
-export type QueryOutputKind = "scalar";
+export type QueryOutputKind = "scalar" | "series";
+export type QueryResponseShape = "series" | "card" | "value" | "items";
 export type FilterOp = "eq" | "ne" | "gt" | "ge" | "lt" | "le";
 export interface QueryParamBinding {
     $param: {
@@ -24,15 +25,29 @@ export interface QueryTemplateDescriptor {
     output: QueryOutputKind;
     params: ConfigSchema;
 }
+export interface QueryPoint {
+    x: number | string;
+    y: number;
+}
+export type QueryResponseBody = Record<string, unknown>;
+export interface QueryPreview {
+    output: QueryOutputKind;
+    response?: QueryResponseShape;
+    body: QueryResponseBody;
+    truncated: boolean;
+}
 export interface AddQueryInput {
     name: string;
     resource: ResourceRef;
     template: string;
     params?: Record<string, QueryParamValue>;
+    response?: QueryResponseShape;
+    compare?: boolean;
     endpoint?: string;
 }
 export interface QueryStructure {
     name: string;
+    response?: QueryResponseShape;
     endpoint: string;
     resource?: ResourceRef;
     modelMethod?: string;
@@ -43,6 +58,7 @@ export interface QueryStructure {
         name: string;
         in: "query" | "param" | "header";
     }[];
+    compare?: boolean;
     opaque?: boolean;
     opaqueReason?: "unparseable_route" | "unparseable_chain";
 }

package/dist/queries.js.map

@@ -1 +1 @@
-{"version":3,"file":"queries.js","sourceRoot":"","sources":["../src/queries.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AAgIlD,QAAA,kBAAkB,GAC7B,IAAA,kCAAiB,GAEd,CAAC;AAEO,QAAA,QAAQ,GACnB,IAAA,kCAAiB,GAMd,CAAC;AAEO,QAAA,cAAc,GACzB,IAAA,kCAAiB,GAMd,CAAC;AAEO,QAAA,WAAW,GACtB,IAAA,kCAAiB,GAEd,CAAC"}
+{"version":3,"file":"queries.js","sourceRoot":"","sources":["../src/queries.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AAyMlD,QAAA,kBAAkB,GAC7B,IAAA,kCAAiB,GAEd,CAAC;AAEO,QAAA,QAAQ,GACnB,IAAA,kCAAiB,GAMd,CAAC;AAEO,QAAA,cAAc,GACzB,IAAA,kCAAiB,GAMd,CAAC;AAEO,QAAA,WAAW,GACtB,IAAA,kCAAiB,GAEd,CAAC"}

package/dist/resources.js.map

@@ -1 +1 @@
-{"version":3,"file":"resources.js","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AA4MlD,QAAA,cAAc,GACzB,IAAA,kCAAiB,GAId,CAAC;AAcO,QAAA,iBAAiB,GAC5B,IAAA,kCAAiB,GAMd,CAAC;AAEO,QAAA,cAAc,GACzB,IAAA,kCAAiB,GAEd,CAAC;AACO,QAAA,QAAQ,GACnB,IAAA,kCAAiB,GAMd,CAAC;AACO,QAAA,cAAc,GACzB,IAAA,kCAAiB,GAMd,CAAC;AACO,QAAA,WAAW,GACtB,IAAA,kCAAiB,GAEd,CAAC;AACO,QAAA,aAAa,GACxB,IAAA,kCAAiB,GAAoC,CAAC;AAC3C,QAAA,oBAAoB,GAC/B,IAAA,kCAAiB,GAEd,CAAC"}
+{"version":3,"file":"resources.js","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AAgNlD,QAAA,cAAc,GACzB,IAAA,kCAAiB,GAId,CAAC;AAcO,QAAA,iBAAiB,GAC5B,IAAA,kCAAiB,GAMd,CAAC;AAOO,QAAA,cAAc,GACzB,IAAA,kCAAiB,GAEd,CAAC;AACO,QAAA,QAAQ,GACnB,IAAA,kCAAiB,GAMd,CAAC;AACO,QAAA,cAAc,GACzB,IAAA,kCAAiB,GAMd,CAAC;AACO,QAAA,WAAW,GACtB,IAAA,kCAAiB,GAEd,CAAC;AACO,QAAA,aAAa,GACxB,IAAA,kCAAiB,GAAoC,CAAC;AAC3C,QAAA,oBAAoB,GAC/B,IAAA,kCAAiB,GAEd,CAAC"}

package/dist/results.d.ts

@@ -14,7 +14,7 @@ export interface TypecheckError {
     message: string;
 }
 export interface OpWarning {
-    code: "index_clamped" | "datatype_fallback" | "data_not_dropped" | "route_changed";
+    code: "query_opaque" | "query_kept" | "index_clamped" | "datatype_fallback" | "data_not_dropped" | "route_changed";
     message: string;
 }
 export type DuplicateScope = "page" | "siblings" | "category" | "resource" | "query";

package/dist/structure.d.ts

@@ -48,6 +48,9 @@ export interface PageSummary {
     category: CategoryRef;
     moduleId?: string;
     filepath: string;
+    icon?: string;
+    order?: number;
+    hidden?: boolean;
 }
 export interface CategorySummary {
     ref: CategoryRef;

package/docs/1.introduction.md

@@ -81,6 +81,8 @@ for (const change of block.changes) {
 - [Catalog](./3.catalog.md) - The block types, DataTypes and reserved names the builder can report
 - [Page Operations](./4.page-operations.md) - Create pages and categories, and edit a page's block tree
 - [Resources](./5.resources.md) - Generate tables, DataAPI controllers and their fields
-- [Queries](./6.queries.md) - Compile counts and aggregates into a model method and a page route
+- [Queries](./6.queries.md) - Compile a measure, grouped or not, into a model method and a page route
 - [Value Encodings](./7.values.md) - Write configuration values that are not plain literals
 - [Results and Errors](./8.results-and-errors.md) - Branch on `OpResult`, read diagnostics, and make a write conditional
+- [Drafts and Preview](./9.drafts-and-preview.md) - Write a page's blocks and the data they read in one transaction, and preview either
+- [A Chart Without Code](./10.a-chart-without-code.md) - The whole journey, from picking a measure to reopening the page

package/docs/10.a-chart-without-code.md

@@ -0,0 +1,195 @@
+# A Chart Without Code
+
+The journey the no-code data sources were built for, end to end: someone picks a
+resource, a measure and a grouping, sees their own data, saves, and reopens the
+page to find it as they left it. No route written, no endpoint typed.
+
+This page follows what the engine does underneath, so a consumer building that
+experience knows which call belongs where.
+
+## What the block asks for
+
+A block declares the shape of answer it can read, next to its factory:
+
+```typescript
+fetchUrl: ui(z.string().optional(), {
+  label: "Data source",
+  group: "data",
+  widget: "dataSource",
+  responseShape: "card",
+  periodOption: "periodScope",
+});
+```
+
+An editor reads that from the catalog and offers only calculations whose answer
+the block can display — a series cannot be wired into a slot that renders one
+number — and knows which of the block's own options carries the period, so
+binding a source writes both in one patch.
+
+## Show the data before writing anything
+
+While the person is still choosing, `PreviewQuery` runs the calculation against
+the real table and answers what the route would:
+
+```typescript
+import { PreviewQuery } from "@antelopejs/interface-dms-builder";
+
+const preview = await PreviewQuery({
+  query: {
+    name: "revenueChart",
+    resource: "order",
+    template: "series",
+    params: {
+      op: "sum",
+      field: "amount",
+      groupBy: "createdAt",
+      bucket: "month",
+      timezone: "Europe/Brussels",
+      where: [{ field: "status", op: "eq", value: "paid" }],
+    },
+    response: "card",
+  },
+});
+```
+
+Nothing has been written at this point: no route, no model method, no file. The
+numbers on screen are the ones the saved page will show, because the calculation
+previewed and the calculation written are the same plan rendered two ways — and
+`preview.data.body` is the envelope the route will serve, arranged by the same
+helper, so the card's headline figure is previewed rather than guessed at.
+
+## Save the block and its data together
+
+The query travels in the page draft, so one save writes the block, the model
+method and the route in a single transaction:
+
+```typescript
+import { SetPageBlocks } from "@antelopejs/interface-dms-builder";
+
+await SetPageBlocks("/shop/board", {
+  blocks: [
+    {
+      name: "revenueCard",
+      type: "ChartCard",
+      config: {
+        title: "Revenue",
+        fetchUrl: "/shop/board/stats/revenue-chart",
+        periodScope: "page",
+        chart: {
+          $block: { type: "ChartArea", config: { xaxisType: "category" } },
+        },
+      },
+    },
+  ],
+  queries: [
+    {
+      name: "revenueChart",
+      resource: "order",
+      template: "series",
+      params: {
+        op: "sum",
+        field: "amount",
+        groupBy: "createdAt",
+        bucket: "month",
+        timezone: "Europe/Brussels",
+        where: [
+          { field: "status", op: "eq", value: "paid" },
+          { field: "createdAt", op: "ge", value: { $param: { name: "from" } } },
+          { field: "createdAt", op: "le", value: { $param: { name: "to" } } },
+        ],
+      },
+      response: "card",
+      compare: true,
+    },
+  ],
+});
+```
+
+Either all of it lands or none of it does. A draft that fails on its query leaves
+the blocks as they were.
+
+Two details the engine will hold you to. The block and the query cannot share a
+name: both become members of the page class, so a query named after the block it
+feeds comes back as `duplicate_name` in the `query` scope — name the block for
+what it is and the query for what it answers. And a `ChartCard` requires the
+chart it wraps, so a config without `chart` fails the save on `typecheck_failed`
+rather than on a validation message.
+
+## What ends up in the project
+
+A method on the resource's model:
+
+```typescript
+revenueChart(minCreatedAt: Date, maxCreatedAt: Date) {
+  return this.table
+    .filter((row) => row.key("status").eq("paid"))
+    .filter((row) => row.key("createdAt").ge(minCreatedAt))
+    .filter((row) => row.key("createdAt").le(maxCreatedAt))
+    .map((row) => ({
+      bucket: row.key("createdAt").year("Europe/Brussels").mul(100).add(row.key("createdAt").month("Europe/Brussels")),
+      value: row.key("amount"),
+    }))
+    .group("bucket", (rows, group) => ({ x: group, y: rows.sum("value") }))
+    .orderBy("x", "asc");
+}
+```
+
+And a route on the page, guarded with the page's own permission:
+
+```typescript
+@Get("/stats/revenue-chart")
+async revenueChart(
+  @AuthUserWithPermission(BoardPage) _user: User,
+  @Model(OrderModel) model: OrderModel,
+  @Parameter("from", "query") from: string,
+  @Parameter("to", "query") to: string,
+  @Parameter("compareFrom", "query") compareFrom: string,
+  @Parameter("compareTo", "query") compareTo: string,
+): Promise<ChartCardData> {
+  return chartCardData(
+    await model.revenueChart(new Date(from), new Date(to)),
+    {
+      measure: "sum",
+      label: "Amount",
+      previous: await model.revenueChart(new Date(compareFrom), new Date(compareTo)),
+    },
+  );
+}
+```
+
+Ordinary code, in the application's own style, that a developer can read, edit
+and own.
+
+`label` is what a legend and a tooltip call the series. The builder takes it from
+the field being measured — the label the resource gives it — and from the resource
+itself for a count, which has no field to name: left out, the helper falls back to
+the measure's own word, and a reader who never asked for one would be shown "sum".
+
+## Reopen it
+
+`GetPageStructure` reads the route and its chain back into the parameters that
+produced them, so the editor reopens filled in rather than empty:
+
+```typescript
+const structure = await GetPageStructure("/shop/board");
+const source = structure.data.queries.find((q) => q.name === "revenueChart");
+// source.template === "series"
+// source.response === "card"
+// source.params  === the parameters above, with the ordering made explicit
+```
+
+That read-back is what makes the journey repeatable rather than one-way. It is
+also what decides ownership: a chain edited past what the grammar accepts reads as
+`opaque`, and from then on the builder will list it and remove it but never
+rewrite it.
+
+## Where each guarantee lives
+
+| Guarantee | Where it comes from |
+| --- | --- |
+| The preview matches the saved page | One `QueryPlan`, rendered by the emitter and run by the executor |
+| The block and its data save together | `PageDraft.queries`, written in the page's transaction |
+| Reopening shows what was configured | The chain reads back into its parameters |
+| A developer's edit survives | An unreadable chain is opaque, and opaque is never rewritten |
+| The data is not public | The route carries the page's permission |
+| A tenant reads its own rows | The model provider is chosen from the resource's schema |

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

@@ -170,6 +170,9 @@ if (result.ok) {
 | `category` | `CategoryRef` | The category the page belongs to. |
 | `moduleId` | `string` | The module the page comes from, for pages declared inside a module. |
 | `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. |
 
 `CategorySummary`:
 

package/docs/6.queries.md

@@ -2,7 +2,9 @@
 
 ## Overview
 
-A query is derived data: a count, a sum, an average taken over a resource's rows and served from a page. `AddQuery` compiles a query template into a method on the resource's model and a route on the page's controller, so a block on that page can fetch a single number without you writing either half.
+A query is derived data: a count, a sum, an average taken over a resource's rows and served from a page. `AddQuery` compiles a query template into a method on the resource's model and a route on the page's controller, so a block on that page can fetch its data without you writing either half.
+
+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.
 
 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.
 
@@ -42,7 +44,17 @@ for (const template of templates) {
 | `output` | `QueryOutputKind` | The shape the query's route responds with. |
 | `params` | `ConfigSchema` | The template's parameter schema, in the same vocabulary as the block catalog. |
 
-`QueryOutputKind` is `"scalar"`: the route responds with a `{ value }` object.
+`QueryOutputKind` says what the route responds with:
+
+| Kind | Response | Templates |
+| --- | --- | --- |
+| `"scalar"` | `{ value }` — one number | `count`, `aggregate` |
+| `"series"` | `{ series }` — one point per group, each `{ x, y }` | `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.
 
 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`.
 
@@ -74,6 +86,8 @@ 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's slug. Defaults to `/stats/<kebab-name>`. |
+| `response` | `QueryResponseShape` | How the answer is arranged for the block reading it. Defaults to what the calculation 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 page slug joined with the endpoint — the URL a block fetches from.
 
@@ -164,6 +178,96 @@ await AddQuery("/books", {
 });
 ```
 
+## 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.
+
+```typescript
+import { AddQuery } from "@antelopejs/interface-dms-builder";
+
+await AddQuery("/dashboard", {
+  name: "monthlyRevenue",
+  resource: "order",
+  template: "series",
+  params: {
+    op: "sum",
+    field: "amount",
+    groupBy: "createdAt",
+    bucket: "month",
+    timezone: "Europe/Brussels",
+    where: [{ field: "status", op: "eq", value: "paid" }],
+  },
+});
+// GET /dashboard/stats/monthly-revenue
+// { series: [{ x: 202601, y: 1250 }, { x: 202602, y: 980 }] }
+```
+
+| 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" \| "month" \| "quarter" \| "year"` | Groups a date field by period instead of by exact value. 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`. |
+| `direction` | `"asc" \| "desc"` | Defaults to `asc`. |
+| `limit` | `number` | Keep only the first N points after ordering — a top N. At most 1000. |
+| `where` | `QueryFilter[]` | As for every other template. |
+
+Three rules worth planning for:
+
+- **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**, which moves every row near a period boundary into its neighbour. Pass the zone the reader thinks in.
+- **A top N is an ordering plus a limit**, not a separate template: `orderBy: "measure"`, `direction: "desc"`, `limit: 5`.
+
+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 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 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.
+
+## 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.
+
+| 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 |
+
+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.
+
+Two rules worth planning for:
+
+- **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.
+
+```typescript
+import { AddQuery } from "@antelopejs/interface-dms-builder";
+
+await AddQuery("/dashboard", {
+  name: "revenue",
+  resource: "order",
+  template: "series",
+  params: {
+    op: "sum",
+    field: "amount",
+    groupBy: "createdAt",
+    bucket: "month",
+    where: [
+      { field: "createdAt", op: "ge", value: { $param: { name: "from" } } },
+      { field: "createdAt", op: "le", value: { $param: { name: "to" } } },
+    ],
+  },
+  response: "card",
+  compare: true,
+});
+// GET /dashboard/stats/revenue?from=…&to=…&compareFrom=…&compareTo=…
+// { value, series, previousValue, delta, comparisonSeries }
+```
+
 ## 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.
@@ -199,8 +303,8 @@ await RemoveQuery("/books@cheaperThan");
 | `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. Several queries may share one method, but only while they want the exact same chain. |
-| `output` | `QueryOutputKind` | The output shape, from the template descriptor. |
+| `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. |
 | `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. |

package/docs/9.drafts-and-preview.md

@@ -21,6 +21,39 @@ import {
 | --- | --- | --- |
 | `page` | `Partial<EditablePageMeta>` | Metadata to patch alongside the blocks. Omit to leave it alone. |
 | `blocks` | `BlockDraft[]` | The top-level blocks, in the order they should appear. |
+| `queries` | `AddQueryInput[]` | The queries the page should serve, written with the blocks. Omit to leave the page's queries alone. |
+
+A block and the data it reads are one edit, so they are one write: the blocks, the model methods and the routes land in a single transaction with a single typecheck, or none of them land.
+
+Omitting `queries` is not the same as passing an empty array. Omitted leaves whatever the page already serves untouched — which is what a caller written before queries joined the draft keeps doing. An empty array says the page should serve none, and removes the generated ones.
+
+Two things a draft never destroys silently:
+
+- **A query edited past the grammar** is left exactly as it is, whether the draft still lists it or not. The engine reports `query_opaque` and moves on, because a chain it cannot read is one a human owns.
+- **A query the draft forgot** is kept when a block on the page still reads its URL, reported as `query_kept`. A draft that dropped a source a block depends on is a draft that would break that block, and keeping it is the recoverable side of the mistake.
+
+```typescript
+import { SetPageBlocks } from "@antelopejs/interface-dms-builder";
+
+await SetPageBlocks("/shop/board", {
+  blocks: [
+    {
+      name: "revenueChart",
+      type: "ChartCard",
+      config: { title: "Revenue", fetchUrl: "/shop/board/stats/revenue" },
+    },
+  ],
+  queries: [
+    {
+      name: "revenue",
+      resource: "order",
+      template: "series",
+      params: { op: "sum", field: "amount", groupBy: "createdAt", bucket: "month" },
+      response: "card",
+    },
+  ],
+});
+```
 
 `BlockDraft` is one block:
 
@@ -134,7 +167,41 @@ if (preview.ok) {
 
 A block lands in `degraded` when the preview cannot reach what the running page holds: a controller-leading block such as `TableView` (the DataAPI class lives in the app, not in the builder), a `$ref`, an `$expr`, a `preserve` block (which the draft does not describe), or a factory that threw. Render the last known-good layout for those rather than trusting the preview.
 
+## Preview a Query
+
+`PreviewLayout` says what the page will look like; `PreviewQuery` says what its blocks will be showing. It runs a query the caller has not saved and answers what its route would, so a source can be configured against real data before anything is written.
+
+```typescript
+import { PreviewQuery } from "@antelopejs/interface-dms-builder";
+
+const result = await PreviewQuery({
+  query: {
+    name: "revenue",
+    resource: "order",
+    template: "series",
+    params: { op: "sum", field: "amount", groupBy: "createdAt", bucket: "month" },
+  },
+  args: { from: "2026-01-01T00:00:00.000Z", to: "2026-09-01T00:00:00.000Z" },
+});
+if (result.ok) {
+  console.log(result.data.body); // { series: [{ x: 202601, y: 1250 }, …] }
+  console.log(result.data.truncated); // whether it stopped reading early
+}
+```
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `query` | `AddQueryInput` | What to run. Validated the same way `AddQuery` validates it. |
+| `args` | `Record<string, unknown>` | Values the route would receive, by the name it exposes them under. A bound value with nothing supplied is refused rather than compared against nothing. |
+| `tenant` | `string` | Whose rows to read, for a resource in a per-tenant schema. |
+
+What comes back is the route's own response body, not a rendering of it: `body` is built by the same helper the generated route would call, and `output` and `response` report it the way `GetPageStructure` reports the saved query. Ask for `response: "card"` and the preview answers a `ChartCardData` — the headline figure included — so a block can be handed it directly. `response` is set only when a helper arranged the body, which is the same condition read-back reports it under; a plain `{ value }` or `{ series }` leaves it absent. An arrangement the installed DMS does not publish is refused as `unsupported` rather than answered as bare points, because saving that query would fail its typecheck on the very same helper.
+
+Read-only by construction: a query is filters, a grouping and a measure, and there is no way to spell a write in one. It stops at 500 points and sets `truncated`, because a chart that quietly lost its tail is worse than one that reports it. A database that refuses comes back as a failed `OpResult`, not as a rejection.
+
 ## Next Steps
 
+- [A Chart Without Code](./10.a-chart-without-code.md) - The journey these calls add up to
+
 - [Results and Errors](./8.results-and-errors.md) - Branch on `OpResult` and handle `stale`
 - [Catalog](./3.catalog.md) - The block types, their schemas and their defaults

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/interface-dms-builder",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",