@cube-nl/dmp-sdk 1.0.0-rc.3 → 1.1.0-rc.1

package/README.md

@@ -1,4 +1,4 @@
-# @cube/dmp-sdk
+# @cube-nl/dmp-sdk
 
 **Nederlands.** De TypeScript-SDK voor het DMP: één client waarmee een app de REST-API van
 `cube/api` aanroept, in de browser of in Node 20+. Zonder runtime-dependencies: alleen `fetch`,
@@ -9,8 +9,9 @@
 een persoonlijk token voor een PoC. Het token blijft standaard alleen in het geheugen.
 
 Dit pakket vervangt `dmp.js` en `oauth.js` uit de hackathon-starter van `cube/resources`
-(`docs/hackathon/starter/public/`): dezelfde logica, getypt en getest. Het staat nog in **geen
-enkele registry**; installeer het voorlopig uit git of uit het `npm pack`-artefact van de CI.
+(`docs/hackathon/starter/public/`): dezelfde logica, getypt en getest. Het staat openbaar op npm:
+`npm install @cube-nl/dmp-sdk@next` (zolang het een release candidate is), of als losse
+`cube-sdk.js` via jsDelivr of unpkg.
 
 Besluit OP-05: **één client, resources als eigenschap** —
 `createClient(...).resources('projects').list()`, geen ingang per soort.
