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

package/dist/ui/blocks/board.js

@@ -0,0 +1,292 @@
+import { isDmpError } from '../../errors.js';
+import { CARD_CSS, requiredAttr, wholeAttr } from '../aggregate-block.js';
+import { BlockStateError, stateFor } from '../block.js';
+import { clear, h } from '../dom.js';
+import { columnsFor, fieldList, readFieldConfigs } from '../fields.js';
+import { formatValue, humanize } from '../format.js';
+import { blockFilter } from '../query.js';
+import { NL } from '../texts.js';
+import { attemptFor, userOf, WRITE_CSS } from '../write.js';
+const CSS = `${CARD_CSS}${WRITE_CSS}
+.board{display:grid;grid-auto-flow:column;grid-auto-columns:minmax(14rem,1fr);gap:1rem;
+position:relative;overflow-x:auto}
+@media (max-width:640px){.board{grid-auto-flow:row;grid-auto-columns:auto}}
+section{min-width:0}
+h3{margin:0 0 .5rem;font-size:1rem}
+article{margin-top:.5rem;padding:.75rem;border:1px solid var(--cube-color-border);
+border-radius:var(--cube-radius-small);background:var(--cube-color-bg);overflow-wrap:anywhere}
+article[draggable=true]{cursor:grab}
+.title{margin:0;font-weight:600}
+dl{display:grid;grid-template-columns:auto 1fr;gap:0 .5rem;margin:.25rem 0 0;font-size:.875rem}
+dd{margin:0;min-width:0}
+.moves{display:flex;flex-wrap:wrap;gap:.25rem;margin-top:.5rem}
+.moves button{min-height:2rem;padding:.25rem .5rem;font-size:.875rem}
+.moves button::before{content:"\\2192  "}
+.muted{margin:.5rem 0 0}
+.not-saved{display:inline-block;margin-bottom:.75rem}
+`;
+const keyOf = (row) => String(row.id);
+/** Why a move was refused, in words for the person; never the server's or the browser's own text. */
+function reason(error) {
+    if (isDmpError(error) && (error.status === 409 || error.status === 412))
+        return NL.changedMeanwhile;
+    const kind = stateFor(error).kind;
+    return kind === 'forbidden' ? NL.forbidden : kind === 'signed-out' ? NL.signedOut : NL.tryAgain;
+}
+/**
+ * `<cube-board>`: the rows of a resource as cards in a column per value of a status field. A card moves by drag
+ * and drop or by a button per other column ("Verplaats naar …"): at once on screen, then saved; a refusal puts it
+ * back.
+ */
+export function boardBlock(Base, scope) {
+    const doc = scope.document;
+    class CubeBoard extends Base {
+        static tag = 'cube-board';
+        static css = CSS;
+        /** Outside the body, so the reload after a refusal keeps the reason on screen. */
+        alert = h(doc, 'div', { class: 'alert', role: 'alert', hidden: true });
+        loaded = null;
+        tracks = new Map();
+        /** Moves queued or on their way: a reload waits for them, or it would show a card where it no longer is. */
+        pending = 0;
+        stale = false;
+        /** Set while its own cube-data-change is under way: the board already shows what it saved. */
+        own = false;
+        dragged = null;
+        /** The card to focus once the board is drawn again. */
+        focusKey = null;
+        attempt = null;
+        ids = 0;
+        constructor() {
+            super();
+            this.shadowRoot?.insertBefore(this.alert, this.body);
+        }
+        shownFields() {
+            const loaded = this.loaded;
+            return loaded === null ? [] : [loaded.status, loaded.title, ...loaded.fields.map((field) => field.name)];
+        }
+        refresh() {
+            if (this.own)
+                return Promise.resolve();
+            if (this.pending > 0) {
+                this.stale = true;
+                return Promise.resolve();
+            }
+            this.stale = false;
+            const focused = this.shadowRoot?.activeElement?.closest('article')?.getAttribute('data-id');
+            if (focused !== undefined && focused !== null)
+                this.focusKey = focused;
+            return super.refresh();
+        }
+        async load(signal, session) {
+            if (session === null)
+                return;
+            this.loaded = null;
+            const resource = requiredAttr(this, 'resource');
+            const status = requiredAttr(this, 'status-field');
+            const title = requiredAttr(this, 'title-field');
+            const filter = blockFilter(this);
+            const size = Math.min(wholeAttr(this, 'page-size', 1, 50), 200);
+            const sort = this.attr('sort')?.trim() ?? '';
+            const schema = await session.schema(resource);
+            if (signal.aborted)
+                return;
+            const field = schema?.fields.find((candidate) => candidate.name === status);
+            const names = fieldList(this.attr('fields'));
+            const fields = names === null ? [] : columnsFor(schema, names, readFieldConfigs(this));
+            const query = {
+                fields: [...new Set(['id', title, status, ...fields.map((column) => column.name)])],
+                page: { size },
+            };
+            if (sort !== '')
+                query.sort = sort;
+            const client = session.resource(resource);
+            const answers = await Promise.all(this.columnValues(field?.enum ?? null).map(async (column) => {
+                const { data, meta } = await client.list({ ...query, filter: { ...filter, [status]: column.value } }, {
+                    signal,
+                });
+                return { ...column, rows: [...data], total: meta.page?.total ?? data.length };
+            }));
+            if (signal.aborted)
+                return;
+            const loaded = {
+                session,
+                user: userOf(session),
+                resource,
+                status,
+                title,
+                fields,
+                columns: answers,
+                canMove: schema !== null && schema.actions.includes('update') && field?.readonly === false,
+            };
+            this.loaded = loaded;
+            this.tracks.clear();
+            this.render(loaded);
+        }
+        /** The `cube-column` children, else the status field's enum; without either the page must say. */
+        columnValues(values) {
+            const children = Array.from(this.children).filter((child) => child.localName === 'cube-column');
+            const columns = children.length > 0
+                ? children.map((child) => {
+                    const value = requiredAttr(child, 'value');
+                    return { value, label: child.getAttribute('label')?.trim() || humanize(value) };
+                })
+                : (values ?? []).map((value) => ({ value, label: humanize(value) }));
+            if (columns.length === 0)
+                throw new BlockStateError({ kind: 'error', detail: NL.noColumns, retry: false });
+            return columns;
+        }
+        render(loaded) {
+            const cards = new Map();
+            clear(this.body);
+            this.body.append(...[loaded.canMove && this.notSaved(loaded.session), h(doc, 'div', { class: 'board' }, ...loaded.columns.map((column) => this.column(loaded, column, cards)))].filter((node) => !!node));
+            const focus = this.focusKey;
+            this.focusKey = null;
+            if (focus !== null)
+                cards.get(focus)?.focus();
+        }
+        column(loaded, column, cards) {
+            const heading = `b${++this.ids}`;
+            const more = column.total - column.rows.length;
+            return h(doc, 'section', {
+                class: 'card',
+                'aria-labelledby': heading,
+                ondragover: (event) => {
+                    if (loaded.canMove && this.dragged !== null)
+                        event.preventDefault();
+                },
+                ondrop: (event) => {
+                    event.preventDefault();
+                    const key = this.dragged;
+                    this.dragged = null;
+                    if (key !== null)
+                        this.move(loaded, key, column.value);
+                },
+            }, h(doc, 'h3', { id: heading }, column.label, ' ', h(doc, 'span', { class: 'badge' }, `${column.total}`)), ...(column.rows.length === 0
+                ? [h(doc, 'p', { class: 'muted' }, NL.emptyColumn)]
+                : column.rows.map((row) => this.card(loaded, column, row, cards))), more > 0 ? h(doc, 'p', { class: 'muted' }, NL.more(more)) : null);
+        }
+        card(loaded, column, row, cards) {
+            const key = keyOf(row);
+            const title = `b${++this.ids}`;
+            const card = h(doc, 'article', {
+                tabindex: '0',
+                draggable: loaded.canMove ? 'true' : 'false',
+                'data-id': key,
+                'aria-labelledby': title,
+                ondragstart: (event) => {
+                    this.dragged = key;
+                    event.dataTransfer?.setData('text/plain', key);
+                },
+                ondragend: () => {
+                    this.dragged = null;
+                },
+            }, h(doc, 'p', { class: 'title', id: title }, formatValue(row[loaded.title], 'text')), loaded.fields.length === 0
+                ? null
+                : h(doc, 'dl', {}, ...loaded.fields.flatMap((field) => [
+                    h(doc, 'dt', {}, field.label),
+                    h(doc, 'dd', {}, formatValue(row[field.name], field.format)),
+                ])), loaded.canMove
+                ? h(doc, 'div', { class: 'moves' }, ...loaded.columns
+                    .filter((other) => other !== column)
+                    .map((other) => h(doc, 'button', {
+                    type: 'button',
+                    class: 'secondary',
+                    'aria-label': NL.moveTo(other.label),
+                    'aria-describedby': title,
+                    onclick: () => this.move(loaded, key, other.value),
+                }, other.label)))
+                : null);
+            cards.set(key, card);
+            return card;
+        }
+        /** Takes the card out of its column and puts it on top of `to`; null when it is not on the board. */
+        place(loaded, key, to) {
+            const target = loaded.columns.find((column) => column.value === to);
+            for (const column of loaded.columns) {
+                const index = column.rows.findIndex((row) => keyOf(row) === key);
+                const row = column.rows[index];
+                if (row === undefined || target === undefined)
+                    continue;
+                column.rows.splice(index, 1);
+                column.total--;
+                target.rows.unshift(row);
+                target.total++;
+                return { row, from: column.value };
+            }
+            return null;
+        }
+        move(loaded, key, to) {
+            const current = loaded.columns.find((column) => column.rows.some((row) => keyOf(row) === key));
+            if (!loaded.canMove || this.loaded !== loaded || current === undefined || current.value === to)
+                return;
+            const placed = this.place(loaded, key, to);
+            if (placed === null)
+                return;
+            const { row, from } = placed;
+            this.alert.hidden = true;
+            this.focusKey = key;
+            this.render(loaded);
+            let track = this.tracks.get(key);
+            if (track === undefined) {
+                track = { confirmed: from, tail: Promise.resolve(), generation: 0 };
+                this.tracks.set(key, track);
+            }
+            const queued = track;
+            const generation = queued.generation;
+            this.pending++;
+            queued.tail = queued.tail
+                .then(() => (generation === queued.generation ? this.send(loaded, queued, row, from, to) : undefined))
+                .finally(() => {
+                if (--this.pending === 0 && this.stale)
+                    void this.refresh();
+            });
+        }
+        async send(loaded, track, row, from, to) {
+            const key = keyOf(row);
+            const body = { [loaded.status]: to };
+            const attempt = attemptFor(this.attempt, JSON.stringify([loaded.resource, key, body]));
+            this.attempt = attempt;
+            try {
+                // The session as it is now: one that changed meanwhile must not send what the old one queued.
+                const session = await this.session();
+                if (userOf(session) !== loaded.user) {
+                    track.generation++;
+                    this.stale = true;
+                    return;
+                }
+                await session.resource(loaded.resource).update(row.id, body, {
+                    idempotencyKey: attempt.key,
+                });
+                if (this.attempt === attempt)
+                    this.attempt = null;
+                track.confirmed = to;
+                this.emit('cube-move', { resource: loaded.resource, id: row.id, from, to });
+                this.own = true;
+                this.emit('cube-data-change', { resource: loaded.resource });
+                // After the reload the event scheduled, which is a microtask queued before this one.
+                queueMicrotask(() => {
+                    this.own = false;
+                });
+            }
+            catch (error) {
+                // The DMP answered, so the attempt is over; without an answer the same move may go again with its key.
+                if (isDmpError(error) && this.attempt === attempt)
+                    this.attempt = null;
+                // The moves queued after this one counted on it.
+                track.generation++;
+                if (isDmpError(error) && (error.status === 409 || error.status === 412))
+                    this.stale = true;
+                if (this.loaded !== loaded)
+                    return;
+                this.place(loaded, key, track.confirmed);
+                this.focusKey = key;
+                this.render(loaded);
+                clear(this.alert);
+                this.alert.append(`${NL.moveFailed} ${reason(error)}`);
+                this.alert.hidden = false;
+            }
+        }
+    }
+    return CubeBoard;
+}

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

