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

package/dist/ui/chart-svg.d.ts

@@ -0,0 +1,28 @@
+export interface Series {
+    label: string;
+    points: Array<{
+        key: string;
+        label: string;
+        value: number | null;
+        tick?: string;
+    }>;
+    /** Categories get a label each, cut to its band; points in time are thinned to the labels that fit. */
+    categories?: boolean;
+}
+/** Formats a value; `compact` for the axis (`4K`), the full form for the point's title. */
+export type ChartFormat = (n: number, compact?: boolean) => string;
+/**
+ * Round axis values covering min..max, about `count` steps of 1, 2 or 5 × 10ⁿ. The range is widened to take in
+ * 0 (bars grow from the zero line), so 0 is always a tick; with nothing to span (0..0) it is `[0, 1]`.
+ */
+export declare function niceTicks(min: number, max: number, count?: number): number[];
+/** A line through the points (a gap where a value is null), with a dot and a title per point. */
+export declare function renderLine(doc: Document, series: Series, size: {
+    width: number;
+    height: number;
+}, format: ChartFormat): SVGElement;
+/** One bar per point from the zero line, with a title each. */
+export declare function renderBars(doc: Document, series: Series, size: {
+    width: number;
+    height: number;
+}, format: ChartFormat): SVGElement;

package/dist/ui/chart-svg.js

