@adminiumjs/widgets 0.1.0-rc.1

package/dist/families/domain/block-lib.js

@@ -0,0 +1,390 @@
+/**
+ * TRACK BUILDER — pure helpers behind `document-canvas` and the 22 `block-*`
+ * document-vocabulary widgets (annex §13).
+ *
+ * JSX-free and DOM-free on purpose: money recomputation, payload projection and
+ * the reorder algebra are all pure functions of their inputs, so they are
+ * golden-testable and `blocks-config.ts` can import them for `demoData` without
+ * dragging component code into the eager registry chunk (04 §2.3).
+ *
+ * MONEY + DATES go through the `@adminium/i18n` Intl layer (10 §4). `getFormatters`
+ * already applies the data-context numeral policy (latn digits + gregorian for
+ * mono cells), so callers never pass a `-u-nu-latn` tag themselves.
+ *
+ * TOTALS ARE DERIVED, NEVER STORED — the annex's canvas "live-recomputing
+ * totals" is `computeTotals` below: `block-totals-summary`, `block-tax-breakdown`
+ * and `block-qr-pay` all recompute from the same items + rates, so a canvas edit
+ * can never desync one block's arithmetic from another's.
+ */
+import { getFormatters } from '@adminium/i18n';
+import { asRecord, numberField, resolveLocale, stringField } from './domain-lib.js';
+// --- the block vocabulary -----------------------------------------------------
+/**
+ * The 22 `block-*` registry ids, in annex §13 bullet order. `document-canvas`
+ * validates `blockOrder[]` against this set, so a doc row carrying a typo'd or
+ * hostile block id renders nothing rather than resolving an arbitrary widget.
+ */
+export const BLOCK_IDS = [
+    'block-totals-summary',
+    'block-line-items',
+    'block-kpi-row',
+    'block-bar-chart',
+    'block-line-chart',
+    'block-two-col-table',
+    'block-tax-breakdown',
+    'block-multi-currency',
+    'block-payment-history',
+    'block-discount-codes',
+    'block-loyalty-banner',
+    'block-recurring-banner',
+    'block-qr-pay',
+    'block-delivery-stepper',
+    'block-signature',
+    'block-terms-checkbox',
+    'block-approval',
+    'block-attachments',
+    'block-late-fees',
+    'block-image-placeholder',
+    'block-contact',
+    'block-highlight-box',
+];
+const BLOCK_ID_SET = new Set(BLOCK_IDS);
+/** Is this an annex §13 document-block id? */
+export function isBlockId(value) {
+    return typeof value === 'string' && BLOCK_ID_SET.has(value);
+}
+export const DOC_TYPES = ['invoice', 'report', 'email'];
+/**
+ * The blocks each document surface starts with (annex §13 evidence column —
+ * which comp each block is cited from). `document-canvas` falls back to these
+ * when a doc row carries no `blockOrder[]`, which is what makes a freshly
+ * seeded doc render something useful instead of an empty page.
+ */
+export const DOC_TYPE_BLOCKS = {
+    invoice: [
+        'block-line-items',
+        'block-tax-breakdown',
+        'block-totals-summary',
+        'block-payment-history',
+        'block-qr-pay',
+        'block-recurring-banner',
+    ],
+    report: [
+        'block-kpi-row',
+        'block-bar-chart',
+        'block-line-chart',
+        'block-two-col-table',
+        'block-attachments',
+        'block-signature',
+    ],
+    email: [
+        'block-highlight-box',
+        'block-discount-codes',
+        'block-loyalty-banner',
+        'block-delivery-stepper',
+        'block-contact',
+    ],
+};
+/** Coerce an untrusted value to a `DocType`, defaulting to `invoice`. */
+export function docTypeOf(value, fallback = 'invoice') {
+    return typeof value === 'string' && DOC_TYPES.includes(value)
+        ? value
+        : fallback;
+}
+// --- money --------------------------------------------------------------------
+/** Fixed demo anchor for the block vocabulary — 2026-06-01T00:00:00Z. */
+export const BLOCK_DEMO_EPOCH = Date.UTC(2026, 5, 1);
+/** Milliseconds in a whole day. */
+export const BLOCK_DAY_MS = 86_400_000;
+/**
+ * Currency formatting for a money figure (10 §4.4 — the code comes from the
+ * doc/column metadata, never from the viewer's locale).
+ *
+ * `|| 'USD'` rather than `??`: `format.currency: ''` is schema-valid (the shared
+ * config types it as a free string) and `{ style: 'currency', currency: '' }`
+ * throws `RangeError` inside `Intl` — the exact crash the config-fuzz gate
+ * samples for (see qa/zod-sample.ts's `FIELD_POOLS`).
+ */
+export function formatBlockMoney(value, options) {
+    if (!Number.isFinite(value))
+        return '—';
+    return getFormatters(resolveLocale(options?.locale)).number(value, {
+        style: 'currency',
+        currency: options?.currency || 'USD',
+    });
+}
+/**
+ * Percent formatting for a FRACTIONAL rate (0.075 → "7.5%").
+ *
+ * The whole-percent test rounds BEFORE the modulo. `rate * 100` is a float:
+ * `0.07 * 100` is `7.000000000000001` and `0.29 * 100` is `28.999999999999996`,
+ * so testing `% 1 === 0` on the raw product answers "no" for two perfectly
+ * ordinary tax rates — and the same tax table would then print `20%` next to
+ * `7.00%`. Scaling to 1e6 keeps four decimal places of a percent (0.0001%),
+ * which is finer than any rate this renders and coarse enough to swallow the
+ * representation error.
+ */
+export function formatBlockRate(rate, locale) {
+    if (!Number.isFinite(rate))
+        return '—';
+    const wholePercent = Math.round(rate * 1e6) % 1e4 === 0;
+    return getFormatters(resolveLocale(locale)).percent(rate, { fractionDigits: wholePercent ? 0 : 2 });
+}
+/** Plain number formatting (loyalty points, cycle counts). */
+export function formatBlockNumber(value, locale) {
+    if (!Number.isFinite(value))
+        return '—';
+    return getFormatters(resolveLocale(locale)).number(value);
+}
+/** Short date formatting for a doc date field; blank input renders an em dash. */
+export function formatBlockDate(value, locale) {
+    if (value === undefined || value === '')
+        return '—';
+    const ms = typeof value === 'number' ? value : Date.parse(value);
+    if (!Number.isFinite(ms))
+        return typeof value === 'string' ? value : '—';
+    return getFormatters(resolveLocale(locale)).date(ms, 'medium');
+}
+/** Byte-size formatting for `block-attachments`' mono size column. */
+export function formatBlockSize(bytes, locale) {
+    if (!Number.isFinite(bytes))
+        return '—';
+    return getFormatters(resolveLocale(locale)).bytes(bytes);
+}
+/**
+ * Mask a payment method for `block-payment-history` — never render a full PAN.
+ * Only the last four digits ever reach the DOM, and they come from the row's own
+ * `last4` field (a masked column), not from a parsed number.
+ */
+export function maskMethod(method, last4) {
+    const tail = (last4 ?? '').replace(/\D/g, '').slice(-4);
+    return tail === '' ? method : `${method} ···· ${tail}`;
+}
+/**
+ * The canvas's live-recomputing totals (annex §13): subtotal from the line
+ * items, discount off the subtotal, tax on the discounted base, total due.
+ *
+ * Every figure is derived here and nowhere else, so `block-totals-summary`,
+ * `block-tax-breakdown` and `block-qr-pay` can never disagree. Non-finite or
+ * negative quantities are coerced to 0 rather than poisoning the arithmetic with
+ * `NaN` — untrusted rows reach this from a live table.
+ */
+export function computeTotals(items, rates, currencyFallback = 'USD') {
+    const subtotal = items.reduce((sum, item) => sum + safeMoney(item.qty) * safeMoney(item.rate), 0);
+    const discountRate = clamp01(rates?.discountRate ?? 0);
+    const taxRate = clamp01(rates?.taxRate ?? 0);
+    const discount = round2(subtotal * discountRate);
+    const taxable = round2(subtotal - discount);
+    const tax = round2(taxable * taxRate);
+    return {
+        subtotal: round2(subtotal),
+        discount,
+        taxable,
+        tax,
+        total: round2(taxable + tax),
+        currency: rates?.currency || currencyFallback,
+    };
+}
+function safeMoney(value) {
+    return Number.isFinite(value) && value > 0 ? value : 0;
+}
+/** Rates are fractions; anything outside [0,1] is corrupt input, not a 900% tax. */
+function clamp01(value) {
+    return Number.isFinite(value) ? Math.min(1, Math.max(0, value)) : 0;
+}
+/** Round to cents — float money must never render `19.999999999999998`. */
+export function round2(value) {
+    return Number.isFinite(value) ? Math.round(value * 100) / 100 : 0;
+}
+// --- payload projection -------------------------------------------------------
+/**
+ * Project an untrusted `record` payload onto its row. Accepts both the canonical
+ * `{ row }` envelope and a BARE object (what a hand-written manifest or a story
+ * tends to pass), so a block never blanks out over an envelope detail.
+ */
+export function rowOf(data) {
+    const record = asRecord(data);
+    if (record === null)
+        return null;
+    if ('row' in record)
+        return asRecord(record.row) ?? null;
+    return record;
+}
+/** Project an untrusted `record-list` payload onto its rows. */
+export function rowsOf(data) {
+    const record = asRecord(data);
+    if (record === null)
+        return Array.isArray(data) ? data : [];
+    const rows = record.rows;
+    return Array.isArray(rows) ? rows.filter((row) => asRecord(row) !== null) : [];
+}
+/** Project an untrusted `categorical` payload onto its label/value items. */
+export function categoricalItemsOf(data) {
+    const record = asRecord(data);
+    const items = record?.items;
+    if (!Array.isArray(items))
+        return [];
+    return items.flatMap((raw, index) => {
+        const row = asRecord(raw);
+        if (row === null)
+            return [];
+        const value = numberField(row, 'value');
+        if (value === undefined)
+            return [];
+        return [{ label: stringField(row, 'label') ?? String(index + 1), value }];
+    });
+}
+/** Project untrusted rows onto `DocLineItem`s via the configured field naming. */
+export function lineItemsOf(data, fields) {
+    return rowsOf(data).map((row, index) => ({
+        id: stringField(row, fields.idField) ?? `item-${index}`,
+        desc: stringField(row, fields.descField) ?? '',
+        qty: numberField(row, fields.qtyField) ?? 0,
+        rate: numberField(row, fields.rateField) ?? 0,
+    }));
+}
+/** `block-two-col-table` rows: `rows[][]` coerced to [left, right] string pairs. */
+export function twoColRowsOf(data) {
+    const record = asRecord(data);
+    const rows = record?.rows;
+    if (!Array.isArray(rows))
+        return [];
+    return rows.flatMap((raw) => {
+        if (Array.isArray(raw)) {
+            return [[cell(raw[0]), cell(raw[1])]];
+        }
+        const row = asRecord(raw);
+        if (row === null)
+            return [];
+        const values = Object.values(row);
+        return [[cell(values[0]), cell(values[1])]];
+    });
+}
+function cell(value) {
+    if (value === null || value === undefined)
+        return '';
+    return typeof value === 'string' ? value : String(value);
+}
+// --- document-canvas block order ---------------------------------------------
+/**
+ * Resolve the canvas's ordered block instances from an untrusted doc row.
+ *
+ * Precedence: the doc's own `blockOrder[]` → the `enabledBlocks` config → the
+ * doc type's default composition. Unknown ids are DROPPED (never rendered as an
+ * arbitrary widget), and `flags[blockId] === false` hides a block — the annex's
+ * "~20 boolean show-flags per doc".
+ */
+export function blockOrderOf(doc, options) {
+    const declared = doc?.blockOrder;
+    const source = Array.isArray(declared)
+        ? declared.flatMap((raw, index) => {
+            const row = asRecord(raw);
+            // A blockOrder entry may be a bare id string or a full instance object.
+            const block = row === null ? raw : row.block;
+            if (!isBlockId(block))
+                return [];
+            const id = row === null ? `${block}-${index}` : (stringField(row, 'id') ?? `${block}-${index}`);
+            const label = row === null ? undefined : stringField(row, 'label');
+            return [{ id, block, ...(label === undefined ? {} : { label }) }];
+        })
+        : (options.enabledBlocks ?? DOC_TYPE_BLOCKS[options.docType])
+            .filter(isBlockId)
+            .map((block, index) => ({ id: `${block}-${index}`, block }));
+    const enabled = options.enabledBlocks === undefined ? null : new Set(options.enabledBlocks);
+    const flags = doc?.flags;
+    return source.filter((instance) => {
+        if (enabled !== null && !enabled.has(instance.block))
+            return false;
+        return flags?.[instance.block] !== false;
+    });
+}
+/**
+ * Project the canvas's single doc object onto ONE block's own §3 payload.
+ *
+ * The money blocks are DERIVED from the doc's `items` + `rates` rather than read
+ * from storage — that is the annex's "live-recomputing totals", and it is what
+ * guarantees `block-totals-summary`, `block-tax-breakdown` and `block-qr-pay`
+ * can never disagree about the same invoice. Every other block is doc content
+ * with no canonical derivation, so it comes from the `blocks` bag as-is; a block
+ * with no payload gets `null` and renders its own empty copy.
+ *
+ * Pure, so the projection is golden-testable without mounting the canvas.
+ */
+export function blockDataOf(blockId, doc) {
+    if (doc === null)
+        return null;
+    const items = Array.isArray(doc.items) ? doc.items : [];
+    switch (blockId) {
+        case 'block-line-items':
+            return rowsData(items);
+        case 'block-totals-summary':
+            return rowData({ items, rates: doc.rates ?? {} });
+        case 'block-tax-breakdown': {
+            // One derived line per declared rate — the doc's own tax lines win when it
+            // carries them (a multi-jurisdiction invoice can't be derived from one rate).
+            const declared = doc.blocks?.['block-tax-breakdown'];
+            if (declared !== undefined)
+                return declared;
+            const rate = doc.rates?.taxRate;
+            if (rate === undefined || rate === 0)
+                return rowsData([]);
+            const totals = computeTotals(items, doc.rates, doc.currency || 'USD');
+            return rowsData([{ id: 'tax-1', label: 'Tax', rate, amount: totals.tax }]);
+        }
+        case 'block-qr-pay': {
+            const totals = computeTotals(items, doc.rates, doc.currency || 'USD');
+            return rowData({
+                caption: 'Scan to pay',
+                total: totals.total,
+                currency: totals.currency,
+            });
+        }
+        default:
+            return doc.blocks?.[blockId] ?? null;
+    }
+}
+/**
+ * Move the item at `index` by `delta` positions, returning a NEW list. Out-of-
+ * range moves return the list unchanged, so a "move up" on the first block is a
+ * no-op rather than a wrap-around — the canvas's up/down controls rely on that
+ * to stay predictable at the ends.
+ *
+ * This is deliberately an index algebra rather than a pointer drag: reorder in
+ * the canvas is driven by keyboard-reachable buttons (and the page-builder page
+ * may drive the same callback from a pointer layer), so the ordering logic stays
+ * pure, testable, and identical for both input modes.
+ */
+export function moveBlock(list, index, delta) {
+    const target = index + delta;
+    if (index < 0 || index >= list.length || target < 0 || target >= list.length)
+        return [...list];
+    const next = [...list];
+    const [moved] = next.splice(index, 1);
+    next.splice(target, 0, moved);
+    return next;
+}
+/**
+ * Resolve `config.binding` to the `{ connectionId, table }` a mutate intent
+ * needs. The descriptor names the table at `binding.source.name` (+ an optional
+ * `schema` qualifier for Postgres) — NOT `binding.table` (04 §5).
+ *
+ * `null` for an unbound (demo) widget: an edit then has nowhere to go, so the
+ * blocks skip emitting rather than inventing a table name.
+ */
+export function blockBindingSourceOf(binding) {
+    if (binding === undefined)
+        return null;
+    const { schema, name } = binding.source;
+    return { connectionId: binding.connectionId, table: schema === undefined ? name : `${schema}.${name}` };
+}
+// --- envelope constructors (shared by demoData + stories) ---------------------
+export function rowsData(rows) {
+    return { rows, total: rows.length };
+}
+export function rowData(row) {
+    return { row };
+}
+export function categoricalData(items) {
+    return { items };
+}
+//# sourceMappingURL=block-lib.js.map

