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

package/dist/index.d.ts

@@ -5,4 +5,10 @@ export { buildQuery } from './query.js';
 export type * from './types.js';
 export { CubeApp, type ConnectOptions, type CubeAppConfig, type CubeAppSession, type CubeAppStatic, type CubeAppUser, } from './app.js';
 export type { AppManifest, MockData, MockField, MockResource, MockSchema } from './preview.js';
+export { defineBlocks, type BlockScope, type DefineOptions } from './ui/define.js';
+export { contrastRatio, deriveTheme, FONTS, TOKEN_NAMES } from './ui/theme.js';
+export type { Corners, FontFile, FontId, ResolvedTheme, ThemeFile, ThemeSource, ThemeTokens, ThemeWarning, TokenName, } from './ui/theme.js';
+export { formatValue, type Format } from './ui/format.js';
+export type { FieldInfo, ResourceSchema } from './ui/schema.js';
+export { blockManifest, type AttributeSpec, type BlockManifest, type BlockSpec } from './ui/manifest.js';
 export { VERSION } from './version.js';

package/dist/index.js

@@ -3,4 +3,8 @@ export { bearer, createOAuth, discoverMetadata, memoryKeyValueStore, memoryToken
 export { DmpError, isDmpError } from './errors.js';
 export { buildQuery } from './query.js';
 export { CubeApp, } from './app.js';
+export { defineBlocks } from './ui/define.js';
+export { contrastRatio, deriveTheme, FONTS, TOKEN_NAMES } from './ui/theme.js';
+export { formatValue } from './ui/format.js';
+export { blockManifest } from './ui/manifest.js';
 export { VERSION } from './version.js';

package/dist/preview.d.ts

@@ -1,5 +1,6 @@
 import type { ResourceClient } from './client.js';
 import type { DmpRecord } from './types.js';
+import type { ResourceSchema } from './ui/schema.js';
 /**
  * One field as `dmp.describe` (and so `cube.mock_data`) writes it: a JSON Schema. `type` is a
  * name, or a list of names where `'null'` makes it nullable. `_capabilities`' own field shape
@@ -53,6 +54,10 @@ export interface AppManifest {
     description?: string;
     uses?: Record<string, readonly string[]>;
     sdk?: string;
+    /** `'wireframe'`: a proposal whose data partly does not exist yet; see `ontbreekt`. */
+    soort?: string;
+    /** What a wireframe needs that the DMP does not have yet: the gap entries (`readGaps`). */
+    ontbreekt?: unknown[];
     [key: string]: unknown;
 }
 /**
@@ -68,7 +73,11 @@ export declare class PreviewStore {
     constructor(data: MockData, manifest?: AppManifest | null, 
     /** Runs before every call; throw to refuse it (the preview's signed-out state). */
     guard?: () => void);
+    /** The rows a resource holds now; empty for an unknown resource. */
+    rows(name: string): readonly DmpRecord[];
     resourceNames(): string[];
+    /** The resource as a block sees it, built from the parsed schema; null for an unknown resource. */
+    describe(name: string): ResourceSchema | null;
     resource<T extends DmpRecord = DmpRecord>(name: string): ResourceClient<T>;
     /**
      * Unknown resource first (404, as the REST face answers it), then the manifest: live, the app's
@@ -76,3 +85,5 @@ export declare class PreviewStore {
      */
     private authorize;
 }
+/** Nulls first, numbers as numbers, everything else as text (ISO dates sort correctly as text). */
+export declare function compare(a: unknown, b: unknown): number;

package/dist/preview.js

@@ -2,7 +2,14 @@ import { DmpError } from './errors.js';
 import { buildQuery } from './query.js';
 const RESOURCE_NAME = /^[a-z][a-z0-9_]*$/;
 const OPERATORS = ['eq', 'neq', 'gt', 'gte', 'lt', 'lte', 'in', 'like', 'ilike', 'is', 'between'];
-const SYMBOLS = [['>=', 'gte'], ['<=', 'lte'], ['<>', 'neq'], ['>', 'gt'], ['<', 'lt'], ['=', 'eq']];
+const SYMBOLS = [
+    ['>=', 'gte'],
+    ['<=', 'lte'],
+    ['<>', 'neq'],
+    ['>', 'gt'],
+    ['<', 'lt'],
+    ['=', 'eq'],
+];
 const FUNCTIONS = ['count', 'sum', 'avg', 'min', 'max'];
 const UNITS = ['day', 'week', 'month', 'quarter', 'year'];
 const MAX_FILTERS = 20;