@@ -0,0 +1,111 @@
+import { svg } from './dom.js';
+import { NL } from './texts.js';
+const LEFT = 56;
+const RIGHT = 8;
+const TOP = 8;
+const BOTTOM = 24;
+/** An estimate of one character of the 12px axis text, and the room between two labels. */
+const CHAR = 7;
+const GAP = 8;
+/**
+ * Round axis values covering min..max, about `count` steps of 1, 2 or 5 × 10ⁿ. The range is widened to take in
+ * 0 (bars grow from the zero line), so 0 is always a tick; with nothing to span (0..0) it is `[0, 1]`.
+ */
+export function niceTicks(min, max, count = 4) {
+    const low = Math.min(min, 0);
+    const high = Math.max(max, 0);
+    if (high <= low)
+        return [0, 1];
+    const raw = (high - low) / count;
+    const magnitude = 10 ** Math.floor(Math.log10(raw));
+    const norm = raw / magnitude;
+    const step = (norm <= 1 ? 1 : norm <= 2 ? 2 : norm <= 5 ? 5 : 10) * magnitude;
+    const ticks = [];
+    for (let i = Math.floor(low / step); i <= Math.ceil(high / step); i++) {
+        ticks.push(Number((i * step).toPrecision(12)));
+    }
+    return ticks;
+}
+/**
+ * An x label, cut to `room` with an ellipsis (the full text in its title) and centred under `x`, moved inward only as
+ * far as it takes to stay between `left` and `right`.
+ */
+function xLabel(doc, text, room, at) {
+    const fits = Math.max(1, Math.floor(room / CHAR));
+    const shown = text.length <= fits ? text : `${text.slice(0, fits - 1)}…`;
+    const half = (shown.length * CHAR) / 2;
+    const x = Math.min(Math.max(at.x, at.left + half), at.right - half);
+    const label = svg(doc, 'text', { class: 'x', x, y: at.y }, shown);
+    if (shown !== text)
+        label.append(svg(doc, 'title', {}, text));
+    return label;
+}
+/** The axes and grid of a chart, and the scale its marks are drawn with. One unit is one CSS pixel. */
+function frame(doc, series, size, format) {
+    const { width, height } = size;
+    const values = series.points.map((point) => point.value ?? 0);
+    const ticks = niceTicks(Math.min(...values), Math.max(...values));
+    const low = ticks[0] ?? 0;
+    const span = (ticks.at(-1) ?? 1) - low || 1;
+    const plot = height - TOP - BOTTOM;
+    const plotWidth = Math.max(width - LEFT - RIGHT, 1);
+    const count = series.points.length;
+    const band = plotWidth / Math.max(count, 1);
+    const y = (value) => TOP + plot * (1 - (value - low) / span);
+    const x = (index) => LEFT + band * (index + 0.5);
+    const root = svg(doc, 'svg', {
+        viewBox: `0 0 ${width} ${height}`,
+        width: '100%',
+        height,
+        role: 'img',
+        'aria-label': `${series.label}, ${NL.points(count)}`,
+    });
+    for (const tick of ticks) {
+        root.append(svg(doc, 'line', { class: 'grid', x1: LEFT, x2: width - RIGHT, y1: y(tick), y2: y(tick) }), svg(doc, 'text', { class: 'tick', x: LEFT - 6, y: y(tick) + 4 }, format(tick, true)));
+    }
+    const ticksText = series.points.map((point) => point.tick ?? point.label);
+    const chars = Math.max(1, ...ticksText.map((text) => text.length));
+    const every = series.categories === true
+        ? 1
+        : Math.ceil(count / Math.max(1, Math.floor(plotWidth / (chars * CHAR + GAP))));
+    const shown = series.points.map((_, index) => index).filter((index) => index % every === 0);
+    const room = band * every - GAP / 2;
+    for (const index of shown) {
+        const at = { x: x(index), y: height - 6, left: LEFT, right: width - RIGHT };
+        root.append(xLabel(doc, ticksText[index] ?? '', room, at));
+    }
+    const title = (point) => svg(doc, 'title', {}, `${point.label}: ${point.value === null ? NL.emptyValue : format(point.value)}`);
+    return { root, band, x, y, title };
+}
+/** A line through the points (a gap where a value is null), with a dot and a title per point. */
+export function renderLine(doc, series, size, format) {
+    const { root, x, y, title } = frame(doc, series, size, format);
+    let d = '';
+    let pen = 'M';
+    series.points.forEach((point, index) => {
+        if (point.value === null) {
+            pen = 'M';
+            return;
+        }
+        d += `${pen}${x(index).toFixed(1)} ${y(point.value).toFixed(1)}`;
+        pen = 'L';
+    });
+    root.append(svg(doc, 'path', { class: 's1', d }));
+    series.points.forEach((point, index) => {
+        if (point.value !== null) {
+            root.append(svg(doc, 'circle', { class: 's1', cx: x(index), cy: y(point.value), r: 3 }, title(point)));
+        }
+    });
+    return root;
+}
+/** One bar per point from the zero line, with a title each. */
+export function renderBars(doc, series, size, format) {
+    const { root, band, x, y, title } = frame(doc, series, size, format);
+    const width = band * 0.7;
+    series.points.forEach((point, index) => {
+        const top = y(Math.max(point.value ?? 0, 0));
+        const bottom = y(Math.min(point.value ?? 0, 0));
+        root.append(svg(doc, 'rect', { class: 's1', x: x(index) - width / 2, y: top, width, height: bottom - top }, title(point)));
+    });
+    return root;
+}

package/dist/ui/csv.d.ts

@@ -0,0 +1,9 @@
+import type { DmpRecord } from '../types.js';
+import type { Column } from './fields.js';
+/**
+ * The rows as CSV for a Dutch spreadsheet: a UTF-8 BOM, `;` between values, CRLF after every line, the column
+ * labels as header. Numbers get a decimal comma and no grouping, booleans ja/nee, dates stay as the API sent them.
+ */
+export declare function toCsv(columns: readonly Column[], rows: readonly DmpRecord[]): string;
+/** Saves `text` as `name` through a temporary object URL of the document's own window, revoked once handed over. */
+export declare function downloadCsv(doc: Document, name: string, text: string): void;

package/dist/ui/csv.js

