@bestagentkits/render 0.2.0 → 0.3.0

package/dist/data/format-value.js

@@ -0,0 +1,214 @@
+/**
+ * Deterministic, locale-free value formatting.
+ *
+ * Every data-bound block formats numbers, dates and units through this one
+ * function, so a value reads the same in a table cell, a chart label and a
+ * metric. Nothing here consults `Intl`, the host locale, or the clock: grouping
+ * uses a fixed comma, months use fixed English names, and rounding uses
+ * `toFixed`, which is specified exactly by ECMAScript.
+ */
+export const VALUE_FORMATS = [
+    'text',
+    'number',
+    'integer',
+    'compact',
+    'percent',
+    'currency',
+    'duration',
+    'bytes',
+    'date',
+];
+export const CURRENCIES = [
+    'USD',
+    'EUR',
+    'GBP',
+    'JPY',
+    'CNY',
+    'INR',
+    'VND',
+    'AUD',
+    'CAD',
+    'CHF',
+    'SGD',
+    'KRW',
+];
+/** Prop-schema fields to spread into a column or axis schema. */
+export const FORMAT_FIELDS = {
+    format: {
+        kind: 'string',
+        enum: VALUE_FORMATS,
+        default: 'text',
+        description: 'percent takes 87 for 87%; duration takes milliseconds; date takes YYYY-MM-DD.',
+    },
+    unit: { kind: 'string', maxLength: 12, description: 'Appended to number-like values.' },
+    currency: { kind: 'string', enum: CURRENCIES, default: 'USD' },
+    decimals: { kind: 'number', integer: true, min: 0, max: 4 },
+};
+/** Shown for a null value or a missing field. */
+export const EMPTY_VALUE = '—';
+const CURRENCY_SYMBOLS = {
+    USD: { symbol: '$', decimals: 2 },
+    EUR: { symbol: '€', decimals: 2 },
+    GBP: { symbol: '£', decimals: 2 },
+    JPY: { symbol: '¥', decimals: 0 },
+    CNY: { symbol: 'CN¥', decimals: 2 },
+    INR: { symbol: '₹', decimals: 2 },
+    VND: { symbol: '₫', decimals: 0 },
+    AUD: { symbol: 'A$', decimals: 2 },
+    CAD: { symbol: 'CA$', decimals: 2 },
+    CHF: { symbol: 'CHF ', decimals: 2 },
+    SGD: { symbol: 'S$', decimals: 2 },
+    KRW: { symbol: '₩', decimals: 0 },
+};
+const MONTHS = [
+    'Jan',
+    'Feb',
+    'Mar',
+    'Apr',
+    'May',
+    'Jun',
+    'Jul',
+    'Aug',
+    'Sep',
+    'Oct',
+    'Nov',
+    'Dec',
+];
+const ISO_DATE = /^(\d{4})-(\d{2})-(\d{2})$/u;
+const PLAIN_NUMBER = /^-?\d+(?:\.\d+)?$/u;
+/**
+ * A number with grouped digits. With `fixed`, exactly that many decimals;
+ * otherwise rounded to `maxDecimals` with trailing zeros trimmed.
+ */
+export function groupedNumber(value, maxDecimals, fixed) {
+    if (!Number.isFinite(value))
+        return String(value);
+    if (Math.abs(value) >= 1e21)
+        return String(value);
+    const places = fixed ?? maxDecimals;
+    let text = Math.abs(value).toFixed(places);
+    if (fixed === undefined && text.includes('.'))
+        text = text.replace(/\.?0+$/u, '');
+    const [whole = '0', fraction] = text.split('.');
+    const grouped = whole.replace(/\B(?=(\d{3})+(?!\d))/gu, ',');
+    const body = fraction === undefined ? grouped : `${grouped}.${fraction}`;
+    // A value that rounds to zero carries no sign.
+    const negative = value < 0 && /[1-9]/u.test(body);
+    return `${negative ? '-' : ''}${body}`;
+}
+function withUnit(text, unit) {
+    return unit === undefined || unit === '' ? text : `${text} ${unit}`;
+}
+/** Scale a value through a unit ladder, carrying to the next step after rounding. */
+function scaled(value, ladder, decimals, defaultDecimals) {
+    const magnitude = Math.abs(value);
+    let step = 0;
+    for (let index = ladder.length - 1; index >= 0; index -= 1) {
+        if (magnitude >= (ladder[index]?.factor ?? 1)) {
+            step = index;
+            break;
+        }
+    }
+    for (;;) {
+        const entry = ladder[step] ?? { factor: 1, suffix: '' };
+        const amount = value / entry.factor;
+        const text = groupedNumber(amount, defaultDecimals, decimals);
+        const next = ladder[step + 1];
+        const reached = Math.abs(Number(text.replace(/,/gu, '')));
+        if (next !== undefined && reached * entry.factor >= next.factor) {
+            step += 1;
+            continue;
+        }
+        return { amount, text, suffix: entry.suffix };
+    }
+}
+const COMPACT_LADDER = [
+    { factor: 1, suffix: '' },
+    { factor: 1e3, suffix: 'k' },
+    { factor: 1e6, suffix: 'M' },
+    { factor: 1e9, suffix: 'B' },
+    { factor: 1e12, suffix: 'T' },
+];
+const BYTES_LADDER = [
+    { factor: 1, suffix: ' B' },
+    { factor: 1e3, suffix: ' kB' },
+    { factor: 1e6, suffix: ' MB' },
+    { factor: 1e9, suffix: ' GB' },
+    { factor: 1e12, suffix: ' TB' },
+];
+const DURATION_LADDER = [
+    { factor: 1, suffix: ' ms' },
+    { factor: 1e3, suffix: ' s' },
+    { factor: 6e4, suffix: ' min' },
+    { factor: 3.6e6, suffix: ' h' },
+];
+function formatDate(value) {
+    const match = ISO_DATE.exec(value);
+    if (match === null)
+        return value;
+    const year = Number(match[1]);
+    const month = Number(match[2]);
+    const day = Number(match[3]);
+    const leap = (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+    const lengths = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+    const name = MONTHS[month - 1];
+    if (name === undefined || day < 1 || day > (lengths[month - 1] ?? 0))
+        return value;
+    return `${name} ${day}, ${year}`;
+}
+function formatNumber(value, spec, format) {
+    const { decimals, unit } = spec;
+    switch (format) {
+        case 'integer':
+            return withUnit(groupedNumber(Math.round(value), 0, 0), unit);
+        case 'compact': {
+            const result = scaled(value, COMPACT_LADDER, decimals, 1);
+            return withUnit(`${result.text}${result.suffix}`, unit);
+        }
+        case 'percent':
+            return `${groupedNumber(value, 1, decimals)}%`;
+        case 'currency': {
+            const code = CURRENCIES.includes(spec.currency ?? '')
+                ? spec.currency
+                : 'USD';
+            const { symbol, decimals: places } = CURRENCY_SYMBOLS[code];
+            const text = groupedNumber(Math.abs(value), places, decimals ?? places);
+            const negative = value < 0 && /[1-9]/u.test(text);
+            return `${negative ? '-' : ''}${symbol}${text}`;
+        }
+        case 'duration': {
+            const result = scaled(value, DURATION_LADDER, decimals, 1);
+            return `${result.text}${result.suffix}`;
+        }
+        case 'bytes': {
+            const result = scaled(value, BYTES_LADDER, decimals, 1);
+            return `${result.text}${result.suffix}`;
+        }
+        default:
+            return withUnit(groupedNumber(value, 2, decimals), unit);
+    }
+}
+/**
+ * Format one value for display. Null reads as an em dash; booleans read as
+ * Yes/No; a numeric string is formatted like the number it spells; any other
+ * string is returned unchanged (dates excepted, which must be `YYYY-MM-DD`).
+ */
+export function formatValue(value, spec = {}) {
+    const format = spec.format ?? 'text';
+    if (value === null)
+        return EMPTY_VALUE;
+    if (typeof value === 'boolean')
+        return value ? 'Yes' : 'No';
+    if (format === 'date')
+        return typeof value === 'string' ? formatDate(value) : String(value);
+    if (format === 'text') {
+        return typeof value === 'number' ? withUnit(String(value), spec.unit) : value;
+    }
+    if (typeof value === 'string') {
+        if (!PLAIN_NUMBER.test(value.trim()))
+            return value;
+        return formatNumber(Number(value.trim()), spec, format);
+    }
+    return formatNumber(value, spec, format);
+}
+//# sourceMappingURL=format-value.js.map

package/dist/data/format-value.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-value.js","sourceRoot":"","sources":["../../src/data/format-value.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,MAAM;IACN,QAAQ;IACR,SAAS;IACT,SAAS;IACT,SAAS;IACT,UAAU;IACV,UAAU;IACV,OAAO;IACP,MAAM;CACE,CAAC;AAGX,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;CACG,CAAC;AAYX,iEAAiE;AACjE,MAAM,CAAC,MAAM,aAAa,GAA+B;IACvD,MAAM,EAAE;QACN,IAAI,EAAE,QAAQ;QACd,IAAI,EAAE,aAAa;QACnB,OAAO,EAAE,MAAM;QACf,WAAW,EAAE,+EAA+E;KAC7F;IACD,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,EAAE,EAAE,WAAW,EAAE,iCAAiC,EAAE;IACvF,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,KAAK,EAAE;IAC9D,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE;CAC5D,CAAC;AAEF,iDAAiD;AACjD,MAAM,CAAC,MAAM,WAAW,GAAG,GAAG,CAAC;AAE/B,MAAM,gBAAgB,GAAqE;IACzF,GAAG,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,EAAE;IACjC,GAAG,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,EAAE;IACjC,GAAG,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,EAAE;IACjC,GAAG,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,EAAE;IACjC,GAAG,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,EAAE;IACnC,GAAG,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,EAAE;IACjC,GAAG,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,EAAE;IACjC,GAAG,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,EAAE;IAClC,GAAG,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,EAAE;IACnC,GAAG,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,EAAE;IACpC,GAAG,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,EAAE;IAClC,GAAG,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,EAAE;CAClC,CAAC;AAEF,MAAM,MAAM,GAAG;IACb,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;CACG,CAAC;AAEX,MAAM,QAAQ,GAAG,4BAA4B,CAAC;AAC9C,MAAM,YAAY,GAAG,oBAAoB,CAAC;AAE1C;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,KAAa,EAAE,WAAmB,EAAE,KAAc;IAC9E,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IAClD,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IAClD,MAAM,MAAM,GAAG,KAAK,IAAI,WAAW,CAAC;IACpC,IAAI,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC3C,IAAI,KAAK,KAAK,SAAS,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;IAClF,MAAM,CAAC,KAAK,GAAG,GAAG,EAAE,QAAQ,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAChD,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,wBAAwB,EAAE,GAAG,CAAC,CAAC;IAC7D,MAAM,IAAI,GAAG,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,IAAI,QAAQ,EAAE,CAAC;IACzE,+CAA+C;IAC/C,MAAM,QAAQ,GAAG,KAAK,GAAG,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAClD,OAAO,GAAG,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,CAAC;AACzC,CAAC;AAED,SAAS,QAAQ,CAAC,IAAY,EAAE,IAAwB;IACtD,OAAO,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC;AACtE,CAAC;AAED,qFAAqF;AACrF,SAAS,MAAM,CACb,KAAa,EACb,MAAqD,EACrD,QAA4B,EAC5B,eAAuB;IAEvB,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAClC,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,IAAI,KAAK,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QAC3D,IAAI,SAAS,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,MAAM,IAAI,CAAC,CAAC,EAAE,CAAC;YAC9C,IAAI,GAAG,KAAK,CAAC;YACb,MAAM;QACR,CAAC;IACH,CAAC;IACD,SAAS,CAAC;QACR,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;QACxD,MAAM,MAAM,GAAG,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC;QACpC,MAAM,IAAI,GAAG,aAAa,CAAC,MAAM,EAAE,eAAe,EAAE,QAAQ,CAAC,CAAC;QAC9D,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC;QAC9B,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;QAC1D,IAAI,IAAI,KAAK,SAAS,IAAI,OAAO,GAAG,KAAK,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChE,IAAI,IAAI,CAAC,CAAC;YACV,SAAS;QACX,CAAC;QACD,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC;IAChD,CAAC;AACH,CAAC;AAED,MAAM,cAAc,GAAG;IACrB,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE;IACzB,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE;IAC5B,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE;IAC5B,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE;IAC5B,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE;CACrB,CAAC;AACX,MAAM,YAAY,GAAG;IACnB,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE;IAC3B,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE;IAC9B,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE;IAC9B,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE;IAC9B,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE;CACvB,CAAC;AACX,MAAM,eAAe,GAAG;IACtB,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE;IAC5B,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE;IAC7B,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE;IAC/B,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE;CACvB,CAAC;AAEX,SAAS,UAAU,CAAC,KAAa;IAC/B,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACnC,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IACjC,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9B,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/B,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7B,MAAM,IAAI,GAAG,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI,GAAG,GAAG,KAAK,CAAC,CAAC,IAAI,IAAI,GAAG,GAAG,KAAK,CAAC,CAAC;IACtE,MAAM,OAAO,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;IAC7E,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;IAC/B,IAAI,IAAI,KAAK,SAAS,IAAI,GAAG,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,OAAO,CAAC,KAAK,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IACnF,OAAO,GAAG,IAAI,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;AACnC,CAAC;AAED,SAAS,YAAY,CAAC,KAAa,EAAE,IAAgB,EAAE,MAAmB;IACxE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC;IAChC,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,SAAS;YACZ,OAAO,QAAQ,CAAC,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;QAChE,KAAK,SAAS,CAAC,CAAC,CAAC;YACf,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC;YAC1D,OAAO,QAAQ,CAAC,GAAG,MAAM,CAAC,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,EAAE,IAAI,CAAC,CAAC;QAC1D,CAAC;QACD,KAAK,SAAS;YACZ,OAAO,GAAG,aAAa,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,CAAC,GAAG,CAAC;QACjD,KAAK,UAAU,CAAC,CAAC,CAAC;YAChB,MAAM,IAAI,GAAI,UAAgC,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC;gBAC1E,CAAC,CAAE,IAAI,CAAC,QAAqB;gBAC7B,CAAC,CAAC,KAAK,CAAC;YACV,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;YAC5D,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,QAAQ,IAAI,MAAM,CAAC,CAAC;YACxE,MAAM,QAAQ,GAAG,KAAK,GAAG,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAClD,OAAO,GAAG,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,MAAM,GAAG,IAAI,EAAE,CAAC;QAClD,CAAC;QACD,KAAK,UAAU,CAAC,CAAC,CAAC;YAChB,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,eAAe,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC;YAC3D,OAAO,GAAG,MAAM,CAAC,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC;QAC1C,CAAC;QACD,KAAK,OAAO,CAAC,CAAC,CAAC;YACb,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC;YACxD,OAAO,GAAG,MAAM,CAAC,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC;QAC1C,CAAC;QACD;YACE,OAAO,QAAQ,CAAC,aAAa,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,CAAC,EAAE,IAAI,CAAC,CAAC;IAC7D,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,KAAiB,EAAE,OAAmB,EAAE;IAClE,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC;IACrC,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,WAAW,CAAC;IACvC,IAAI,OAAO,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;IAC5D,IAAI,MAAM,KAAK,MAAM;QAAE,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC5F,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;QACtB,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IAChF,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;YAAE,OAAO,KAAK,CAAC;QACnD,OAAO,YAAY,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IAC1D,CAAC;IACD,OAAO,YAAY,CAAC,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;AAC3C,CAAC"}

package/dist/data/resolve-block-data.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Per-block data binding: `dataRef` or inline `data`, plus an optional
+ * `transform`, materialized once at normalize time.
+ *
+ * The block's renderer and its `check()` only ever see the materialized rows and
+ * the field list, so every block reads data the same way and every unknown
+ * field is reported with the path the author wrote and the fields that exist.
+ */
+import { type DiagnosticBag } from '../diagnostics.js';
+import { type DataRow, type MaterializedData } from './dataset-types.js';
+export { fieldValue } from './dataset-types.js';
+export interface BlockDataInput {
+    dataRef?: unknown;
+    data?: unknown;
+    transform?: unknown;
+}
+/** Diagnostic for an unknown field reference; `details.allowed` lists the fields. */
+export declare function reportUnknownField(field: string, data: MaterializedData, path: string, bag: DiagnosticBag, nodeId?: string): void;
+/**
+ * Resolve a block's data. Returns undefined when the block binds no data or the
+ * binding is invalid (the problem is reported).
+ */
+export declare function resolveBlockData(input: BlockDataInput, datasets: Record<string, DataRow[]>, path: string, bag: DiagnosticBag): MaterializedData | undefined;
+//# sourceMappingURL=resolve-block-data.d.ts.map

package/dist/data/resolve-block-data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-block-data.d.ts","sourceRoot":"","sources":["../../src/data/resolve-block-data.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,KAAK,aAAa,EAAsB,MAAM,mBAAmB,CAAC;AAG3E,OAAO,EAAE,KAAK,OAAO,EAA0B,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAWjG,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEhD,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,qFAAqF;AACrF,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,gBAAgB,EACtB,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,aAAa,EAClB,MAAM,CAAC,EAAE,MAAM,GACd,IAAI,CAQN;AAiHD;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,cAAc,EACrB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,EACnC,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,aAAa,GACjB,gBAAgB,GAAG,SAAS,CA4D9B"}

package/dist/data/resolve-block-data.js

@@ -0,0 +1,190 @@
+/**
+ * Per-block data binding: `dataRef` or inline `data`, plus an optional
+ * `transform`, materialized once at normalize time.
+ *
+ * The block's renderer and its `check()` only ever see the materialized rows and
+ * the field list, so every block reads data the same way and every unknown
+ * field is reported with the path the author wrote and the fields that exist.
+ */
+import { pathIndex, pathKey } from '../diagnostics.js';
+import { isPlainObject } from '../json.js';
+import { validateProp } from '../registry/prop-schema.js';
+import { fieldsOf, isDataScalar } from './dataset-types.js';
+import { aggregateField, applyTransform, FILTER_OPERATORS, sortKeys, TRANSFORM_PROP_SCHEMA, } from './transform-pipeline.js';
+import { validateRows } from './validate-datasets.js';
+export { fieldValue } from './dataset-types.js';
+/** Diagnostic for an unknown field reference; `details.allowed` lists the fields. */
+export function reportUnknownField(field, data, path, bag, nodeId) {
+    bag.add({
+        code: 'SPEC_VALIDATION_ERROR',
+        path,
+        message: `unknown field "${field}"${data.source === null ? '' : ` in dataset "${data.source}"`}`,
+        details: { field, allowed: [...data.fields] },
+        ...(nodeId === undefined ? {} : { nodeId }),
+    });
+}
+/** Report `field` at `path` unless the stage's field list contains it. */
+function requireField(field, fields, source, path, bag) {
+    if (fields.includes(field))
+        return true;
+    reportUnknownField(field, { source, fields: [...fields], rows: [] }, path, bag);
+    return false;
+}
+/**
+ * Check a schema-valid transform against the fields each stage can see, and
+ * the rules the prop schema cannot express. Returns false when any problem was
+ * reported, in which case the transform is not applied.
+ */
+function checkTransform(spec, sourceFields, source, path, bag) {
+    let ok = true;
+    let fields = [...sourceFields];
+    spec.filter?.forEach((clause, index) => {
+        const clausePath = pathIndex(pathKey(path, 'filter'), index);
+        const operators = FILTER_OPERATORS.filter((operator) => clause[operator] !== undefined);
+        if (operators.length !== 1) {
+            ok = false;
+            bag.add({
+                code: 'SPEC_VALIDATION_ERROR',
+                path: clausePath,
+                message: `a filter clause needs exactly one operator, found ${operators.length}`,
+                details: { allowed: [...FILTER_OPERATORS] },
+            });
+        }
+        const scalarValues = [clause.equals, clause.notEquals, ...(clause.in ?? [])];
+        if (scalarValues.some((value) => value !== undefined && !isDataScalar(value))) {
+            ok = false;
+            bag.add({
+                code: 'SPEC_VALIDATION_ERROR',
+                path: clausePath,
+                message: 'filter values must be strings, numbers, booleans, or null',
+            });
+        }
+        if (!requireField(clause.field, fields, source, pathKey(clausePath, 'field'), bag))
+            ok = false;
+    });
+    const groupBy = spec.groupBy;
+    if (groupBy !== undefined) {
+        const groupPath = pathKey(path, 'groupBy');
+        if (!requireField(groupBy.field, fields, source, pathKey(groupPath, 'field'), bag))
+            ok = false;
+        if (groupBy.aggregate !== 'count') {
+            if (groupBy.value === undefined) {
+                ok = false;
+                bag.add({
+                    code: 'SPEC_VALIDATION_ERROR',
+                    path: pathKey(groupPath, 'value'),
+                    message: `aggregate "${groupBy.aggregate}" needs a numeric "value" field`,
+                    details: { allowed: [...fields] },
+                });
+            }
+            else if (!requireField(groupBy.value, fields, source, pathKey(groupPath, 'value'), bag)) {
+                ok = false;
+            }
+        }
+        const output = aggregateField(groupBy);
+        if (output === groupBy.field) {
+            ok = false;
+            bag.add({
+                code: 'SPEC_VALIDATION_ERROR',
+                path: pathKey(groupPath, 'as'),
+                message: `the aggregate field "${output}" would overwrite the group field; set "as"`,
+            });
+        }
+        fields = [groupBy.field, output];
+    }
+    const keys = sortKeys(spec.sort);
+    const sortIsList = Array.isArray(spec.sort);
+    keys.forEach((key, index) => {
+        const keyPath = sortIsList
+            ? pathKey(pathIndex(pathKey(path, 'sort'), index), 'by')
+            : pathKey(pathKey(path, 'sort'), 'by');
+        if (!requireField(key.by, fields, source, keyPath, bag))
+            ok = false;
+    });
+    if (spec.select !== undefined) {
+        const seen = new Set();
+        spec.select.forEach((field, index) => {
+            const selectPath = pathIndex(pathKey(path, 'select'), index);
+            if (seen.has(field)) {
+                ok = false;
+                bag.add({
+                    code: 'SPEC_VALIDATION_ERROR',
+                    path: selectPath,
+                    message: `field "${field}" is selected twice`,
+                });
+            }
+            seen.add(field);
+            if (!requireField(field, fields, source, selectPath, bag))
+                ok = false;
+        });
+        fields = [...spec.select];
+    }
+    return { ok, fields };
+}
+/**
+ * Resolve a block's data. Returns undefined when the block binds no data or the
+ * binding is invalid (the problem is reported).
+ */
+export function resolveBlockData(input, datasets, path, bag) {
+    const { dataRef, data, transform } = input;
+    if (dataRef !== undefined && data !== undefined) {
+        bag.add({
+            code: 'SPEC_VALIDATION_ERROR',
+            path: pathKey(path, 'dataRef'),
+            message: 'set either "dataRef" or "data", not both',
+        });
+        return undefined;
+    }
+    if (dataRef === undefined && data === undefined) {
+        if (transform !== undefined) {
+            bag.add({
+                code: 'SPEC_VALIDATION_ERROR',
+                path: pathKey(path, 'transform'),
+                message: 'a transform needs "dataRef" or "data" to apply to',
+            });
+        }
+        return undefined;
+    }
+    let source = null;
+    let rows;
+    if (dataRef !== undefined) {
+        const refPath = pathKey(path, 'dataRef');
+        const known = Object.keys(datasets);
+        if (typeof dataRef !== 'string') {
+            bag.add({ code: 'SPEC_VALIDATION_ERROR', path: refPath, message: 'expected a dataset name' });
+            return undefined;
+        }
+        const named = Object.hasOwn(datasets, dataRef) ? datasets[dataRef] : undefined;
+        if (named === undefined) {
+            bag.add({
+                code: 'SPEC_VALIDATION_ERROR',
+                path: refPath,
+                message: `unknown dataset "${dataRef}"`,
+                details: { dataRef, known },
+            });
+            return undefined;
+        }
+        source = dataRef;
+        rows = named;
+    }
+    else {
+        rows = validateRows(data, pathKey(path, 'data'), bag);
+    }
+    const sourceFields = fieldsOf(rows);
+    if (transform === undefined)
+        return { source, fields: sourceFields, rows: [...rows] };
+    const transformPath = pathKey(path, 'transform');
+    const attempt = bag.errorCount;
+    validateProp(TRANSFORM_PROP_SCHEMA, transform, transformPath, bag);
+    if (bag.errorCount > attempt || !isPlainObject(transform))
+        return undefined;
+    // The author's value, not validateProp's output: the validated copy fills
+    // optional lists with `[]`, which would read as "select nothing" or "in
+    // nothing". The schema already rejected every unknown key and wrong type.
+    const spec = transform;
+    const checked = checkTransform(spec, sourceFields, source, transformPath, bag);
+    if (!checked.ok)
+        return undefined;
+    return { source, fields: checked.fields, rows: applyTransform(rows, spec) };
+}
+//# sourceMappingURL=resolve-block-data.js.map

package/dist/data/resolve-block-data.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-block-data.js","sourceRoot":"","sources":["../../src/data/resolve-block-data.ts"],"names":[],"mappings":"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"}

package/dist/data/transform-pipeline.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Bounded, deterministic dataset transforms.
+ *
+ * A transform is data, not an expression: a fixed pipeline of five optional
+ * stages that always run in the same order (filter → groupBy → sort → select →
+ * limit). Comparison never consults a locale, and sorting is stable, so the same
+ * rows and the same transform always produce the same rows in the same order.
+ */
+import type { PropSchema } from '../registry/prop-schema.js';
+import { type DataRow, type DataScalar } from './dataset-types.js';
+export type FilterOperator = 'equals' | 'notEquals' | 'in' | 'gt' | 'gte' | 'lt' | 'lte';
+export declare const FILTER_OPERATORS: readonly FilterOperator[];
+export interface FilterClause {
+    field: string;
+    equals?: DataScalar;
+    notEquals?: DataScalar;
+    in?: DataScalar[];
+    gt?: number;
+    gte?: number;
+    lt?: number;
+    lte?: number;
+}
+export type Aggregate = 'count' | 'sum' | 'mean' | 'min' | 'max';
+export declare const AGGREGATES: readonly Aggregate[];
+export interface GroupBySpec {
+    field: string;
+    aggregate: Aggregate;
+    /** Numeric field to aggregate; required for everything except `count`. */
+    value?: string;
+    /** Output field name; defaults to `count`, or to the `value` field name. */
+    as?: string;
+}
+export interface SortKey {
+    by: string;
+    direction?: 'asc' | 'desc';
+}
+export interface TransformSpec {
+    /** Up to 8 clauses, combined with AND; each has exactly one operator. */
+    filter?: FilterClause[];
+    groupBy?: GroupBySpec;
+    /** One key or up to 3 keys, applied in order. */
+    sort?: SortKey | SortKey[];
+    /** Fields to keep, in this order (up to 24). */
+    select?: string[];
+    /** Keep the first N rows (1–200). */
+    limit?: number;
+}
+export declare const TRANSFORM_LIMITS: {
+    readonly maxFilters: 8;
+    readonly maxSortKeys: 3;
+    readonly maxSelect: 24;
+};
+/** Prop schema for `transform`: used for validation, the JSON Schema, and describe. */
+export declare const TRANSFORM_PROP_SCHEMA: PropSchema;
+/** The output field name of a groupBy aggregate. */
+export declare function aggregateField(groupBy: GroupBySpec): string;
+/** Comparator for one key: nulls sort last in both directions. */
+export declare function compareScalars(left: DataScalar, right: DataScalar, direction?: 'asc' | 'desc'): number;
+export declare function sortKeys(sort: TransformSpec['sort']): SortKey[];
+/**
+ * Apply a validated transform. Pure: the input rows are never mutated.
+ * Fixed order: filter → groupBy → sort → select → limit.
+ */
+export declare function applyTransform(rows: DataRow[], spec: TransformSpec): DataRow[];
+//# sourceMappingURL=transform-pipeline.d.ts.map

package/dist/data/transform-pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transform-pipeline.d.ts","sourceRoot":"","sources":["../../src/data/transform-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,UAAU,EAAc,MAAM,oBAAoB,CAAC;AAE/E,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,WAAW,GAAG,IAAI,GAAG,IAAI,GAAG,KAAK,GAAG,IAAI,GAAG,KAAK,CAAC;AACzF,eAAO,MAAM,gBAAgB,EAAE,SAAS,cAAc,EAQrD,CAAC;AAEF,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,SAAS,CAAC,EAAE,UAAU,CAAC;IACvB,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC;IAClB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,KAAK,CAAC;AACjE,eAAO,MAAM,UAAU,EAAE,SAAS,SAAS,EAA2C,CAAC;AAEvF,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,SAAS,CAAC;IACrB,0EAA0E;IAC1E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,aAAa;IAC5B,yEAAyE;IACzE,MAAM,CAAC,EAAE,YAAY,EAAE,CAAC;IACxB,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,iDAAiD;IACjD,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,EAAE,CAAC;IAC3B,gDAAgD;IAChD,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,eAAO,MAAM,gBAAgB;;;;CAA4D,CAAC;AAiB1F,uFAAuF;AACvF,eAAO,MAAM,qBAAqB,EAAE,UAmDnC,CAAC;AAEF,oDAAoD;AACpD,wBAAgB,cAAc,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAI3D;AAsBD,kEAAkE;AAClE,wBAAgB,cAAc,CAC5B,IAAI,EAAE,UAAU,EAChB,KAAK,EAAE,UAAU,EACjB,SAAS,GAAE,KAAK,GAAG,MAAc,GAChC,MAAM,CAMR;AAqDD,wBAAgB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,OAAO,EAAE,CAG/D;AA0BD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,aAAa,GAAG,OAAO,EAAE,CAY9E"}