@antelopejs/interface-dms-builder 0.0.1

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

@@ -0,0 +1,140 @@
+# Drafts and Preview
+
+## Overview
+
+The per-block operations — `AddBlock`, `ConfigureBlock`, `MoveBlock`, `RemoveBlock` — each rewrite the page file, typecheck the project and write to disk. That is the right shape for an agent applying one edit at a time, and the wrong shape for an editor: a visual builder holds a whole page in memory, and replaying twenty edits at save time would mean twenty typechecks and twenty chances to stop half way.
+
+`SetPageBlocks` is the declarative counterpart. You hand it the page's whole block tree and it writes that tree: one transaction, one typecheck, one `changes` list. `PreviewLayout` is its read-only twin — it serializes a draft through the real `dms-base` factories so you can render it without writing anything.
+
+```typescript
+import {
+  PreviewLayout,
+  SetPageBlocks,
+} from "@antelopejs/interface-dms-builder";
+```
+
+## Describe a Draft
+
+`PageDraft` is a page as you want it written.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `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. |
+
+`BlockDraft` is one block:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `name` | `string` | Static key (top-level) or `.child()` id (nested). Must be a valid identifier. |
+| `type` | `string` | A `BlockTypeDescriptor.type` from the catalog. Ignored when `preserve` is set. |
+| `config` | `Record<string, unknown>` | The factory's options. |
+| `slot` | `string` | The slot the block sits in. |
+| `meta` | `Record<string, unknown>` | Child metadata emitted with `slot` — `{ colSpan: 2 }` on a grid child. |
+| `controller` | `ResourceRef` | Required for a controller-leading type such as `TableView`. |
+| `children` | `BlockDraft[]` | Nested blocks, in `.child()` order. |
+| `preserve` | `boolean` | Write the block back exactly as it stands on disk. |
+
+## Carry an Opaque Block Through a Write
+
+A whole-tree write has to answer for blocks the builder can read but not rewrite: a `CustomComponent`, a block behind a computed expression, anything `GetPageStructure` reported with `editable: false`. `preserve` is that answer — the block is matched by name among its siblings and its source text is written back untouched.
+
+Round-tripping a page therefore means keeping every block you did not edit, marking the opaque ones:
+
+```typescript
+import {
+  GetPageStructure,
+  SetPageBlocks,
+} from "@antelopejs/interface-dms-builder";
+
+const structure = await GetPageStructure("/dashboard");
+if (structure.ok) {
+  const blocks = structure.data.blocks.map((block) =>
+    block.editable
+      ? { name: block.name, type: block.type as string, config: block.config }
+      : { name: block.name, preserve: true },
+  );
+  await SetPageBlocks("/dashboard", { blocks }, {
+    expectedVersion: structure.data.version,
+  });
+}
+```
+
+A `preserve` block whose name matches nothing on disk is rejected with `invalid_config`.
+
+## Write a Whole Page
+
+```typescript
+const result = await SetPageBlocks(
+  "/dashboard",
+  {
+    page: { displayName: "Revenue" },
+    blocks: [
+      {
+        name: "kpis",
+        type: "Grid",
+        config: { gap: "1rem" },
+        children: [
+          {
+            name: "row",
+            type: "GridRow",
+            children: [
+              {
+                name: "revenue",
+                type: "KpiCard",
+                config: { title: "Revenue", valueFormat: "currency" },
+                meta: { colSpan: 2 },
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  },
+  { expectedVersion: "8826e812c4f58d51" },
+);
+```
+
+On success the result carries the staged `changes` and the page's new `version`, ready to be passed as the next `expectedVersion`.
+
+Blocks absent from the draft are removed. Static members that are not blocks are left where they are, and named imports nothing references any more are dropped, so a page shrinks cleanly rather than accumulating dead imports.
+
+`$expr` is refused anywhere in a draft: a whole-tree write stays structured, and arbitrary code would defeat the guarantee. `$dataType`, `$ref` and `$block` are all accepted — see [Value Encodings](./7.values.md).
+
+## Read the Failures
+
+`SetPageBlocks` validates the whole draft before touching anything, so one call reports every problem at once, each addressed by a JSON pointer into the draft:
+
+| Pointer | Cause |
+| --- | --- |
+| `/blocks/1/name` | Not a valid identifier, or a duplicate among its siblings. |
+| `/blocks/2/type` | Unknown block type, or a child a container does not accept. |
+| `/blocks/0/controller` | A controller-leading type without one, or a controller on a type that takes none. |
+| `/blocks/3/config/title` | `$expr` inside a config value. |
+
+Beyond `invalid_config`, the write fails the same way the per-block operations do: `stale` when `expectedVersion` no longer matches, `typecheck_failed` when the emitted source does not compile — and then nothing is written. See [Results and Errors](./8.results-and-errors.md).
+
+## Preview a Draft
+
+`PreviewLayout` serializes a draft the way the runtime would, by calling the same `dms-base` factories the emitted source would call. Nothing is typechecked and nothing reaches disk, so it is cheap enough to run on every edit.
+
+```typescript
+const preview = await PreviewLayout("/dashboard", draft);
+if (preview.ok) {
+  const grid = preview.data.components.kpis; // ComponentPreview
+}
+```
+
+`PageLayoutPreview` holds:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `components` | `Record<string, ComponentPreview>` | The serialized tree, keyed by top-level block name — the shape the DMS frontend renders. |
+| `degraded` | `BlockPath[]` | Blocks the preview could not build faithfully. |
+
+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.
+
+## Next Steps
+
+- [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

@@ -0,0 +1,67 @@
+{
+  "name": "@antelopejs/interface-dms-builder",
+  "version": "0.0.1",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AntelopeJS/dms-builder.git"
+  },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "dist",
+    "docs"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "dist/*": [
+        "dist/*",
+        "dist/*/index.d.ts"
+      ],
+      "*": [
+        "dist/*",
+        "dist/*/index.d.ts"
+      ]
+    }
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    },
+    "./dist": {
+      "types": "./dist/index.d.ts"
+    },
+    "./dist/*": {
+      "types": "./dist/*.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "@antelopejs/interface-core": "^0.0.12",
+    "release-it": "^19.2.4",
+    "release-it-changelogen": "^0.1.0",
+    "rimraf": "^6.1.3",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "@antelopejs/interface-core": ">=0.0.12 <1.0.0"
+  },
+  "antelopeJs": {},
+  "scripts": {
+    "build": "rimraf dist && tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "release": "release-it"
+  }
+}