@happyvertical/smrt-svelte 0.55.23 → 0.55.24

package/dist/components/overview/widgets/line-totals.js

@@ -0,0 +1,91 @@
+/**
+ * The totals block of a document's line items (#3718 record page), pure and
+ * Node-tested. The record's own subtotal / discount / tax / total are
+ * authoritative and shown as they are; a missing one is computed from the
+ * lines (subtotal = sum of line amounts, total = subtotal - discount + tax).
+ * Lines that add up to the recorded total are tax-inclusive and agree.
+ * When the record's figures disagree with the lines, the block flags it
+ * ("Lines add up to $X") instead of silently overriding either side.
+ *
+ * Money is integer minor units throughout.
+ */
+function money(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value)
+        ? value
+        : null;
+}
+/** Sum of integer minor-unit amounts; `null` on a non-integer or past the safe range. */
+export function sumLineAmounts(amounts) {
+    let total = 0;
+    for (const amount of amounts) {
+        if (amount === null || amount === undefined || amount === '')
+            continue;
+        const value = money(amount);
+        if (value === null)
+            return null;
+        total += value;
+        if (!Number.isSafeInteger(total))
+            return null;
+    }
+    return total;
+}
+/**
+ * The totals block for `record` totals over lines summing to `lineSum`
+ * (`null` when the lines are a partial page and the host sent no sum).
+ */
+export function lineItemTotals(record, lineSum) {
+    const subtotalRecorded = money(record?.subtotal);
+    const discount = money(record?.discount);
+    const tax = money(record?.tax);
+    const totalRecorded = money(record?.total);
+    const lines = [];
+    // Line amounts may be tax-inclusive (smrt-commerce's are: qty x price -
+    // discount + tax), so lines adding up to the recorded total agree with the
+    // record, and a missing subtotal is backed out of that total, not the sum.
+    const inclusive = lineSum !== null && totalRecorded !== null && lineSum === totalRecorded;
+    const subtotal = subtotalRecorded ??
+        (inclusive ? totalRecorded + (discount ?? 0) - (tax ?? 0) : lineSum);
+    if (subtotal !== null) {
+        lines.push({
+            key: 'subtotal',
+            value: subtotal,
+            computed: subtotalRecorded === null,
+        });
+    }
+    if (discount !== null && discount !== 0) {
+        lines.push({ key: 'discount', value: discount, computed: false });
+    }
+    if (tax !== null && tax !== 0) {
+        lines.push({ key: 'tax', value: tax, computed: false });
+    }
+    const computedTotal = subtotal === null ? null : subtotal - (discount ?? 0) + (tax ?? 0);
+    const total = totalRecorded ?? computedTotal;
+    if (total !== null) {
+        lines.push({
+            key: 'total',
+            value: total,
+            computed: totalRecorded === null,
+        });
+    }
+    let mismatch = null;
+    if (lineSum !== null && !inclusive) {
+        if (subtotalRecorded !== null && subtotalRecorded !== lineSum) {
+            mismatch = {
+                field: 'subtotal',
+                recorded: subtotalRecorded,
+                lines: lineSum,
+            };
+        }
+        else if (subtotalRecorded === null && totalRecorded !== null) {
+            const fromLines = lineSum - (discount ?? 0) + (tax ?? 0);
+            if (fromLines !== totalRecorded) {
+                mismatch = {
+                    field: 'total',
+                    recorded: totalRecorded,
+                    lines: fromLines,
+                };
+            }
+        }
+    }
+    return { lines, lineSum, mismatch };
+}

