@cube-nl/dmp-sdk 1.0.0-rc.3 → 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
@@ -25,6 +26,15 @@ export interface MockSchema {
     readonly?: readonly string[];
     /** What a row carries when the query names no `fields`, as on the REST face. Absent: every field. */
     summary_fields?: readonly string[];
+    /** The fields `group` may name. Absent: every field. */
+    groupable?: readonly string[];
+    /** Per field the functions `fn` may apply. Absent: every field, every function. Bare `count` is always allowed. */
+    aggregatable?: Record<string, readonly string[]>;
+    /** The allowed values of each choice field, and whether a write may set it (apps#93). */
+    choices?: Record<string, {
+        values: readonly unknown[];
+        writable: boolean;
+    }>;
     max_results?: number;
     fields?: Record<string, MockField> | ReadonlyArray<MockField & {
         name: string;
@@ -44,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;
 }
 /**
@@ -59,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

@@ -3,7 +3,11 @@ 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 FUNCTIONS = ['count', 'sum', 'avg', 'min', 'max'];
+const UNITS = ['day', 'week', 'month', 'quarter', 'year'];
 const MAX_FILTERS = 20;
+const MAX_DIMENSIONS = 5;
+const MAX_GROUPS = 1000;
 const MAX_IN_VALUES = 200;
 const DEFAULT_PAGE_SIZE = 50;
 const MAX_PAGE_SIZE = 200;
@@ -33,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_]*.`);
@@ -64,7 +101,7 @@ export class PreviewStore {
                 }
             },
             get: (id, query = {}) => run('get', (table) => getRow(table, id, query)),
-            aggregate: (query) => run('list', (table) => aggregateRows(table, query)),
+            aggregate: (query) => run('aggregate', (table) => aggregateRows(table, query)),
             create: (body, options = {}) => run('create', (table) => createRow(table, body, options)),
             update: (id, body, options = {}) => run('update', (table) => updateRow(table, id, body, options)),
             delete: (id, options = {}) => run('delete', (table) => deleteRow(table, id, options)),
@@ -115,21 +152,45 @@ 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 });
             }
         }
     }
     const names = [...fields.keys()];
+    // A malformed key or entry is ignored as if absent, so one bad line in a mock never breaks the preview.
+    const choiceEntries = (isObject(schema.choices) ? Object.entries(schema.choices) : []).filter((entry) => isObject(entry[1]) && Array.isArray(entry[1].values));
     const readonly = new Set([
         'id',
         ...(schema.readonly ?? []),
         ...declared.filter(([, definition]) => definition.readonly === true).map(([fieldName]) => fieldName),
+        ...choiceEntries
+            .filter(([, choice]) => choice.writable === false)
+            .map(([fieldName]) => fieldName),
     ]);
-    const known = (list) => list === undefined ? null : list.filter((item) => fields.has(item));
+    const choices = new Map();
+    for (const [fieldName, definition] of declared) {
+        if (Array.isArray(definition.enum)) {
+            choices.set(fieldName, definition.enum);
+        }
+    }
+    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;
     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,
+        aggregatable: new Map(isObject(schema.aggregatable)
+            ? Object.entries(schema.aggregatable)
+                .filter(([fieldName, allowed]) => fields.has(fieldName) && Array.isArray(allowed))
+                .map(([fieldName, allowed]) => [fieldName, [...allowed]])
+            : names.map((fieldName) => [fieldName, [...FUNCTIONS]])),
+        choices,
         writable: new Set(names.filter((fieldName) => !readonly.has(fieldName))),
         summary: (known(schema.summary_fields) ?? []).length > 0 ? known(schema.summary_fields) : names,
         rows,
@@ -144,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,
     };
 }
 /**
@@ -342,14 +405,25 @@ function readPage(params) {
 }
 function aggregateRows(table, query) {
     const params = parse(table, query);
-    const filters = readFilters(table, params);
-    const functions = (params.get('fn') ?? '').split(',').filter((item) => item !== '');
-    const groups = (params.get('group') ?? '').split(',').filter((item) => item !== '');
-    if (functions.length === 0) {
-        throw problem(422, 'query_invalid', 'fn is required.', { fn: ['Name at least one function, e.g. fn=count.'] });
+    // As the wire reads a query: fn entries, then group entries, then filters.
+    const rawFn = (params.get('fn') ?? '').trim();
+    if (rawFn === '') {
+        throw problem(422, 'query_invalid', 'fn is required: name at least one aggregation function.', {
+            fn: [`Expected e.g. fn=count or fn=sum(field). ${aggregatableHint(table)}`],
+        });
     }
+    const functions = rawFn.split(',').map((item) => item.trim());
     const readers = functions.map((fn) => aggregator(table, fn));
+    rejectDuplicates(functions, 'fn');
+    const rawGroup = (params.get('group') ?? '').trim();
+    const groups = rawGroup === '' ? [] : rawGroup.split(',').map((item) => item.trim());
+    // Before the entries: the repair for too many dimensions is a coarser question, not a fixed name.
+    if (groups.length > MAX_DIMENSIONS) {
+        throw problem(422, 'cardinality_exceeded', `group may not exceed ${MAX_DIMENSIONS} dimensions, ${groups.length} given.`, { group: [`Use at most ${MAX_DIMENSIONS} dimensions.`] });
+    }
     const dimensions = groups.map((group) => dimension(table, group));
+    rejectDuplicates(groups, 'group');
+    const filters = readFilters(table, params);
     const buckets = new Map();
     for (const row of table.rows.filter((candidate) => filters.every((filter) => matches(table, candidate, filter)))) {
         const key = {};
@@ -364,39 +438,86 @@ function aggregateRows(table, query) {
     if (groups.length === 0 && buckets.size === 0) {
         buckets.set('[]', { key: {}, rows: [] });
     }
-    const data = [...buckets.values()].map(({ key, rows }) => {
+    if (buckets.size > MAX_GROUPS) {
+        throw problem(422, 'cardinality_exceeded', 'The grouping produces more groups than the configured maximum.', {
+            groepen: [
+                'The grouping produces more groups than the configured maximum.',
+                `Allowed values: groepeer grover, of filter eerst; maximaal ${MAX_GROUPS} groepen.`,
+            ],
+        }, 'too_many_groups');
+    }
+    const ordered = [...buckets.values()].sort((a, b) => {
+        for (const group of groups) {
+            const order = compare(a.key[group], b.key[group]);
+            if (order !== 0) {
+                return order;
+            }
+        }
+        return 0;
+    });
+    const data = ordered.map(({ key, rows }) => {
         const result = { ...key };
         for (const [index, fn] of functions.entries()) {
             result[fn] = readers[index](rows);
         }
         return result;
     });
-    return response(200, data, { ...meta(table, null, []), groups: groups.length === 0 ? null : data.length });
+    return response(200, data, { ...meta(table, null, []), groups: data.length });
+}
+/** As live refuses it: two entries would collapse into one response key. */
+function rejectDuplicates(entries, parameter) {
+    const duplicates = [...new Set(entries.filter((entry, index) => entries.indexOf(entry) !== index))];
+    if (duplicates.length > 0) {
+        throw problem(422, 'query_invalid', `Duplicate ${parameter} entry: ${duplicates.join(', ')}.`, {
+            [parameter]: [`List each ${parameter} entry once.`],
+        });
+    }
+}
+function aggregatableHint(table) {
+    return table.aggregatable.size === 0
+        ? 'This resource has no aggregatable fields; only bare count is available.'
+        : `Aggregatable fields: ${[...table.aggregatable.keys()].join(', ')}.`;
 }
 function aggregator(table, fn) {
-    if (fn === 'count') {
+    const call = /^([a-z]+)\(([a-z0-9_]+)\)$/.exec(fn);
+    if (call === null && !/^[a-z]+$/.test(fn)) {
+        throw problem(422, 'query_invalid', `Unparseable fn entry: ${fn}.`, {
+            fn: ['Expected `count` or `function(field)`, e.g. sum(field).'],
+        });
+    }
+    const name = call === null ? fn : call[1];
+    const target = call === null ? null : call[2];
+    if (!FUNCTIONS.includes(name)) {
+        throw problem(422, 'query_invalid', `Unknown aggregation function: ${name}.`, {
+            fn: [`Allowed values: ${FUNCTIONS.join(', ')}.`],
+        });
+    }
+    if (target === null) {
+        if (name !== 'count') {
+            throw problem(422, 'query_invalid', `${name} must be applied to a field, e.g. ${name}(field).`, {
+                fn: [aggregatableHint(table)],
+            });
+        }
         return (rows) => rows.length;
     }
-    const match = /^(count|sum|avg|min|max)\(([^)]+)\)$/.exec(fn);
-    if (match === null) {
-        throw problem(422, 'query_invalid', `Unknown function: ${fn}.`, {
-            fn: ['Allowed: count, count(field), sum(field), avg(field), min(field), max(field).'],
-        }, 'unknown_function');
+    const allowed = table.aggregatable.get(target);
+    if (allowed === undefined) {
+        throw problem(422, 'query_invalid', `Unknown aggregatable field: ${target}.`, { fn: [aggregatableHint(table)] });
     }
-    const [, name, target] = match;
-    if (!table.fields.has(target)) {
-        throw problem(422, 'query_invalid', `Unknown fn: ${target}.`, {
-            fn: [`Allowed values: ${[...table.fields.keys()].join(', ')}.`],
-        }, 'not_aggregatable');
+    if (!allowed.includes(name)) {
+        throw problem(422, 'query_invalid', `${name} is not allowed on ${target}.`, {
+            fn: [`Allowed functions for ${target}: ${allowed.join(', ')}.`],
+        });
     }
     return (rows) => {
         const values = rows.map((row) => row[target]).filter((value) => value != null);
         const numbers = values.map(Number).filter((value) => Number.isFinite(value));
         switch (name) {
             case 'count':
-                return values.length;
+                // Live emits count(*) whatever the field, so count(field) counts the group's rows, nulls included.
+                return rows.length;
             case 'sum':
-                return numbers.reduce((sum, value) => sum + value, 0);
+                return numbers.length === 0 ? null : numbers.reduce((sum, value) => sum + value, 0);
             case 'avg':
                 return numbers.length === 0 ? null : numbers.reduce((sum, value) => sum + value, 0) / numbers.length;
             case 'min':
@@ -407,23 +528,58 @@ function aggregator(table, fn) {
     };
 }
 function dimension(table, group) {
-    const [name, truncation] = group.split('.');
-    if (!table.fields.has(name)) {
+    const parts = group.split('.');
+    if (parts.length > 2) {
+        throw problem(422, 'query_invalid', `Unparseable group entry: ${group}.`, {
+            group: ['Expected `field` or `field.unit`, e.g. published_at.month.'],
+        });
+    }
+    const [name, truncation] = parts;
+    if (!table.groupable.includes(name)) {
         throw problem(422, 'query_invalid', `Unknown group: ${name}.`, {
-            group: [`Allowed values: ${[...table.fields.keys()].join(', ')}.`],
+            group: [`Allowed values: ${table.groupable.join(', ')}.`],
         }, 'not_groupable');
     }
-    const lengths = { year: 4, month: 7, day: 10 };
     if (truncation === undefined) {
         return (row) => row[name] ?? null;
     }
-    const length = lengths[truncation];
-    if (length === undefined) {
-        throw problem(422, 'query_invalid', `Unknown truncation: ${truncation}.`, {
-            group: ['Allowed truncations in the preview: year, month, day.'],
-        }, 'unknown_truncation');
+    if (!UNITS.includes(truncation)) {
+        throw problem(422, 'query_invalid', `Unknown truncation unit: ${truncation}.`, {
+            group: [`Allowed values: ${UNITS.join(', ')}.`],
+        });
+    }
+    return (row) => bucket(row[name], truncation);
+}
+/** The date as written (first 10 characters), never shifted through a time zone; null when it is not a date. */
+function bucket(value, unit) {
+    const match = typeof value === 'string' ? /^(\d{4})-(\d{2})-(\d{2})/.exec(value) : null;
+    if (match === null) {
+        return null;
+    }
+    const [year, month, day] = [Number(match[1]), Number(match[2]), Number(match[3])];
+    const date = new Date(Date.UTC(year, month - 1, day));
+    if (date.getUTCFullYear() !== year || date.getUTCMonth() !== month - 1 || date.getUTCDate() !== day) {
+        return null;
+    }
+    switch (unit) {
+        case 'day':
+            return match[0];
+        case 'week': {
+            // ISO week: the Thursday of the Monday-based week decides the ISO year.
+            const thursday = new Date(date.getTime() + (3 - ((date.getUTCDay() + 6) % 7)) * 86_400_000);
+            const isoYear = thursday.getUTCFullYear();
+            const week = 1 + Math.floor((thursday.getTime() - Date.UTC(isoYear, 0, 1)) / (7 * 86_400_000));
+            return `${isoYear}-W${String(week).padStart(2, '0')}`;
+        }
+        case 'month':
+            return match[0].slice(0, 7);
+        case 'quarter':
+            return `${match[1]}-Q${Math.ceil(month / 3)}`;
+        case 'year':
+            return match[1];
+        default:
+            return null;
     }
-    return (row) => (typeof row[name] === 'string' ? row[name].slice(0, length) : null);
 }
 // ---------------------------------------------------------------------------------------------
 // Writing
@@ -491,7 +647,8 @@ function validate(table, body) {
     }
     const errors = {};
     for (const [name, value] of Object.entries(body)) {
-        const problemText = typeError(table.fields.get(name), value);
+        const definition = table.fields.get(name);
+        const problemText = typeError(definition, value) ?? choiceError(table, definition, name, value);
         if (problemText !== null) {
             errors[name] = [problemText];
         }
@@ -501,6 +658,14 @@ function validate(table, body) {
     }
     return clone(body);
 }
+/** Laravel's `in` rule: a value outside the field's allowed values. Runs only after the type check passed. */
+function choiceError(table, definition, name, value) {
+    const allowed = table.choices.get(name);
+    if (allowed === undefined || (value === null && definition?.nullable === true) || allowed.includes(value)) {
+        return null;
+    }
+    return `The selected ${name.replace(/_/g, ' ')} is invalid.`;
+}
 /** Laravel's rules and wording for the one declared type, as the REST face's TypeRules applies them. */
 function typeError(definition, value) {
     if (definition === undefined || definition.types.length !== 1) {

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[]>>;