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

package/dist/ui/blocks/gap-list.js

@@ -0,0 +1,36 @@
+import { CARD_CSS } from '../aggregate-block.js';
+import { clear, h } from '../dom.js';
+import { NL } from '../texts.js';
+// One card per gap: a label sits beside its value where there is room and above it where there is not (320 px).
+// role="list" on the <ul>: Safari drops the list role of a list styled without bullets.
+const CSS = `${CARD_CSS}
+ul{list-style:none;margin:0;padding:0;display:grid;gap:.75rem}
+h3{margin:0 0 .5rem;font-size:1rem;overflow-wrap:anywhere}
+dl{margin:0;display:grid;gap:.375rem}
+dl div{display:flex;flex-wrap:wrap;gap:0 .75rem}
+dt{flex:0 0 8rem;font-weight:600}
+dd{flex:1 1 12rem;margin:0;min-width:0;overflow-wrap:break-word}
+p{margin:0}
+`;
+/** `<cube-gap-list>`: what a wireframe shows that the DMP does not have yet, and why, for the people who build it. */
+export function gapListBlock(Base, scope) {
+    const doc = scope.document;
+    class CubeGapList extends Base {
+        static tag = 'cube-gap-list';
+        static css = CSS;
+        async load(signal, session) {
+            if (session === null || signal.aborted)
+                return;
+            const screen = this.attr('scherm')?.trim() ?? '';
+            const gaps = (session.gaps ?? []).filter((gap) => screen === '' || gap.scherm === screen);
+            const pair = (label, value) => h(doc, 'div', {}, h(doc, 'dt', {}, label), h(doc, 'dd', {}, value));
+            clear(this.body);
+            this.body.appendChild(gaps.length === 0
+                ? h(doc, 'div', { class: 'card' }, h(doc, 'p', {}, NL.gaps.none))
+                : h(doc, 'ul', { role: 'list', 'aria-label': NL.gaps.what }, ...gaps.map((gap) => h(doc, 'li', { class: 'card' }, h(doc, 'h3', {}, gap.veld === undefined ? gap.resource : `${gap.resource}.${gap.veld}`), h(doc, 'dl', {}, pair(NL.gaps.screen, gap.scherm), pair(NL.gaps.type, gap.type === 'keuze'
+                    ? `${NL.gaps.types.keuze}: ${(gap.waarden ?? []).join(', ')}`
+                    : NL.gaps.types[gap.type]), pair(NL.gaps.why, gap.reden))))));
+        }
+    }
+    return CubeGapList;
+}

package/dist/ui/blocks/kpi.d.ts

@@ -0,0 +1,4 @@
+import type { BlockClass } from '../block.js';
+import type { BlockScope } from '../define.js';
+/** `<cube-kpi>`: one figure (count, sum, average…) of a resource, optionally over a period and compared. */
+export declare function kpiBlock(Base: BlockClass, scope: BlockScope): BlockClass;

package/dist/ui/blocks/kpi.js

