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

package/dist/ui/format.js

@@ -0,0 +1,215 @@
+import { AuthorError } from './author-error.js';
+import { NL } from './texts.js';
+/** The formats that hold a number: right-aligned, read and written as numbers. */
+export const NUMERIC_FORMATS = ['number', 'integer', 'currency', 'percent'];
+const LOCALE = 'nl-NL';
+const TRUNCATIONS = ['day', 'week', 'month', 'quarter', 'year'];
+const DATE_ONLY = /^(\d{4})-(\d{2})-(\d{2})$/;
+const NUMERIC = /^\s*-?(\d+\.?\d*|\.\d+)(e[+-]?\d+)?\s*$/i;
+const MEASURE = /^(count|sum|avg|min|max)(?:\(([A-Za-z_][A-Za-z0-9_]*)\))?$/;
+const DIMENSION = /^([A-Za-z_][A-Za-z0-9_]*)(?:\.([a-z]+))?$/;
+const numberFormats = new Map();
+const dateFormats = new Map();
+function numberFormat(options) {
+    const key = JSON.stringify(options);
+    let format = numberFormats.get(key);
+    if (format === undefined) {
+        format = new Intl.NumberFormat(LOCALE, options);
+        numberFormats.set(key, format);
+    }
+    return format;
+}
+function dateFormat(options) {
+    const key = JSON.stringify(options);
+    let format = dateFormats.get(key);
+    if (format === undefined) {
+        format = new Intl.DateTimeFormat(LOCALE, options);
+        dateFormats.set(key, format);
+    }
+    return format;
+}
+/** A number, or a numeric string as the API may send a decimal (`"80.50"`); null for anything else. */
+export function toNumber(value) {
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? value : null;
+    if (typeof value === 'bigint')
+        return Number(value);
+    if (typeof value === 'string' && NUMERIC.test(value))
+        return Number(value);
+    return null;
+}
+function toDate(value) {
+    if (value instanceof Date)
+        return Number.isNaN(value.getTime()) ? null : value;
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? new Date(value) : null;
+    if (typeof value === 'string')
+        return parseLocalDate(value);
+    return null;
+}
+/** Text for one value in the house format: nl-NL numbers, amounts and dates; `—` for nothing. */
+export function formatValue(value, format, options = {}) {
+    if (value === null || value === undefined || value === '')
+        return NL.emptyValue;
+    switch (format) {
+        case 'number':
+        case 'integer':
+        case 'currency':
+        case 'percent': {
+            const n = toNumber(value);
+            if (n === null)
+                return String(value);
+            const compact = options.compact === true ? { notation: 'compact' } : {};
+            if (format === 'currency') {
+                return numberFormat({ style: 'currency', currency: options.currency ?? 'EUR', ...compact }).format(n);
+            }
+            if (format === 'percent')
+                return numberFormat({ style: 'percent', maximumFractionDigits: 1 }).format(n);
+            const digits = format === 'integer' ? 0 : options.compact === true ? 1 : 2;
+            return numberFormat({ maximumFractionDigits: digits, ...compact }).format(n);
+        }
+        case 'date':
+        case 'datetime': {
+            const date = toDate(value);
+            if (date === null)
+                return String(value);
+            const parts = { day: 'numeric', month: 'short', year: 'numeric' };
+            if (format === 'datetime')
+                Object.assign(parts, { hour: '2-digit', minute: '2-digit' });
+            // A bare date is a calendar day, not an instant: shifting it into another zone would change the day.
+            const bareDate = typeof value === 'string' && DATE_ONLY.test(value);
+            if (options.timeZone !== undefined && !bareDate)
+                parts.timeZone = options.timeZone;
+            return dateFormat(parts).format(date);
+        }
+        case 'boolean':
+            if (value === true || value === 'true' || value === 1)
+                return NL.yes;
+            if (value === false || value === 'false' || value === 0)
+                return NL.no;
+            return String(value);
+        default:
+            if (Array.isArray(value))
+                return value.map((item) => formatValue(item, 'text')).join(', ');
+            if (typeof value === 'object')
+                return JSON.stringify(value);
+            return String(value);
+    }
+}
+/**
+ * A label for an aggregate bucket key (`2026-Q2` → `K2 2026`). An unknown key comes back as is. `short` writes a
+ * month without its year (`nov`), for an axis.
+ */
+export function formatBucket(key, truncation, options = {}) {
+    switch (truncation) {
+        case 'year':
+            return key;
+        case 'quarter': {
+            const m = /^(\d{4})-Q([1-4])$/.exec(key);
+            return m?.[1] !== undefined && m[2] !== undefined ? NL.quarter(m[2], m[1]) : key;
+        }
+        case 'week': {
+            const m = /^(\d{4})-W(\d{2})$/.exec(key);
+            return m?.[1] !== undefined && m[2] !== undefined ? NL.week(Number(m[2]), m[1]) : key;
+        }
+        case 'month': {
+            const m = /^(\d{4})-(\d{2})$/.exec(key);
+            if (m?.[1] === undefined || m[2] === undefined)
+                return key;
+            const month = localDate(Number(m[1]), Number(m[2]) - 1, 1);
+            return dateFormat(options.short === true ? { month: 'short' } : { month: 'short', year: 'numeric' })
+                .format(month);
+        }
+        case 'day': {
+            const date = DATE_ONLY.test(key) ? parseLocalDate(key) : null;
+            return date === null ? key : dateFormat({ day: 'numeric', month: 'short' }).format(date);
+        }
+        default:
+            return key;
+    }
+}
+/** `sum(total)` → `{ fn: 'sum', field: 'total' }`; a bare `count` counts rows. */
+export function parseMeasure(measure) {
+    const m = MEASURE.exec(measure.trim());
+    const fn = m?.[1];
+    if (fn === undefined || (fn !== 'count' && m?.[2] === undefined)) {
+        throw new AuthorError(NL.invalid.measure(measure));
+    }
+    return { fn, field: m?.[2] ?? null };
+}
+/** `placed_on.month` → `{ field: 'placed_on', truncation: 'month' }`. */
+export function parseDimension(by) {
+    const m = DIMENSION.exec(by.trim());
+    const field = m?.[1];
+    const truncation = m?.[2];
+    if (field === undefined || (truncation !== undefined && !TRUNCATIONS.includes(truncation))) {
+        throw new AuthorError(NL.invalid.dimension(by));
+    }
+    return { field, truncation: truncation ?? null };
+}
+/** The format a field's values get when the page does not say: from its schema type, else from a sample value. */
+export function inferFormat(field, sample) {
+    if (field?.format === 'date')
+        return 'date';
+    if (field?.format === 'date-time')
+        return 'datetime';
+    if (field?.format === 'currency')
+        return 'currency';
+    switch (field?.type) {
+        case 'integer':
+            return 'integer';
+        case 'number':
+            return 'number';
+        case 'boolean':
+            return 'boolean';
+        case 'string':
+            // Live schemas carry no `format`, so a date column is only recognisable by its values.
+            return sampleDate(sample) ?? 'text';
+    }
+    // Unknown or union types (`string|integer`): the sample decides.
+    if (typeof sample === 'boolean')
+        return 'boolean';
+    if (typeof sample === 'number')
+        return Number.isInteger(sample) ? 'integer' : 'number';
+    return sampleDate(sample) ?? 'text';
+}
+function sampleDate(sample) {
+    if (typeof sample !== 'string')
+        return null;
+    if (DATE_ONLY.test(sample))
+        return parseLocalDate(sample) === null ? null : 'date';
+    if (/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}/.test(sample) && !Number.isNaN(Date.parse(sample)))
+        return 'datetime';
+    return null;
+}
+/** A readable label from a field name: `placed_on` → `Placed on`, `customer_id` → `Customer`. */
+export function humanize(field) {
+    const words = field
+        .replace(/_id$/, '')
+        .replace(/([a-z])([A-Z])/g, '$1 $2')
+        .replace(/[_\-.]+/g, ' ')
+        .trim()
+        .toLowerCase();
+    return words === '' ? field : words.charAt(0).toUpperCase() + words.slice(1);
+}
+/** `YYYY-MM-DD` as local midnight (Date.parse would make it UTC midnight); anything else via Date.parse. */
+export function parseLocalDate(value) {
+    const m = DATE_ONLY.exec(value);
+    if (m?.[1] !== undefined && m[2] !== undefined && m[3] !== undefined) {
+        const date = localDate(Number(m[1]), Number(m[2]) - 1, Number(m[3]));
+        return date.getMonth() === Number(m[2]) - 1 ? date : null;
+    }
+    const time = Date.parse(value);
+    return Number.isNaN(time) ? null : new Date(time);
+}
+// `new Date(y, m, d)` maps years 0-99 to 1900-1999; setFullYear does not.
+function localDate(year, month, day) {
+    const date = new Date(2000, 0, 1);
+    date.setFullYear(year, month, day);
+    return date;
+}
+/** The local calendar day as `YYYY-MM-DD`. */
+export function isoDate(date) {
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${String(date.getFullYear()).padStart(4, '0')}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+}