package/dist/components/overview/widgets/record-loaders.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Loaders of the record-page widgets (#3718 record page), Svelte-free (on
+ * both entries); the definitions are in `record-widgets.ts`. The widgets: `related` (one tab per
+ * `children` relation, each a records table with a totals footer) and, with
+ * `line-items`, the document's lines and totals block. They are built from
+ * the record's relations, so they register per record view
+ * (`registerRecordWidgets`), not with the core widgets.
+ *
+ * Loader contract: `related` needs no loader of its own. Each tab is ONE
+ * call of the host's core `records` loader with the parent-filter
+ * vocabulary — `{ model, field, filter: 'parent', sort: 'createdAt',
+ * direction: 'desc', limit, columns }` — so a host that implements the
+ * `records` widget's `filter: 'parent'` already implements `related`. The
+ * `columns` option tells the loader which `cells` to fill; `summaries` in
+ * its data (totals over every matching record) fill the footer when the tab
+ * shows a page of a longer list.
+ */
+import type { ScreenRelation } from '../../screens/relations.js';
+import type { OverviewOptions, WidgetLoad } from '../types.js';
+import { type LineItemsWidgetData, type RecordListWidgetData, type RelatedWidgetData } from './data.js';
+import type { LineItemsTotals } from './line-totals.js';
+/** Rows per tab by default. */
+export declare const RELATED_WIDGET_LIMIT = 5;
+/** At most this many relations (tabs) one `related` widget lists. */
+export declare const RELATED_WIDGET_MAX_TABS = 20;
+export interface RecordWidgetsOptions {
+    /** The record's relations (`deriveScreenRelations`). */
+    relations: readonly ScreenRelation[];
+    /** The host's core `records` loader; every tab is one parent-filtered load. */
+    records: WidgetLoad<RecordListWidgetData>;
+    /** A tab's "View all" link; else the loaded data's `href`. */
+    viewAllHref?: (relation: ScreenRelation) => string | undefined;
+    /**
+     * `line-items`: the parent record's own subtotal / discount / tax / total
+     * (read when the widget loads; `RecordScreen` reads them by role).
+     */
+    totals?: () => LineItemsTotals | undefined;
+    /** `line-items`: the currency of the parent's amounts. */
+    currency?: () => string | undefined;
+}
+/** Lines a `line-items` widget loads by default (and at most). */
+export declare const LINE_ITEMS_LIMIT = 50;
+/** The relations a `related` widget lists: `children` (never `items`), or the named ones. */
+export declare function relatedRelations(relations: readonly ScreenRelation[], keys: readonly string[]): ScreenRelation[];
+/** The `records` loader options one tab loads with. */
+export declare function relatedTabOptions(relation: ScreenRelation, limit: number): OverviewOptions;
+/**
+ * The `related` widget's load: one `records` load per listed relation, in
+ * parallel. A tab whose load fails is left out; if every tab fails, the
+ * first error is the widget's.
+ */
+export declare function createRelatedLoader(options: RecordWidgetsOptions): WidgetLoad<RelatedWidgetData>;
+/** The `items` relation a `line-items` widget shows: the named one, else the first. */
+export declare function lineItemsRelation(relations: readonly ScreenRelation[], key: unknown): ScreenRelation | undefined;
+/** The `records` loader options the line items load with. */
+export declare function lineItemsOptions(relation: ScreenRelation, limit: number): OverviewOptions;
+/**
+ * The `line-items` widget's load: one `records` load of the `items`
+ * relation (`filter: 'parent'`, in line order, up to {@link LINE_ITEMS_LIMIT}),
+ * plus the parent's totals. No `items` relation is an empty result.
+ */
+export declare function createLineItemsLoader(options: RecordWidgetsOptions): WidgetLoad<LineItemsWidgetData>;
+//# sourceMappingURL=record-loaders.d.ts.map

package/dist/components/overview/widgets/record-loaders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-loaders.d.ts","sourceRoot":"","sources":["../../../../src/components/overview/widgets/record-loaders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAEjE,OAAO,KAAK,EACV,eAAe,EACf,UAAU,EAEX,MAAM,aAAa,CAAC;AACrB,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EAEvB,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAQxD,+BAA+B;AAC/B,eAAO,MAAM,oBAAoB,IAAI,CAAC;AACtC,qEAAqE;AACrE,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAE1C,MAAM,WAAW,oBAAoB;IACnC,wDAAwD;IACxD,SAAS,EAAE,SAAS,cAAc,EAAE,CAAC;IACrC,+EAA+E;IAC/E,OAAO,EAAE,UAAU,CAAC,oBAAoB,CAAC,CAAC;IAC1C,8DAA8D;IAC9D,WAAW,CAAC,EAAE,CAAC,QAAQ,EAAE,cAAc,KAAK,MAAM,GAAG,SAAS,CAAC;IAC/D;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,eAAe,GAAG,SAAS,CAAC;IAC3C,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;CACrC;AAED,kEAAkE;AAClE,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAEnC,6FAA6F;AAC7F,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,SAAS,cAAc,EAAE,EACpC,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB,cAAc,EAAE,CAMlB;AAED,uDAAuD;AACvD,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,cAAc,EACxB,KAAK,EAAE,MAAM,GACZ,eAAe,CAWjB;AA2CD;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,oBAAoB,GAC5B,UAAU,CAAC,iBAAiB,CAAC,CAkC/B;AAED,uFAAuF;AACvF,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,SAAS,cAAc,EAAE,EACpC,GAAG,EAAE,OAAO,GACX,cAAc,GAAG,SAAS,CAM5B;AAED,6DAA6D;AAC7D,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,cAAc,EACxB,KAAK,EAAE,MAAM,GACZ,eAAe,CAWjB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,oBAAoB,GAC5B,UAAU,CAAC,mBAAmB,CAAC,CA6BjC"}