@@ -0,0 +1,75 @@
+import { aggregateFields, aggregateQuery, CARD_CSS, PeriodFollower, requiredAttr, toNumber, valueFormatter, } from '../aggregate-block.js';
+import { AuthorError } from '../author-error.js';
+import { clear, h } from '../dom.js';
+import { NL } from '../texts.js';
+const CHANGE = new Intl.NumberFormat('nl-NL', { minimumFractionDigits: 1, maximumFractionDigits: 1 });
+const CSS = `${CARD_CSS}
+.kpi{display:flex;flex-direction:column;gap:.25rem}
+.label{margin:0;font-size:.875rem;font-weight:600;color:var(--cube-color-text-muted)}
+.value{margin:0;font-size:2rem;font-weight:700;line-height:1.2;overflow-wrap:anywhere}
+.compare{margin:0;font-size:.875rem;color:var(--cube-color-text-muted)}
+.compare.up{color:var(--cube-color-success)}
+.compare.down{color:var(--cube-color-danger)}
+`;
+/** `<cube-kpi>`: one figure (count, sum, average…) of a resource, optionally over a period and compared. */
+export function kpiBlock(Base, scope) {
+    class CubeKpi extends Base {
+        static tag = 'cube-kpi';
+        static css = CSS;
+        shownFields() {
+            return aggregateFields(this);
+        }
+        /** The picker this block follows, and so listens to. */
+        period = new PeriodFollower(this);
+        async load(signal, session) {
+            if (session === null)
+                return;
+            const resource = requiredAttr(this, 'resource');
+            if (this.flag('compare') && !this.attr('period'))
+                throw new AuthorError(NL.invalid.compare(this.localName));
+            const query = await aggregateQuery(this, this.period, signal);
+            if (query === null)
+                return;
+            const { fn, period } = query;
+            const api = session.resource(resource);
+            const ask = async (range) => {
+                const { data } = await api.aggregate({ fn, filter: query.filterFor(range) }, { signal });
+                return toNumber(data[0]?.[fn]);
+            };
+            const before = this.flag('compare') ? (period?.previous ?? null) : null;
+            const [current, previous] = await Promise.all([ask(period), before === null ? null : ask(before)]);
+            if (signal.aborted)
+                return;
+            this.render(current, before === null ? undefined : previous, query.count);
+        }
+        /** `previous` undefined: no comparison asked; null: nothing to compare with. */
+        render(current, previous, count) {
+            const doc = scope.document;
+            const format = valueFormatter(this, count);
+            const label = this.attr('label');
+            const value = current === null
+                ? h(doc, 'p', { class: 'value' }, h(doc, 'span', { 'aria-hidden': 'true' }, NL.emptyValue), h(doc, 'span', { class: 'sr-only' }, NL.noData))
+                : h(doc, 'p', { class: 'value' }, h(doc, 'data', { value: String(current) }, format(current)));
+            clear(this.body);
+            this.body.appendChild(h(doc, 'div', { class: 'card kpi' }, label === null || label === '' ? null : h(doc, 'p', { class: 'label' }, label), value, previous === undefined || current === null ? null : this.compareLine(current, previous)));
+        }
+        compareLine(current, previous) {
+            const doc = scope.document;
+            // Nothing (or zero) before: any change would be infinite, so the figure is simply new.
+            if (previous === null || previous === 0)
+                return h(doc, 'p', { class: 'compare new' }, NL.newValue);
+            const change = (current - previous) / Math.abs(previous);
+            const percent = CHANGE.format(Math.abs(change) * 100);
+            if (percent === CHANGE.format(0)) {
+                return h(doc, 'p', { class: 'compare same' }, `${percent}% ${NL.comparedTo}`);
+            }
+            const up = change > 0;
+            return h(doc, 'p', {
+                class: up ? 'compare up' : 'compare down',
+                role: 'img',
+                'aria-label': NL.change(percent, up ? NL.higher : NL.lower),
+            }, `${up ? '▲' : '▼'} ${percent}% ${NL.comparedTo}`);
+        }
+    }
+    return CubeKpi;
+}

package/dist/ui/blocks/period-picker.d.ts

@@ -0,0 +1,4 @@
+import type { BlockClass } from '../block.js';
+import type { BlockScope } from '../define.js';
+/** `<cube-period-picker>`: chooses the period that period-aware blocks on the page follow. */
+export declare function periodPickerBlock(Base: BlockClass, scope: BlockScope): BlockClass;

package/dist/ui/blocks/period-picker.js