@@ -0,0 +1,9 @@
+import { type BlockClass } from '../block.js';
+import type { BlockScope } from '../define.js';
+export type CalcValues = Record<string, number | string | boolean | null>;
+export type CalcFormula = (values: CalcValues) => Record<string, unknown> | number | string | null;
+/**
+ * `<cube-calc>`: a calculator. Its `cube-input`s are editors, its `cube-result`s outputs, and `formula` (a function
+ * the app sets; never a string, which would need eval) turns the one into the other on every keystroke.
+ */
+export declare function calcBlock(Base: BlockClass, scope: BlockScope): BlockClass;

package/dist/ui/blocks/calc.js

@@ -0,0 +1,240 @@
+import { CARD_CSS, LABEL_CSS, requiredAttr } from '../aggregate-block.js';
+import { BlockStateError } from '../block.js';
+import { clear, h } from '../dom.js';
+import { parseOptions } from '../fields.js';
+import { formatValue } from '../format.js';
+import { EDITOR_CSS, editorFor, parseInput } from '../inputs.js';
+import { NL } from '../texts.js';
+const CSS = `${CARD_CSS}${LABEL_CSS}${EDITOR_CSS}
+.inputs{display:grid;gap:1rem;grid-template-columns:repeat(auto-fit,minmax(12rem,1fr))}
+.inputs:empty{display:none}
+.results{display:flex;flex-wrap:wrap;gap:1rem 2rem;margin-top:1.25rem;padding-top:1rem;
+border-top:1px solid var(--cube-color-border)}
+.inputs:empty+.results{margin-top:0;padding-top:0;border-top:0}
+.result{display:flex;flex-direction:column;min-width:0}
+.result label{font-size:.875rem;font-weight:600;color:var(--cube-color-text-muted)}
+.result output{font-size:1.25rem;font-weight:600;font-variant-numeric:tabular-nums;overflow-wrap:anywhere}
+.result.emphasis output{font-size:2rem;font-weight:700;line-height:1.2}
+.alert{margin:1rem 0 0;color:var(--cube-color-danger,#b42318)}
+`;
+const INPUT_TYPES = ['number', 'integer', 'currency', 'percent', 'text', 'select', 'checkbox'];
+const RESULT_FORMATS = ['number', 'integer', 'currency', 'percent', 'text'];
+let nextId = 0;
+/** An enum attribute: its default when absent or blank, a TypeError naming the value when it is none of them. */
+function choice(el, name, values) {
+    const raw = el.getAttribute(name)?.trim() ?? '';
+    const value = raw === '' ? values[0] : raw;
+    if (!values.includes(value))
+        throw new TypeError(NL.invalid.value(el.localName, name, value));
+    return value;
+}
+function numberAttr(el, name) {
+    const raw = el.getAttribute(name)?.trim() ?? '';
+    if (raw === '')
+        return null;
+    const value = Number(raw);
+    if (!Number.isFinite(value) || (name === 'step' && value <= 0)) {
+        throw new TypeError(NL.invalid.number(el.localName, name));
+    }
+    return value;
+}
+const plain = (n) => formatValue(n, 'number');
+/** What the formula gets for one input: null for nothing, for what is no number, and outside min, max or step. */
+function readInput(input) {
+    const read = input.editor.read();
+    if ('error' in read || typeof read.value !== 'number')
+        return read;
+    // Bounds are in what the person types: a percentage's 21, not the 0.21 the formula gets.
+    const typed = input.format === 'percent' ? Number((read.value * 100).toPrecision(12)) : read.value;
+    const { min, max, step } = input;
+    if ((min !== null && typed < min) || (max !== null && typed > max)) {
+        return {
+            error: min === null ? NL.atMost(plain(max))
+                : max === null ? NL.atLeast(plain(min)) : NL.range(plain(min), plain(max)),
+        };
+    }
+    if (step !== null) {
+        const steps = (typed - (min ?? 0)) / step;
+        if (Math.abs(steps - Math.round(steps)) > 1e-9)
+            return { error: NL.step(plain(step)) };
+    }
+    return read;
+}
+/**
+ * `<cube-calc>`: a calculator. Its `cube-input`s are editors, its `cube-result`s outputs, and `formula` (a function
+ * the app sets; never a string, which would need eval) turns the one into the other on every keystroke.
+ */
+export function calcBlock(Base, scope) {
+    const doc = scope.document;
+    class CubeCalc extends Base {
+        static tag = 'cube-calc';
+        static css = CSS;
+        static needsSession = false;
+        fn = null;
+        drawn = null;
+        shownValues = {};
+        shownResults = {};
+        constructor() {
+            super();
+            // A page script that ran before the tag was defined set a plain property; take it over.
+            const early = Object.getOwnPropertyDescriptor(this, 'formula');
+            if (early !== undefined) {
+                delete this.formula;
+                this.fn = early.value;
+            }
+        }
+        get formula() {
+            return typeof this.fn === 'function' ? this.fn : null;
+        }
+        set formula(value) {
+            this.fn = value;
+            if (this.drawn !== null && (value === null || typeof value === 'function')) {
+                this.calculate(true);
+            }
+            else {
+                this.drawn = null;
+                void this.refresh();
+            }
+        }
+        get values() {
+            return { ...this.shownValues };
+        }
+        get results() {
+            return { ...this.shownResults };
+        }
+        refresh() {
+            // A session change or a reconnect must not wipe what was typed; only a new label redraws.
+            if (this.drawn !== null && this.drawn.label === this.attr('label'))
+                return Promise.resolve();
+            this.drawn = null;
+            return super.refresh();
+        }
+        async load() {
+            this.drawn = null;
+            if (this.fn !== null && typeof this.fn !== 'function') {
+                // Only a new formula helps, so no retry.
+                throw new BlockStateError({ kind: 'error', detail: NL.invalid.formula, retry: false });
+            }
+            const children = Array.from(this.children);
+            const inputs = children.filter((el) => el.localName === 'cube-input').map(inputFor);
+            const results = children.filter((el) => el.localName === 'cube-result').map(resultFor);
+            if (results.length === 0)
+                throw new TypeError(NL.invalid.missing(this.localName, 'cube-result'));
+            const label = this.attr('label');
+            const heading = label === null || label.trim() === ''
+                ? null
+                : h(doc, 'p', { class: 'label', id: `cube-calc-${++nextId}` }, label);
+            const alert = h(doc, 'p', { class: 'alert', role: 'alert', hidden: true });
+            const form = h(doc, 'form', { novalidate: true, 'aria-labelledby': heading?.id ?? null }, h(doc, 'div', { class: 'inputs' }, ...inputs.map((input) => input.editor.element)), h(doc, 'div', { class: 'results', 'aria-live': 'polite' }, ...results.map((r) => r.element)), alert);
+            form.addEventListener('submit', (event) => event.preventDefault());
+            form.addEventListener('input', () => this.calculate(true));
+            form.addEventListener('change', () => this.showErrors());
+            clear(this.body);
+            this.body.appendChild(h(doc, 'div', { class: 'card' }, heading, form));
+            this.drawn = { label, inputs, results, alert };
+            this.showErrors();
+            this.calculate(false);
+        }
+        /** Shows the message of every input that has one: what the page set at once, what was typed on change. */
+        showErrors() {
+            for (const input of this.drawn?.inputs ?? []) {
+                const read = readInput(input);
+                input.shown = 'error' in read;
+                input.editor.setError('error' in read ? read.error : null);
+            }
+        }
+        calculate(announce) {
+            const drawn = this.drawn;
+            if (drawn === null)
+                return;
+            const values = {};
+            for (const input of drawn.inputs) {
+                const read = readInput(input);
+                values[input.editor.name] = 'error' in read ? null : read.value;
+                // While typing a message may change or go, but not appear: half a number is no mistake yet.
+                if (!input.shown)
+                    continue;
+                input.shown = 'error' in read;
+                input.editor.setError('error' in read ? read.error : null);
+            }
+            const results = {};
+            let failed = false;
+            try {
+                const fn = this.formula;
+                const out = fn === null ? null : fn({ ...values });
+                const single = out === null || typeof out !== 'object';
+                if (single && out !== null && out !== undefined && drawn.results.length > 1) {
+                    this.drawn = null;
+                    this.showState({ kind: 'error', detail: NL.invalid.calcSingle, retry: false });
+                    return;
+                }
+                for (const result of drawn.results) {
+                    const value = single ? out : out[result.name];
+                    const broken = typeof value === 'number' && !Number.isFinite(value);
+                    failed ||= broken;
+                    results[result.name] = broken || value === undefined ? null : value;
+                }
+            }
+            catch {
+                failed = true;
+                for (const result of drawn.results)
+                    results[result.name] = null;
+            }
+            for (const result of drawn.results) {
+                result.output.textContent = formatValue(results[result.name], result.format, {
+                    currency: result.currency,
+                });
+            }
+            // Set once per failure: a new text on every keystroke would make the reader say it again and again.
+            if (failed && drawn.alert.hidden)
+                drawn.alert.textContent = NL.calcFailed;
+            if (!failed)
+                drawn.alert.textContent = '';
+            drawn.alert.hidden = !failed;
+            this.shownValues = values;
+            this.shownResults = results;
+            if (announce)
+                this.emit('cube-change', { values: { ...values }, results: { ...results } });
+        }
+    }
+    function inputFor(el) {
+        const name = requiredAttr(el, 'name');
+        const label = requiredAttr(el, 'label');
+        const type = choice(el, 'type', INPUT_TYPES);
+        const format = (type === 'select' ? 'text' : type === 'checkbox' ? 'boolean' : type);
+        const options = type === 'checkbox' ? null : parseOptions(el.getAttribute('options'));
+        if (type === 'select' && options === null)
+            throw new TypeError(NL.invalid.missing(el.localName, 'options'));
+        // `value` is written as a person would type it: a percentage as 21.
+        const raw = el.getAttribute('value');
+        const parsed = raw === null ? { value: null } : parseInput(raw, format);
+        const config = { name, label, format, multiline: false, options, hidden: false };
+        const column = { name, label, format, field: undefined, config };
+        return {
+            editor: editorFor(doc, column, 'error' in parsed ? raw : parsed.value, false),
+            format,
+            min: numberAttr(el, 'min'),
+            max: numberAttr(el, 'max'),
+            step: numberAttr(el, 'step'),
+            shown: false,
+        };
+    }
+    function resultFor(el) {
+        const name = requiredAttr(el, 'name');
+        const label = requiredAttr(el, 'label');
+        const format = choice(el, 'format', RESULT_FORMATS);
+        const currency = el.getAttribute('currency')?.trim().toUpperCase() || 'EUR';
+        try {
+            formatValue(0, 'currency', { currency });
+        }
+        catch {
+            throw new TypeError(NL.invalid.value(el.localName, 'currency', currency));
+        }
+        const id = `cube-result-${++nextId}`;
+        const output = h(doc, 'output', { id, name });
+        const emphasis = el.hasAttribute('emphasis') && el.getAttribute('emphasis') !== 'false';
+        const element = h(doc, 'div', { class: emphasis ? 'result emphasis' : 'result' }, h(doc, 'label', { for: id }, label), output);
+        return { name, format, currency, element, output };
+    }
+    return CubeCalc;
+}

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

@@ -0,0 +1,7 @@
+import type { BlockClass } from '../block.js';
+import type { BlockScope } from '../define.js';
+import { type Truncation } from '../format.js';
+/** Every bucket key from `from` to `to` (ISO dates, inclusive), in order. */
+export declare function periodBuckets(from: string, to: string, unit: Truncation): string[];
+/** `<cube-chart>`: one measure over time (a line) or per category (bars), with a table for screen readers. */
+export declare function chartBlock(Base: BlockClass, scope: BlockScope): BlockClass;