package/dist/components/overview/widgets/record-loaders.js

@@ -0,0 +1,150 @@
+import { relationKey } from '../../screens/relations.js';
+import { isRecord, } from './data.js';
+import { formatColumnsOption, parseColumnsOption, readRecordRows, resolveRecordColumns, } from './record-table.js';
+/** Rows per tab by default. */
+export const RELATED_WIDGET_LIMIT = 5;
+/** At most this many relations (tabs) one `related` widget lists. */
+export const RELATED_WIDGET_MAX_TABS = 20;
+/** Lines a `line-items` widget loads by default (and at most). */
+export const LINE_ITEMS_LIMIT = 50;
+/** The relations a `related` widget lists: `children` (never `items`), or the named ones. */
+export function relatedRelations(relations, keys) {
+    const children = relations.filter((r) => r.kind === 'children');
+    if (keys.length === 0)
+        return children.slice(0, RELATED_WIDGET_MAX_TABS);
+    return keys
+        .map((key) => children.find((r) => relationKey(r) === key))
+        .filter((r) => r !== undefined);
+}
+/** The `records` loader options one tab loads with. */
+export function relatedTabOptions(relation, limit) {
+    return {
+        title: relation.label,
+        model: relation.model,
+        field: relation.field,
+        filter: 'parent',
+        sort: 'createdAt',
+        direction: 'desc',
+        limit,
+        columns: formatColumnsOption((relation.columns ?? []).map((c) => c.key)),
+    };
+}
+function toTab(relation, data, href) {
+    const record = isRecord(data) ? data : {};
+    const rows = readRecordRows(record);
+    const keys = (relation.columns ?? []).map((c) => c.key);
+    const declared = [
+        ...(Array.isArray(record.columns) ? record.columns : []),
+        ...(relation.columns ?? []),
+    ];
+    const summaries = {};
+    if (isRecord(record.summaries)) {
+        for (const [key, value] of Object.entries(record.summaries)) {
+            if (typeof value === 'number' && Number.isFinite(value))
+                summaries[key] = value;
+        }
+    }
+    const total = typeof record.total === 'number' && Number.isFinite(record.total)
+        ? record.total
+        : rows.length;
+    const dataHref = typeof record.href === 'string' ? record.href : undefined;
+    return {
+        key: relationKey(relation),
+        label: relation.label,
+        rows,
+        total,
+        columns: resolveRecordColumns(keys, declared),
+        ...((href ?? dataHref) ? { href: href ?? dataHref } : {}),
+        ...(typeof record.currency === 'string'
+            ? { currency: record.currency }
+            : {}),
+        ...(typeof record.timeZone === 'string'
+            ? { timeZone: record.timeZone }
+            : {}),
+        ...(Object.keys(summaries).length > 0 ? { summaries } : {}),
+    };
+}
+/**
+ * The `related` widget's load: one `records` load per listed relation, in
+ * parallel. A tab whose load fails is left out; if every tab fails, the
+ * first error is the widget's.
+ */
+export function createRelatedLoader(options) {
+    return async (widgetOptions, ctx) => {
+        const keys = parseColumnsOption(widgetOptions.relations, RELATED_WIDGET_MAX_TABS);
+        const limit = typeof widgetOptions.limit === 'number'
+            ? widgetOptions.limit
+            : RELATED_WIDGET_LIMIT;
+        const selected = relatedRelations(options.relations, keys);
+        const settled = await Promise.allSettled(
+        // A loader that throws synchronously fails its tab, not the widget.
+        selected.map((relation) => new Promise((resolve) => resolve(options.records(relatedTabOptions(relation, limit), ctx)))));
+        const tabs = [];
+        let failure;
+        settled.forEach((result, index) => {
+            const relation = selected[index];
+            if (!relation)
+                return;
+            if (result.status === 'rejected') {
+                failure ??= result.reason;
+                return;
+            }
+            tabs.push(toTab(relation, result.value, options.viewAllHref?.(relation)));
+        });
+        if (tabs.length === 0 && failure !== undefined)
+            throw failure;
+        return { tabs };
+    };
+}
+/** The `items` relation a `line-items` widget shows: the named one, else the first. */
+export function lineItemsRelation(relations, key) {
+    const items = relations.filter((r) => r.kind === 'items');
+    if (typeof key === 'string' && key !== '') {
+        return items.find((r) => relationKey(r) === key);
+    }
+    return items[0];
+}
+/** The `records` loader options the line items load with. */
+export function lineItemsOptions(relation, limit) {
+    return {
+        title: relation.label,
+        model: relation.model,
+        field: relation.field,
+        filter: 'parent',
+        sort: relation.sort ?? 'createdAt',
+        direction: 'asc',
+        limit,
+        columns: formatColumnsOption((relation.columns ?? []).map((c) => c.key)),
+    };
+}
+/**
+ * The `line-items` widget's load: one `records` load of the `items`
+ * relation (`filter: 'parent'`, in line order, up to {@link LINE_ITEMS_LIMIT}),
+ * plus the parent's totals. No `items` relation is an empty result.
+ */
+export function createLineItemsLoader(options) {
+    return async (widgetOptions, ctx) => {
+        const relation = lineItemsRelation(options.relations, widgetOptions.relation);
+        const totals = options.totals?.();
+        const currency = options.currency?.();
+        if (!relation) {
+            return { rows: [], columns: [], ...(totals ? { totals } : {}) };
+        }
+        const limit = typeof widgetOptions.limit === 'number'
+            ? widgetOptions.limit
+            : LINE_ITEMS_LIMIT;
+        const data = await options.records(lineItemsOptions(relation, limit), ctx);
+        const tab = toTab(relation, data, undefined);
+        return {
+            rows: tab.rows,
+            columns: tab.columns,
+            ...(tab.total !== undefined ? { total: tab.total } : {}),
+            ...(totals ? { totals } : {}),
+            ...((tab.currency ?? currency)
+                ? { currency: tab.currency ?? currency }
+                : {}),
+            ...(tab.summaries ? { summaries: tab.summaries } : {}),
+            ...(tab.href ? { href: tab.href } : {}),
+        };
+    };
+}

