@antelopejs/interface-dms-builder 0.2.0 → 0.2.2

package/README.md

@@ -1,12 +1,84 @@
+<div align="center">
+
 # @antelopejs/interface-dms-builder
 
-The public interface contract for AntelopeJS DMS builder implementations.
+<a href="https://www.npmjs.com/package/@antelopejs/interface-dms-builder"><img alt="npm" src="https://img.shields.io/npm/v/@antelopejs/interface-dms-builder?style=for-the-badge&labelColor=000000&color=000000"></a>
+<a href="./LICENSE"><img alt="License" src="https://img.shields.io/npm/l/@antelopejs/interface-dms-builder?style=for-the-badge&labelColor=000000&color=000000"></a>
+<a href="https://discord.gg/sjK28QHrA7"><img alt="Discord" src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000"></a>
+<a href="https://dms.antelopejs.com/docs/modules/builder/extending"><img alt="Documentation" src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000"></a>
+
+The AntelopeJS interface to edit a DMS project's pages, blocks, resources and queries from code.
+
+</div>
+
+## What it does
+
+- Creates and edits pages, categories and their block trees: `CreatePage`, `AddBlock`, `ConfigureBlock`, `MoveBlock`, `SetPageBlocks`…
+- Generates resources (a `Table`, a `DataController` and a model) and edits their fields.
+- Compiles query templates into a model method and a page route, so a card gets a number without hand-written code.
+- Reports every block type and DataType the builder can write, with a schema for its options (`GetCatalog`).
+- Returns every mutation as an `OpResult`: the files changed on success, a typed error otherwise.
+
+Every operation is an `InterfaceFunction` routed to [`@antelopejs/dms-builder`](https://www.npmjs.com/package/@antelopejs/dms-builder), which parses the project, applies the edit as an AST rewrite, and writes only if the project still typechecks.
+
+## Install
+
+Add the interface to the module that calls the builder:
+
+```bash
+pnpm add @antelopejs/interface-dms-builder
+```
+
+## Quick start
+
+Create a page and put a KPI card on it:
 
 ```ts
-import { GetCatalog } from "@antelopejs/interface-dms-builder";
+import { AddBlock, CreatePage } from "@antelopejs/interface-dms-builder";
+
+const page = await CreatePage({
+  name: "revenue",
+  displayName: "Revenue",
+  category: "pages",
+  icon: "i-ph-chart-line",
+});
+if (!page.ok) {
+  throw new Error(`could not create the page: ${page.error.code}`);
+}
+
+const block = await AddBlock({
+  page: page.data.ref,
+  name: "total",
+  type: "KpiCard",
+  config: { title: "Total revenue", icon: "i-ph-currency-eur" },
+});
+if (!block.ok) {
+  throw new Error(`could not add the block: ${block.error.code}`);
+}
 ```
 
-The package contains only the interface types and `InterfaceFunction`
-definitions. The implementation is provided by `@antelopejs/dms-builder`.
+## Compatibility
+
+The interface declares this peer dependency:
+
+<!-- docs-compat: ./package.json#peerDependencies -->
+
+| Package | Range |
+| --- | --- |
+| `@antelopejs/interface-core` | `>=0.2.4 <1.0.0` |
+
+The 0.2 interface is implemented by `@antelopejs/dms-builder` 0.4, used with DMS 0.9. These implementation versions are not peer dependencies of the interface package. The implementation runs in development only, unless its [`api.enabled`](https://dms.antelopejs.com/docs/modules/builder/configuration) option forces it.
+
+## Documentation
+
+- [Extending the builder](https://dms.antelopejs.com/docs/modules/builder/extending): the interface and the HTTP API
+- [Interface reference](./docs/1.introduction.md): the canonical contract, shipped with this package and published at [/docs/modules/builder/reference](https://dms.antelopejs.com/docs/modules/builder/reference)
+- [A chart without code](./docs/10.a-chart-without-code.md): the whole journey, from picking a measure to reopening the page
+
+## Contributing
+
+This package lives in the [`AntelopeJS/dms-builder`](https://github.com/AntelopeJS/dms-builder) pnpm workspace, next to the module that implements it. Read [CONTRIBUTING.md](https://github.com/AntelopeJS/dms-builder/blob/main/CONTRIBUTING.md) and the [repository README](https://github.com/AntelopeJS/dms-builder#contributing) for the development commands. Release this package before the module that implements it.
+
+## License
 
-The contract is documented in [`docs`](./docs/1.introduction.md).
+[Apache-2.0](./LICENSE)

package/dist/drafts.d.ts

@@ -7,6 +7,7 @@ export interface BlockDraft {
     name: string;
     type?: string;
     config?: Record<string, unknown>;
+    lockedOptions?: Record<string, string>;
     slot?: string;
     meta?: Record<string, unknown>;
     controller?: ResourceRef;

package/dist/drafts.js.map

@@ -1 +1 @@
-{"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"}
+{"version":3,"file":"drafts.js","sourceRoot":"","sources":["../src/drafts.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AAwFlD,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/queries.js.map

@@ -1 +1 @@
-{"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"}
+{"version":3,"file":"queries.js","sourceRoot":"","sources":["../src/queries.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AA0MlD,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/structure.d.ts

@@ -35,6 +35,7 @@ export interface BlockNode {
     slot?: string;
     meta?: Record<string, unknown>;
     config?: Record<string, unknown>;
+    lockedOptions?: Record<string, string>;
     controller?: ResourceRef;
     children?: BlockNode[];
 }

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

@@ -73,7 +73,7 @@ await SetPageBlocks("/shop/board", {
       type: "ChartCard",
       config: {
         title: "Revenue",
-        fetchUrl: "/shop/board/stats/revenue-chart",
+        fetchUrl: "/dms/pages/shop/board/stats/revenue-chart",
         periodScope: "page",
         chart: {
           $block: { type: "ChartArea", config: { xaxisType: "category" } },

package/docs/4.page-operations.md

@@ -247,6 +247,7 @@ if (result.ok) {
 | `parent` | `BlockPath` | The container to nest under. Omit to add a top-level block. |
 | `slot` | `string` | The slot within the parent container. |
 | `index` | `number` | Position among siblings. Defaults to appending. |
+| `meta` | `Record<string, unknown>` | Child metadata emitted alongside `slot` in the third argument of `.child()`, such as `{ colSpan: 2 }`. Ignored for top-level blocks. |
 | `controller` | `ResourceRef` | The resource whose DataAPI class is the leading argument, for controller-leading block types. |
 
 `config` is plain JSON by default; values that are not literals — a DataType instance, a reference to a generated class — use the sentinel encodings in [Value Encodings](./7.values.md).
@@ -286,15 +287,23 @@ await ConfigureBlock("/revenue#total", {
 | --- | --- | --- |
 | `replace` | `boolean` | Replace the whole options object instead of merging into it. |
 | `expectedVersion` | `string` | The `PageStructure.version` you last read. A mismatch fails with `stale`. |
+| `meta` | `Record<string, unknown>` | Patch child metadata (`slot`, `colSpan`, …). A key set to `undefined` is removed. Rejected for a top-level block, which has no `.child()` call. |
 
-```typescript
-import { ConfigureBlock } from "@antelopejs/interface-dms-builder";
+Read the version before changing an existing child. Here `/revenue#grid/total` must already be a child of the page's grid:
+
+```ts docs-check
+import { ConfigureBlock, GetPageStructure } from "@antelopejs/interface-dms-builder";
 
-await ConfigureBlock(
-  "/revenue#total",
-  { title: "Revenue" },
-  { replace: true, expectedVersion: version },
-);
+export async function resizeRevenueCard() {
+  const read = await GetPageStructure("/revenue");
+  if (!read.ok) return read;
+
+  return ConfigureBlock(
+    "/revenue#grid/total",
+    { title: "Revenue" },
+    { expectedVersion: read.data.version, meta: { colSpan: 2 } },
+  );
+}
 ```
 
 An opaque block fails with `opaque_target`: the builder can read it but not rewrite it.

package/docs/6.queries.md

@@ -73,7 +73,7 @@ const result = await AddQuery("/books", {
 });
 if (result.ok) {
   console.log(result.data.query); // "/books@inStockCount"
-  console.log(result.data.route); // "/books/stats/in-stock-count"
+  console.log(result.data.route); // "/dms/pages/books/stats/in-stock-count"
 }
 ```
 
@@ -85,11 +85,11 @@ if (result.ok) {
 | `resource` | `ResourceRef` | The resource the query reads. Required, and it must exist. |
 | `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>`. |
+| `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. |
 | `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.
+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.
 
 A few rules the operation enforces:
 
@@ -143,7 +143,7 @@ await AddQuery("/books", {
     ],
   },
 });
-// GET /books/stats/cheaper-than?maxPrice=20
+// GET /dms/pages/books/stats/cheaper-than?maxPrice=20
 ```
 
 | Field | Type | Description |

package/docs/8.results-and-errors.md

@@ -164,7 +164,7 @@ Diagnostics are collected across the project, not just the file the operation ed
 
 ## Make a Write Conditional
 
-`MutationOpts` is the trailing options argument a mutating operation takes.
+`MutationOpts` is the trailing options argument of version-checked mutations, not of every mutation.
 
 | Option | Type | Description |
 | --- | --- | --- |
@@ -198,4 +198,4 @@ if (!write.ok && write.error.code === "stale") {
 
 Omitting `expectedVersion` writes unconditionally. Pass it whenever a human or another process may have touched the file between your read and your write.
 
-Two operations extend `MutationOpts` with a field of their own: `ConfigureBlockOpts` adds `replace`, described in [Page Operations](./4.page-operations.md), and `DeleteResourceOpts` adds `keepData`, described in [Resources](./5.resources.md).
+Two operations extend `MutationOpts` with options of their own: `ConfigureBlockOpts` adds `replace` and `meta`, described in [Page Operations](./4.page-operations.md), and `DeleteResourceOpts` adds `keepData`, described in [Resources](./5.resources.md).

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

@@ -40,7 +40,7 @@ await SetPageBlocks("/shop/board", {
     {
       name: "revenueChart",
       type: "ChartCard",
-      config: { title: "Revenue", fetchUrl: "/shop/board/stats/revenue" },
+      config: { title: "Revenue", fetchUrl: "/dms/pages/shop/board/stats/revenue" },
     },
   ],
   queries: [

package/docs/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "..",
+    "composite": false,
+    "incremental": false,
+    "noEmit": true
+  },
+  "include": ["../src/**/*.ts", "**/*.ts"]
+}

package/package.json

@@ -1,10 +1,23 @@
 {
   "name": "@antelopejs/interface-dms-builder",
-  "version": "0.2.0",
+  "version": "0.2.2",
+  "description": "AntelopeJS interface for the DMS builder: create and edit pages, blocks, resources and queries in a DMS project from another module.",
+  "keywords": [
+    "antelopejs",
+    "builder",
+    "codegen",
+    "dms",
+    "interface"
+  ],
+  "homepage": "https://dms.antelopejs.com/docs/modules/builder/extending",
+  "bugs": {
+    "url": "https://github.com/AntelopeJS/dms-builder/issues"
+  },
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/AntelopeJS/dms-builder.git"
+    "url": "git+https://github.com/AntelopeJS/dms-builder.git",
+    "directory": "packages/interface-dms-builder"
   },
   "files": [
     "LICENSE",
@@ -37,14 +50,14 @@
     "prepack": "pnpm run build"
   },
   "devDependencies": {
-    "@antelopejs/interface-core": ">=0.2.0 <1.0.0",
+    "@antelopejs/interface-core": ">=0.2.4 <1.0.0",
     "release-it": "^19.2.4",
     "release-it-changelogen": "^0.1.0",
     "rimraf": "^6.1.3",
     "typescript": "^6.0.3"
   },
   "peerDependencies": {
-    "@antelopejs/interface-core": ">=0.1.1 <1.0.0"
+    "@antelopejs/interface-core": ">=0.2.4 <1.0.0"
   },
   "packageManager": "pnpm@10.2.0",
   "antelopeJs": {}