@@ -0,0 +1,155 @@
+import { h } from '../dom.js';
+import { isoDate, parseLocalDate } from '../format.js';
+import { resolvePeriod } from '../period.js';
+import { NL } from '../texts.js';
+const KEYS = ['this-month', '12m', 'this-year', 'custom'];
+const DEFAULT = '12m';
+const CSS = `
+.picker{display:flex;flex-wrap:wrap;align-items:flex-end;gap:.75rem}
+.field{display:flex;flex-direction:column;gap:.25rem;min-width:0}
+label{font-weight:600;font-size:.875rem}
+.custom{display:flex;flex-wrap:wrap;gap:.75rem}
+.custom[hidden]{display:none}
+.custom .error{flex-basis:100%;margin:0;font-weight:600;color:var(--cube-color-danger)}
+.custom .error:empty{flex-basis:0}
+input[aria-invalid=true]{border:2px solid var(--cube-color-danger)}
+@media (max-width:640px){.picker,.custom{flex-direction:column;align-items:stretch}}
+`;
+function field(doc, id, text, control) {
+    return h(doc, 'div', { class: 'field' }, h(doc, 'label', { for: id }, text), control);
+}
+/** `<cube-period-picker>`: chooses the period that period-aware blocks on the page follow. */
+export function periodPickerBlock(Base, scope) {
+    class CubePeriodPicker extends Base {
+        static tag = 'cube-period-picker';
+        static css = CSS;
+        static needsSession = false;
+        select;
+        label;
+        custom;
+        from;
+        to;
+        error;
+        /** The user's choice; until there is one the `default` attribute decides. */
+        chosen = null;
+        /** The last valid custom range, kept while an input is half-typed. */
+        range = null;
+        /** The value last made known, to dispatch cube-change only when it changes. */
+        announced = null;
+        constructor() {
+            super();
+            const doc = scope.document;
+            this.select = h(doc, 'select', { id: 'period', onchange: () => this.onSelect() }, ...KEYS.map((key) => h(doc, 'option', { value: key }, NL.period[key])));
+            this.label = h(doc, 'label', { for: 'period' });
+            const date = (id) => h(doc, 'input', { type: 'date', id, onchange: () => this.onDates() });
+            this.from = date('from');
+            this.to = date('to');
+            // A polite live region that stays in the page (empty while the range is valid), so a message is read.
+            this.error = h(doc, 'p', { id: 'range-error', class: 'error', 'aria-live': 'polite' });
+            this.custom = h(doc, 'div', { class: 'custom', hidden: true }, field(doc, 'from', NL.period.from, this.from), field(doc, 'to', NL.period.to, this.to), this.error);
+            const picker = h(doc, 'div', { class: 'field' }, this.label, this.select);
+            this.body.appendChild(h(doc, 'div', { class: 'picker' }, picker, this.custom));
+        }
+        /** The chosen period around `today`, with the one before it and that today. */
+        get value() {
+            const key = this.key();
+            const today = this.today();
+            const period = key === 'custom' && this.range !== null
+                ? resolvePeriod('custom', today, this.range)
+                // Custom without dates yet stands for the period it was switched from: 12 months.
+                : resolvePeriod(key === 'custom' ? DEFAULT : key, today);
+            return { ...period, today: isoDate(today) };
+        }
+        // Renders from its attributes and the user's choice: no loading state, which would drop the controls.
+        // A script that changes `default` or `today` changes the period as much as the user does.
+        refresh() {
+            this.render();
+            this.changed();
+            return Promise.resolve();
+        }
+        async load() {
+            this.render();
+        }
+        showState() {
+            this.render();
+        }
+        key() {
+            if (this.chosen !== null)
+                return this.chosen;
+            const wanted = this.attr('default');
+            return KEYS.includes(wanted) ? wanted : DEFAULT;
+        }
+        today() {
+            const raw = this.attr('today');
+            return (raw === null ? null : parseLocalDate(raw)) ?? new Date();
+        }
+        render() {
+            const key = this.key();
+            this.label.textContent = this.attr('label') ?? NL.period.label;
+            this.select.value = key;
+            this.custom.hidden = key !== 'custom';
+            if (key === 'custom' && this.range === null)
+                this.fillDates();
+        }
+        /** Switching to custom starts from the range that was shown, so the period does not jump. */
+        fillDates() {
+            const { from, to } = this.value;
+            this.range = { from, to };
+            this.from.value = from;
+            this.to.value = to;
+            this.explain(null);
+        }
+        onSelect() {
+            const key = this.select.value;
+            if (!KEYS.includes(key))
+                return;
+            if (key === 'custom' && this.key() !== 'custom') {
+                this.range = null;
+                this.fillDates();
+            }
+            this.chosen = key;
+            this.render();
+            this.changed();
+        }
+        /** A range that is not a period keeps the last valid one; the inputs say why, nothing is dispatched. */
+        onDates() {
+            const range = { from: this.from.value, to: this.to.value };
+            const from = parseLocalDate(range.from);
+            const to = parseLocalDate(range.to);
+            if (from === null || to === null) {
+                this.explain(NL.period.incompleteDate);
+                return;
+            }
+            if (to < from) {
+                this.explain(NL.period.invalidRange);
+                return;
+            }
+            this.explain(null);
+            this.range = range;
+            this.changed();
+        }
+        /** Dispatches cube-change when the value differs from the one last made known (not on the first render). */
+        changed() {
+            const value = this.value;
+            const seen = JSON.stringify(value);
+            const before = this.announced;
+            this.announced = seen;
+            if (before !== null && before !== seen)
+                this.emit('cube-change', value);
+        }
+        explain(message) {
+            this.error.textContent = message ?? '';
+            for (const input of [this.from, this.to]) {
+                if (message === null) {
+                    input.removeAttribute('aria-invalid');
+                    input.removeAttribute('aria-describedby');
+                }
+                else {
+                    input.setAttribute('aria-invalid', 'true');
+                    input.setAttribute('aria-describedby', this.error.id);
+                }
+            }
+        }
+    }
+    return CubePeriodPicker;
+}