package/dist/components/overview/widgets/record-table.d.ts

@@ -0,0 +1,45 @@
+import type { FieldRole } from '../../screens/roles.js';
+import { type RecordListColumn, type RecordListRow, type RecordStatusTone } from './data.js';
+export { lineItemColumns, relatedColumns } from '../../screens/columns.js';
+/** At most this many columns render (the widget is compact). */
+export declare const RECORD_TABLE_MAX_COLUMNS = 6;
+/** At most this many rows render. */
+export declare const RECORD_TABLE_MAX_ROWS = 50;
+/**
+ * The `columns` widget option: a comma-separated list of field names
+ * (`"number,status,issuedAt,totalAmount"`). Options are flat JSON
+ * primitives, so a list travels as text; invalid or repeated keys are
+ * dropped and the list is capped at {@link RECORD_TABLE_MAX_COLUMNS}.
+ */
+export declare function parseColumnsOption(value: unknown, max?: number): string[];
+/** The inverse of {@link parseColumnsOption}. */
+export declare function formatColumnsOption(columns: readonly string[]): string;
+/** Common status values and their badge tone; anything else is neutral. */
+export declare const DEFAULT_STATUS_TONES: Readonly<Record<string, RecordStatusTone>>;
+/** Badge tone of a status value: `tones`, then the defaults, else neutral. */
+export declare function statusTone(value: unknown, tones?: Readonly<Record<string, RecordStatusTone>>): RecordStatusTone;
+/** `in_progress` -> `In progress`: a status value as a badge label. */
+export declare function statusLabel(value: unknown): string;
+export interface RecordCellContext {
+    currency?: string;
+    locale?: string;
+    timeZone?: string;
+}
+/** A cell's text, by its column role. Empty values are `''`. */
+export declare function formatRecordCell(column: Pick<RecordListColumn, 'role'>, value: unknown, context?: RecordCellContext): string;
+/** True for the roles a footer sums. */
+export declare function isSummedRole(role: FieldRole | undefined): boolean;
+/** True when the footer sums this column (`summarize`, else by role). */
+export declare function isSummedColumn(column: Pick<RecordListColumn, 'role' | 'summarize'>): boolean;
+/**
+ * Rows of untrusted widget data, validated: a row needs a string `title`
+ * (or any cells), ids default to the position, `cells` must be an object.
+ */
+export declare function readRecordRows(data: unknown): RecordListRow[];
+/**
+ * The columns to render: `keys` (the `columns` option) when given, else the
+ * data's own `columns`; a key's label and role come from the data's column
+ * list, else a humanized label and no role.
+ */
+export declare function resolveRecordColumns(keys: readonly string[], dataColumns: unknown): RecordListColumn[];
+//# sourceMappingURL=record-table.d.ts.map

