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

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;

package/dist/ui/block.js

@@ -0,0 +1,229 @@
+import { CubeApp } from '../app.js';
+import { isDmpError } from '../errors.js';
+import { BLOCK_ATTRIBUTES } from './attributes.js';
+import { clear, h } from './dom.js';
+import { BASE_CSS, sheet } from './styles.js';
+import { NL } from './texts.js';
+/** Thrown by a block's load to show exactly this state. */
+export class BlockStateError extends Error {
+    state;
+    constructor(state) {
+        super(state.detail ?? state.kind);
+        this.state = state;
+    }
+}
+/**
+ * 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 function stateFor(error) {
+    if (error instanceof BlockStateError)
+        return error.state;
+    if (isDmpError(error)) {
+        if (error.status === 401)
+            return { kind: 'signed-out', detail: null };
+        if (error.status === 403)
+            return { kind: 'forbidden', detail: null };
+    }
+    if (error instanceof TypeError)
+        return { kind: 'error', detail: error.message };
+    return { kind: 'error', detail: null };
+}
+/**
+ * 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 function pageReady(doc) {
+    return new Promise((resolve) => {
+        if (doc.readyState === 'loading') {
+            doc.addEventListener('DOMContentLoaded', () => resolve(), { once: true });
+        }
+        else {
+            (doc.defaultView?.setTimeout ?? setTimeout)(resolve, 0);
+        }
+    });
+}
+/** The header mark of an invented field: `Voorbeeld` on screen, the whole of exampleMissing read out. */
+export function exampleBadge(doc) {
+    return h(doc, 'span', { class: 'badge example' }, NL.example, h(doc, 'span', { class: 'sr-only' }, NL.exampleMissing.slice(NL.example.length)));
+}
+function isAbort(error) {
+    return error !== null && typeof error === 'object' && error.name === 'AbortError';
+}
+export function blockBase(scope, options = {}) {
+    const getSession = options.session ?? (() => CubeApp.ready());
+    class CubeBlock extends scope.HTMLElement {
+        static tag = '';
+        static css = '';
+        static needsSession = true;
+        static get observedAttributes() {
+            return [...(BLOCK_ATTRIBUTES[this.tag] ?? [])];
+        }
+        body;
+        current = Promise.resolve();
+        scheduled = false;
+        controller = null;
+        /** Outside the body, so a block that redraws its body (a board move, an edit) keeps it. */
+        badge = null;
+        onSessionChange = () => this.schedule();
+        onDataChange = (event) => {
+            const resource = event.detail?.resource;
+            const own = this.getAttribute('resource')?.trim() ?? '';
+            if (typeof resource === 'string' && own !== '' && resource.trim() === own)
+                this.schedule();
+        };
+        constructor() {
+            super();
+            const ctor = this.constructor;
+            const root = this.attachShadow({ mode: 'open' });
+            root.adoptedStyleSheets = ctor.css === ''
+                ? [sheet(scope, BASE_CSS)]
+                : [sheet(scope, BASE_CSS), sheet(scope, ctor.css)];
+            this.body = h(scope.document, 'div', { class: 'cube-body', part: 'body' });
+            root.appendChild(this.body);
+            // Bubbles up from the cube-state in this block's own shadow tree; an outer block must not reload too.
+            root.addEventListener('cube-retry', (event) => {
+                event.stopPropagation();
+                this.schedule();
+            });
+        }
+        get updateComplete() {
+            return (async () => {
+                let seen;
+                do {
+                    seen = this.current;
+                    await seen;
+                } while (seen !== this.current);
+            })();
+        }
+        connectedCallback() {
+            this.ownerDocument.addEventListener('cube-session-change', this.onSessionChange);
+            this.ownerDocument.addEventListener('cube-data-change', this.onDataChange);
+            this.schedule();
+        }
+        disconnectedCallback() {
+            this.ownerDocument.removeEventListener('cube-session-change', this.onSessionChange);
+            this.ownerDocument.removeEventListener('cube-data-change', this.onDataChange);
+            this.controller?.abort();
+            this.controller = null;
+            this.removeAttribute('aria-busy');
+        }
+        attributeChangedCallback(_name, oldValue, newValue) {
+            if (oldValue !== newValue)
+                this.schedule();
+        }
+        refresh() {
+            if (!this.isConnected)
+                return this.current;
+            this.controller?.abort();
+            const controller = new AbortController();
+            this.controller = controller;
+            const run = this.run(controller.signal);
+            this.current = run;
+            return run;
+        }
+        /** Several changes in one tick (attributes set one by one, say) make one load. */
+        schedule() {
+            if (this.scheduled || !this.isConnected)
+                return;
+            this.scheduled = true;
+            this.current = new Promise((resolve) => {
+                queueMicrotask(() => {
+                    this.scheduled = false;
+                    resolve(this.isConnected ? this.refresh() : undefined);
+                });
+            });
+        }
+        async run(signal) {
+            const ctor = this.constructor;
+            this.showState('loading');
+            try {
+                await pageReady(this.ownerDocument);
+                if (signal.aborted)
+                    return;
+                const session = ctor.needsSession ? await this.session() : null;
+                if (signal.aborted)
+                    return;
+                await this.load(signal, session);
+                if (!signal.aborted)
+                    this.mark(session);
+            }
+            catch (error) {
+                if (signal.aborted || isAbort(error))
+                    return;
+                this.badge?.remove();
+                this.showState(stateFor(error));
+            }
+            finally {
+                // An aborted run leaves the flag to the newer run (or to disconnect).
+                if (!signal.aborted)
+                    this.removeAttribute('aria-busy');
+            }
+        }
+        session() {
+            return getSession();
+        }
+        shownFields() {
+            return [];
+        }
+        // Optional calls: a session made by hand (a test, an older embedder) may not know about wireframes.
+        exampleField(session, resource, field) {
+            return session.isExample?.(resource, field) === true && !session.isExample(resource);
+        }
+        notSaved(session) {
+            return session.simulatesWrites === true
+                ? h(this.ownerDocument, 'p', { class: 'note not-saved' }, NL.exampleNotSaved)
+                : null;
+        }
+        mark(session) {
+            const resource = this.getAttribute('resource')?.trim() ?? '';
+            const marked = session?.isExample !== undefined && resource !== ''
+                && (session.isExample(resource) || this.shownFields().some((f) => session.isExample(resource, f)));
+            if (!marked) {
+                this.badge?.remove();
+                return;
+            }
+            this.badge ??= h(this.ownerDocument, 'p', { class: 'badge example', role: 'note' }, NL.exampleMissing);
+            this.shadowRoot?.insertBefore(this.badge, this.body);
+        }
+        showState(state, detail = null) {
+            const { kind, detail: message, retry } = typeof state === 'string' ? { kind: state, detail } : state;
+            // Busy until the run ends; a block that draws its own loading (the shell's frame) is never busy.
+            if (kind === 'loading')
+                this.setAttribute('aria-busy', 'true');
+            clear(this.body);
+            this.body.appendChild(h(this.ownerDocument, 'cube-state', { kind, message, retry: retry === false ? 'false' : null }));
+        }
+        attr(name) {
+            return this.getAttribute(name);
+        }
+        flag(name) {
+            return this.hasAttribute(name) && this.getAttribute(name) !== 'false';
+        }
+        num(name, fallback) {
+            const raw = this.getAttribute(name);
+            if (raw === null || raw.trim() === '')
+                return fallback;
+            const value = Number(raw);
+            if (!Number.isFinite(value))
+                throw new TypeError(NL.invalid.number(this.localName, name));
+            return value;
+        }
+        json(name) {
+            const raw = this.getAttribute(name);
+            if (raw === null || raw.trim() === '')
+                return null;
+            try {
+                return JSON.parse(raw);
+            }
+            catch {
+                throw new TypeError(NL.invalid.json(this.localName, name));
+            }
+        }
+        emit(name, detail = null) {
+            const View = this.ownerDocument.defaultView?.CustomEvent ?? CustomEvent;
+            return this.dispatchEvent(new View(name, { detail, bubbles: true, composed: true }));
+        }
+    }
+    return CubeBlock;
+}