package/dist/ui/inputs.d.ts

@@ -0,0 +1,35 @@
+import { type Column } from './fields.js';
+import { type Format } from './format.js';
+/** One labelled input for one field. `read` checks and converts what was typed; `setError` shows a message. */
+export interface Editor {
+    element: HTMLElement;
+    name: string;
+    read(): {
+        value: unknown;
+    } | {
+        error: string;
+    };
+    setError(message: string | null): void;
+}
+type Parsed = {
+    value: unknown;
+} | {
+    error: string;
+};
+/** Styles for the editors, for the blocks that show them to include in their own `css`. */
+export declare const EDITOR_CSS = "\n.field{display:flex;flex-direction:column;gap:.25rem;min-width:0}\n.field label{font-weight:600}\n.field .required{font-weight:400;color:var(--cube-color-text-muted)}\n.field.check{flex-direction:row;align-items:center;gap:.5rem}\n.field.check input{min-height:auto;width:1.25rem;height:1.25rem}\n.field [aria-invalid=true]{border-color:var(--cube-color-danger,#b42318)}\n.field-error{margin:0;color:var(--cube-color-danger,#b42318);font-size:.875rem}\n";
+/**
+ * What a typed text means for a field of `format`: nothing typed is null; numbers are read the Dutch way
+ * (`12,5`, `1.234,5`) or the plain way (`12.5`); a percentage is typed as 21 and stored as 0.21.
+ */
+export declare function parseInput(raw: string, format: Format): Parsed;
+/** The first message per field of a 422 from the DMP, or null when the error is not one. */
+export declare function fieldErrors(error: unknown): Record<string, string> | null;
+/**
+ * The editor for one field: a text box, a number box that takes Dutch decimals, a date or date-time picker, a
+ * checkbox or a list of choices. `required` is announced with aria-required, not the native attribute, so the
+ * message the person reads is ours, in Dutch; the label shows " (verplicht)", hidden from the reader that already
+ * hears aria-required.
+ */
+export declare function editorFor(doc: Document, column: Column, value: unknown, required: boolean): Editor;
+export {};

