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

package/dist/ui/theme.js

@@ -0,0 +1,311 @@
+import { THEME_TEXTS } from './texts.js';
+export const TOKEN_NAMES = [
+    'color-primary',
+    'color-primary-hover',
+    'color-primary-subtle',
+    'color-primary-text',
+    'color-on-primary',
+    'color-accent',
+    'color-on-accent',
+    'color-text',
+    'color-text-muted',
+    'color-bg',
+    'color-surface',
+    'color-border',
+    'color-focus',
+    'color-danger',
+    'color-success',
+    'color-warning',
+    'color-example-bg',
+    'color-example-text',
+    'color-series-1',
+    'color-series-2',
+    'color-series-3',
+    'color-series-4',
+    'color-series-5',
+    'color-series-6',
+    'radius',
+    'radius-small',
+    'font-family',
+];
+export const NEUTRAL_SOURCE = { primary_colour: '#475467', corners: 'normaal', font: 'system' };
+export const FONTS = {
+    inter: {
+        family: 'Inter',
+        files: [{ file: 'inter.woff2', weight: '100 900', style: 'normal' }],
+    },
+    'albert-sans': {
+        family: 'Albert Sans',
+        files: [{ file: 'albert-sans.woff2', weight: '100 900', style: 'normal' }],
+    },
+    'source-sans-3': {
+        family: 'Source Sans 3',
+        files: [{ file: 'source-sans-3.woff2', weight: '200 900', style: 'normal' }],
+    },
+    'nunito-sans': {
+        family: 'Nunito Sans',
+        files: [{ file: 'nunito-sans.woff2', weight: '200 1000', style: 'normal' }],
+    },
+    'ibm-plex-sans': {
+        family: 'IBM Plex Sans',
+        files: [{ file: 'ibm-plex-sans.woff2', weight: '100 700', style: 'normal' }],
+    },
+};
+const FONT_FALLBACK = 'system-ui, -apple-system, "Segoe UI", Roboto, sans-serif';
+const SURFACE = '#f6f8fa';
+function parseHex(value) {
+    if (typeof value !== 'string')
+        return null;
+    const m = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(value);
+    if (!m || m[1] === undefined)
+        return null;
+    let h = m[1].toLowerCase();
+    if (h.length === 3)
+        h = [...h].map((c) => c + c).join('');
+    return [parseInt(h.slice(0, 2), 16), parseInt(h.slice(2, 4), 16), parseInt(h.slice(4, 6), 16)];
+}
+function toHex(rgb) {
+    return '#' + rgb.map((c) => Math.max(0, Math.min(255, c)).toString(16).padStart(2, '0')).join('');
+}
+function luminance(rgb) {
+    const [r, g, b] = rgb.map((c) => {
+        const s = c / 255;
+        return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+    });
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+export function contrastRatio(a, b) {
+    const ra = parseHex(a);
+    const rb = parseHex(b);
+    if (!ra || !rb)
+        return 1;
+    const la = luminance(ra);
+    const lb = luminance(rb);
+    return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
+}
+function mix(a, b, t) {
+    const ra = parseHex(a);
+    const rb = parseHex(b);
+    return toHex(ra.map((c, i) => Math.round(c * (1 - t) + rb[i] * t)));
+}
+function on(c) {
+    return contrastRatio(c, '#ffffff') >= contrastRatio(c, '#000000') ? '#ffffff' : '#000000';
+}
+function rotateHue(hex, degrees) {
+    const [r, g, b] = parseHex(hex).map((c) => c / 255);
+    const max = Math.max(r, g, b);
+    const min = Math.min(r, g, b);
+    const l = (max + min) / 2;
+    const d = max - min;
+    let h = 0;
+    let s = 0;
+    if (d !== 0) {
+        s = d / (1 - Math.abs(2 * l - 1));
+        if (max === r)
+            h = ((g - b) / d) % 6;
+        else if (max === g)
+            h = (b - r) / d + 2;
+        else
+            h = (r - g) / d + 4;
+        h *= 60;
+    }
+    h = (((h + degrees) % 360) + 360) % 360;
+    const c = (1 - Math.abs(2 * l - 1)) * s;
+    const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
+    const m = l - c / 2;
+    const sector = Math.floor(h / 60) % 6;
+    const [r1, g1, b1] = [
+        [c, x, 0],
+        [x, c, 0],
+        [0, c, x],
+        [0, x, c],
+        [x, 0, c],
+        [c, 0, x],
+    ][sector];
+    return toHex([r1, g1, b1].map((v) => Math.round((v + m) * 255)));
+}
+function normalise(value) {
+    const rgb = parseHex(value);
+    return rgb ? toHex(rgb) : null;
+}
+export function deriveTheme(source) {
+    const warnings = [];
+    let p = normalise(source.primary_colour);
+    if (p === null) {
+        p = normalise(NEUTRAL_SOURCE.primary_colour);
+        warnings.push({ code: 'invalid-primary', message: THEME_TEXTS.invalidPrimary });
+    }
+    let accent = null;
+    if (source.accent_colour !== undefined && source.accent_colour !== null) {
+        accent = normalise(source.accent_colour);
+        if (accent === null)
+            warnings.push({ code: 'invalid-accent', message: THEME_TEXTS.invalidAccent });
+    }
+    accent ??= rotateHue(p, 330);
+    if (contrastRatio(p, '#ffffff') < 3)
+        warnings.push({ code: 'primary-light', message: THEME_TEXTS.primaryLight });
+    // Primary text sits on the surface and on the subtle primary (secondary-button hover, badges): AA on both.
+    const subtle = mix(p, '#ffffff', 0.9);
+    let primaryText = p;
+    for (let i = 0; i <= 20; i++) {
+        primaryText = mix(p, '#000000', i / 20);
+        if (contrastRatio(primaryText, SURFACE) >= 4.5 && contrastRatio(primaryText, subtle) >= 4.5)
+            break;
+    }
+    if (primaryText !== p)
+        warnings.push({ code: 'primary-darkened-for-text', message: THEME_TEXTS.primaryDarkened });
+    const onPrimary = on(p);
+    const radii = {
+        scherp: ['0px', '0px'],
+        normaal: ['6px', '4px'],
+        rond: ['12px', '8px'],
+    };
+    const corners = typeof source.corners === 'string' && Object.hasOwn(radii, source.corners) ? source.corners : 'normaal';
+    const [radius, radiusSmall] = radii[corners];
+    const font = typeof source.font === 'string' && Object.hasOwn(FONTS, source.font) ? source.font : 'system';
+    const fontFamily = font === 'system' ? FONT_FALLBACK : `"${FONTS[font].family}", ${FONT_FALLBACK}`;
+    const tokens = {
+        'color-primary': p,
+        'color-primary-hover': mix(p, onPrimary === '#ffffff' ? '#000000' : '#ffffff', 0.15),
+        'color-primary-subtle': subtle,
+        'color-primary-text': primaryText,
+        'color-on-primary': onPrimary,
+        'color-accent': accent,
+        'color-on-accent': on(accent),
+        'color-text': '#1f2328',
+        'color-text-muted': '#59636e',
+        'color-bg': '#ffffff',
+        'color-surface': SURFACE,
+        'color-border': '#d1d9e0',
+        'color-focus': primaryText,
+        'color-danger': '#b42318',
+        'color-success': '#067647',
+        'color-warning': '#b54708',
+        'color-example-bg': '#fef0c7',
+        'color-example-text': '#7a2e0e',
+        'color-series-1': p,
+        'color-series-2': accent,
+        'color-series-3': '#0e9384',
+        'color-series-4': '#dc6803',
+        'color-series-5': '#7a5af8',
+        'color-series-6': '#475467',
+        radius,
+        'radius-small': radiusSmall,
+        'font-family': fontFamily,
+    };
+    return { tokens, warnings };
+}
+const COLOR_TOKEN = /^#[0-9a-f]{6}$/i;
+const RADIUS_TOKEN = /^\d+(\.\d+)?(px|rem)$/;
+const INLINE_IMAGE = /^data:image\/(svg\+xml|png);/;
+// `/*` could swallow the rest of the stylesheet; the brief's list covers the other ways out of a declaration.
+const UNSAFE_FONT_FAMILY = /[;{}<>\\\u0000-\u001f]|\/\*/;
+const UNSAFE_URL = /["'()\\\s]/;
+// A comma-separated list of quoted names and bare words: an unbalanced quote would run on through the stylesheet.
+const FONT_FAMILY_ITEM = String.raw `(?:\s*"[^"]*"\s*|\s*'[^']*'\s*|[^"',]+)`;
+const FONT_FAMILY_LIST = new RegExp(`^${FONT_FAMILY_ITEM}(?:,${FONT_FAMILY_ITEM})*$`);
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function validToken(name, value) {
+    if (typeof value !== 'string')
+        return false;
+    if (name.startsWith('color-'))
+        return COLOR_TOKEN.test(value);
+    if (name.startsWith('radius'))
+        return RADIUS_TOKEN.test(value);
+    return (value.length > 0 && value.length <= 200 && !UNSAFE_FONT_FAMILY.test(value) && FONT_FAMILY_LIST.test(value));
+}
+function safeUrl(value, baseUrl, allowInline) {
+    if (typeof value !== 'string' || value === '')
+        return null;
+    if (allowInline && INLINE_IMAGE.test(value))
+        return UNSAFE_URL.test(value) ? null : value;
+    try {
+        const base = new URL(baseUrl);
+        const url = new URL(value, base);
+        const sameOrigin = (url.protocol === 'https:' || url.protocol === 'http:') && url.origin === base.origin;
+        if (sameOrigin && !UNSAFE_URL.test(url.href))
+            return url.href;
+    }
+    catch {
+        // An unparsable address is simply dropped.
+    }
+    return null;
+}
+function resolveFontFiles(files, baseUrl) {
+    const resolved = [];
+    for (const entry of Array.isArray(files) ? files : []) {
+        if (!isRecord(entry))
+            continue;
+        const src = safeUrl(entry.src, baseUrl, false);
+        if (src === null)
+            continue;
+        const weight = typeof entry.weight === 'string' && /^\d{1,4}( \d{1,4})?$/.test(entry.weight) ? entry.weight : '400';
+        resolved.push({ src, weight, style: entry.style === 'italic' ? 'italic' : 'normal' });
+    }
+    return resolved;
+}
+export function resolveTheme(input, baseUrl) {
+    const raw = input;
+    let source = NEUTRAL_SOURCE;
+    let tokenOverrides = null;
+    let fontFiles = null;
+    if (isRecord(raw)) {
+        if (Object.hasOwn(raw, 'source') && isRecord(raw.source)) {
+            source = raw.source;
+            tokenOverrides = Object.hasOwn(raw, 'tokens') ? raw.tokens : null;
+            fontFiles = Object.hasOwn(raw, 'font_files') ? raw.font_files : null;
+        }
+        else if (Object.hasOwn(raw, 'primary_colour')) {
+            source = raw;
+        }
+    }
+    const { tokens, warnings } = deriveTheme(source);
+    if (isRecord(tokenOverrides)) {
+        for (const name of TOKEN_NAMES) {
+            if (Object.hasOwn(tokenOverrides, name) && validToken(name, tokenOverrides[name])) {
+                tokens[name] = tokenOverrides[name];
+            }
+        }
+    }
+    const font = typeof source.font === 'string' && Object.hasOwn(FONTS, source.font)
+        ? source.font
+        : null;
+    let files = resolveFontFiles(fontFiles, baseUrl);
+    if (font !== null && files.length === 0 && !Array.isArray(fontFiles)) {
+        files = FONTS[font].files.flatMap((entry) => {
+            const src = safeUrl('cube-theme/' + entry.file, baseUrl, false);
+            return src === null ? [] : [{ src, weight: entry.weight, style: entry.style }];
+        });
+    }
+    return {
+        tokens,
+        logo: safeUrl(source.logo, baseUrl, true),
+        logoDark: safeUrl(source.logo_dark, baseUrl, true),
+        fontFamily: font === null ? null : FONTS[font].family,
+        fontFiles: files,
+        warnings,
+    };
+}
+export function themeCss(theme) {
+    // Zero specificity: an app's own `:root { --cube-... }` overrides a token although this sheet comes later.
+    return ':where(:root){' + TOKEN_NAMES.map((name) => `--cube-${name}:${theme.tokens[name]}`).join(';') + '}';
+}
+let current = null;
+const listeners = new Set();
+export function currentTheme() {
+    current ??= resolveTheme(null, 'http://localhost/');
+    return current;
+}
+export function setTheme(theme) {
+    current = theme;
+    for (const listener of [...listeners])
+        listener(theme);
+}
+export function onTheme(listener) {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+}

package/dist/ui/write.d.ts

@@ -0,0 +1,20 @@
+import type { CubeAppSession } from '../app.js';
+import { type Editor } from './inputs.js';
+export declare const WRITE_CSS = "\nform{display:flex;flex-direction:column;gap:1rem}\n.actions{display:flex;flex-wrap:wrap;gap:.5rem;margin-top:1rem}\n.alert{margin:0 0 1rem;padding:.75rem 1rem;border:1px solid var(--cube-color-danger,#b42318);\nborder-radius:var(--cube-radius-small)}\n.alert p{margin:0}\n.alert ul{margin:.5rem 0 0;padding-inline-start:1.25rem}\n.alert button{margin-top:.5rem}\n.status{margin:.5rem 0 0}\n.status:empty{margin:0}\n";
+/** One key per write attempt: kept only while the same body is sent again after the answer never came. */
+export interface Attempt {
+    key: string;
+    body: string;
+}
+/** The attempt for `fingerprint`: the earlier one when it is the same body, else a new key. */
+export declare function attemptFor(earlier: Attempt | null, fingerprint: string): Attempt;
+/** Shows `message` (and `action`) in the alert above a form and moves focus there. */
+export declare function showAlert(doc: Document, target: HTMLElement, message: string, action?: HTMLElement | null): void;
+/**
+ * Shows why a write failed: a 422 on the fields it names, with the form-level line, and the messages for fields
+ * without an editor listed in the alert (`label` names them); anything else as one line. Never the browser's own
+ * (English) text of a network failure: stateFor would show a TypeError's message.
+ */
+export declare function showWriteFailure(doc: Document, alert: HTMLElement, error: unknown, editors: Editor[], label: (field: string) => string): void;
+/** Who is signed in, as a key: null when nobody is. A write must not go out as somebody who signed in since. */
+export declare function userOf(session: CubeAppSession | undefined): string | null;

package/dist/ui/write.js

@@ -0,0 +1,54 @@
+// What the blocks that write (cube-detail, cube-form, cube-board) share: the form frame, the alert above it, the
+// message for a failed write, the idempotency key per attempt and who a write goes out as.
+import { newIdempotencyKey } from '../client.js';
+import { stateFor } from './block.js';
+import { clear, h } from './dom.js';
+import { fieldErrors } from './inputs.js';
+import { NL } from './texts.js';
+export const WRITE_CSS = `
+form{display:flex;flex-direction:column;gap:1rem}
+.actions{display:flex;flex-wrap:wrap;gap:.5rem;margin-top:1rem}
+.alert{margin:0 0 1rem;padding:.75rem 1rem;border:1px solid var(--cube-color-danger,#b42318);
+border-radius:var(--cube-radius-small)}
+.alert p{margin:0}
+.alert ul{margin:.5rem 0 0;padding-inline-start:1.25rem}
+.alert button{margin-top:.5rem}
+.status{margin:.5rem 0 0}
+.status:empty{margin:0}
+`;
+/** The attempt for `fingerprint`: the earlier one when it is the same body, else a new key. */
+export function attemptFor(earlier, fingerprint) {
+    return earlier?.body === fingerprint ? earlier : { key: newIdempotencyKey(), body: fingerprint };
+}
+/** Shows `message` (and `action`) in the alert above a form and moves focus there. */
+export function showAlert(doc, target, message, action) {
+    clear(target);
+    target.append(h(doc, 'p', {}, message), ...(action === undefined || action === null ? [] : [action]));
+    target.hidden = false;
+    target.focus();
+}
+/**
+ * Shows why a write failed: a 422 on the fields it names, with the form-level line, and the messages for fields
+ * without an editor listed in the alert (`label` names them); anything else as one line. Never the browser's own
+ * (English) text of a network failure: stateFor would show a TypeError's message.
+ */
+export function showWriteFailure(doc, alert, error, editors, label) {
+    const errors = fieldErrors(error);
+    if (errors !== null) {
+        for (const editor of editors)
+            editor.setError(errors[editor.name] ?? null);
+        const rest = Object.entries(errors).filter(([field]) => !editors.some((editor) => editor.name === field));
+        const list = rest.length === 0
+            ? null
+            : h(doc, 'ul', {}, ...rest.map(([field, message]) => h(doc, 'li', {}, `${label(field)}: ${message}`)));
+        showAlert(doc, alert, NL.formInvalid, list);
+        return;
+    }
+    const kind = stateFor(error).kind;
+    showAlert(doc, alert, kind === 'forbidden' ? NL.forbidden : kind === 'signed-out' ? NL.signedOut : NL.saveFailed);
+}
+/** Who is signed in, as a key: null when nobody is. A write must not go out as somebody who signed in since. */
+export function userOf(session) {
+    const user = session?.user() ?? null;
+    return user === null ? null : String(user.id);
+}

package/dist/version.d.ts

@@ -1,4 +1,4 @@
 /** This package's version. A test holds it equal to package.json's. */
-export declare const VERSION = "1.0.0-rc.3";
+export declare const VERSION = "1.1.0-rc.1";
 /** The `"sdk"` value a `cube-app.json` manifest names for the API `CubeApp` offers here. */
 export declare const MANIFEST_SDK = "1";

package/dist/version.js

@@ -1,4 +1,4 @@
 /** This package's version. A test holds it equal to package.json's. */
-export const VERSION = '1.0.0-rc.3';
+export const VERSION = '1.1.0-rc.1';
 /** The `"sdk"` value a `cube-app.json` manifest names for the API `CubeApp` offers here. */
 export const MANIFEST_SDK = '1';

package/dist/wireframe.d.ts

@@ -0,0 +1,37 @@
+import type { ResourceClient } from './client.js';
+import { PreviewStore } from './preview.js';
+import type { DmpRecord } from './types.js';
+import { type Format } from './ui/format.js';
+import type { ResourceSchema } from './ui/schema.js';
+export type GapType = 'tekst' | 'getal' | 'bedrag' | 'datum' | 'keuze' | 'ja/nee';
+/** One entry of `ontbreekt[]` in cube-app.json: a field (or a whole resource) the DMP does not have yet. */
+export interface GapEntry {
+    resource: string;
+    veld?: string;
+    type: GapType;
+    waarden?: string[];
+    scherm: string;
+    reden: string;
+}
+/** The valid gap entries of `ontbreekt`; malformed ones are dropped with a single warning. */
+export declare function readGaps(value: unknown): GapEntry[];
+export declare function gapFormat(type: GapType): Format;
+/**
+ * A schema with the missing fields of its resource added, so a block that takes its columns from the schema shows
+ * them, and can filter and sort on them (the page only). They are writable: a wireframe's writes stay in the browser.
+ */
+export declare function withGaps(schema: ResourceSchema | null, gaps: readonly GapEntry[]): ResourceSchema | null;
+/** An example value for a missing field of row `id`: from mock rows that carry the field, else made up by type. */
+export declare function inventValue(gap: GapEntry, id: unknown, mockRows: readonly DmpRecord[]): unknown;
+/**
+ * A live resource some of whose fields do not exist yet. Those fields never reach the server (naming one would be a
+ * 422): each row gets an invented value, a filter or sort on one applies to the returned page only, and an aggregate
+ * that names one is answered from the mock rows.
+ */
+export declare function mixedResource<T extends DmpRecord>(live: ResourceClient<T>, gaps: readonly GapEntry[], mock: PreviewStore, mockRows: readonly DmpRecord[]): ResourceClient<T>;
+/**
+ * A wireframe's writes, answered in this browser and never sent: what is created, changed or deleted lies over the
+ * wrapped client's reads until the page reloads. A created row's id is `voorbeeld-<n>`. A list shows a created or
+ * changed row only where the query's filter puts it, so a moved board card lands in its new column.
+ */
+export declare function simulatedWrites<T extends DmpRecord>(client: ResourceClient<T>, name: string): ResourceClient<T>;