package/dist/families/domain/block-lib.js.map

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

package/dist/families/domain/block-types.d.ts

@@ -0,0 +1,227 @@
+/**
+ * TRACK BUILDER — payload types for `document-canvas` and the 22 `block-*`
+ * document-vocabulary widgets (annex §13, "Document blocks").
+ *
+ * DOM-free and React-free: these are the §3 data-contract envelopes the blocks
+ * bind to, so `blocks-config.ts` can describe them (and generate demo payloads
+ * for them) without the definitions module ever reaching component code
+ * (04 §2.3; the chunk-budget gate).
+ *
+ * ENVELOPE CHOICE (04 §3) — the annex gives each block a bespoke "Data:" note
+ * rather than naming a canonical shape, so each note is mapped onto the closest
+ * §3 envelope and the mapping is documented on the definition:
+ *   - a bag of scalars for ONE document field group ({sigName, sigTitle},
+ *     {balance, earned, tier}, …) → `record`, i.e. `{ row }` — the shape the
+ *     shared `isEmptyByShape.record` predicate reads via `row == null`;
+ *   - a repeating row set (items[], taxLines[], payHist[], steps[], files[]) →
+ *     `record-list`, i.e. `{ rows, total }` — empty ⇔ `total === 0 && !cursor`;
+ *   - the mini report charts → `categorical` (`{ items }`, label/value);
+ *   - `block-terms-checkbox` → `form-state` (a control whose payload is its own
+ *     checked state, never "empty").
+ */
+/** The three document surfaces the canvas renders (annex §13 `docType`). */
+export type DocType = 'invoice' | 'report' | 'email';
+/**
+ * One block instance on the canvas. `block` is the annex registry id
+ * (`block-line-items`, …) — the canvas renders the ordered list, and the
+ * page-builder page owns add/remove/reorder through callbacks.
+ */
+export interface DocBlockInstance {
+    /** Stable instance key (`blockOrder[]` entry). */
+    id: string;
+    /** Registry id of the block widget to render. */
+    block: string;
+    /** Localized section heading shown above the block. */
+    label?: string | undefined;
+}
+/**
+ * The single doc object `document-canvas` binds to (annex §13: "single doc
+ * object (strings, address lines, items[], rates, flags, blockOrder[])").
+ * Carried in the §3 `record` envelope, so `{ row: null }` routes to the empty
+ * state through the host's shared predicate.
+ */
+export interface DocRecord {
+    docType?: DocType | undefined;
+    title?: string | undefined;
+    number?: string | undefined;
+    issuedAt?: string | undefined;
+    dueAt?: string | undefined;
+    /** Sender / recipient address lines, rendered as-is. */
+    fromLines?: readonly string[] | undefined;
+    toLines?: readonly string[] | undefined;
+    currency?: string | undefined;
+    items?: readonly DocLineItem[] | undefined;
+    rates?: DocRates | undefined;
+    /** Ordered block instances — the canvas's render order. */
+    blockOrder?: readonly DocBlockInstance[] | undefined;
+    /** ~20 per-doc boolean show-flags keyed by block id (annex §13). */
+    flags?: Readonly<Record<string, boolean>> | undefined;
+    /**
+     * Per-block payload bag, keyed by block registry id.
+     *
+     * The money blocks (`block-line-items`, `block-totals-summary`,
+     * `block-tax-breakdown`, `block-qr-pay`) are DERIVED from `items` + `rates`
+     * and ignore this — that is what makes the canvas's totals live-recompute and
+     * keeps two blocks from disagreeing. Everything else (payment history, the
+     * banners, the signature…) is doc content with no canonical derivation, so it
+     * rides here and `blockDataOf` hands it straight to the block.
+     */
+    blocks?: Readonly<Record<string, unknown>> | undefined;
+}
+export interface DocData {
+    row: DocRecord | null;
+}
+/** An editable line item feeding the totals (annex `block-line-items`). */
+export interface DocLineItem {
+    id: string;
+    desc: string;
+    qty: number;
+    rate: number;
+}
+/** The rate set the totals block applies to the line-item subtotal. */
+export interface DocRates {
+    /** Fractional tax rate (0.2 = 20%). */
+    taxRate?: number | undefined;
+    /** Fractional discount rate applied before tax. */
+    discountRate?: number | undefined;
+    currency?: string | undefined;
+}
+/** Recomputed money for a doc — every figure derived, never stored. */
+export interface DocTotals {
+    subtotal: number;
+    discount: number;
+    taxable: number;
+    tax: number;
+    total: number;
+    currency: string;
+}
+/** `block-kpi-row` — stat tiles with sign-aware delta coloring. */
+export interface BlockKpi {
+    id: string;
+    label: string;
+    value: number;
+    delta?: number | undefined;
+    unit?: 'plain' | 'currency' | 'percent' | undefined;
+}
+/** `block-tax-breakdown` — label/rate/amount rows applied to the subtotal. */
+export interface BlockTaxLine {
+    id: string;
+    label: string;
+    /** Fractional rate (0.075 = 7.5%). */
+    rate: number;
+    /** Explicit amount; derived from `rate × subtotal` when absent. */
+    amount?: number | undefined;
+}
+/** `block-multi-currency` — base amount × indicative rate per currency. */
+export interface BlockFxLine {
+    currency: string;
+    rate: number;
+}
+export interface BlockMultiCurrency {
+    amount: number;
+    baseCurrency?: string | undefined;
+    fx: readonly BlockFxLine[];
+}
+/** `block-payment-history` — date, masked method, amount, status pill. */
+export interface BlockPayment {
+    id: string;
+    date: string;
+    method: string;
+    last4?: string | undefined;
+    amount: number;
+    status: string;
+}
+/** `block-discount-codes` — mono code chip + label + green amount. */
+export interface BlockDiscountCode {
+    id: string;
+    code: string;
+    label: string;
+    amount: number;
+}
+/** `block-loyalty-banner` — award icon, balance pts · tier, green earned. */
+export interface BlockLoyalty {
+    balance: number;
+    earned: number;
+    tier: string;
+}
+/** `block-recurring-banner` — "Recurring — Monthly · Next on … · N cycles". */
+export interface BlockRecurring {
+    freq: string;
+    next: string;
+    count: number;
+}
+/** `block-qr-pay` — QR tile + caption + amount due. */
+export interface BlockQrPay {
+    caption: string;
+    total: number;
+    currency?: string | undefined;
+}
+/** `block-delivery-stepper` — horizontal done/current/todo dots. */
+export interface BlockStep {
+    id: string;
+    label: string;
+    state: 'done' | 'current' | 'todo';
+}
+/** `block-signature` — editable signature lines + date. */
+export interface BlockSignature {
+    sigName: string;
+    sigTitle: string;
+    sigDate?: string | undefined;
+}
+/** `block-terms-checkbox` — toggle + editable label (a `form-state` payload). */
+export interface BlockTerms {
+    label: string;
+    checked: boolean;
+}
+/** `block-approval` — approver card + status-tinted pill. */
+export interface BlockApproval {
+    name: string;
+    title: string;
+    status: 'pending' | 'approved' | 'rejected';
+}
+/** `block-attachments` — paperclip rows with mono sizes. */
+export interface BlockAttachment {
+    id: string;
+    name: string;
+    size: number;
+}
+/** `block-late-fees` — warn callout with templated rate/days copy. */
+export interface BlockLateFees {
+    /** Fractional rate (0.015 = 1.5%). */
+    rate: number;
+    days: number;
+}
+/** `block-image-placeholder` — dashed diagonal-stripe box + caption. */
+export interface BlockImagePlaceholder {
+    text: string;
+}
+/** `block-contact` — icon rows name/email/phone, mono values. */
+export interface BlockContact {
+    name: string;
+    email: string;
+    phone: string;
+}
+/** `block-highlight-box` — gray callout, label + large mono value. */
+export interface BlockHighlight {
+    label: string;
+    value: string;
+}
+/** `block-two-col-table` — first row styled header, right col mono. */
+export type BlockTwoColRow = readonly [string, string];
+/** Canonical `record-list` envelope (04 §3). */
+export interface RowsData<T> {
+    rows: readonly T[];
+    total: number;
+}
+/** Canonical `record` envelope (04 §3) — empty ⇔ `row == null`. */
+export interface RowData<T> {
+    row: T | null;
+}
+/** Canonical `categorical` envelope (04 §3) — the mini report charts. */
+export interface CategoricalData {
+    items: readonly {
+        label: string;
+        value: number;
+    }[];
+}
+//# sourceMappingURL=block-types.d.ts.map

