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

package/dist/ui/block.js

@@ -0,0 +1,238 @@
+import { CubeApp } from '../app.js';
+import { isDmpError } from '../errors.js';
+import { BLOCK_ATTRIBUTES } from './attributes.js';
+import { AuthorError } from './author-error.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 an AuthorError carries its message: the blocks throw
+ * those for a wrong attribute, in Dutch. A server's text, a network failure or a client's English programmer error
+ * never does.
+ */
+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 AuthorError)
+        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 reloadsOnOwnChange = 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) => {
+            if (event.composedPath()[0] === this && !this.constructor.reloadsOnOwnChange)
+                return;
+            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));
+                // The page shows only the generic text; the builder finds the real reason in the console.
+                if (error instanceof TypeError && !(error instanceof AuthorError)) {
+                    console.warn(`${this.localName}:`, 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 AuthorError(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 AuthorError(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).split('?')[0] ?? '');
+                }
+                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;