package/dist/ui/inputs.js

@@ -0,0 +1,161 @@
+import { isDmpError } from '../errors.js';
+import { h } from './dom.js';
+import { choicesFor } from './fields.js';
+import { isoDate, NUMERIC_FORMATS } from './format.js';
+import { NL } from './texts.js';
+/** Styles for the editors, for the blocks that show them to include in their own `css`. */
+export const EDITOR_CSS = `
+.field{display:flex;flex-direction:column;gap:.25rem;min-width:0}
+.field label{font-weight:600}
+.field .required{font-weight:400;color:var(--cube-color-text-muted)}
+.field.check{flex-direction:row;align-items:center;gap:.5rem}
+.field.check input{min-height:auto;width:1.25rem;height:1.25rem}
+.field [aria-invalid=true]{border-color:var(--cube-color-danger,#b42318)}
+.field-error{margin:0;color:var(--cube-color-danger,#b42318);font-size:.875rem}
+`;
+// With a comma the dots can only group thousands: 1.234,5. Without one, a dot before exactly three digits groups
+// thousands too (nl-NL input: 1.234 is 1234), unless the number starts with 0 (0.125); any other dot is a decimal.
+const WITH_COMMA = /^-?(\d{1,3}(\.\d{3})+|\d*)(,\d+)?$/;
+const GROUPED = /^-?[1-9]\d{0,2}(\.\d{3})+$/;
+const PLAIN = /^-?(\d+\.?\d*|\.\d+)$/;
+let nextId = 0;
+function parseDutchNumber(text) {
+    if (text.includes(',')) {
+        return WITH_COMMA.test(text) && /\d/.test(text) ? Number(text.replace(/\./g, '').replace(',', '.')) : null;
+    }
+    if (GROUPED.test(text))
+        return Number(text.replace(/\./g, ''));
+    return PLAIN.test(text) ? Number(text) : null;
+}
+// toPrecision drops the binary noise of a division or multiplication by 100 (0.07 * 100 = 7.000000000000001).
+const tidy = (n) => Number(n.toPrecision(12));
+/**
+ * What a typed text means for a field of `format`: nothing typed is null; numbers are read the Dutch way
+ * (`12,5`, `1.234,5`) or the plain way (`12.5`); a percentage is typed as 21 and stored as 0.21.
+ */
+export function parseInput(raw, format) {
+    if (raw.trim() === '')
+        return { value: null };
+    if (NUMERIC_FORMATS.includes(format)) {
+        const n = parseDutchNumber(raw.replace(/[\s €%]/g, ''));
+        if (n === null || !Number.isFinite(n))
+            return { error: NL.notANumber };
+        if (format === 'integer' && !Number.isInteger(n))
+            return { error: NL.notAnInteger };
+        return { value: format === 'percent' ? tidy(n / 100) : n };
+    }
+    if (format === 'boolean')
+        return { value: raw === 'true' || raw === '1' };
+    if (format === 'datetime') {
+        const time = Date.parse(raw);
+        return { value: Number.isNaN(time) ? raw : new Date(time).toISOString() };
+    }
+    return { value: raw };
+}
+/** The first message per field of a 422 from the DMP, or null when the error is not one. */
+export function fieldErrors(error) {
+    if (!isDmpError(error) || error.status !== 422 || error.errors === null)
+        return null;
+    const result = {};
+    for (const [field, messages] of Object.entries(error.errors)) {
+        const first = Array.isArray(messages) ? messages.find((m) => typeof m === 'string') : undefined;
+        if (first !== undefined)
+            result[field] = first;
+    }
+    return Object.keys(result).length > 0 ? result : null;
+}
+/** A stored value as the text an input shows: `1234,5`, a percentage as 21, a date-time in local time. */
+function inputText(value, format) {
+    if (value === null || value === undefined)
+        return '';
+    if (NUMERIC_FORMATS.includes(format)) {
+        const n = typeof value === 'number' ? value : Number(value);
+        if (typeof value === 'boolean' || !Number.isFinite(n))
+            return String(value);
+        return String(format === 'percent' ? tidy(n * 100) : n).replace('.', ',');
+    }
+    if (format === 'date' && typeof value === 'string')
+        return value.slice(0, 10);
+    if (format === 'datetime' && typeof value === 'string') {
+        const time = Date.parse(value);
+        if (Number.isNaN(time))
+            return value;
+        const date = new Date(time);
+        const pad = (n) => String(n).padStart(2, '0');
+        return `${isoDate(date)}T${pad(date.getHours())}:${pad(date.getMinutes())}`;
+    }
+    return typeof value === 'object' ? JSON.stringify(value) : String(value);
+}
+function control(doc, column, value, id) {
+    const choices = choicesFor(column);
+    const text = inputText(value, column.format);
+    if (choices !== null) {
+        const known = choices.some((choice) => choice.value === text);
+        const list = text === '' || known ? choices : [...choices, { value: text, label: text }];
+        const select = h(doc, 'select', { id, name: column.name }, h(doc, 'option', { value: '' }, NL.emptyValue), ...list.map((choice) => h(doc, 'option', { value: choice.value }, choice.label)));
+        select.value = text;
+        return select;
+    }
+    if (column.format === 'text' && column.config?.multiline === true) {
+        const area = h(doc, 'textarea', { id, name: column.name, rows: '4' });
+        area.value = text;
+        return area;
+    }
+    const numeric = NUMERIC_FORMATS.includes(column.format);
+    const type = column.format === 'date' ? 'date' : column.format === 'datetime' ? 'datetime-local' : 'text';
+    const input = h(doc, 'input', {
+        id,
+        name: column.name,
+        type: column.format === 'boolean' ? 'checkbox' : type,
+        inputmode: numeric ? 'decimal' : null,
+    });
+    if (column.format === 'boolean') {
+        input.checked = value === true || value === 'true' || value === 1;
+    }
+    else {
+        input.value = text;
+    }
+    return input;
+}
+/**
+ * The editor for one field: a text box, a number box that takes Dutch decimals, a date or date-time picker, a
+ * checkbox or a list of choices. `required` is announced with aria-required, not the native attribute, so the
+ * message the person reads is ours, in Dutch; the label shows " (verplicht)", hidden from the reader that already
+ * hears aria-required.
+ */
+export function editorFor(doc, column, value, required) {
+    const id = `cube-input-${++nextId}`;
+    const input = control(doc, column, value, id);
+    const checkbox = input.getAttribute('type') === 'checkbox';
+    if (required && !checkbox)
+        input.setAttribute('aria-required', 'true');
+    const mark = required && !checkbox
+        ? h(doc, 'span', { class: 'required', 'aria-hidden': 'true' }, NL.requiredMark)
+        : null;
+    const label = h(doc, 'label', { for: id }, column.label, mark);
+    const errorLine = h(doc, 'p', { id: `${id}-error`, class: 'field-error', hidden: true });
+    const element = h(doc, 'div', { class: checkbox ? 'field check' : 'field' }, ...(checkbox ? [input, label] : [label, input]), errorLine);
+    return {
+        element,
+        name: column.name,
+        read() {
+            if (checkbox)
+                return { value: input.checked };
+            if (required && input.value.trim() === '')
+                return { error: NL.required };
+            return parseInput(input.value, column.format);
+        },
+        setError(message) {
+            errorLine.textContent = message ?? '';
+            errorLine.hidden = message === null;
+            if (message === null) {
+                input.removeAttribute('aria-invalid');
+                input.removeAttribute('aria-describedby');
+            }
+            else {
+                input.setAttribute('aria-invalid', 'true');
+                input.setAttribute('aria-describedby', errorLine.id);
+            }
+        },
+    };
+}

