@cube-nl/dmp-sdk 1.0.0-rc.4 → 1.1.0-rc.2

package/README.md

@@ -29,6 +29,7 @@ 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)
@@ -49,9 +50,9 @@ For an app without a build step, the single-file browser build is on the npm CDN
 version:
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/@cube-nl/dmp-sdk@1.0.0-rc.4/dist/cube-sdk.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@cube-nl/dmp-sdk@1.1.0-rc.2/dist/cube-sdk.js"></script>
 <!-- or -->
-<script src="https://unpkg.com/@cube-nl/dmp-sdk@1.0.0-rc.4/dist/cube-sdk.js"></script>
+<script src="https://unpkg.com/@cube-nl/dmp-sdk@1.1.0-rc.2/dist/cube-sdk.js"></script>
 ```
 
 Fallback, for an unreleased commit: `npm install
@@ -577,6 +578,63 @@ What the preview cannot do: mock data names no relations, so an `include` or `wi
 in `meta.omitted` (show it as "not visible", as live) and `has` is not applied; custom operations
 are `404 not_found`; `location` and `etag` are null.
 
+### Trial (proefversie)
+
+A maker can try an app on their own data before it is approved: the DMP serves the app's files in a sandboxed page
+(CSP `sandbox`, an opaque origin) and writes a read-only token into that page. The SDK then runs the app as a third
+mode, `'trial'`, with the same code as preview and live.
+
+The DMP inserts one data block as the first child of `<head>` (a JSON data block, not a script, so the CSP does not
+apply to it):
+
+```html
+<script type="application/json" id="cube-trial-config">{"mode":"trial","dmpUrl":"https://dmp.example.nl",
+"apiUrl":"https://dmp.example.nl/apps/api/v1","token":"cubeproef_…","expiresAt":"2026-10-20T15:42:00+02:00",
+"statusUrl":"https://dmp.example.nl/apps/api/v1/_trial","version":"1.0.3","soort":null,"userId":"42",
+"leest":["orders","klanten"]}</script>
+```
+
+| Member | |
+|---|---|
+| `mode` | Must be `"trial"` |
+| `dmpUrl`, `apiUrl`, `token`, `expiresAt`, `statusUrl` | Required non-empty strings. `expiresAt` is ISO 8601 |
+| `version`, `soort`, `userId` | A string or `null` |
+| `leest` | The resources the trial reads, for the banner; default `[]` |
+
+- **Read once, then removed.** When `cube-sdk.js` (or the ES module, in a browser) evaluates, it reads the element,
+  removes it from the DOM and keeps the config in memory. A config that is not JSON, not `mode: "trial"` or misses a
+  member gives one `console.warn` (without its content) and the app starts as it would without it.
+- **The session.** `connect()` checks the trial config first: it does not fetch `cube-app.config.json`, does no OAuth
+  (no discovery, no PKCE, no callback) and touches neither `sessionStorage` nor `localStorage`. Every request carries
+  `Authorization: Bearer cubeproef_…` to `apiUrl`. `user()` is `{ id: userId, name: null, scopes: ['api:read'] }`;
+  `signIn()` reloads the page (the DMP writes a token on every load); `signOut()` makes calls from the app stop carrying
+  the token (they answer `401`); the banner's status poll keeps it. The SDK refuses a write in a trial before it
+  leaves the page (the browser would block it at the CORS preflight): it fails as the DMP's `403` would, a `DmpError`
+  with status 403 that blocks show as "no access", never faked; only a
+  wireframe (`soort: "wireframe"`) runs in the same mixed mode as live, with simulated writes.
+- **The token is never stored and never logged.** It lives in a variable of the page for as long as the page. This
+  keeps it out of storage, logs and an innocent `innerHTML` dump; it is no defence against hostile code in the page,
+  which the DMP bounds instead (read-only, bound to the maker's IP and `Origin: null`, at most 60 minutes).
+- **The banner.** `cube-sdk.js` puts `<cube-trial-banner>` first in `<body>` (shadow DOM, constructable stylesheet,
+  house-style tokens): *"Proefversie · alleen jij · alleen lezen · verloopt om 15:42 · leest: orders, klanten · Plak
+  geen gegevens uit deze proefversie in je AI-gesprek."* (the time in nl-NL local time).
+- **The poll.** It asks `GET statusUrl` (with the token, `cache: 'no-store'`, a 10 s timeout) every 5 s while the
+  page is visible and every 60 s while hidden, and right away when the page becomes visible again. When `expiresAt`
+  passes it shows the expired state without a request.
+
+| Answer | Banner |
+|---|---|
+| `200` | Nothing changes, polling goes on |
+| Network error, timeout, `429`, `5xx` | Polling goes on |
+| `401 trial_replaced`, `wider: false` | *"Nieuwe versie wordt geladen…"*, then `location.assign(newer)` |
+| `401 trial_replaced`, otherwise | *"Er is een nieuwe versie die meer gegevens leest."* with **Laden**: only the maker's click navigates |
+| `401 trial_elsewhere` | *"Laad de pagina opnieuw."* with **Opnieuw laden** |
+| `401 trial_expired` | *"Deze proefversie is verlopen. Vraag in je gesprek om een nieuwe."* |
+| `401 trial_closed`, any other answer | *"Deze proefversie is gesloten."* |
+
+`newer` is followed only when it has `dmpUrl`'s origin and a path under `/apps/proef/`; any other URL counts as
+closed. Every state except `200` and the transient ones stops the polling.
+
 ### Mock data
 
 The shape is `cube.mock_data`'s output as is: per REST resource the `dmp.describe` payload and the
@@ -616,14 +674,19 @@ Without them the preview is permissive: every field, every function; only a fiel
 |---|---|
 | `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, e.g. `'1.0.0-rc.4'` |