package/dist/families/domain/block-types.d.ts.map

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

package/dist/families/domain/block-types.js

@@ -0,0 +1,23 @@
+/**
+ * TRACK BUILDER — payload types for `document-canvas` and the 22 `block-*`
+ * document-vocabulary widgets (annex §13, "Document blocks").
+ *
+ * DOM-free and React-free: these are the §3 data-contract envelopes the blocks
+ * bind to, so `blocks-config.ts` can describe them (and generate demo payloads
+ * for them) without the definitions module ever reaching component code
+ * (04 §2.3; the chunk-budget gate).
+ *
+ * ENVELOPE CHOICE (04 §3) — the annex gives each block a bespoke "Data:" note
+ * rather than naming a canonical shape, so each note is mapped onto the closest
+ * §3 envelope and the mapping is documented on the definition:
+ *   - a bag of scalars for ONE document field group ({sigName, sigTitle},
+ *     {balance, earned, tier}, …) → `record`, i.e. `{ row }` — the shape the
+ *     shared `isEmptyByShape.record` predicate reads via `row == null`;
+ *   - a repeating row set (items[], taxLines[], payHist[], steps[], files[]) →
+ *     `record-list`, i.e. `{ rows, total }` — empty ⇔ `total === 0 && !cursor`;
+ *   - the mini report charts → `categorical` (`{ items }`, label/value);
+ *   - `block-terms-checkbox` → `form-state` (a control whose payload is its own
+ *     checked state, never "empty").
+ */
+export {};
+//# sourceMappingURL=block-types.js.map

package/dist/families/domain/block-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"block-types.js","sourceRoot":"","sources":["../../../src/families/domain/block-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG"}