package/dist/components/overview/widgets/record-table.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-table.d.ts","sourceRoot":"","sources":["../../../../src/components/overview/widgets/record-table.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAExD,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACtB,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAI3E,gEAAgE;AAChE,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAC1C,qCAAqC;AACrC,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAExC;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,EACd,GAAG,GAAE,MAAiC,GACrC,MAAM,EAAE,CAUV;AAED,iDAAiD;AACjD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAEtE;AAED,2EAA2E;AAC3E,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CA+BzE,CAAC;AAEJ,8EAA8E;AAC9E,wBAAgB,UAAU,CACxB,KAAK,EAAE,OAAO,EACd,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,GACjD,gBAAgB,CASlB;AAED,uEAAuE;AACvE,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAGlD;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,gEAAgE;AAChE,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,IAAI,CAAC,gBAAgB,EAAE,MAAM,CAAC,EACtC,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,iBAAsB,GAC9B,MAAM,CA8BR;AAED,wCAAwC;AACxC,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS,GAAG,OAAO,CAEjE;AAED,yEAAyE;AACzE,wBAAgB,cAAc,CAC5B,MAAM,EAAE,IAAI,CAAC,gBAAgB,EAAE,MAAM,GAAG,WAAW,CAAC,GACnD,OAAO,CAET;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,aAAa,EAAE,CAiB7D;AAgBD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,WAAW,EAAE,OAAO,GACnB,gBAAgB,EAAE,CA6BpB"}

package/dist/components/overview/widgets/record-table.js