+| `CubeApp.version` | This SDK's version, e.g. `'1.1.0-rc.2'` |
 | `CubeApp.sdk` | The manifest `"sdk"` this build serves, `'1'` |
-| `session.mode` | `'preview'` or `'live'` |
+| `session.mode` | `'preview'`, `'live'` or `'trial'` (a proefversie the DMP serves: the maker's own data, read-only, with a token written into the page) |
 | `session.user()` | `{ id, name, scopes }` or `null` |
-| `session.signIn()` | Live: navigates to the DMP's sign-in. Preview: signs the stand-in in |
-| `session.signOut()` | Forgets the tokens in this browser (not a revocation). Preview: signs the stand-in out |
+| `session.signIn()` | Live: navigates to the DMP's sign-in. Preview: signs the stand-in in. Trial: reloads the page |
+| `session.signOut()` | Forgets the tokens in this browser (not a revocation). Preview: signs the stand-in out. Trial: forgets the token, calls then answer 401 |
 | `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
@@ -639,13 +702,313 @@ app with a build (route A).
 | | |
 |---|---|
 | 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 | 31.4 KiB minified, 11.3 KiB gzipped (1.0.0-rc.4) |
-| Version | The banner's first line, `/*! @cube-nl/dmp-sdk 1.0.0-rc.4 cube-sdk.js … */`, and `CubeApp.version` |
+| Size | 134.7 KiB minified, 45.4 KiB gzipped (17.7 KiB core + 27.6 KiB blocks and the trial banner) in 1.1.0-rc.2; `dist/size.json` has the exact numbers |
+| Version | The banner's first line, `/*! @cube-nl/dmp-sdk 1.1.0-rc.2 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`. A block's error state shows the Dutch reason for a wrong attribute; any other failure shows the general text, and a network error or the SDK's own `TypeError` is also logged in the console |
+| `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. The rows are one Tab stop: arrow keys, Home and End move between rows; Enter or Space chooses one, 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 `search` box or a contains filter on a field that `filter` fixes or
+  gives an `ilike`, or a choice filter on a field that `filter` limits with an operator (such as `in`), changes
+  nothing (the base wins); the console warns once. 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 is refused with an error). 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`, `Infinity` or an object (for a number, integer, currency or percent
+  result), shows "—" and one alert that stays in place; the inputs keep working. A formula that throws logs
+  one `console.warn` per failure streak. Two or more `cube-result`s need an object back: a single number or text then
+  shows an error instead of the calculator on draw, but while typing it is a failed calculation ("—" and the alert),
+  as the formula may just have taken another branch. The `name` of each `cube-input`, and of each `cube-result`,
+  must be unique: a duplicate is refused.
+  `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. The card
+  is placed in the new column by `sort` until the next load, which shows the server's order (on top without
+  `sort`). A status field of type integer or number
+  gets the column value as a number.
+- **Read-only**: without `update` in the app's `uses`, when the status field is read-only, or when the resource has no
+  `id` field (the board then does not request `id`), 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:
+
+```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, or an `ontbreekt` that is not a list, 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 (the page's count then
+  counts only the rows it shows), 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`. A gap of type
+  `bedrag` shows as money also when the mock data has the field; other types follow the field's values.
+- **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 sorted list places created rows, rows that join it and rows changed in a
+  sort field into the server's order when its rows carry the sort field; without a sort, created rows come first on
+  page 1. They also work signed out, and the preview does not check them against `uses`: a wireframe shows the idea,
+  not the access rules. 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
 
 - **No per-resource generated types.** `_capabilities` is per token and at runtime, and OpenAPI
@@ -679,7 +1042,7 @@ 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.0.0-rc.4`). The tag pipeline's
+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).

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. */
@@ -50,8 +60,11 @@ export interface CubeAppUser {
     scopes: string[];
 }
 export interface CubeAppSession {
-    /** `'preview'`: mock data in this browser, no DMP. `'live'`: the real DMP, as the signed-in person. */
-    readonly mode: 'preview' | 'live';
+    /**
+     * `'preview'`: mock data in this browser, no DMP. `'live'`: the real DMP, as the signed-in person. `'trial'`: the
+     * maker's own data, read-only, with the token the DMP wrote into the page.
+     */
+    readonly mode: 'preview' | 'live' | 'trial';
     /** Who is signed in, or null. In the preview a stand-in user is signed in from the start. */
     user(): CubeAppUser | null;
     /** Live: navigates to the DMP's sign-in (the page is gone after this). Preview: signs the stand-in in again. */
@@ -62,6 +75,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 +92,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.4'`. */
-    version: "1.0.0-rc.4";
+    theme: typeof theme;
+    /** This SDK's version, e.g. `'1.1.0-rc.2'`. */
+    version: "1.1.0-rc.2";
     /** The manifest `"sdk"` value this build serves. */
     sdk: "1";
 }>;