@@ -28,22 +29,35 @@ The rest of this document is in English.
 - [Errors](#errors)
 - [Voor AI-tools](#voor-ai-tools)
 - [Route B: apps without a build step](#route-b-apps-without-a-build-step)
+- [Bouwstenen (UI)](#bouwstenen-ui)
 - [What this SDK deliberately does not do](#what-this-sdk-deliberately-does-not-do)
 - [Development](#development)
 - [Integration tests](#integration-tests)
 
 ## Install
 
-Not published yet. Until it is:
+Published on the public npm registry as [`@cube-nl/dmp-sdk`](https://www.npmjs.com/package/@cube-nl/dmp-sdk):
 
 ```bash
-npm install git+ssh://git@gitlab.cube.nl/cube/packages/laravel/filament/dmp/sdk-js.git#5.0.x
-# or the tarball the CI's pack job keeps for a week:
-npm install ./cube-dmp-sdk-1.0.0-rc.3.tgz
+npm install @cube-nl/dmp-sdk@next   # while 1.0.0 is a release candidate
+npm install @cube-nl/dmp-sdk        # once a stable version is out
 ```
 
-A git install runs `prepare`, which builds `dist/` with `tsc`. The package is an ES module with
-its own `.d.ts`; there is no CommonJS build.
+Release candidates go to the `next` dist-tag, stable versions to `latest`. The package is an ES
+module with its own `.d.ts`; there is no CommonJS build.
+
+For an app without a build step, the single-file browser build is on the npm CDNs. Pin an exact
+version:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@cube-nl/dmp-sdk@1.1.0-rc.1/dist/cube-sdk.js"></script>
+<!-- or -->
+<script src="https://unpkg.com/@cube-nl/dmp-sdk@1.1.0-rc.1/dist/cube-sdk.js"></script>
+```
+
+Fallback, for an unreleased commit: `npm install
+git+ssh://git@gitlab.cube.nl/cube/packages/laravel/filament/dmp/sdk-js.git#5.0.x` (needs access to
+our GitLab; `prepare` builds `dist/`).
 
 ## Quick start
 
@@ -51,7 +65,7 @@ These ten lines ran as they are (24-09-2026, Node 24, installed from `npm pack`)
 hackathon demo DMP on `127.0.0.1:8000`, with a personal token in `DMP_TOKEN`:
 
 ```js
-import { createClient } from '@cube/dmp-sdk';
+import { createClient } from '@cube-nl/dmp-sdk';
 
 const dmp = createClient({ baseUrl: 'http://127.0.0.1:8000/apps/api/v1', auth: process.env.DMP_TOKEN });
 
@@ -97,7 +111,7 @@ Every request carries `Authorization: Bearer <token>`. The API refuses a browser
 ### OAuth 2.1 + PKCE (the right way for an app)
 
 ```ts
-import { createClient, createOAuth } from '@cube/dmp-sdk';
+import { createClient, createOAuth } from '@cube-nl/dmp-sdk';
 
 const oauth = createOAuth({
     issuer: 'https://dmp.example.nl',             // discovery: {issuer}/.well-known/oauth-authorization-server
@@ -181,7 +195,7 @@ Token limits the API applies to an OAuth token: it reaches **no custom operation
 ### A personal token or an API-client token
 
 ```ts
-import { bearer, createClient } from '@cube/dmp-sdk';
+import { bearer, createClient } from '@cube-nl/dmp-sdk';
 
 createClient({ baseUrl, auth: process.env.DMP_TOKEN });          // a string
 createClient({ baseUrl, auth: () => tokenFromSomewhere() });      // read on every call
@@ -282,7 +296,7 @@ not from assumptions.
 ## Writing
 
 ```ts
-import { newIdempotencyKey } from '@cube/dmp-sdk';
+import { newIdempotencyKey } from '@cube-nl/dmp-sdk';
 
 const projects = dmp.resources('projects');
 
@@ -344,7 +358,7 @@ name, and an OAuth token reaches none. Names starting with `_` are reserved and
 Every non-2xx answer throws a `DmpError`:
 
 ```ts
-import { isDmpError } from '@cube/dmp-sdk';
+import { isDmpError } from '@cube-nl/dmp-sdk';
 
 try {
     await dmp.resources('projects').list({ sort: 'nope' });
@@ -548,7 +562,14 @@ the REST face reads it:
   Laravel's sentence per field; an empty body `422 validation_failed`. `ifMatch` with a stale
   `recordVersion` is `409 conflict`; `idempotencyKey` replays the first answer.
 - `aggregate` with `count`, `count(f)`, `sum(f)`, `avg(f)`, `min(f)`, `max(f)`, grouped on fields
-  and on `.year`, `.month` and `.day`.
+  and on `.day`, `.week` (ISO, `2026-W23`), `.month`, `.quarter` (`2026-Q2`) and `.year`; a date-time is
+  bucketed by the date as written. A call needs `aggregate` in the manifest's `uses` (`list` alone no longer
+  suffices). Grouping is limited to the schema's `groupable` fields and a function to what `aggregatable` allows
+  (absent: every field, every function; a bare `count` is always allowed). Groups come ascending by their values,
+  nulls first; a `sum` of nothing is `null`; a whole-set aggregate over no rows answers one row. At most 5
+  dimensions and 1000 groups; a repeated entry is refused.
+- A field with `choices` in the schema: a value outside `values` (else the field's own `enum`) is
+  `422 validation_failed` ("The selected status is invalid."), and a choice that is not `writable` is read-only.
 - With a `cube-app.json` next to the page (or the `manifest` option), a call outside its `uses` is
   `403 client_scope_exceeded`, as the live client is capped to it.
 - Signed out (`signOut()`), every call is `401 token_invalid`.
@@ -586,13 +607,17 @@ synthetic rows.
 Ship it as `cube-mock.json` next to `index.html`, or register it in a script before the app's
 module runs: `CubeApp.mock({ ... })`. A resource without a `schema` takes its fields from its rows.
 
+The schema may also carry three keys that `cube.mock_data` writes: `groupable` (fields an aggregate may group on),
+`aggregatable` (per field, the functions allowed) and `choices` (per field, `{ "values": [...], "writable": true }`).
+Without them the preview is permissive: every field, every function; only a field's own `enum` is checked on writes.
+
 ### `CubeApp` API
 
 | | |
 |---|---|
 | `CubeApp.connect(options?)` | `Promise<CubeAppSession>`. Options: `mock`, `manifest` (an object, or `false` to check nothing), `pageUrl` (default the page's URL), `fetch`, `tokenStorage` (`'session'`, the default, or `'memory'`), `autoSignIn` (default `false`) |
 | `CubeApp.mock(data)` | Registers preview data for the next `connect()`; `null` forgets it |
-| `CubeApp.version` | This SDK's version, `'0.2.0'` |
+| `CubeApp.version` | This SDK's version, e.g. `'1.1.0-rc.1'` |
 | `CubeApp.sdk` | The manifest `"sdk"` this build serves, `'1'` |
 | `session.mode` | `'preview'` or `'live'` |
 | `session.user()` | `{ id, name, scopes }` or `null` |
@@ -600,6 +625,11 @@ module runs: `CubeApp.mock({ ... })`. A resource without a `schema` takes its fi
 | `session.signOut()` | Forgets the tokens in this browser (not a revocation). Preview: signs the stand-in out |
 | `session.resource(name)` | A `ResourceClient`: `list`, `pages`, `all`, `get`, `aggregate`, `create`, `update`, `delete`, `operation`, `collectionOperation` |
 | `session.signInError` | The error the last sign-in came back with (a refused consent: `code` `access_denied`), else `null`; `connect()` does not reject for it |
+| `session.schema(name)` | `Promise<ResourceSchema \| null>`: one resource as a block sees it (fields, actions, what may be filtered, sorted, grouped); `null` when unknown. In a wireframe it includes the missing fields |
+| `session.soort` | What the app is: live the config's `soort`, in the preview the manifest's (`'wireframe'`, say); `null` when neither says |
+| `session.gaps` | A wireframe's `ontbreekt` entries (see [Wireframe](#wireframe)); `[]` for any other app |
+| `session.isExample(resource, field?)` | Whether a wireframe shows invented data there: the whole resource, or that field of it, does not exist yet |
+| `session.simulatesWrites` | `true` in a wireframe: writes are answered in the browser and never saved |
 
 Live, `connect()` handles the OAuth callback itself (on the `redirectUri`), so the redirect URI can
 be the app's own `index.html`. The tokens go to `sessionStorage` by default, unlike `createOAuth`'s
@@ -607,21 +637,306 @@ memory default: a no-build app reloads often, and a redirect round trip on every
 its users than a token that lives as long as the tab. `tokenStorage: 'memory'` opts out. `user()` reads
 the id and scopes from the access token for display; the DMP checks the token on every request.
 
-`CubeApp` is also exported from the ES module (`import { CubeApp } from '@cube/dmp-sdk'`) for an
+`CubeApp` is also exported from the ES module (`import { CubeApp } from '@cube-nl/dmp-sdk'`) for an
 app with a build (route A).
 
 ### For the host: serving `cube-sdk.js`
 
 | | |
 |---|---|
-| File | `dist/cube-sdk.js` in the package, `@cube/dmp-sdk/cube-sdk.js` as an export; the CI's `pack` job also keeps it as an artifact |
-| Size | 28.7 KiB minified, 10.3 KiB gzipped (0.2.0) |
-| Version | The banner's first line, `/*! @cube/dmp-sdk 0.2.0 cube-sdk.js … */`, and `CubeApp.version` |
+| File | `dist/cube-sdk.js` in the package, `@cube-nl/dmp-sdk/cube-sdk.js` as an export; on jsDelivr/unpkg as `@cube-nl/dmp-sdk@<version>/dist/cube-sdk.js`; the CI's `pack` job also keeps it as an artifact |
+| Size | 126.9 KiB minified, 42.4 KiB gzipped (17.0 KiB core + 25.5 KiB blocks) in 1.1.0-rc.1; `dist/size.json` has the exact numbers |
+| Version | The banner's first line, `/*! @cube-nl/dmp-sdk 1.1.0-rc.1 cube-sdk.js … */`, and `CubeApp.version` |
+
+Pin it by copying the built file of a known version into the host, rather than fetching it at
+runtime: `npm pack @cube-nl/dmp-sdk@<version>` downloads the tarball, `package/dist/cube-sdk.js` is
+the file. Nothing from a CDN, nothing at request time.
+
+## Bouwstenen (UI)
+
+**Nederlands.** `cube-sdk.js` bevat ook kant-en-klare bouwstenen: custom elements met het voorvoegsel `cube-`
+die zelf hun gegevens ophalen, de huisstijl van de klant volgen en onder de CSP van een gehost DMP-app
+werken. De eerste set is `cube-app-shell` (kader met kop, navigatie en inloggen), `cube-page` (één pagina van
+het kader) en `cube-state` (laden, leeg, fout, geen toegang, niet ingelogd). Alle teksten zijn Nederlands en
+getallen, bedragen en datums zijn `nl-NL`.
+
+```html
+<script src="./cube-sdk.js"></script>
+<script type="module" src="./app.js"></script>
+
+<cube-app-shell name="Verkoop">
+    <cube-page name="overzicht" label="Overzicht">
+        <cube-state kind="empty" message="Nog geen bestellingen deze week."></cube-state>
+    </cube-page>
+    <cube-page name="details" label="Details">...</cube-page>
+</cube-app-shell>
+```
+
+How the blocks find the session: a block never signs in by itself. It takes the session the app made with
+`CubeApp.connect()` (`CubeApp.ready`), so a block that sits in the page before the script runs still uses the app's
+session. **Call `CubeApp.connect()` before any `await`** in your script: start it first and await it after.
+Set the house style in the same call, `CubeApp.connect({ theme })`, or call `CubeApp.theme()` before `connect()`: a
+`CubeApp.theme()` call made after `connect()` can be painted over by the theme the start-up applies.
+
+```js
+const session = CubeApp.connect(); // first, so the blocks take this session
+const extra = await (await fetch('./extra.json')).json();
+await session;
+```
+
+An app that never connects gets a session with the defaults, but only once the page has fully loaded (the window's
+`load` event, plus one task), so an app that connects a little later still gets there first and the page signs in
+once. If the app connects after that default session exists, its own session replaces it: `CubeApp.connect()`
+dispatches `cube-session-change` on the document and every block takes the new one. That is a safety net, not a
+way to start: in a live app the default start-up has then handled the sign-in callback with the default options.
+A 401 shows "niet ingelogd", a 403 "geen toegang" (with the right ARIA role), never the raw message. After signing
+in or out the shell dispatches `cube-session-change` on the document and every block loads again.
+
+With the classic script the blocks are defined when `cube-sdk.js` loads, and `window.CubeApp` also has
+`CubeApp.defineBlocks(options?)`. On a page without `customElements` (an old engine, a server) it does nothing and
+`CubeApp` still works. Through npm the blocks are not defined on import: call `defineBlocks` yourself.
+
+```js
+import { CubeApp, defineBlocks } from '@cube-nl/dmp-sdk';
+
+defineBlocks(); // the ESM `CubeApp` has no defineBlocks; import it from the package
+await CubeApp.connect();
+```
+
+`defineBlocks({ session })` takes a function returning the session the blocks use; the default is `CubeApp.ready`.
+
+The manifest `dist/cube-ui.manifest.json` (export `@cube-nl/dmp-sdk/cube-ui.manifest.json`) lists every element
+with its attributes, events, an example and the version it appeared in (`since`), plus the 27 theme tokens and
+the fonts. Its shape is final for 1.1. It is what Claude reads to compose an app. The build also writes `dist/size.json`
+(`core_gzip`, `total_gzip`, `ui_gzip`, `budget_gzip`): the blocks may add at most 40 KiB gzipped to the core and the
+build fails above it.
+
+### Huisstijl
+
+The house style is one file next to `index.html`: `cube-theme.json`. Its shape below is final for 1.1. The DMP writes it when an app is published;
+without it (or with a broken one) the neutral theme applies and the app starts anyway. Read once by
+`CubeApp.connect()`, applied to every block through `adoptedStyleSheets`.
+
+```json
+{
+  "theme": 1,
+  "captured_at": "2026-10-19T09:00:00Z",
+  "source": {
+    "primary_colour": "#0b5fff",
+    "accent_colour": null,
+    "font": "inter",
+    "corners": "normaal",
+    "logo": "cube-theme/logo.svg",
+    "logo_dark": null
+  },
+  "tokens": { "color-danger": "#b42318" },
+  "font_files": [{ "src": "cube-theme/inter.woff2", "weight": "100 900", "style": "normal" }]
+}
+```
+
+| Key | Meaning |
+|---|---|
+| `source.primary_colour` | `#rrggbb`; everything else is derived from it. An invalid value falls back to the neutral `#475467` |
+| `source.accent_colour` | `#rrggbb` or `null` (then the hue of the primary colour turned 330 degrees) |
+| `source.font` | `system`, `inter`, `albert-sans`, `source-sans-3`, `nunito-sans` or `ibm-plex-sans` |
+| `source.corners` | `scherp` (0 px), `normaal` (6 px) or `rond` (12 px) |
+| `source.logo`, `source.logo_dark` | `cube-theme/logo.<ext>` next to the app, or `null` |
+| `tokens` | Optional per-token overrides; only a valid value is used, anything else keeps the derived one |
+| `font_files` | Optional; default the files of the chosen font as `cube-theme/<file>` |
+
+The tokens are the CSS custom properties `--cube-<name>` on every block: `color-primary`, `color-primary-hover`,
+`color-primary-subtle`, `color-primary-text`, `color-on-primary`, `color-accent`, `color-on-accent`, `color-text`,
+`color-text-muted`, `color-bg`, `color-surface`, `color-border`, `color-focus`, `color-danger`, `color-success`,
+`color-warning`, `color-example-bg`, `color-example-text`, `color-series-1` to `color-series-6`, `radius`,
+`radius-small` and `font-family`. Text colours are checked for WCAG 2.1 AA contrast: `color-on-primary` and
+`color-on-accent` on their colours, and `color-primary-text` (also the focus ring) at 4.5:1 on both the surface
+`#f6f8fa` and `color-primary-subtle`; a primary colour that falls short is darkened for text in 5% steps (warning
+`primary-darkened-for-text`).
+
+A value that could break out of the stylesheet never reaches it: colours must be `#rrggbb`, radii a number of `px`
+or `rem`, and `font-family` a comma-separated list of names (quoted names allowed, but no unbalanced quote, no
+semicolon, brace, backslash or comment). Logo and font addresses are kept only when they are on the page's own
+origin (or a base64 `data:` image) and hold no quote, parenthesis or whitespace. A `data:` logo shows in the chat
+preview, but a hosted app's CSP (`img-src 'self'`) blocks it: a published app uses `cube-theme/logo.<ext>`.
+
+The theme sheet sets the tokens on `:where(:root)`, which has no specificity, so an app's own stylesheet can
+override any token in `:root`, for example `:root { --cube-color-primary: #0b5fff; }`.
+
+`CubeApp.theme(fileOrSource)` registers a theme from code (a `cube-theme.json` object, or just its `source`) and
+applies it at once; `CubeApp.theme(null)` forgets it. `connect({ theme })` takes the same value, or `false` for
+the neutral theme without reading `cube-theme.json`. The font files ship in the package under `fonts/`; a host
+serves them as `cube-theme/<file>` (for example `fonts/inter.woff2` as `cube-theme/inter.woff2`). Each font has
+its own OFL licence text next to it.
+
+### Blokken
+
+Every block is a custom element; the full list with attributes lives in the manifest. Row data is only
+ever rendered as text, never as HTML. Every control works with the keyboard and shows a focus ring, and the
+blocks work from 320 px wide.
+
+| Element | Use |
+|---|---|
+| `cube-app-shell` | `name` (required), `logo`, `logo-alt`. Header, user with Inloggen/Uitloggen, page navigation that follows `#/<name>` |
+| `cube-page` | `name` (id in the address), `label` (text in the navigation). A configuration element: it only holds blocks |
+| `cube-state` | `kind`: `loading`, `empty`, `error`, `forbidden`, `signed-out`; `message` replaces the standard text; `retry="false"` leaves out the retry button. Event `cube-retry` |
+| `cube-period-picker` | `default` (`this-month`, `12m`, `this-year`, `custom`), `label`, `today`. Feeds other blocks; `value` is `{ key, from, to, previous, today }`, event `cube-change` |
+| `cube-kpi` | `resource`, `measure` (required), `label`, `format`, `currency`, `filter`, `period`, `date-field`, `compare`. One figure; `compare` adds the change against the previous period (`nieuw` when that was zero) |
+| `cube-chart` | `resource`, `measure`, `by` (required), `kind` (`line`/`bar`), `label`, `format`, `currency`, `filter`, `period`, `date-field`, `lookup`, `height`, `limit`. Own SVG, no chart library; a table for screen readers |
+| `cube-top` | `resource`, `measure`, `by` (required), `limit`, `order`, `label`, `format`, `currency`, `filter`, `period`, `date-field`, `lookup`. Sorted and cut in the browser (an aggregate cannot be sorted by the API). Over 1000 groups the DMP refuses the aggregate (`422 cardinality_exceeded`, reason `too_many_groups`); the block then asks for a shorter period or a filter, without a retry. Event `cube-select` |
+| `cube-field` | `name` (required), `label`, `format` (`text`, `number`, `integer`, `currency`, `percent`, `date`, `datetime`, `boolean`), `multiline`, `options` (`value=Label,...`), `hidden`. A configuration element, a direct child of `cube-table`, `cube-detail`, `cube-form` or `cube-board`; it is never rendered. Live `_capabilities` carries no `format` or `enum`, so a date column or a choice filter there comes from `format`/`options` here or from the values themselves, never from a guess at the type |
+| `cube-table` | `resource` (required), `fields`, `search` (one field, box "Zoeken"), `filters` (a control per field: choices, Alle/Ja/Nee, from-to dates or numbers, else contains), `sort` (`-` for descending), `page-size` (default 25, at most 200), `export`, `detail` (selector of a `cube-detail`), `filter`, `period`, `date-field`. Needs `list`. Search waits 300 ms and the last answer wins. Enter or Space chooses a row, which stays marked (`aria-current`). Event `cube-select` |
+| `cube-detail` | `resource` (required), `record-id`, `fields`, `editable`. Needs `get`, and `update` for `editable`. Events `cube-saved`, `cube-data-change` |
+| `cube-form` | `resource` (required), `fields`, `submit-label` (default "Opslaan"), `success-text` (default "Opgeslagen. Dank je wel!"). Needs `create`. Events `cube-created`, `cube-data-change` |
+| `cube-calc` | `label`. A calculator that needs no data: an editor per `cube-input`, an output per `cube-result`, recalculated on every keystroke by the `formula` property. Read-only `values` and `results`, event `cube-change` (`{ values, results }`) |
+| `cube-input` | `name`, `label` (required), `type` (`number`, `integer`, `currency`, `percent`, `text`, `select`, `checkbox`), `value`, `min`, `max`, `step`, `options` (a select needs it; `value=Label,...` as in `cube-field`). A configuration element, a direct child of `cube-calc`; it is never rendered. Numbers are typed the Dutch way (`7,5`) |
+| `cube-result` | `name`, `label` (required), `format` (`number`, `integer`, `currency`, `percent`, `text`), `currency` (default `EUR`), `emphasis` (the large figure). A configuration element, a direct child of `cube-calc`; it is never rendered |
+| `cube-board` | `resource`, `status-field`, `title-field` (required), `fields` (extra lines on a card), `sort`, `filter`, `page-size` (default 50, at most 200; a column with more says "en nog N"). `cube-field` children label and format the `fields` of a card. Cards in a column per status value. `status-field` must be filterable and `sort` a sortable field. Needs `list`; `update` is optional (without it the board is read-only). Event `cube-move` (`{ resource, id, from, to }`), followed by `cube-data-change` |
+| `cube-column` | `value` (required), `label`. A configuration element, a direct child of `cube-board`, in order; it is never rendered |
+
+`cube-table`, `cube-detail` and `cube-form` need the matching actions in the app's `uses`
+(`"orders": ["list", "get", "create", "update"]`). A table sends the row it chose to the `cube-detail` named by
+`detail="#bestelling"`; after a save or a create every block on that resource loads again (`cube-data-change`).
+
+- **CSV export** (`export`): the filtered rows, at most 10 000, with `;` as the separator, a UTF-8 BOM and CRLF line
+  ends, so a Dutch spreadsheet opens it with the right columns. A text value that starts with `=`, `+`, `-`, `@`, a
+  tab or a carriage return gets a `'` in front (formula injection); a genuine number in a numeric column, such as
+  `-5` or `12,5`, is not prefixed (in a text column `-5` becomes `'-5`). Pressing the button again while it runs
+  cancels.
+- **Filters**: `filter` and the followed period are always applied; the controls can only narrow them. A bound
+  takes the stricter of the two (a "Vanaf" before the period start keeps the period start), and a field that
+  `filter` fixes to one value gets no control. A `filters` or `search` field the resource cannot be filtered on
+  (not in the schema's `filterable`) shows an error naming that field instead of a table.
+- **Required fields**: a field the DMP requires shows " (verplicht)" after its label, besides `aria-required`.
+- **Writes**: every submit attempt carries an `Idempotency-Key` (`newIdempotencyKey()`), the button is disabled
+  while saving, and a retry after a network error reuses the key, so a double click creates one row. `cube-detail`
+  sends only the changed fields with `ifMatch` set to the `recordVersion` it loaded. When someone else changed the
+  row meanwhile (409 or 412) it shows "Iemand anders heeft deze rij intussen gewijzigd" with "Opnieuw laden", keeps
+  what you typed and does not retry by itself. Read-only fields are never shown as an input and never sent.
+- **Numbers**: a number field takes Dutch input. `12,5` is sent as `12.5`, `1.234` is one thousand two hundred
+  thirty-four (the dot is a thousands separator), `12.5` also works, and `abc` is refused in the browser with
+  "Vul een getal in."
+
+```html
+<cube-table resource="orders" fields="reference,placed_on,total,status" search="reference" filters="status,placed_on"
+    export detail="#bestelling">
+    <cube-field name="total" label="Bedrag" format="currency"></cube-field>
+</cube-table>
+<cube-detail id="bestelling" resource="orders" editable></cube-detail>
+<cube-form resource="orders" fields="reference,placed_on,total,status"></cube-form>
+```
+
+The three data blocks (`cube-kpi`, `cube-chart`, `cube-top`) read aggregates, so the app's `cube-app.json` needs
+`aggregate` in `uses` for each resource they read; `lookup` also needs `list` on the lookup resource
+(`"orders": ["list", "aggregate"], "customers": ["list"]`). The `cube-period-picker` reads nothing itself: it only
+feeds them. `period="#periode"` points at a picker by CSS selector and needs `date-field`, the date the period
+filters on, except on a `cube-chart` whose `by` is a truncated date (`placed_on.month`): that field is used.
+`compare` needs `period`. The period filter is always `{ gte: from, lt: dayAfterTo }` on that field, never
+`between`, so it is right for dates and datetimes alike. A chart leaves the buckets after the picker's `today` empty
+(a gap, not a zero). An aggregate over more than 1000 groups is refused by the DMP; `cube-chart` and `cube-top` then
+say so ("Te veel groepen…") and ask for a shorter period or a filter, without a retry button.
+
+```html
+<cube-period-picker id="periode" default="12m"></cube-period-picker>
+<cube-kpi resource="orders" measure="sum(total)" label="Omzet" format="currency"
+    period="#periode" date-field="placed_on" compare></cube-kpi>
+<cube-chart resource="orders" measure="sum(total)" by="placed_on.month" period="#periode"></cube-chart>
+<cube-top resource="orders" measure="sum(total)" by="customer_id" lookup="customers.name"
+    period="#periode" date-field="placed_on"></cube-top>
+```
+
+#### Calculator and board
+
+- **Formula** (`cube-calc`): `formula` is a synchronous JavaScript function property, set from a script, never an
+  attribute (an `async` one returns a Promise, which shows "—"). A string is refused and nothing is evaluated, so it
+  works under the CSP. It gets `values` by `cube-input` name and returns an object by `cube-result` name (or one
+  number or text when there is a single result):
+
+  ```js
+  document.querySelector('cube-calc').formula = ({ uren, tarief, btw }) => ({
+      totaal: uren * tarief * (1 + btw),
+  });
+  ```
+
+  A `percent` input is typed as `21` and arrives as the fraction `0.21`; an empty or invalid input arrives as
+  `null` (also below `min`, above `max` or off `step`). A result that is `null` or `undefined` just shows "—". A
+  formula that throws, or a result that is `NaN` or `Infinity`, shows "—" and one alert; the inputs keep working. Two
+  or more `cube-result`s need an object back: a single number or text then shows an error instead of the calculator.
+  `cube-change` follows a recalculation by typing or by a new formula on a drawn calculator; not the first draw.
+- **Columns** (`cube-board`): the columns come from the `cube-column` children, in that order. Without them the
+  board takes the `enum` of the status field, but live `_capabilities` carries no `enum`, so a starter must always
+  write the `cube-column`s (live without any shows an error). Each column loads its own cards, filtered on the
+  status field, so that field must be filterable on the resource (and `sort` a sortable field), else the board
+  shows an error; a status value without a column is not shown.
+- **Moving**: drag and drop, or a compact button per other column on each card, so it works with the keyboard too.
+  A button shows an arrow and the column name ("→ Bezig"); its accessible name is "Verplaats naar Bezig". The card
+  moves at once, then is saved (`update` of only the status field); a refusal puts it back with an alert.
+- **Read-only**: without `update` in the app's `uses`, or when the status field is read-only, cards cannot move and
+  show no buttons. Columns stack on a narrow screen (from 320 px).
+
+### Wireframe
+
+A wireframe is a proposal that shows what an app would look like, partly on real data and partly on invented data.
+The kind is `soort`: `"wireframe"` in `cube-app.json`, copied by the DMP into `cube-app.config.json`. Only a
+wireframe gets any of what follows; a live app without `soort: "wireframe"` never reads `cube-mock.json` and never
+answers from invented data, and a broken server stays an error.
+
+What the DMP does not have yet is listed in `ontbreekt` in `cube-app.json`, one entry per missing field or per
+missing resource:
 
-Pin it by copying the built file from a known commit or tag into the host, rather than fetching it
-at runtime: `npm pack git+ssh://git@gitlab.cube.nl/cube/packages/laravel/filament/dmp/sdk-js.git#<ref>`
-builds the tarball, `package/dist/cube-sdk.js` is the file. Nothing from a CDN, nothing at request
-time.
+```json
+{
+  "soort": "wireframe",
+  "ontbreekt": [
+    { "resource": "orders", "veld": "delivery_note", "type": "tekst", "scherm": "Lijst",
+      "reden": "Een opmerking voor de bezorger staat nog niet bij een bestelling." },
+    { "resource": "visits", "type": "tekst", "scherm": "Wat ontbreekt",
+      "reden": "Bezoeken aan de winkel worden nog nergens vastgelegd." }
+  ]
+}
+```
+
+`resource` is a REST resource name, `veld` the missing field (left out when the whole resource is missing), `type`
+one of `tekst`, `getal`, `bedrag`, `datum`, `keuze`, `ja/nee`, `waarden` the choices (required for `keuze`), `scherm`
+the screen that shows it and `reden` why it is needed. The SDK only reads this; `cube/apps` validates it. A
+malformed entry is dropped with one `console.warn`.
+
+- **Mixed mode.** What exists runs live. A missing field is added to the live rows with a value invented from the
+  row's `id` (the same row shows the same value every time); a missing resource is answered from `cube-mock.json`.
+  The live request never names a missing field: a filter or sort on it applies to the returned page only, and an
+  aggregate that groups by or sums it is answered from the mock rows. The preview does the same; there, an aggregate
+  on a missing field needs that field in the rows of `cube-mock.json`.
+- **Marking.** Blocks mark what is invented: `Voorbeeld — bestaat nog niet`. A table or detail marks the column or
+  field; the other blocks mark the whole block.
+- **Simulated writes.** `create`, `update`, `delete`, `operation` and `collectionOperation` are answered in the
+  browser, in live and in preview, and forgotten on reload. A block that writes says
+  `Voorbeeld — wordt niet opgeslagen`. A wireframe never writes real data: that covers everything that goes through
+  the session (`session.resource()` and the blocks). App code that builds its own client with the exported
+  `createClient` bypasses it.
+- **Numbers.** KPI and chart numbers do not reflect simulated writes: they come from the rows the session holds
+  without them.
+- **`cube-gap-list`.** One card per gap, for the people who build the real thing: what is missing
+  (`resource.veld`) as its heading, then Scherm, Soort gegeven and Waarom. It stays readable at 320 px.
+  `scherm="Lijst"` shows only that screen's gaps; without gaps it says nothing is missing.
+
+```html
+<cube-page name="wat-ontbreekt" label="Wat ontbreekt">
+    <cube-gap-list></cube-gap-list>
+</cube-page>
+```
+
+`npm run visual` serves the pages with the hosted-app CSP; add `?wireframe=1` to see a wireframe with two gaps.
+
+### CSP
+
+The blocks run under `default-src 'self'; style-src 'self'; img-src 'self'; font-src 'self'; script-src 'self'`,
+the policy of a hosted app. Therefore: no inline `<script>` or `<style>`, no `style` attribute, no `innerHTML`;
+styles are made with `CSSStyleSheet.replaceSync` and `adoptedStyleSheets`. The test suite guards this (a grep of
+the bundle and a walk through the rendered blocks). Your own page must follow the same rule: load `cube-sdk.js`
+and your module with `src`, and keep the logo, the fonts and the mock data on the same origin.
+
+To look at the blocks under that policy, run `npm run visual` and open `http://127.0.0.1:4173/`,
+`/?huisstijl=b` and `/?huisstijl=geen`. The server (`scripts/serve-visual.mjs`, bound to 127.0.0.1) sends the
+policy above on every response and serves only `test/visual/`, `dist/cube-sdk.js`, the test mock and the fonts.
 
 ## What this SDK deliberately does not do
 
@@ -636,7 +951,6 @@ time.
 - **No token revocation call**: `cube/oauth-server` publishes no revocation endpoint. `signOut()`
   forgets locally; the person revokes the connection in the DMP under *Verbonden apps*.
 - **No `_history`**: the API has not built it. `request()` reaches any path once it exists.
-- **Not published** to any registry yet.
 
 ## Development
 
@@ -654,6 +968,14 @@ then says what the SDK still reads wrong.
 TypeScript and esbuild (which bundles `dist/cube-sdk.js`, see `scripts/build-browser.mjs`) are the only
 dev dependencies; there are no runtime dependencies, and there should not be.
 
+### Releasing
+
+Bump `version` in `package.json` and `src/version.ts` (a test holds them equal), add the CHANGELOG
+entry, merge, then push a tag that equals the version (e.g. `1.1.0-rc.1`). The tag pipeline's
+`publish` job checks that, builds, and runs `npm publish`: a version with a `-` goes to the `next`
+dist-tag, any other to `latest`. It needs the masked, protected CI variable `NPM_TOKEN` (an npm
+granular access token with write access to the `cube-nl` org).
+
 ## Integration tests
 
 `test/integration.test.js` runs the SDK against a real DMP. `npm test` includes it, and it skips

package/dist/app.d.ts

@@ -2,6 +2,9 @@ import { type AuthorizationServerMetadata } from './auth.js';
 import { type ResourceClient } from './client.js';
 import { type AppManifest, type MockData } from './preview.js';
 import type { DmpRecord } from './types.js';
+import { type ResourceSchema } from './ui/schema.js';
+import { type ThemeFile, type ThemeSource } from './ui/theme.js';
+import { type GapEntry } from './wireframe.js';
 /**
  * `cube-app.config.json`, which the DMP writes next to the app only when it publishes an approved
  * release. Never part of what the maker or an AI sends: its presence is what makes an app live.
@@ -21,6 +24,8 @@ export interface CubeAppConfig {
     issuer?: string;
     /** Passed to `createOAuth`: endpoints to use instead of (or on top of) discovery. */
     metadata?: Partial<AuthorizationServerMetadata>;
+    /** `'wireframe'`: what exists runs live, what `ontbreekt` in cube-app.json lists comes from `cube-mock.json`. */
+    soort?: string;
 }
 export interface ConnectOptions {
     /** Preview data: `cube.mock_data`'s output. Default: what `CubeApp.mock()` registered, else `./cube-mock.json`. */
@@ -40,6 +45,11 @@ export interface ConnectOptions {
     tokenStorage?: 'session' | 'memory';
     /** Live only: go to the DMP's sign-in right away when nobody is signed in. Default false. */
     autoSignIn?: boolean;
+    /**
+     * The house style. Default: what `CubeApp.theme()` registered, else `./cube-theme.json`, else the
+     * neutral theme. `false`: neutral, and `./cube-theme.json` is not read.
+     */
+    theme?: ThemeFile | ThemeSource | false;
 }
 export interface CubeAppUser {
     /** The DMP's user id (the token's `sub`), or `'preview'`. Null when the token does not say. */
@@ -62,6 +72,16 @@ export interface CubeAppSession {
     resource<T extends DmpRecord = DmpRecord>(name: string): ResourceClient<T>;
     /** Why the last sign-in came back without a session (consent refused, say); null otherwise. */
     readonly signInError: Error | null;
+    /** One resource as a block sees it: fields, actions, what may be filtered, sorted, grouped. Null when unknown. */
+    schema(resource: string): Promise<ResourceSchema | null>;
+    /** What the app is: live the config's `soort`, in the preview the manifest's. Null when neither says. */
+    readonly soort: string | null;
+    /** A wireframe's gap entries: what it shows that the DMP does not have yet. Empty for any other app. */
+    readonly gaps: readonly GapEntry[];
+    /** Whether a wireframe shows invented data here: the whole resource, or this field of it, does not exist yet. */
+    isExample(resource: string, field?: string): boolean;
+    /** A wireframe: writes are answered in the browser and never saved. */
+    readonly simulatesWrites: boolean;
 }
 /**
  * Starts the app. Reads `./cube-app.config.json` next to the page: absent, the app runs in the
@@ -69,17 +89,31 @@ export interface CubeAppSession {
  * OAuth (authorization code + PKCE) and talks to the DMP's REST face. The app's code is the same.
  */
 declare function connect(options?: ConnectOptions): Promise<CubeAppSession>;
+/**
+ * The session `connect()` made for this page, or one with the defaults when the app never connected. The default one
+ * starts only once the page has loaded (and one task later), so an app that awaits something before it calls
+ * `connect()` still gets there first and the page signs in once.
+ */
+declare function ready(): Promise<CubeAppSession>;
 /**
  * Registers preview data before `connect()`, for an app that embeds its mock data in a script tag
  * instead of shipping `cube-mock.json`. Has no effect on a live app. `null` forgets it again.
  */
 declare function mock(data: MockData | null): void;
+/**
+ * Registers the house style before `connect()`, for an app that holds it in code instead of shipping
+ * `cube-theme.json`, and applies it right away. `null` forgets it again (neutral).
+ */
+declare function theme(input: ThemeFile | ThemeSource | null): void;
 /** What `cube-sdk.js` puts on `window`, and what this package exports as `CubeApp`. */
 export declare const CubeApp: Readonly<{
     connect: typeof connect;
+    /** The session the app connected, or one connected with the defaults. What blocks use. */
+    ready: typeof ready;
     mock: typeof mock;
-    /** This SDK's version, e.g. `'1.0.0-rc.3'`. */
-    version: "1.0.0-rc.3";
+    theme: typeof theme;
+    /** This SDK's version, e.g. `'1.1.0-rc.1'`. */
+    version: "1.1.0-rc.1";
     /** The manifest `"sdk"` value this build serves. */
     sdk: "1";
 }>;