@@ -0,0 +1,55 @@
+import { h } from './dom.js';
+import { NUMERIC_FORMATS, toNumber } from './format.js';
+import { NL } from './texts.js';
+// A spreadsheet runs a cell that starts with one of these as a formula.
+const FORMULA = /^[=+\-@\t\r]/;
+const QUOTE = /[;"\r\n]/;
+/** One value as spreadsheet text: a real number keeps its sign and gets a decimal comma, anything else is guarded. */
+function cell(value, format) {
+    if (value === null || value === undefined)
+        return '';
+    const n = NUMERIC_FORMATS.includes(format) ? toNumber(value) : null;
+    let text;
+    if (n !== null) {
+        // A genuine number cannot be a formula, so a negative one stays a number in the sheet. Plain digits, never
+        // an exponent (1e21) a spreadsheet would read differently.
+        const plain = String(n).includes('e')
+            ? n.toLocaleString('en-US', { useGrouping: false, maximumFractionDigits: 20 })
+            : String(n);
+        text = plain.replace('.', ',');
+    }
+    else {
+        if (typeof value === 'boolean')
+            text = value ? NL.yes.toLowerCase() : NL.no.toLowerCase();
+        else if (typeof value === 'object')
+            text = JSON.stringify(value);
+        else
+            text = String(value);
+        if (FORMULA.test(text))
+            text = `'${text}`;
+    }
+    return QUOTE.test(text) ? `"${text.replace(/"/g, '""')}"` : text;
+}
+/**
+ * The rows as CSV for a Dutch spreadsheet: a UTF-8 BOM, `;` between values, CRLF after every line, the column
+ * labels as header. Numbers get a decimal comma and no grouping, booleans ja/nee, dates stay as the API sent them.
+ */
+export function toCsv(columns, rows) {
+    const lines = [
+        columns.map((column) => cell(column.label, 'text')),
+        ...rows.map((row) => columns.map((column) => cell(row[column.name], column.format))),
+    ];
+    return `\uFEFF${lines.map((line) => `${line.join(';')}\r\n`).join('')}`;
+}
+/** Saves `text` as `name` through a temporary object URL of the document's own window, revoked once handed over. */
+export function downloadCsv(doc, name, text) {
+    const view = doc.defaultView;
+    const blob = new (view?.Blob ?? Blob)([text], { type: 'text/csv;charset=utf-8' });
+    const url = (view?.URL ?? URL).createObjectURL(blob);
+    const link = h(doc, 'a', { href: url, download: name, hidden: true });
+    doc.body.appendChild(link);
+    link.click();
+    link.remove();
+    // Revoking in the same task can cancel the download in some browsers.
+    (view?.setTimeout ?? setTimeout)(() => (view?.URL ?? URL).revokeObjectURL(url), 0);
+}

package/dist/ui/define.d.ts

@@ -0,0 +1,24 @@
+import type { CubeAppSession } from '../app.js';
+/** The window the blocks are defined in: the page's own, or a test DOM's. Nothing is read from globals. */
+export interface BlockScope {
+    customElements: CustomElementRegistry;
+    HTMLElement: typeof HTMLElement;
+    document: Document;
+    CSSStyleSheet: typeof CSSStyleSheet;
+    setTimeout: typeof setTimeout;
+    clearTimeout: typeof clearTimeout;
+    location?: Location;
+    FontFace?: typeof FontFace;
+    /** Lets a chart redraw at its new width; without it a chart keeps the width it was drawn at. */
+    ResizeObserver?: typeof ResizeObserver;
+}
+export interface DefineOptions {
+    /** Where blocks get their session. Default `CubeApp.ready`: the session the app connected, or a default one. */
+    session?: () => Promise<CubeAppSession>;
+}
+/**
+ * Defines every `cube-*` element in `scope` (default: this window) and applies the theme to its document.
+ * Without `customElements` (an old engine, a script run outside a page) it does nothing. A tag already defined
+ * is left as it is, so calling it twice is harmless.
+ */
+export declare function defineBlocks(scope?: BlockScope, options?: DefineOptions): void;

package/dist/ui/define.js

@@ -0,0 +1,107 @@
+import { blockBase } from './block.js';
+import { appShellBlock } from './blocks/app-shell.js';
+import { boardBlock } from './blocks/board.js';
+import { calcBlock } from './blocks/calc.js';
+import { chartBlock } from './blocks/chart.js';
+import { detailBlock } from './blocks/detail.js';
+import { fieldElement } from './blocks/field.js';
+import { formBlock } from './blocks/form.js';
+import { gapListBlock } from './blocks/gap-list.js';
+import { kpiBlock } from './blocks/kpi.js';
+import { periodPickerBlock } from './blocks/period-picker.js';
+import { stateBlock } from './blocks/state.js';
+import { tableBlock } from './blocks/table.js';
+import { topBlock } from './blocks/top.js';
+import { currentTheme, onTheme, themeCss } from './theme.js';
+/** Every block, by tag. Later steps add theirs here; each tag also has its entry in BLOCK_SPECS. */
+const BLOCKS = [
+    ['cube-state', stateBlock],
+    ['cube-app-shell', appShellBlock],
+    ['cube-period-picker', periodPickerBlock],
+    ['cube-kpi', kpiBlock],
+    ['cube-chart', chartBlock],
+    ['cube-top', topBlock],
+    ['cube-table', tableBlock],
+    ['cube-detail', detailBlock],
+    ['cube-form', formBlock],
+    ['cube-calc', calcBlock],
+    ['cube-board', boardBlock],
+    ['cube-gap-list', gapListBlock],
+];
+/** The theme sheet per document: defining again replaces it, a theme change rewrites it, it never stacks. */
+const applied = new WeakMap();
+/** `<cube-page>`: a light-DOM container the shell shows or hides. It has no behaviour of its own. */
+function pageElement(scope) {
+    return class CubePage extends scope.HTMLElement {
+    };
+}
+function loadFonts(scope, theme, seen) {
+    // Set-like at runtime; the DOM lib types its add() only under DOM.Iterable, which this build leaves out.
+    const fonts = scope.document.fonts;
+    if (theme.fontFamily === null || scope.FontFace === undefined || fonts === undefined)
+        return;
+    for (const file of theme.fontFiles) {
+        const key = `${theme.fontFamily}|${file.src}|${file.weight ?? ''}|${file.style ?? ''}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        try {
+            const descriptors = { style: file.style ?? 'normal' };
+            if (file.weight !== undefined)
+                descriptors.weight = file.weight;
+            // The src was validated in resolveTheme: same-origin, no quote, parenthesis or whitespace.
+            const face = new scope.FontFace(theme.fontFamily, `url("${file.src}")`, descriptors);
+            fonts.add(face);
+            face.load().catch(() => undefined);
+        }
+        catch {
+            // A font that cannot be added only costs the typeface: the fallback stack applies.
+        }
+    }
+}
+function applyTheme(scope) {
+    const doc = scope.document;
+    const previous = applied.get(doc);
+    previous?.stop();
+    const sheet = new scope.CSSStyleSheet();
+    const fonts = previous?.fonts ?? new Set();
+    const paint = (theme) => {
+        try {
+            sheet.replaceSync(themeCss(theme));
+            loadFonts(scope, theme, fonts);
+        }
+        catch {
+            // A document whose window has gone (a closed test DOM) keeps its last theme.
+        }
+    };
+    paint(currentTheme());
+    doc.adoptedStyleSheets = [...doc.adoptedStyleSheets.filter((s) => s !== previous?.sheet), sheet];
+    applied.set(doc, { sheet, stop: onTheme(paint), fonts });
+}
+/**
+ * Defines every `cube-*` element in `scope` (default: this window) and applies the theme to its document.
+ * Without `customElements` (an old engine, a script run outside a page) it does nothing. A tag already defined
+ * is left as it is, so calling it twice is harmless.
+ */
+export function defineBlocks(scope, options = {}) {
+    const target = scope ?? globalThis;
+    if (target.customElements === undefined || target.HTMLElement === undefined || target.document === undefined) {
+        return;
+    }
+    const window = target;
+    const registry = window.customElements;
+    applyTheme(window);
+    const Base = blockBase(window, options);
+    for (const [tag, factory] of BLOCKS) {
+        if (registry.get(tag) === undefined) {
+            registry.define(tag, factory(Base, window));
+        }
+    }
+    if (registry.get('cube-page') === undefined)
+        registry.define('cube-page', pageElement(window));
+    // Config elements: each tag needs a class of its own, so each gets a fresh one.
+    for (const tag of ['cube-field', 'cube-input', 'cube-result', 'cube-column']) {
+        if (registry.get(tag) === undefined)
+            registry.define(tag, fieldElement(window));
+    }
+}

package/dist/ui/dom.d.ts

@@ -0,0 +1,12 @@
+type AttrValue = string | boolean | null | undefined | EventListener;
+type Child = Node | string | null | undefined | false;
+/**
+ * An element with attributes and children. `true` sets an empty attribute; `false`, null and undefined leave it
+ * out; a function under `on<event>` becomes a listener. Strings become text nodes. A `style` attribute and an
+ * `on<event>` attribute (anything but a listener) throw: the CSP forbids both, and they would run as code or style.
+ */
+export declare function h(doc: Document, tag: string, attrs?: Record<string, AttrValue>, ...children: Child[]): HTMLElement;
+/** An SVG element (namespaced, so it renders); numbers become attribute strings. Refuses `style` and `on*`. */
+export declare function svg(doc: Document, tag: string, attrs?: Record<string, string | number>, ...children: Array<Node | string>): SVGElement;
+export declare function clear(node: Node): void;
+export {};

package/dist/ui/dom.js

@@ -0,0 +1,57 @@
+// The UI builds every node through these helpers: no HTML string is ever parsed, so row data cannot become markup.
+import { NL } from './texts.js';
+const SVG_NS = 'http://www.w3.org/2000/svg';
+/**
+ * An element with attributes and children. `true` sets an empty attribute; `false`, null and undefined leave it
+ * out; a function under `on<event>` becomes a listener. Strings become text nodes. A `style` attribute and an
+ * `on<event>` attribute (anything but a listener) throw: the CSP forbids both, and they would run as code or style.
+ */
+export function h(doc, tag, attrs = {}, ...children) {
+    const el = doc.createElement(tag);
+    for (const [name, value] of Object.entries(attrs)) {
+        refuseUnsafe(name, value === true || typeof value === 'string');
+        if (typeof value === 'function') {
+            el.addEventListener(name.replace(/^on/, ''), value);
+        }
+        else if (value === true) {
+            el.setAttribute(name, '');
+        }
+        else if (typeof value === 'string') {
+            el.setAttribute(name, value);
+        }
+    }
+    append(doc, el, children);
+    return el;
+}
+/** An SVG element (namespaced, so it renders); numbers become attribute strings. Refuses `style` and `on*`. */
+export function svg(doc, tag, attrs = {}, ...children) {
+    const el = doc.createElementNS(SVG_NS, tag);
+    for (const [name, value] of Object.entries(attrs)) {
+        refuseUnsafe(name, true);
+        el.setAttribute(name, String(value));
+    }
+    append(doc, el, children);
+    return el;
+}
+/** `style` in any form, and an `on<event>` that would become an attribute rather than a listener. */
+function refuseUnsafe(name, setsAttribute) {
+    const lower = name.toLowerCase();
+    if (lower === 'style' || (setsAttribute && lower.startsWith('on'))) {
+        throw new TypeError(NL.invalid.attribute(name));
+    }
+}
+export function clear(node) {
+    while (node.firstChild !== null) {
+        node.removeChild(node.firstChild);
+    }
+}
+function append(doc, el, children) {
+    for (const child of children) {
+        if (typeof child === 'string') {
+            el.appendChild(doc.createTextNode(child));
+        }
+        else if (child !== null && child !== undefined && child !== false) {
+            el.appendChild(child);
+        }
+    }
+}

package/dist/ui/fields.d.ts

@@ -0,0 +1,39 @@
+import type { DmpRecord } from '../types.js';
+import { type Format } from './format.js';
+import type { FieldInfo, ResourceSchema } from './schema.js';
+export interface FieldOption {
+    value: string;
+    label: string;
+}
+/** What one `<cube-field>` says about a field. Null means "not said": the schema or the values decide. */
+export interface FieldConfig {
+    name: string;
+    label: string | null;
+    format: Format | null;
+    multiline: boolean;
+    options: FieldOption[] | null;
+    hidden: boolean;
+}
+/** One field as a table, detail or form shows it. */
+export interface Column {
+    name: string;
+    label: string;
+    format: Format;
+    field: FieldInfo | undefined;
+    config: FieldConfig | undefined;
+}
+/** The choices for a field: the cube-field's `options`, else the schema's enum; null when neither gives any. */
+export declare function choicesFor(column: Column): FieldOption[] | null;
+/** A comma-separated list of field names, or null when it names none. */
+export declare function fieldList(raw: string | null): string[] | null;
+/** `laag=Laag,hoog=Hoog`, or `a,b,c` where each value is its own label. */
+export declare function parseOptions(raw: string | null): FieldOption[] | null;
+/** The `<cube-field>` elements directly under `host`, by name; one without a name is ignored. */
+export declare function readFieldConfigs(host: Element): Map<string, FieldConfig>;
+/** What a field is called on screen: its cube-field label, else its name made readable. */
+export declare function fieldLabel(configs: Map<string, FieldConfig>, name: string): string;
+/**
+ * The fields to show, in order: the `fields` list, else the schema's summary, else the keys of a sample row.
+ * Fields a cube-field hides are left out. Label and format come from the cube-field, else from name and schema.
+ */
+export declare function columnsFor(schema: ResourceSchema | null, list: string[] | null, configs: Map<string, FieldConfig>, sample?: DmpRecord): Column[];

package/dist/ui/fields.js

@@ -0,0 +1,73 @@
+import { AUTHOR_HIDDEN } from './blocks/field.js';
+import { humanize, inferFormat } from './format.js';
+/** The choices for a field: the cube-field's `options`, else the schema's enum; null when neither gives any. */
+export function choicesFor(column) {
+    const values = column.field?.enum ?? null;
+    return column.config?.options ?? (values === null ? null : values.map((value) => ({ value, label: value })));
+}
+const FORMATS = ['text', 'number', 'integer', 'currency', 'percent', 'date', 'datetime', 'boolean'];
+/** A comma-separated list of field names, or null when it names none. */
+export function fieldList(raw) {
+    const names = (raw ?? '').split(',').map((name) => name.trim()).filter((name) => name !== '');
+    return names.length > 0 ? names : null;
+}
+/** `laag=Laag,hoog=Hoog`, or `a,b,c` where each value is its own label. */
+export function parseOptions(raw) {
+    if (raw === null)
+        return null;
+    const options = raw
+        .split(',')
+        .map((part) => {
+        const at = part.indexOf('=');
+        const value = (at < 0 ? part : part.slice(0, at)).trim();
+        const label = at < 0 ? value : part.slice(at + 1).trim();
+        return { value, label: label === '' ? value : label };
+    })
+        .filter((option) => option.value !== '');
+    return options.length > 0 ? options : null;
+}
+/** The `<cube-field>` elements directly under `host`, by name; one without a name is ignored. */
+export function readFieldConfigs(host) {
+    const configs = new Map();
+    for (const child of Array.from(host.children)) {
+        const name = child.getAttribute('name')?.trim() ?? '';
+        if (child.localName !== 'cube-field' || name === '')
+            continue;
+        const format = child.getAttribute('format');
+        const authorHidden = child[AUTHOR_HIDDEN];
+        configs.set(name, {
+            name,
+            label: child.getAttribute('label'),
+            format: format !== null && FORMATS.includes(format) ? format : null,
+            multiline: child.hasAttribute('multiline'),
+            options: parseOptions(child.getAttribute('options')),
+            hidden: authorHidden ?? child.hasAttribute('hidden'),
+        });
+    }
+    return configs;
+}
+/** What a field is called on screen: its cube-field label, else its name made readable. */
+export function fieldLabel(configs, name) {
+    return configs.get(name)?.label ?? humanize(name);
+}
+/**
+ * The fields to show, in order: the `fields` list, else the schema's summary, else the keys of a sample row.
+ * Fields a cube-field hides are left out. Label and format come from the cube-field, else from name and schema.
+ */
+export function columnsFor(schema, list, configs, sample) {
+    const summary = schema !== null && schema.summary.length > 0 ? schema.summary : null;
+    const names = list ?? summary ?? (sample === undefined ? [] : Object.keys(sample));
+    return names
+        .filter((name) => configs.get(name)?.hidden !== true)
+        .map((name) => {
+        const field = schema?.fields.find((candidate) => candidate.name === name);
+        const config = configs.get(name);
+        return {
+            name,
+            label: fieldLabel(configs, name),
+            format: config?.format ?? inferFormat(field, sample?.[name]),
+            field,
+            config,
+        };
+    });
+}

package/dist/ui/format.d.ts

@@ -0,0 +1,44 @@
+import type { FieldInfo } from './schema.js';
+export type Format = 'text' | 'number' | 'integer' | 'currency' | 'percent' | 'date' | 'datetime' | 'boolean';
+/** The formats that hold a number: right-aligned, read and written as numbers. */
+export declare const NUMERIC_FORMATS: readonly Format[];
+export type Truncation = 'day' | 'week' | 'month' | 'quarter' | 'year';
+export interface FormatOptions {
+    /** ISO 4217 code; default EUR. */
+    currency?: string;
+    /** IANA zone for date-times; default the browser's own. */
+    timeZone?: string;
+    /** `1,2 mln.` instead of `1.234.567`. */
+    compact?: boolean;
+}
+type MeasureFn = 'count' | 'sum' | 'avg' | 'min' | 'max';
+/** A number, or a numeric string as the API may send a decimal (`"80.50"`); null for anything else. */
+export declare function toNumber(value: unknown): number | null;
+/** Text for one value in the house format: nl-NL numbers, amounts and dates; `—` for nothing. */
+export declare function formatValue(value: unknown, format: Format, options?: FormatOptions): string;
+/**
+ * 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 declare function formatBucket(key: string, truncation: Truncation, options?: {
+    short?: boolean;
+}): string;
+/** `sum(total)` → `{ fn: 'sum', field: 'total' }`; a bare `count` counts rows. */
+export declare function parseMeasure(measure: string): {
+    fn: MeasureFn;
+    field: string | null;
+};
+/** `placed_on.month` → `{ field: 'placed_on', truncation: 'month' }`. */
+export declare function parseDimension(by: string): {
+    field: string;
+    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 declare function inferFormat(field: FieldInfo | undefined, sample?: unknown): Format;
+/** A readable label from a field name: `placed_on` → `Placed on`, `customer_id` → `Customer`. */
+export declare function humanize(field: string): string;
+/** `YYYY-MM-DD` as local midnight (Date.parse would make it UTC midnight); anything else via Date.parse. */
+export declare function parseLocalDate(value: string): Date | null;
+/** The local calendar day as `YYYY-MM-DD`. */
+export declare function isoDate(date: Date): string;
+export {};