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

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

package/dist/preview.js

@@ -37,9 +37,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 +152,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 });
             }
         }
     }
@@ -146,6 +179,9 @@ function table(name, resource) {
     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 +205,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,
     };
 }
 /**

package/dist/size.json

@@ -0,0 +1,6 @@
+{
+  "core_gzip": 17364,
+  "total_gzip": 43471,
+  "ui_gzip": 26107,
+  "budget_gzip": 40960
+}

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,138 @@
+// 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 { 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 TypeError(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/block.d.ts

@@ -0,0 +1,63 @@
+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 a TypeError carries its message: the blocks throw
+ * those for a wrong attribute, in Dutch. A server's text is never shown.
+ */
+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;
+    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;