package/dist/ui/manifest.d.ts

@@ -0,0 +1,40 @@
+export type AttributeType = 'string' | 'boolean' | 'number' | 'enum' | 'resource' | 'field' | 'fields' | 'measure' | 'dimension' | 'selector' | 'filter' | 'date' | 'url' | 'id';
+export interface AttributeSpec {
+    type: AttributeType;
+    required: boolean;
+    summary: string;
+    values?: readonly string[];
+    default?: string;
+    example?: string;
+    actions?: readonly string[];
+}
+export interface BlockSpec {
+    kind: 'block' | 'config';
+    since: string;
+    summary: string;
+    actions: readonly string[];
+    attributes: Readonly<Record<string, AttributeSpec>>;
+    children?: readonly string[];
+    events?: Readonly<Record<string, string>>;
+    properties?: Readonly<Record<string, string>>;
+    example: string;
+}
+export interface BlockManifest {
+    manifest: 1;
+    package: '@cube-nl/dmp-sdk';
+    version: string;
+    file: 'cube-sdk.js';
+    blocks: Record<string, BlockSpec>;
+    tokens: string[];
+    fonts: Record<string, {
+        family: string;
+        files: Array<{
+            file: string;
+            weight: string;
+            style: string;
+        }>;
+    }>;
+}
+/** What every element does, read by Claude to compose apps. One entry per tag, in English. */
+export declare const BLOCK_SPECS: Readonly<Record<string, BlockSpec>>;
+export declare function blockManifest(version: string): BlockManifest;