package/dist/ui/blocks/app-shell.d.ts

@@ -0,0 +1,4 @@
+import type { BlockClass } from '../block.js';
+import type { BlockScope } from '../define.js';
+/** `<cube-app-shell>`: header, page navigation and the content slot. The content shows whatever the session does. */
+export declare function appShellBlock(Base: BlockClass, scope: BlockScope): BlockClass;

package/dist/ui/blocks/app-shell.js

@@ -0,0 +1,167 @@
+import { clear, h } from '../dom.js';
+import { NL } from '../texts.js';
+import { currentTheme, onTheme } from '../theme.js';
+const CSS = `
+:host{background:var(--cube-color-bg)}
+header{display:flex;flex-wrap:wrap;align-items:center;gap:.75rem 1rem;padding:.75rem 1.5rem;
+border-bottom:1px solid var(--cube-color-border);background:var(--cube-color-surface)}
+.logo{display:block;height:2rem;width:auto;max-width:10rem;object-fit:contain}
+h1{flex:1 1 auto;min-width:0;margin:0;font-size:1.25rem;line-height:1.3;overflow-wrap:anywhere}
+.user{display:flex;flex-wrap:wrap;align-items:center;gap:.75rem;margin-left:auto}
+nav{border-bottom:1px solid var(--cube-color-border);padding:0 1.5rem}
+nav ul{display:flex;gap:.25rem;margin:0;padding:0;list-style:none;position:relative;overflow-x:auto}
+nav a{display:block;padding:.75rem 1rem;white-space:nowrap;text-decoration:none;color:var(--cube-color-text-muted);
+border-bottom:3px solid transparent}
+nav a:hover{color:var(--cube-color-primary-text)}
+nav a[aria-current=page]{font-weight:600;color:var(--cube-color-primary-text);
+border-bottom-color:var(--cube-color-primary)}
+main{padding:1.5rem}
+::slotted(cube-page:not([hidden])){display:flex;flex-direction:column;gap:1.5rem}
+@media (max-width:640px){header{padding:.75rem 1rem}nav{padding:0}main{padding:1rem}}
+`;
+const PREFIX = '#/';
+/** `<cube-app-shell>`: header, page navigation and the content slot. The content shows whatever the session does. */
+export function appShellBlock(Base, scope) {
+    class CubeAppShell extends Base {
+        static tag = 'cube-app-shell';
+        static css = CSS;
+        header;
+        heading;
+        user;
+        nav;
+        list;
+        main;
+        /** The page names and labels the navigation was built from, to rebuild it only when they change. */
+        built = '';
+        stopTheme = null;
+        onHash = () => this.updatePages();
+        constructor() {
+            super();
+            const doc = scope.document;
+            this.heading = h(doc, 'h1');
+            this.user = h(doc, 'div', { class: 'user' });
+            this.header = h(doc, 'header', {}, this.heading, this.user);
+            this.list = h(doc, 'ul');
+            this.nav = h(doc, 'nav', { 'aria-label': NL.pages }, this.list);
+            const slot = h(doc, 'slot', { onslotchange: () => this.updatePages() });
+            this.main = h(doc, 'main', {}, slot);
+            this.body.append(this.header, this.main);
+            this.renderHeader();
+        }
+        connectedCallback() {
+            super.connectedCallback();
+            this.ownerDocument.defaultView?.addEventListener('hashchange', this.onHash);
+            this.stopTheme?.();
+            this.stopTheme = onTheme(() => this.renderHeader());
+            this.renderHeader();
+            this.updatePages();
+        }
+        disconnectedCallback() {
+            super.disconnectedCallback();
+            this.ownerDocument.defaultView?.removeEventListener('hashchange', this.onHash);
+            this.stopTheme?.();
+            this.stopTheme = null;
+        }
+        async load(_signal, session) {
+            this.renderHeader();
+            this.updatePages();
+            if (session !== null)
+                this.renderUser(session);
+        }
+        // The frame stays; only the user area reflects a state. Signed out offers sign-in, anything else stays empty.
+        showState(state) {
+            const kind = typeof state === 'string' ? state : state.kind;
+            clear(this.user);
+            if (kind === 'signed-out')
+                this.user.appendChild(this.signInButton());
+        }
+        renderHeader() {
+            const name = this.attr('name') ?? '';
+            const src = this.attr('logo') ?? currentTheme().logo;
+            const current = this.header.querySelector('.logo');
+            this.heading.textContent = name;
+            if (src === null || src === '') {
+                current?.remove();
+                return;
+            }
+            const logo = h(scope.document, 'img', { class: 'logo', src, alt: this.attr('logo-alt') ?? name });
+            if (current === null)
+                this.header.prepend(logo);
+            else
+                current.replaceWith(logo);
+        }
+        renderUser(session) {
+            const doc = scope.document;
+            const user = session.user();
+            clear(this.user);
+            if (user === null) {
+                this.user.appendChild(this.signInButton());
+                return;
+            }
+            this.user.append(h(doc, 'span', {}, user.name !== null && user.name !== '' ? user.name : NL.signedIn), h(doc, 'button', { type: 'button', class: 'secondary', onclick: () => void this.change((s) => s.signOut()) }, NL.signOut));
+        }
+        signInButton() {
+            return h(scope.document, 'button', { type: 'button', onclick: () => void this.change((s) => s.signIn()) }, NL.signIn);
+        }
+        async change(action) {
+            try {
+                await action(await this.session());
+            }
+            catch {
+                // Nothing changed: show the user area as the session has it, so the button is there to try again.
+                void this.refresh();
+                return;
+            }
+            const View = this.ownerDocument.defaultView?.CustomEvent ?? CustomEvent;
+            this.ownerDocument.dispatchEvent(new View('cube-session-change'));
+        }
+        pages() {
+            return Array.from(this.children).filter((child) => child.localName === 'cube-page');
+        }
+        /** Shows the page the address names (default the first) and marks it in the navigation. */
+        updatePages() {
+            const pages = this.pages();
+            const location = scope.location ?? this.ownerDocument.defaultView?.location;
+            const hash = location?.hash ?? '';
+            let wanted = '';
+            if (hash.startsWith(PREFIX)) {
+                try {
+                    wanted = decodeURIComponent(hash.slice(PREFIX.length));
+                }
+                catch {
+                    wanted = '';
+                }
+            }
+            const active = pages.find((page) => page.getAttribute('name') === wanted) ?? pages[0];
+            for (const page of pages)
+                page.hidden = page !== active;
+            // Not hidden but absent: a single page has no navigation at all, also not for a screen reader.
+            if (pages.length < 2) {
+                this.nav.remove();
+                clear(this.list);
+                this.built = '';
+                return;
+            }
+            if (this.nav.parentNode !== this.body)
+                this.body.insertBefore(this.nav, this.main);
+            const signature = JSON.stringify(pages.map((page) => [page.getAttribute('name'), page.getAttribute('label')]));
+            if (signature !== this.built) {
+                clear(this.list);
+                for (const page of pages) {
+                    const name = page.getAttribute('name') ?? '';
+                    const href = PREFIX + encodeURIComponent(name);
+                    const link = h(scope.document, 'a', { href }, page.getAttribute('label') ?? name);
+                    this.list.appendChild(h(scope.document, 'li', {}, link));
+                }
+                this.built = signature;
+            }
+            Array.from(this.list.querySelectorAll('a')).forEach((link, index) => {
+                if (pages[index] === active)
+                    link.setAttribute('aria-current', 'page');
+                else
+                    link.removeAttribute('aria-current');
+            });
+        }
+    }
+    return CubeAppShell;
+}

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

@@ -0,0 +1,8 @@
+import { type BlockClass } from '../block.js';
+import type { BlockScope } from '../define.js';
+/**
+ * `<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 declare function boardBlock(Base: BlockClass, scope: BlockScope): BlockClass;