@@ -0,0 +1,201 @@
+/**
+ * Pure helpers behind the records tables (#3718 record page): the `records`
+ * widget with columns, each tab of `related`, and `lineItems`. Columns
+ * come by role; cells format by role; the footer (smrt-ui `DataTable`
+ * `summaries`) counts the rows and sums the money and quantity columns.
+ *
+ * Svelte-free and Node-tested. No date is formatted in the viewer's zone:
+ * a date cell shows in `timeZone` (default UTC), so the server and the
+ * browser render the same text.
+ */
+import { humanizeFieldName } from '../../screens/fields.js';
+import { formatScreenValue } from '../../screens/values.js';
+import { isRecord, } from './data.js';
+export { lineItemColumns, relatedColumns } from '../../screens/columns.js';
+/** Column keys: `[A-Za-z_][A-Za-z0-9_.-]{0,63}`, the overview identifier shape. */
+const COLUMN_KEY = /^[A-Za-z_][A-Za-z0-9_.-]{0,63}$/;
+/** At most this many columns render (the widget is compact). */
+export const RECORD_TABLE_MAX_COLUMNS = 6;
+/** At most this many rows render. */
+export const RECORD_TABLE_MAX_ROWS = 50;
+/**
+ * The `columns` widget option: a comma-separated list of field names
+ * (`"number,status,issuedAt,totalAmount"`). Options are flat JSON
+ * primitives, so a list travels as text; invalid or repeated keys are
+ * dropped and the list is capped at {@link RECORD_TABLE_MAX_COLUMNS}.
+ */
+export function parseColumnsOption(value, max = RECORD_TABLE_MAX_COLUMNS) {
+    if (typeof value !== 'string')
+        return [];
+    const out = [];
+    for (const part of value.split(',')) {
+        const key = part.trim();
+        if (!COLUMN_KEY.test(key) || out.includes(key))
+            continue;
+        out.push(key);
+        if (out.length === max)
+            break;
+    }
+    return out;
+}
+/** The inverse of {@link parseColumnsOption}. */
+export function formatColumnsOption(columns) {
+    return columns.join(',');
+}
+/** Common status values and their badge tone; anything else is neutral. */
+export const DEFAULT_STATUS_TONES = {
+    active: 'success',
+    accepted: 'success',
+    approved: 'success',
+    completed: 'success',
+    confirmed: 'success',
+    delivered: 'success',
+    fulfilled: 'success',
+    paid: 'success',
+    settled: 'success',
+    shipped: 'success',
+    open: 'info',
+    pending: 'info',
+    processing: 'info',
+    sent: 'info',
+    viewed: 'info',
+    partial: 'warning',
+    overdue: 'warning',
+    on_hold: 'warning',
+    suspended: 'warning',
+    declined: 'error',
+    failed: 'error',
+    rejected: 'error',
+    refunded: 'default',
+    cancelled: 'default',
+    canceled: 'default',
+    draft: 'default',
+    inactive: 'default',
+    void: 'default',
+    written_off: 'default',
+};
+/** Badge tone of a status value: `tones`, then the defaults, else neutral. */
+export function statusTone(value, tones) {
+    if (typeof value !== 'string')
+        return 'default';
+    const key = value
+        .trim()
+        .toLowerCase()
+        .replace(/[\s-]+/g, '_');
+    return (tones?.[value] ?? tones?.[key] ?? DEFAULT_STATUS_TONES[key] ?? 'default');
+}
+/** `in_progress` -> `In progress`: a status value as a badge label. */
+export function statusLabel(value) {
+    if (typeof value !== 'string' || value.trim() === '')
+        return '';
+    return humanizeFieldName(value.trim());
+}
+/** A cell's text, by its column role. Empty values are `''`. */
+export function formatRecordCell(column, value, context = {}) {
+    if (value === null || value === undefined || value === '')
+        return '';
+    switch (column.role) {
+        case 'money':
+            return formatScreenValue({ kind: 'money' }, value, {
+                currency: context.currency,
+                locale: context.locale,
+            });
+        case 'date':
+            if (typeof value === 'string' && !/^\d{4}-\d{2}-\d{2}/.test(value))
+                return value;
+            return formatScreenValue({ kind: 'datetime', definition: { format: 'date' } }, value, { locale: context.locale, timeZone: context.timeZone ?? 'UTC' });
+        case 'quantity':
+            return formatScreenValue({ kind: 'decimal' }, value, {
+                locale: context.locale,
+            });
+        case 'status':
+            return statusLabel(value);
+        default:
+            if (typeof value === 'number')
+                return formatScreenValue({ kind: 'decimal' }, value, {
+                    locale: context.locale,
+                });
+            if (typeof value === 'boolean')
+                return value ? '✓' : '';
+            return typeof value === 'string' ? value : JSON.stringify(value);
+    }
+}
+/** True for the roles a footer sums. */
+export function isSummedRole(role) {
+    return role === 'money' || role === 'quantity';
+}
+/** True when the footer sums this column (`summarize`, else by role). */
+export function isSummedColumn(column) {
+    return column.summarize ?? isSummedRole(column.role);
+}
+/**
+ * Rows of untrusted widget data, validated: a row needs a string `title`
+ * (or any cells), ids default to the position, `cells` must be an object.
+ */
+export function readRecordRows(data) {
+    if (!isRecord(data) || !Array.isArray(data.rows))
+        return [];
+    const out = [];
+    for (const row of data.rows.slice(0, RECORD_TABLE_MAX_ROWS)) {
+        if (!isRecord(row))
+            continue;
+        const cells = isRecord(row.cells) ? row.cells : undefined;
+        if (typeof row.title !== 'string' && !cells)
+            continue;
+        out.push({
+            id: typeof row.id === 'string' ? row.id : String(out.length),
+            title: typeof row.title === 'string' ? row.title : '',
+            ...(typeof row.subtitle === 'string' ? { subtitle: row.subtitle } : {}),
+            ...(typeof row.meta === 'string' ? { meta: row.meta } : {}),
+            ...(typeof row.href === 'string' ? { href: row.href } : {}),
+            ...(cells ? { cells } : {}),
+        });
+    }
+    return out;
+}
+const ROLES = new Set([
+    'title',
+    'identifier',
+    'status',
+    'money',
+    'quantity',
+    'date',
+    'party',
+    'subtotal',
+    'tax',
+    'discount',
+    'total',
+]);
+/**
+ * The columns to render: `keys` (the `columns` option) when given, else the
+ * data's own `columns`; a key's label and role come from the data's column
+ * list, else a humanized label and no role.
+ */
+export function resolveRecordColumns(keys, dataColumns) {
+    const declared = [];
+    if (Array.isArray(dataColumns)) {
+        for (const entry of dataColumns) {
+            if (!isRecord(entry) || typeof entry.key !== 'string')
+                continue;
+            if (!COLUMN_KEY.test(entry.key))
+                continue;
+            declared.push({
+                key: entry.key,
+                label: typeof entry.label === 'string' && entry.label !== ''
+                    ? entry.label
+                    : humanizeFieldName(entry.key),
+                ...(typeof entry.role === 'string' && ROLES.has(entry.role)
+                    ? { role: entry.role }
+                    : {}),
+                ...(typeof entry.summarize === 'boolean'
+                    ? { summarize: entry.summarize }
+                    : {}),
+            });
+        }
+    }
+    const order = keys.length > 0 ? keys : declared.map((c) => c.key);
+    return order.slice(0, RECORD_TABLE_MAX_COLUMNS).map((key) => declared.find((c) => c.key === key) ?? {
+        key,
+        label: humanizeFieldName(key),
+    });
+}