package/dist/ui/blocks/state.d.ts

@@ -0,0 +1,4 @@
+import type { BlockClass } from '../block.js';
+import type { BlockScope } from '../define.js';
+/** `<cube-state>`: renders straight from its attributes, without a load step of its own. */
+export declare function stateBlock(Base: BlockClass, scope: BlockScope): BlockClass;

package/dist/ui/blocks/state.js

@@ -0,0 +1,135 @@
+import { clear, h } from '../dom.js';
+import { NL } from '../texts.js';
+const KINDS = ['loading', 'empty', 'error', 'forbidden', 'signed-out'];
+const TEXT = {
+    loading: NL.loading,
+    empty: NL.empty,
+    error: NL.error,
+    forbidden: NL.forbidden,
+    'signed-out': NL.signedOut,
+};
+const CSS = `
+.state{display:flex;flex-wrap:wrap;align-items:center;gap:.75rem;padding:1rem;border:1px solid var(--cube-color-border);
+border-radius:var(--cube-radius);background:var(--cube-color-surface)}
+.state[data-kind=error]{border-left:4px solid var(--cube-color-danger)}
+.state[data-kind=forbidden],.state[data-kind=signed-out]{border-left:4px solid var(--cube-color-warning)}
+.state p{margin:0;flex:1 1 12rem}
+.state[data-kind=loading] p,.state[data-kind=empty] p{color:var(--cube-color-text-muted)}
+`;
+/** Kinds that interrupt: of these, only the first one showing in a document is an alert. */
+const URGENT = ['error', 'forbidden', 'signed-out'];
+/** Per document, the cube-state that holds the one urgent alert. A dashboard of blocks must not raise N of them. */
+const alertHolder = new WeakMap();
+/** `<cube-state>`: renders straight from its attributes, without a load step of its own. */
+export function stateBlock(Base, scope) {
+    class CubeState extends Base {
+        static tag = 'cube-state';
+        static css = CSS;
+        static needsSession = false;
+        /** The sign-in click failed: show the generic error until the attributes change again. */
+        failed = false;
+        kind = 'loading';
+        /** The live region stays in place; its text is set after it is in the page, so it is announced. */
+        region;
+        message;
+        action = null;
+        announce = null;
+        constructor() {
+            super();
+            this.message = h(scope.document, 'p');
+            this.region = h(scope.document, 'div', { class: 'state' }, this.message);
+        }
+        disconnectedCallback() {
+            super.disconnectedCallback();
+            if (alertHolder.get(this.ownerDocument) === this)
+                alertHolder.delete(this.ownerDocument);
+            if (this.announce !== null)
+                scope.clearTimeout(this.announce);
+            this.announce = null;
+        }
+        // No loading flash and no wait for the page: the state is known from the attributes alone.
+        refresh() {
+            this.failed = false;
+            this.render();
+            return Promise.resolve();
+        }
+        async load() {
+            this.render();
+        }
+        // The base would put a cube-state inside this one.
+        showState() {
+            this.render();
+        }
+        render() {
+            const raw = this.attr('kind');
+            const kind = this.failed ? 'error' : KINDS.includes(raw) ? raw : 'loading';
+            const doc = this.ownerDocument;
+            this.kind = kind;
+            const alert = URGENT.includes(kind) && this.claimAlert();
+            this.action?.remove();
+            this.action = null;
+            if (kind === 'signed-out') {
+                this.action = h(doc, 'button', { type: 'button', onclick: () => void this.signIn() }, NL.signIn);
+            }
+            else if (kind === 'error' && (this.failed || this.attr('retry') !== 'false')) {
+                this.action = h(doc, 'button', { type: 'button', class: 'secondary', onclick: () => void this.emit('cube-retry') }, NL.retry);
+            }
+            this.region.setAttribute('data-kind', kind);
+            // Loading is not announced: N blocks would each say it once per period change. The host is aria-busy.
+            if (kind === 'loading')
+                this.region.removeAttribute('role');
+            else
+                this.region.setAttribute('role', alert ? 'alert' : 'status');
+            if (alert)
+                this.region.removeAttribute('aria-live');
+            else
+                this.region.setAttribute('aria-live', kind === 'loading' ? 'off' : 'polite');
+            if (this.action !== null)
+                this.region.appendChild(this.action);
+            if (this.region.parentNode !== this.body) {
+                clear(this.body);
+                this.body.appendChild(this.region);
+            }
+            const text = this.failed ? NL.error : (this.attr('message') ?? TEXT[kind]);
+            if (this.announce !== null)
+                scope.clearTimeout(this.announce);
+            this.announce = null;
+            if (this.message.textContent === text)
+                return;
+            if (kind === 'loading') {
+                this.message.textContent = text;
+                return;
+            }
+            this.message.textContent = '';
+            this.announce = scope.setTimeout(() => {
+                this.announce = null;
+                this.message.textContent = text;
+            }, 0);
+        }
+        /** True when no other connected cube-state in this document shows an urgent kind first. */
+        claimAlert() {
+            const doc = this.ownerDocument;
+            const holder = alertHolder.get(doc);
+            if (holder !== undefined && holder !== this && holder.isConnected && URGENT.includes(holder.kind)) {
+                return false;
+            }
+            alertHolder.set(doc, this);
+            return true;
+        }
+        async signIn() {
+            try {
+                const session = await this.session();
+                await session.signIn();
+            }
+            catch {
+                this.failed = true;
+                this.render();
+                return;
+            }
+            // Live, the page has navigated away by now; in the preview every block loads again as the user.
+            const View = this.ownerDocument.defaultView?.CustomEvent ?? CustomEvent;
+            this.ownerDocument.dispatchEvent(new View('cube-session-change'));
+        }
+    }
+    return CubeState;
+}

package/dist/ui/blocks/table.d.ts

@@ -0,0 +1,8 @@
+import { type BlockClass } from '../block.js';
+import type { BlockScope } from '../define.js';
+/**
+ * `<cube-table>`: the rows of a resource, a page at a time, with search, filters, sortable headers and a CSV export.
+ * The controls are built once per load; what they change only asks for rows again, and only the newest answer is
+ * shown.
+ */
+export declare function tableBlock(Base: BlockClass, scope: BlockScope): BlockClass;