@@ -37,9 +44,42 @@ export class PreviewStore {
             }
         }
     }
+    /** The rows a resource holds now; empty for an unknown resource. */
+    rows(name) {
+        return this.tables.get(name)?.rows ?? [];
+    }
     resourceNames() {
         return [...this.tables.keys()];
     }
+    /** The resource as a block sees it, built from the parsed schema; null for an unknown resource. */
+    describe(name) {
+        const table = this.tables.get(name);
+        if (table === undefined) {
+            return null;
+        }
+        return {
+            name,
+            actions: [...table.actions],
+            fields: [...table.fields.values()].map((field) => {
+                const choices = table.choices.get(field.name);
+                return {
+                    name: field.name,
+                    type: field.types.join('|'),
+                    format: field.format,
+                    nullable: field.nullable,
+                    readonly: !table.writable.has(field.name),
+                    enum: choices === undefined ? null : choices.map(String),
+                    description: field.description,
+                };
+            }),
+            summary: [...table.summary],
+            filterable: [...table.filterable],
+            sortable: [...table.fields.keys()],
+            groupable: [...table.groupable],
+            // Live lists the field functions only: a bare count needs no field, so `count` is never offered per field.
+            aggregatable: Object.fromEntries([...table.aggregatable].map(([key, fns]) => [key, fns.filter((fn) => fn !== 'count')])),
+        };
+    }
     resource(name) {
         if (!RESOURCE_NAME.test(name)) {
             throw new TypeError(`'${name}' is not a resource name: cube/api names match [a-z][a-z0-9_]*.`);
@@ -119,7 +159,7 @@ function table(name, resource) {
     for (const row of fields.size === 0 ? rows : []) {
         for (const key of Object.keys(row)) {
             if (!fields.has(key)) {
-                fields.set(key, { name: key, types: [], nullable: true });
+                fields.set(key, { name: key, types: [], nullable: true, format: null, description: null });
             }
         }
     }
@@ -143,9 +183,14 @@ function table(name, resource) {
     for (const [fieldName, choice] of choiceEntries) {
         choices.set(fieldName, choice.values);
     }
-    const known = (list) => Array.isArray(list) ? list.filter((item) => typeof item === 'string' && fields.has(item)) : null;
+    const known = (list) => Array.isArray(list)
+        ? list.filter((item) => typeof item === 'string' && fields.has(item))
+        : null;
     return {
         name,
+        actions: Array.isArray(schema.actions)
+            ? schema.actions.filter((action) => typeof action === 'string')
+            : ['list', 'get', 'create', 'update', 'delete'],
         fields,
         filterable: known(schema.filters) ?? names,
         groupable: known(schema.groupable) ?? names,
@@ -169,6 +214,8 @@ function field(name, definition) {
         name,
         types: list.filter((type) => type !== 'null' && type !== ''),
         nullable: definition.nullable === true || list.includes('null'),
+        format: typeof definition.format === 'string' ? definition.format : null,
+        description: typeof definition.description === 'string' ? definition.description : null,
     };
 }
 /**
@@ -464,7 +511,9 @@ function aggregator(table, fn) {
     }
     const allowed = table.aggregatable.get(target);
     if (allowed === undefined) {
-        throw problem(422, 'query_invalid', `Unknown aggregatable field: ${target}.`, { fn: [aggregatableHint(table)] });
+        throw problem(422, 'query_invalid', `Unknown aggregatable field: ${target}.`, {
+            fn: [aggregatableHint(table)],
+        });
     }
     if (!allowed.includes(name)) {
         throw problem(422, 'query_invalid', `${name} is not allowed on ${target}.`, {
@@ -483,9 +532,13 @@ function aggregator(table, fn) {
             case 'avg':
                 return numbers.length === 0 ? null : numbers.reduce((sum, value) => sum + value, 0) / numbers.length;
             case 'min':
-                return values.length === 0 ? null : values.reduce((low, value) => (compare(value, low) < 0 ? value : low));
+                return values.length === 0
+                    ? null
+                    : values.reduce((low, value) => (compare(value, low) < 0 ? value : low));
             default:
-                return values.length === 0 ? null : values.reduce((high, value) => (compare(value, high) > 0 ? value : high));
+                return values.length === 0
+                    ? null
+                    : values.reduce((high, value) => (compare(value, high) > 0 ? value : high));
         }
     };
 }
@@ -778,7 +831,7 @@ function same(actual, expected) {
     return actual === expected || (typeof actual !== 'object' && String(actual) === String(expected));
 }
 /** Nulls first, numbers as numbers, everything else as text (ISO dates sort correctly as text). */
-function compare(a, b) {
+export function compare(a, b) {
     if (a == null || b == null) {
         return a == null ? (b == null ? 0 : -1) : 1;
     }

package/dist/size.json

@@ -0,0 +1,6 @@
+{
+  "core_gzip": 18169,
+  "total_gzip": 46472,
+  "ui_gzip": 28303,
+  "budget_gzip": 40960
+}

package/dist/trial.d.ts

@@ -0,0 +1,32 @@
+/**
+ * What the DMP writes into a trial page (`<script type="application/json" id="cube-trial-config">`): the maker's
+ * app on the maker's own data, read-only, with a token that lives only in this page.
+ */
+export interface TrialConfig {
+    mode: 'trial';
+    /** The DMP's origin. */
+    dmpUrl: string;
+    /** The REST face's base URL. */
+    apiUrl: string;
+    /** The read-only trial token, `cubeproef_…`. Never stored, never logged. */
+    token: string;
+    /** ISO 8601. */
+    expiresAt: string;
+    /** `GET` answers whether the trial is still open (the auto-refresh polls it). */
+    statusUrl: string;
+    version: string | null;
+    soort: string | null;
+    /** The DMP's user id of the maker. */
+    userId: string | null;
+    /** The resources the trial reads, for the banner. */
+    leest: string[];
+}
+/**
+ * Reads the injected config and removes its element, so the token is out of the DOM. The SDK calls it once when the
+ * script evaluates; the result is what `trialConfig()` answers from then on (a later call that finds an element
+ * replaces it, one that finds none changes nothing and answers null). Anything but a complete `mode: 'trial'` config
+ * is warned about and means no trial: the app starts as it would without one.
+ */
+export declare function readTrialConfig(doc?: Document): TrialConfig | null;
+/** The trial config this page was served with, or null outside a trial. */
+export declare function trialConfig(): TrialConfig | null;

package/dist/trial.js

@@ -0,0 +1,55 @@
+const ELEMENT_ID = 'cube-trial-config';
+const REQUIRED = ['dmpUrl', 'apiUrl', 'token', 'expiresAt', 'statusUrl'];
+let current = null;
+/**
+ * Reads the injected config and removes its element, so the token is out of the DOM. The SDK calls it once when the
+ * script evaluates; the result is what `trialConfig()` answers from then on (a later call that finds an element
+ * replaces it, one that finds none changes nothing and answers null). Anything but a complete `mode: 'trial'` config
+ * is warned about and means no trial: the app starts as it would without one.
+ */
+export function readTrialConfig(doc) {
+    const element = doc?.getElementById(ELEMENT_ID) ?? null;
+    // Without the element there is nothing new to read: the config read before stays (the element is gone by now).
+    if (element === null) {
+        return null;
+    }
+    current = null;
+    element.remove();
+    let value = null;
+    try {
+        const parsed = JSON.parse(element.textContent ?? '');
+        value = parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        // Reported below, without the content: it holds the token.
+    }
+    if (value?.mode !== 'trial' || REQUIRED.some((key) => typeof value[key] !== 'string' || value[key] === '')) {
+        console.warn(`#${ELEMENT_ID} is not a complete trial config; the app starts without it.`);
+        return null;
+    }
+    const text = (key) => (typeof value[key] === 'string' ? value[key] : null);
+    const leest = value.leest;
+    current = {
+        mode: 'trial',
+        dmpUrl: value.dmpUrl,
+        apiUrl: value.apiUrl,
+        token: value.token,
+        expiresAt: value.expiresAt,
+        statusUrl: value.statusUrl,
+        version: text('version'),
+        soort: text('soort'),
+        userId: text('userId'),
+        leest: Array.isArray(leest) ? leest.filter((name) => typeof name === 'string') : [],
+    };
+    return current;
+}
+/** The trial config this page was served with, or null outside a trial. */
+export function trialConfig() {
+    return current;
+}
+// At evaluation, before any app code runs: the element must be gone before the app could read or dump the DOM.
+if (typeof document !== 'undefined') {
+    readTrialConfig(document);
+}

package/dist/ui/aggregate-block.d.ts

@@ -0,0 +1,73 @@
+import type { CubeAppSession } from '../app.js';
+import type { DmpRecord, DmpResponse, FilterValue } from '../types.js';
+import type { Period } from './period.js';
+import { type PeriodSourceLike } from './query.js';
+/** The frame every aggregate block draws its content in, so a dashboard reads as one set of cards. */
+export declare const CARD_CSS = "\n.card{padding:1rem 1.25rem;border:1px solid var(--cube-color-border);border-radius:var(--cube-radius);\nbackground:var(--cube-color-surface)}\n";
+/** The visible title above a chart or a ranking. */
+export declare const LABEL_CSS = "\n.label{margin:0 0 .5rem;font-weight:600}\n";
+export interface AggregateQueryParts {
+    /** The `fn` the API is asked for, and the key of the value in each row: `count`, `sum(total)`. */
+    fn: string;
+    /** The measured field; null for a row count. */
+    field: string | null;
+    count: boolean;
+    /** The period of the followed picker, or null without one. */
+    period: Period | null;
+    /** The block's `filter`, narrowed to `range` on the date field when both are there. */
+    filterFor(range: {
+        from: string;
+        to: string;
+    } | null): Record<string, FilterValue>;
+}
+/** An attribute the block cannot do without; its absence is explained in the block. */
+export declare function requiredAttr(el: Element, name: string): string;
+/** The fields an aggregate block reads: the measured one, the `by` field (without its truncation), the date field. */
+export declare function aggregateFields(el: Element): string[];
+/** A number from an aggregate row (the API may send decimals as strings); null for nothing or not a number. */
+export declare function toNumber(value: unknown): number | null;
+/**
+ * Listens to one period picker at a time and reloads its block on a change. A block that was removed lets go at
+ * the next change instead of reloading, so the blocks need no disconnect step of their own for it.
+ */
+export declare class PeriodFollower {
+    private readonly block;
+    private source;
+    private readonly onChange;
+    constructor(block: {
+        readonly isConnected: boolean;
+        refresh(): Promise<void>;
+    });
+    follow(source: PeriodSourceLike | null): void;
+}
+/**
+ * Reads `measure`, `filter`, `period` and `date-field` (falling back to the field of a truncated `by`), waits for
+ * the picker and follows it. Null when the load was aborted meanwhile: a newer load (or none) owns the block.
+ */
+export declare function aggregateQuery(el: HTMLElement, follower: PeriodFollower, signal: AbortSignal, by?: string | null): Promise<AggregateQueryParts | null>;
+/**
+ * The aggregate of a grouped block (chart, top) over its period. More groups than the DMP returns in one answer
+ * (1000) is refused with a 422; trying again gives the same answer, so the error says what to change instead.
+ */
+export declare function groupedAggregate(session: CubeAppSession, resource: string, by: string, query: AggregateQueryParts, signal: AbortSignal): Promise<DmpResponse<DmpRecord[]>>;
+/** A whole number attribute of at least `min`; absent, not a number or too small gives `fallback`. */
+export declare function wholeAttr(el: Element, name: string, min: number, fallback: number): number;
+export interface RankedGroup {
+    key: string;
+    value: number;
+    /** The lookup's label, `#<id>` for an id it has no row for, or the key itself without a lookup. */
+    label: string;
+}
+/**
+ * The groups of an aggregate ranked by value (`descending` highest first) and cut at `limit`, labelled through the
+ * block's `lookup`. A group without a key or without a value is left out. Null when the load was aborted meanwhile.
+ */
+export declare function rankGroups(el: Element, session: CubeAppSession, rows: DmpRecord[], keys: {
+    by: string;
+    fn: string;
+}, order: {
+    descending: boolean;
+    limit: number;
+}, signal: AbortSignal): Promise<RankedGroup[] | null>;
+/** How the block writes a value: its `format` (default integer for count, else number) and `currency`. */
+export declare function valueFormatter(el: Element, count: boolean): (n: number, compact?: boolean) => string;

package/dist/ui/aggregate-block.js

@@ -0,0 +1,139 @@
+// What the aggregate blocks (cube-kpi, cube-chart, cube-top) share: their required attributes, the measure and
+// filter they ask with, the period picker they follow and how they write a value.
+import { isDmpError } from '../errors.js';
+import { AuthorError } from './author-error.js';
+import { BlockStateError } from './block.js';
+import { formatValue, parseMeasure } from './format.js';
+import { blockFilter, dateFieldFor, lookupLabels, periodFilter, resolvePeriodSource, } from './query.js';
+import { NL } from './texts.js';
+const FORMATS = ['number', 'integer', 'currency', 'percent'];
+/** The frame every aggregate block draws its content in, so a dashboard reads as one set of cards. */
+export const CARD_CSS = `
+.card{padding:1rem 1.25rem;border:1px solid var(--cube-color-border);border-radius:var(--cube-radius);
+background:var(--cube-color-surface)}
+`;
+/** The visible title above a chart or a ranking. */
+export const LABEL_CSS = `
+.label{margin:0 0 .5rem;font-weight:600}
+`;
+/** An attribute the block cannot do without; its absence is explained in the block. */
+export function requiredAttr(el, name) {
+    const value = el.getAttribute(name)?.trim() ?? '';
+    if (value === '')
+        throw new AuthorError(NL.invalid.missing(el.localName, name));
+    return value;
+}
+/** The fields an aggregate block reads: the measured one, the `by` field (without its truncation), the date field. */
+export function aggregateFields(el) {
+    const measured = /\(([^)]+)\)/.exec(el.getAttribute('measure') ?? '')?.[1]?.trim();
+    const by = el.getAttribute('by')?.split('.')[0];
+    return [measured, by, el.getAttribute('date-field')].filter((field) => !!field);
+}
+/** A number from an aggregate row (the API may send decimals as strings); null for nothing or not a number. */
+export function toNumber(value) {
+    if (typeof value === 'string' && value.trim() === '')
+        return null;
+    const n = typeof value === 'number' || typeof value === 'string' ? Number(value) : NaN;
+    return Number.isFinite(n) ? n : null;
+}
+/**
+ * Listens to one period picker at a time and reloads its block on a change. A block that was removed lets go at
+ * the next change instead of reloading, so the blocks need no disconnect step of their own for it.
+ */
+export class PeriodFollower {
+    block;
+    source = null;
+    onChange = () => {
+        if (this.block.isConnected)
+            void this.block.refresh();
+        else
+            this.follow(null);
+    };
+    constructor(block) {
+        this.block = block;
+    }
+    follow(source) {
+        if (source === this.source)
+            return;
+        this.source?.removeEventListener('cube-change', this.onChange);
+        this.source = source;
+        source?.addEventListener('cube-change', this.onChange);
+    }
+}
+/**
+ * Reads `measure`, `filter`, `period` and `date-field` (falling back to the field of a truncated `by`), waits for
+ * the picker and follows it. Null when the load was aborted meanwhile: a newer load (or none) owns the block.
+ */
+export async function aggregateQuery(el, follower, signal, by = null) {
+    const measure = parseMeasure(requiredAttr(el, 'measure'));
+    const filter = blockFilter(el);
+    const selector = el.getAttribute('period');
+    const dateField = selector === null || selector === ''
+        ? null
+        : dateFieldFor(el.getAttribute('date-field'), by, el.localName);
+    const source = await resolvePeriodSource(el, selector);
+    if (signal.aborted)
+        return null;
+    follower.follow(source);
+    return {
+        fn: measure.field === null ? measure.fn : `${measure.fn}(${measure.field})`,
+        field: measure.field,
+        count: measure.fn === 'count',
+        period: source?.value ?? null,
+        filterFor: (range) => range === null || dateField === null ? filter : { ...filter, ...periodFilter(dateField, range) },
+    };
+}
+/**
+ * The aggregate of a grouped block (chart, top) over its period. More groups than the DMP returns in one answer
+ * (1000) is refused with a 422; trying again gives the same answer, so the error says what to change instead.
+ */
+export async function groupedAggregate(session, resource, by, query, signal) {
+    try {
+        return await session
+            .resource(resource)
+            .aggregate({ fn: query.fn, group: by, filter: query.filterFor(query.period) }, { signal });
+    }
+    catch (error) {
+        if (isDmpError(error) && error.status === 422
+            && (error.reason === 'too_many_groups' || error.code === 'cardinality_exceeded')) {
+            throw new BlockStateError({ kind: 'error', detail: NL.tooManyGroups, retry: false });
+        }
+        throw error;
+    }
+}
+/** A whole number attribute of at least `min`; absent, not a number or too small gives `fallback`. */
+export function wholeAttr(el, name, min, fallback) {
+    const raw = el.getAttribute(name);
+    const n = raw === null || raw.trim() === '' ? NaN : Number(raw);
+    return Number.isFinite(n) && n >= min ? Math.floor(n) : fallback;
+}
+/**
+ * The groups of an aggregate ranked by value (`descending` highest first) and cut at `limit`, labelled through the
+ * block's `lookup`. A group without a key or without a value is left out. Null when the load was aborted meanwhile.
+ */
+export async function rankGroups(el, session, rows, keys, order, signal) {
+    const direction = order.descending ? -1 : 1;
+    const ranked = rows
+        .filter((row) => row[keys.by] !== null && row[keys.by] !== undefined)
+        .map((row) => ({ key: String(row[keys.by]), value: toNumber(row[keys.fn]) }))
+        .filter((group) => group.value !== null)
+        .sort((a, b) => direction * (a.value - b.value))
+        .slice(0, order.limit);
+    const lookup = el.getAttribute('lookup');
+    const labels = lookup === null || lookup === '' || ranked.length === 0
+        ? null
+        : await lookupLabels(session, lookup, ranked.map((group) => group.key), signal);
+    if (signal.aborted)
+        return null;
+    return ranked.map((group) => ({
+        ...group,
+        label: labels === null ? group.key : (labels.get(group.key) ?? `#${group.key}`),
+    }));
+}
+/** How the block writes a value: its `format` (default integer for count, else number) and `currency`. */
+export function valueFormatter(el, count) {
+    const wanted = el.getAttribute('format');
+    const format = (wanted !== null && FORMATS.includes(wanted) ? wanted : count ? 'integer' : 'number');
+    const currency = el.getAttribute('currency') || 'EUR';
+    return (n, compact) => formatValue(n, format, { currency, compact: compact === true });
+}

package/dist/ui/attributes.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The attribute names each block observes, apart from manifest.ts so the browser bundle does not carry the
+ * manifest's documentation texts. test/ui-manifest.test.js keeps the two in step.
+ */
+export declare const BLOCK_ATTRIBUTES: Readonly<Record<string, readonly string[]>>;

package/dist/ui/attributes.js

@@ -0,0 +1,72 @@
+/**
+ * The attribute names each block observes, apart from manifest.ts so the browser bundle does not carry the
+ * manifest's documentation texts. test/ui-manifest.test.js keeps the two in step.
+ */
+export const BLOCK_ATTRIBUTES = {
+    'cube-state': ['kind', 'message', 'retry'],
+    'cube-app-shell': ['name', 'logo', 'logo-alt'],
+    'cube-page': ['name', 'label'],
+    'cube-field': ['name', 'label', 'format', 'multiline', 'options', 'hidden'],
+    'cube-period-picker': ['default', 'label', 'today'],
+    'cube-kpi': [
+        'resource',
+        'measure',
+        'label',
+        'format',
+        'currency',
+        'filter',
+        'period',
+        'date-field',
+        'compare',
+    ],
+    'cube-chart': [
+        'resource',
+        'measure',
+        'by',
+        'kind',
+        'label',
+        'format',
+        'currency',
+        'filter',
+        'period',
+        'date-field',
+        'lookup',
+        'height',
+        'limit',
+    ],
+    'cube-top': [
+        'resource',
+        'measure',
+        'by',
+        'limit',
+        'order',
+        'label',
+        'format',
+        'currency',
+        'filter',
+        'period',
+        'date-field',
+        'lookup',
+    ],
+    'cube-table': [
+        'resource',
+        'fields',
+        'search',
+        'filters',
+        'sort',
+        'page-size',
+        'export',
+        'detail',
+        'filter',
+        'period',
+        'date-field',
+    ],
+    'cube-detail': ['resource', 'record-id', 'fields', 'editable'],
+    'cube-form': ['resource', 'fields', 'submit-label', 'success-text'],
+    'cube-calc': ['label'],
+    'cube-input': ['name', 'label', 'type', 'value', 'min', 'max', 'step', 'options'],
+    'cube-result': ['name', 'label', 'format', 'currency', 'emphasis'],
+    'cube-board': ['resource', 'status-field', 'title-field', 'fields', 'sort', 'filter', 'page-size'],
+    'cube-column': ['value', 'label'],
+    'cube-gap-list': ['scherm'],
+};

package/dist/ui/author-error.d.ts

@@ -0,0 +1,3 @@
+/** A wrong attribute or markup by the app's builder: the one error whose (Dutch) message a block shows. */
+export declare class AuthorError extends TypeError {
+}

package/dist/ui/author-error.js

@@ -0,0 +1,3 @@
+/** A wrong attribute or markup by the app's builder: the one error whose (Dutch) message a block shows. */
+export class AuthorError extends TypeError {
+}

package/dist/ui/block.d.ts

@@ -0,0 +1,69 @@
+import { type CubeAppSession } from '../app.js';
+import type { BlockScope, DefineOptions } from './define.js';
+export type StateKind = 'loading' | 'empty' | 'error' | 'forbidden' | 'signed-out';
+export interface BlockState {
+    kind: StateKind;
+    detail: string | null;
+    /** False for an error that trying again cannot solve: the state offers no retry. */
+    retry?: boolean;
+}
+/** Thrown by a block's load to show exactly this state. */
+export declare class BlockStateError extends Error {
+    readonly state: BlockState;
+    constructor(state: BlockState);
+}
+/**
+ * What a failure looks like to the person on the page. Only an AuthorError carries its message: the blocks throw
+ * those for a wrong attribute, in Dutch. A server's text, a network failure or a client's English programmer error
+ * never does.
+ */
+export declare function stateFor(error: unknown): BlockState;
+/**
+ * Resolves once the page's own scripts have run. A block must not take the page session before the app had its
+ * chance to call `CubeApp.connect()` with its own options, or the block would start a second, default one.
+ */
+export declare function pageReady(doc: Document): Promise<void>;
+/** The class every block extends. Declared, not defined: the real one is made per window by `blockBase`. */
+export declare abstract class CubeBlockShape extends HTMLElement {
+    static tag: string;
+    /** The block's own stylesheet text, adopted after BASE_CSS. */
+    static css: string;
+    /** False for blocks that render without data (cube-state): they never take the session to render. */
+    static needsSession: boolean;
+    /**
+     * False for a block that already shows what its own cube-data-change reports (cube-board): it does not reload on
+     * it.
+     */
+    static reloadsOnOwnChange: boolean;
+    static observedAttributes: string[];
+    /** The block's content root inside its shadow root. */
+    readonly body: HTMLElement;
+    /** Settles when the current (and any newer) load has finished. */
+    readonly updateComplete: Promise<void>;
+    /** Loads again: aborts a running load, shows the loading state, then calls `load`. */
+    refresh(): Promise<void>;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+    /** Renders the block into `body`. Throw to show a state; check `signal` before touching the DOM after an await. */
+    protected abstract load(signal: AbortSignal, session: CubeAppSession | null): Promise<void>;
+    /** The fields of `resource` the block shows after its load: one of them invented marks the whole block. */
+    protected shownFields(): string[];
+    /** Whether `field` of `resource` is invented while the resource itself exists: its column is marked. */
+    protected exampleField(session: CubeAppSession, resource: string, field: string): boolean;
+    /** `Voorbeeld — wordt niet opgeslagen` next to a write action of a wireframe; null in any other app. */
+    protected notSaved(session: CubeAppSession): HTMLElement | null;
+    protected session(): Promise<CubeAppSession>;
+    protected showState(state: StateKind | BlockState, detail?: string | null): void;
+    protected attr(name: string): string | null;
+    protected flag(name: string): boolean;
+    protected num(name: string, fallback: number): number;
+    protected json<T>(name: string): T | null;
+    protected emit(name: string, detail?: unknown): boolean;
+}
+export type BlockClass = typeof CubeBlockShape;
+/** A block module's export: makes its element class on top of the window's base class. */
+export type BlockFactory = (Base: BlockClass, scope: BlockScope) => BlockClass;
+/** The header mark of an invented field: `Voorbeeld` on screen, the whole of exampleMissing read out. */
+export declare function exampleBadge(doc: Document): HTMLElement;
+export declare function blockBase(scope: BlockScope, options?: DefineOptions): BlockClass;