package/dist/components/overview/widgets/record-widgets.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The record-page widget definitions (#3718 record page): `related` and
+ * `line-items` (the contract's `lineItems`), registered per record view by `registerRecordWidgets`
+ * because they are built from the record's relations. Loaders and the
+ * loader contract are in `record-loaders.ts`.
+ */
+import { type WidgetRegistry } from '../registry.js';
+import type { WidgetDefinition, WidgetLoad } from '../types.js';
+import type { LineItemsWidgetData, RelatedWidgetData } from './data.js';
+import { type RecordWidgetsOptions } from './record-loaders.js';
+/** `related`: tabbed related records. Options: `title`, `relations`, `limit`. */
+export declare function createRelatedWidget(load: WidgetLoad<RelatedWidgetData>): WidgetDefinition<RelatedWidgetData>;
+/**
+ * `line-items`: a document's lines and totals block. Options: `title`,
+ * `relation` (an `items` relation key; empty = the first), `limit`. The
+ * type id is kebab case (`line-items`): widget type ids are lowercase kebab.
+ */
+export declare function createLineItemsWidget(load: WidgetLoad<LineItemsWidgetData>): WidgetDefinition<LineItemsWidgetData>;
+/**
+ * Register the record-page widgets for one record view's relations,
+ * `related` and `line-items`, both loading through the host's `records`
+ * loader. Returns a disposer.
+ */
+export declare function registerRecordWidgets(registry: WidgetRegistry | undefined, options: RecordWidgetsOptions, registerOptions?: {
+    replace?: boolean;
+}): () => void;
+//# sourceMappingURL=record-widgets.d.ts.map

package/dist/components/overview/widgets/record-widgets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-widgets.d.ts","sourceRoot":"","sources":["../../../../src/components/overview/widgets/record-widgets.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAyB,KAAK,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC5E,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAChE,OAAO,KAAK,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAGxE,OAAO,EAKL,KAAK,oBAAoB,EAC1B,MAAM,qBAAqB,CAAC;AAE7B,iFAAiF;AACjF,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,UAAU,CAAC,iBAAiB,CAAC,GAClC,gBAAgB,CAAC,iBAAiB,CAAC,CAkCrC;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,UAAU,CAAC,mBAAmB,CAAC,GACpC,gBAAgB,CAAC,mBAAmB,CAAC,CAiCvC;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,cAAc,YAAwB,EAChD,OAAO,EAAE,oBAAoB,EAC7B,eAAe,GAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,GAC1C,MAAM,IAAI,CAcZ"}