@happyvertical/smrt-planner 0.0.2 → 0.1.0

package/dist/data/children.js

@@ -1,16 +1,17 @@
-import { isLineModel, settleLine, withTotals } from "./derived.js";
-import { createRandom, fakeId, fakeRecord, hashString, packLine, } from "./fakes.js";
-import { getSamplePack } from "./packs.js";
+import { isLineModel, lineAmount, settleWithLines } from "./derived.js";
+import { createRandom, fakeId, fakeRecord, hashString, packLine, relatedIndex, } from "./fakes.js";
+import { examplePackCodeFor, SEEDED_TAX_CODES, } from "./money.js";
+import { getSamplePack, getSamplePricing } from "./packs.js";
 const MAX_CHILDREN = 4;
 const hasField = (model, name) => model.fields.some((f) => f.name === name);
 /**
  * Sample child rows for one parent record: one to four (journals, an even
  * number of balanced entries), each pointing at the parent through `fk`. Ids
  * and values are seeded from the parent's id, so the same parent always gets
- * the same children. A line item's `amount` is `quantity * unitPrice` so it
- * reads right next to the parent's totals.
+ * the same children. A line's money (`amount`, `taxAmount`, its tax code's
+ * snapshot) is settled with its document's other lines (`settleSample`).
  */
-export function fakeChildrenOf(child, fk, parent, seed) {
+export function fakeChildrenOf(child, fk, parent, seed, rows) {
     const random = createRandom(hashString(`${seed}:${child.id}:${parent.id}`));
     const ledger = hasField(child, 'debit') && hasField(child, 'credit');
     const count = ledger
@@ -21,7 +22,7 @@ export function fakeChildrenOf(child, fk, parent, seed) {
     return Array.from({ length: count }, (_, i) => {
         const index = hashString(`${parent.id}:${i}`) % 997;
         const record = {
-            ...fakeRecord(child, index, seed),
+            ...fakeRecord(child, index, seed, rows),
             id: fakeId(`${child.id}:${parent.id}:${i}`),
             [fk]: parent.id,
         };
@@ -32,7 +33,11 @@ export function fakeChildrenOf(child, fk, parent, seed) {
             const productField = child.fields.find((f) => f.related?.endsWith(':Product') && f.name in record);
             const pack = getSamplePack();
             const { products } = pack;
-            const item = products[(index % 5) % products.length];
+            // The same row the line's `productId` was pointed at (`relatedIndex`).
+            const item = productField
+                ? products[relatedIndex(productField, { modelId: child.id, index, rows }) %
+                    products.length]
+                : products[index % products.length];
             const described = packLine(index);
             if (described) {
                 // Labour and fabrication are not products: no product to point at.
@@ -57,9 +62,8 @@ export function fakeChildrenOf(child, fk, parent, seed) {
             const quantity = low + Math.floor(random() * (high - low + 1));
             if (hasField(child, 'quantity'))
                 record.quantity = quantity;
-            if (hasField(child, 'discount'))
-                record.discount = 0;
-            record.amount = settleLine(record).amount;
+            Object.assign(record, sampleLineMoney(child, parent, i, quantity, Number(record.unitPrice ?? 0)));
+            record.amount = lineAmount(record);
         }
         if (ledger) {
             const debit = i % 2 === 0;
@@ -69,12 +73,138 @@ export function fakeChildrenOf(child, fk, parent, seed) {
         return record;
     });
 }
+/** Does a sample document give a discount (about one in three, by its id)? */
+export function discounted(parent) {
+    return hashString(`discount:${parent.id}`) % 3 === 0;
+}
+/** A tenth off the line's price, in whole currency units. */
+function lineDiscount(quantity, unitPrice) {
+    return Math.round((quantity * unitPrice) / 1000) * 100;
+}
+/**
+ * Does a sample line carry its own tax code (`taxMode: 'override'`), about one
+ * line in seven by its document and position, never a document's first line?
+ */
+export function overridesTax(parent, index) {
+    return (index > 0 && hashString(`tax-override:${parent.id}:${index}`) % 7 === 0);
+}
 /**
- * Bring a parent's totals in line with the line items just generated for it
- * (see `withTotals`).
+ * The code an overriding sample line chooses, by line: in an app whose
+ * currency an example-pack code names, that code half the time (BC GST + PST
+ * for CAD, so its components show apart); otherwise exempt or zero-rated.
  */
-export function syncTotals(parent, parentModel, items) {
-    if (!items.length || !items.every((r) => 'unitPrice' in r))
+export function overrideTaxCode(parent, index, currency = getSamplePricing().currency) {
+    const draw = hashString(`tax-override-kind:${parent.id}:${index}`) % 4;
+    const pack = examplePackCodeFor(currency);
+    if (pack && draw < 2)
+        return pack;
+    const kind = draw % 2 === 0 ? 'exempt' : 'zero-rated';
+    return SEEDED_TAX_CODES.find((c) => c.kind === kind);
+}
+/**
+ * The money inputs of a sample line, for the fields the line has: a
+ * discounted document's first line takes a tenth off, as a percentage
+ * (`discountType: 'percent'`, `discountRate: '10'`) or a whole-unit amount
+ * (`'amount'`, `discount` in minor units), alternating by document; a few
+ * lines carry a tax code of their own (`overrideTaxCode`); every other line
+ * inherits its code. What the line then comes to is the document's to settle.
+ */
+function sampleLineMoney(child, parent, index, quantity, unitPrice) {
+    const money = {};
+    const discount = index === 0 && discounted(parent);
+    const percent = hashString(`discount-kind:${parent.id}`) % 2 === 0;
+    if (hasField(child, 'discountType')) {
+        money.discountType = discount ? (percent ? 'percent' : 'amount') : 'none';
+    }
+    if (hasField(child, 'discountRate')) {
+        money.discountRate = discount && percent ? '10' : null;
+    }
+    if (hasField(child, 'discount')) {
+        money.discount =
+            discount && !(percent && hasField(child, 'discountType'))
+                ? lineDiscount(quantity, unitPrice)
+                : 0;
+    }
+    // A line with a `discount` but no `discountType` field cannot say which
+    // kind it is: an amount is the only one the model can read from it.
+    if (!hasField(child, 'discountType') && money.discount) {
+        money.discountType = 'amount';
+    }
+    const override = overridesTax(parent, index)
+        ? overrideTaxCode(parent, index)
+        : undefined;
+    if (hasField(child, 'taxMode')) {
+        money.taxMode = override ? 'override' : 'inherit';
+    }
+    if (hasField(child, 'taxCodeId'))
+        money.taxCodeId = override?.id ?? null;
+    return money;
+}
+/**
+ * A sample line once the app's hidden fields' values are applied (`carried`):
+ * where the app hides the line's `discount`, an amount discount could not be
+ * seen or entered, so the line takes its tenth off as a percentage instead,
+ * and where it hides `discountRate` too, the line has no discount.
+ */
+export function withCarried(item, carried) {
+    const next = { ...item, ...carried };
+    if ('discount' in carried &&
+        !('discountType' in carried) &&
+        next.discountType === 'amount') {
+        next.discountType = 'percent';
+        next.discountRate = '10';
+        next.discount = 0;
+    }
+    // Neither kind can be seen: no discount at all.
+    if ('discountRate' in carried && next.discountType === 'percent') {
+        next.discountType = 'none';
+        next.discountRate = null;
+        next.discount = 0;
+    }
+    return next;
+}
+/**
+ * The sample documents whose stored totals deliberately disagree with their
+ * lines, so the record page's mismatch flag has something to show: the third
+ * Order and the third Invoice (row index 2), drafts whose subtotal and total
+ * were left stale by an edit made elsewhere. Only a draft's totals are read
+ * against its lines (an issued document shows its frozen figures as they
+ * are), so these two are drafts. Their own fields stay authoritative; the
+ * page only flags the difference. Editing a line recomputes the totals and
+ * clears it.
+ */
+export const MISMATCH_MODELS = [
+    '@happyvertical/smrt-commerce:Order',
+    '@happyvertical/smrt-commerce:Invoice',
+];
+export const MISMATCH_ROW = 2;
+/** What the stale total is off by, in minor units. */
+export const MISMATCH_AMOUNT = 2500;
+/** Leave one document's total stale (see {@link MISMATCH_MODELS}). */
+export function seedMismatch(parent, parentModel, index) {
+    if (index !== MISMATCH_ROW ||
+        !MISMATCH_MODELS.includes(parentModel.id) ||
+        typeof parent.subtotal !== 'number' ||
+        typeof parent.totalAmount !== 'number') {
         return;
-    Object.assign(parent, withTotals(parentModel, parent, items));
+    }
+    if (parentModel.fields.some((f) => f.name === 'status' && f.enum?.includes('draft'))) {
+        parent.status = 'draft';
+    }
+    // Stale but self-consistent: subtotal and total moved together.
+    parent.subtotal += MISMATCH_AMOUNT;
+    parent.totalAmount += MISMATCH_AMOUNT;
+}
+/**
+ * Settle the line items just generated for a parent with it (see
+ * `settleWithLines`): the parent's totals are set in place and the settled
+ * lines returned.
+ */
+export function settleSample(parent, parentModel, items, context) {
+    if (!items.length || !items.every((r) => 'unitPrice' in r)) {
+        return [...items];
+    }
+    const settled = settleWithLines(parentModel, parent, items, context);
+    Object.assign(parent, settled.row);
+    return settled.lines;
 }

package/dist/data/derived.d.ts

@@ -1,37 +1,45 @@
 /**
- * Amounts the commerce models derive rather than take as input, mirrored from
- * `ContractLineItem` / `InvoiceLineItem` / `Invoice` in smrt-commerce:
+ * Amounts a document's lines derive rather than take as input, on
+ * smrt-commerce's money model (released in 0.56.1; `money.ts` holds the
+ * mapping to the package's own calculator):
  *
- *   line subtotal = round(quantity * unitPrice) - discount   (minor units)
- *   line tax      = round(line subtotal * taxRate)           (taxRate is a fraction)
- *   line amount   = line subtotal + line tax
+ *   line amount   = quantity x unitPrice - discount
+ *                   (prices without tax: the line's net; with tax: its gross)
+ *   line tax      = from the line's resolved tax code, per component
+ *   subtotal      = sum of the lines' net
+ *   taxAmount     = sum of the lines' tax
+ *   totalAmount   = subtotal + taxAmount
+ *   discountTotal = sum of the lines' discounts, informational: already
+ *                   inside the line amounts, never subtracted again
  *
- * and a parent with line items takes `subtotal`, `taxAmount` and `totalAmount`
- * from the sum of its lines, ignoring what a form sent.
+ * A parent with line items takes these from its lines, ignoring what a form
+ * sent. See AGENTS.md.
  */
 import type { CatalogModel } from '../catalog/types.ts';
+import { type LineAmountType, type MoneyContext, type SettledDocument, type TaxRoundingScope } from './money.ts';
+export { lineAmount } from './money.ts';
 type Row = Readonly<Record<string, unknown>>;
 /** A line item: it prices a quantity of something. */
 export declare function isLineModel(model: CatalogModel): boolean;
-export interface LineAmounts {
-    subtotal: number;
-    tax: number;
-    amount: number;
-}
-export declare function lineAmounts(line: Row): LineAmounts;
-/** The line with its `amount` brought in line with its other fields. */
-export declare function settleLine<T extends Row>(line: T): T & {
-    amount: number;
-};
-export interface ParentTotals {
-    subtotal: number;
-    taxAmount: number;
-    totalAmount: number;
-}
-export declare function totalsOf(lines: readonly Row[]): ParentTotals;
+/** The totals a document's summary shows: subtotal, tax, total. */
 export declare const TOTAL_FIELDS: readonly ["subtotal", "taxAmount", "totalAmount"];
-/** `row` with the model's total fields set from `lines`. */
-export declare function withTotals<T extends Record<string, unknown>>(model: CatalogModel, row: T, lines: readonly Row[]): T;
+/** Every header field its lines decide, `discountTotal` included. */
+export declare const DOCUMENT_MONEY_FIELDS: readonly ["subtotal", "taxAmount", "totalAmount", "discountTotal"];
+/** The fields of a line its document's calculation writes. */
+export declare const LINE_MONEY_FIELDS: readonly ["amount", "taxAmount", "taxRate", "taxCodeCode", "taxCodeName"];
+/** The document's own pricing mode, else `fallback` (the app's). */
+export declare function documentLineAmountType(row: Row, fallback: LineAmountType): LineAmountType;
+/** The document's own rounding scope, else `fallback` (the app's). */
+export declare function documentRoundingScope(row: Row, fallback: TaxRoundingScope): TaxRoundingScope;
+/**
+ * `row` and its `lines` settled together: the lines' derived fields, and the
+ * model's header money fields (`subtotal`, `discountTotal`, `taxAmount`,
+ * `totalAmount`, where the model has them).
+ */
+export declare function settleWithLines<T extends Record<string, unknown>, L extends Row>(model: CatalogModel, row: T, lines: readonly L[], context: MoneyContext): {
+    row: T;
+    lines: SettledDocument<L>['lines'];
+};
 /** A record that tracks what has been paid against it (an Invoice). */
 export declare function tracksPayments(model: CatalogModel): boolean;
 /** The field of a payment allocation that points at its payment. */
@@ -59,9 +67,10 @@ export declare function settleInvoice(invoice: Row, counted: readonly {
     at: string;
 }[], now: number): Settlement;
 /**
- * The fields a form shows but does not let anyone type: a line's `amount`, a
- * parent's totals when it has line items, and what an invoice has paid (and
- * when) when it has payment allocations.
+ * The fields a form shows but does not let anyone type: a line's money (its
+ * amount, tax and the tax code's snapshot), a parent's totals when it has line
+ * items, and what an invoice has paid (and when) when it has payment
+ * allocations.
  */
 export declare function derivedFieldNames(model: CatalogModel, hasLineChildren: boolean, hasPaymentChildren?: boolean): ReadonlySet<string>;
 /** Does the field of a line item point at a product? */
@@ -76,4 +85,3 @@ export declare function isProductField(field: {
  * editable. A product with no name or price fills nothing.
  */
 export declare function productPrefill(line: CatalogModel, product: Row | undefined): Record<string, unknown>;
-export {};

package/dist/data/derived.js

@@ -1,3 +1,5 @@
+import { settleDocument, } from "./money.js";
+export { lineAmount } from "./money.js";
 const num = (value) => {
     const n = Number(value ?? 0);
     return Number.isFinite(n) ? n : 0;
@@ -7,35 +9,47 @@ const has = (model, name) => model.fields.some((f) => f.name === name);
 export function isLineModel(model) {
     return ['quantity', 'unitPrice', 'amount'].every((n) => has(model, n));
 }
-export function lineAmounts(line) {
-    const subtotal = Math.round(num(line.quantity) * num(line.unitPrice)) - num(line.discount);
-    const tax = Math.round(subtotal * num(line.taxRate));
-    return { subtotal, tax, amount: subtotal + tax };
-}
-/** The line with its `amount` brought in line with its other fields. */
-export function settleLine(line) {
-    return { ...line, amount: lineAmounts(line).amount };
+/** The totals a document's summary shows: subtotal, tax, total. */
+export const TOTAL_FIELDS = ['subtotal', 'taxAmount', 'totalAmount'];
+/** Every header field its lines decide, `discountTotal` included. */
+export const DOCUMENT_MONEY_FIELDS = [
+    ...TOTAL_FIELDS,
+    'discountTotal',
+];
+/** The fields of a line its document's calculation writes. */
+export const LINE_MONEY_FIELDS = [
+    'amount',
+    'taxAmount',
+    'taxRate',
+    'taxCodeCode',
+    'taxCodeName',
+];
+const LINE_AMOUNT_TYPES = ['exclusive', 'inclusive', 'none'];
+/** The document's own pricing mode, else `fallback` (the app's). */
+export function documentLineAmountType(row, fallback) {
+    const value = row.lineAmountType;
+    return typeof value === 'string' && LINE_AMOUNT_TYPES.includes(value)
+        ? value
+        : fallback;
 }
-export function totalsOf(lines) {
-    let subtotal = 0;
-    let taxAmount = 0;
-    for (const line of lines) {
-        const parts = lineAmounts(line);
-        subtotal += parts.subtotal;
-        taxAmount += parts.tax;
-    }
-    return { subtotal, taxAmount, totalAmount: subtotal + taxAmount };
+/** The document's own rounding scope, else `fallback` (the app's). */
+export function documentRoundingScope(row, fallback) {
+    const value = row.taxRoundingScope;
+    return value === 'line' || value === 'document' ? value : fallback;
 }
-export const TOTAL_FIELDS = ['subtotal', 'taxAmount', 'totalAmount'];
-/** `row` with the model's total fields set from `lines`. */
-export function withTotals(model, row, lines) {
-    const totals = totalsOf(lines);
+/**
+ * `row` and its `lines` settled together: the lines' derived fields, and the
+ * model's header money fields (`subtotal`, `discountTotal`, `taxAmount`,
+ * `totalAmount`, where the model has them).
+ */
+export function settleWithLines(model, row, lines, context) {
+    const settled = settleDocument(lines, context);
     const next = { ...row };
-    for (const name of TOTAL_FIELDS) {
+    for (const name of DOCUMENT_MONEY_FIELDS) {
         if (has(model, name))
-            next[name] = totals[name];
+            next[name] = settled[name];
     }
-    return next;
+    return { row: next, lines: settled.lines };
 }
 /** A record that tracks what has been paid against it (an Invoice). */
 export function tracksPayments(model) {
@@ -91,18 +105,23 @@ export function settleInvoice(invoice, counted, now) {
     };
 }
 /**
- * The fields a form shows but does not let anyone type: a line's `amount`, a
- * parent's totals when it has line items, and what an invoice has paid (and
- * when) when it has payment allocations.
+ * The fields a form shows but does not let anyone type: a line's money (its
+ * amount, tax and the tax code's snapshot), a parent's totals when it has line
+ * items, and what an invoice has paid (and when) when it has payment
+ * allocations.
  */
 export function derivedFieldNames(model, hasLineChildren, hasPaymentChildren = false) {
     const names = new Set();
-    if (isLineModel(model))
-        names.add('amount');
+    if (isLineModel(model)) {
+        for (const name of LINE_MONEY_FIELDS)
+            if (has(model, name))
+                names.add(name);
+    }
     if (hasLineChildren) {
-        for (const name of TOTAL_FIELDS)
+        for (const name of DOCUMENT_MONEY_FIELDS) {
             if (has(model, name))
                 names.add(name);
+        }
     }
     if (hasPaymentChildren && tracksPayments(model)) {
         for (const name of ['amountPaid', 'paidDate']) {

package/dist/data/display.d.ts

@@ -1,8 +1,3 @@
-/**
- * Which field labels a record in pickers. `model.display` comes from the
- * manifest's `displayLabelField` (happyvertical/smrt#3611); a model that
- * declares none falls back to the first of `name`, `title`, `label`, `code`.
- */
 import type { CatalogField, CatalogModel } from '../catalog/types.ts';
 export declare const DEFAULT_LABEL_FIELDS: readonly ["name", "title", "label", "code"];
 /** The fields that may label a record of the model, best first. */
@@ -11,13 +6,31 @@ export declare function labelFields(model: CatalogModel): string[];
 export declare function displayLabel(model: CatalogModel, record: Readonly<Record<string, unknown>>): string | undefined;
 /** Finds the label of the record a relation field points at. */
 export type RelatedLabel = (field: CatalogField, id: string) => string | undefined;
+/**
+ * The field that identifies a document to a person (`invoiceNumber`, an
+ * order's `reference`): the first field the framework's field roles
+ * (`deriveFieldRoles`, smrt#3718) give the `identifier` role. `undefined`
+ * for a model with a name of its own: a product's `code` is a detail, its
+ * `name` is what it is called.
+ */
+export declare function identifierField(model: CatalogModel): CatalogField | undefined;
+/** A document's identifier value, e.g. `WIL-1133`; `undefined` when empty. */
+export declare function identifierOf(model: CatalogModel, record: Readonly<Record<string, unknown>>): string | undefined;
 /** A record's own number, e.g. `invoiceNumber` or `number`. */
 export declare function numberOf(model: CatalogModel, record: Readonly<Record<string, unknown>>): string | undefined;
 /** The relation field that best says what a record is about, if it has one. */
 export declare function partyField(fields: readonly CatalogField[], record: Readonly<Record<string, unknown>>): CatalogField | undefined;
 /**
- * The text that names a record: its label field, else its number (plus the
- * party it is for), else the party, with the amount and date for a money record
- * such as a payment. `undefined` when nothing names it.
+ * The text that names a record: its label field, else its identifier (a
+ * document is its number: `GRA-3159`, never `Ridgeline Construction ·
+ * GRA-3159`), else, for a money record such as a payment allocation, the party
+ * it is for with its amount and date, else the party and a description.
+ * `undefined` when nothing names it.
  */
 export declare function recordName(model: CatalogModel, record: Readonly<Record<string, unknown>>, related: RelatedLabel, fields?: readonly CatalogField[]): string | undefined;
+/**
+ * A record page's heading: a document is its kind and identifier
+ * (`Order GRA-3159`), anything else its name. `kind` is the model's name
+ * as a person reads it ("Order", "Purchase order").
+ */
+export declare function recordHeading(model: CatalogModel, record: Readonly<Record<string, unknown>>, name: string, kind: string): string;

package/dist/data/display.js

@@ -1,3 +1,9 @@
+/**
+ * Which field labels a record in pickers. `model.display` comes from the
+ * manifest's `displayLabelField` (happyvertical/smrt#3611); a model that
+ * declares none falls back to the first of `name`, `title`, `label`, `code`.
+ */
+import { deriveFieldRoles, fieldWithRole, } from '@happyvertical/smrt-svelte/screens';
 import { formatMoney } from "./format.js";
 export const DEFAULT_LABEL_FIELDS = ['name', 'title', 'label', 'code'];
 /** The fields that may label a record of the model, best first. */
@@ -27,11 +33,55 @@ const PARTY_ORDER = [
     /^payment/i,
     /^contract/i,
 ];
+/** A document's own number, e.g. `invoiceNumber` or `number`. */
+const NUMBER_NAME = /(^|[a-z])Number$|^number$/;
+/**
+ * The field that identifies a document to a person (`invoiceNumber`, an
+ * order's `reference`): the first field the framework's field roles
+ * (`deriveFieldRoles`, smrt#3718) give the `identifier` role. `undefined`
+ * for a model with a name of its own: a product's `code` is a detail, its
+ * `name` is what it is called.
+ */
+export function identifierField(model) {
+    if (labelFields(model).some((name) => name !== 'code'))
+        return undefined;
+    const own = model.fields.filter((f) => !f.system);
+    const roles = deriveFieldRoles({
+        objectRef: model.id,
+        className: model.name,
+        fields: Object.fromEntries(own.map((f) => [
+            f.name,
+            {
+                type: SCREEN_TYPES.has(f.type) ? f.type : 'text',
+                ...(f.enum?.length ? { enum: f.enum } : {}),
+                ...(f.ui ? { ui: { ...f.ui } } : {}),
+            },
+        ])),
+    });
+    const name = fieldWithRole(roles, 'identifier');
+    return name ? own.find((f) => f.name === name) : undefined;
+}
+const SCREEN_TYPES = new Set([
+    'text',
+    'integer',
+    'decimal',
+    'boolean',
+    'datetime',
+    'json',
+    'foreignKey',
+    'crossPackageRef',
+]);
+/** A document's identifier value, e.g. `WIL-1133`; `undefined` when empty. */
+export function identifierOf(model, record) {
+    const field = identifierField(model);
+    const value = field ? record[field.name] : undefined;
+    return typeof value === 'string' && value.trim() !== '' ? value : undefined;
+}
 /** A record's own number, e.g. `invoiceNumber` or `number`. */
 export function numberOf(model, record) {
     const field = model.fields.find((f) => !f.system &&
         f.type === 'text' &&
-        /(^|[a-z])Number$|^number$/.test(f.name) &&
+        NUMBER_NAME.test(f.name) &&
         typeof record[f.name] === 'string' &&
         String(record[f.name]).trim() !== '');
     return field ? String(record[field.name]) : undefined;
@@ -48,21 +98,23 @@ export function partyField(fields, record) {
 }
 const DATE_NAME = /(paid|allocated|issue|^date$|createdat)/i;
 /**
- * The text that names a record: its label field, else its number (plus the
- * party it is for), else the party, with the amount and date for a money record
- * such as a payment. `undefined` when nothing names it.
+ * The text that names a record: its label field, else its identifier (a
+ * document is its number: `GRA-3159`, never `Ridgeline Construction ·
+ * GRA-3159`), else, for a money record such as a payment allocation, the party
+ * it is for with its amount and date, else the party and a description.
+ * `undefined` when nothing names it.
  */
 export function recordName(model, record, related, fields = model.fields) {
     const own = displayLabel(model, record);
     if (own)
         return own;
+    const identifier = identifierOf(model, record);
+    if (identifier)
+        return identifier;
     const partyOf = partyField(fields, record);
     const party = partyOf?.related
         ? related(partyOf, String(record[partyOf.name]))
         : undefined;
-    const number = numberOf(model, record);
-    if (number)
-        return unique([number, party]);
     const moneyField = model.fields.find((f) => f.name === 'amount' && f.type === 'integer');
     if (moneyField && typeof record.amount === 'number') {
         const dateField = model.fields.find((f) => f.type === 'datetime' && DATE_NAME.test(f.name) && record[f.name]);
@@ -72,10 +124,21 @@ export function recordName(model, record, related, fields = model.fields) {
             dateField ? String(record[dateField.name]).slice(0, 10) : undefined,
         ]);
     }
-    const reference = ['reference', 'description']
-        .map((name) => record[name])
-        .find((v) => typeof v === 'string' && v.trim() !== '');
-    return unique([party, reference]);
+    const description = typeof record.description === 'string' && record.description.trim() !== ''
+        ? record.description
+        : undefined;
+    return unique([party, description]);
+}
+/**
+ * A record page's heading: a document is its kind and identifier
+ * (`Order GRA-3159`), anything else its name. `kind` is the model's name
+ * as a person reads it ("Order", "Purchase order").
+ */
+export function recordHeading(model, record, name, kind) {
+    if (displayLabel(model, record))
+        return name;
+    const identifier = identifierOf(model, record);
+    return identifier && identifier === name ? `${kind} ${identifier}` : name;
 }
 function unique(parts) {
     const kept = parts.filter((p) => Boolean(p));

package/dist/data/fakes.d.ts

@@ -10,8 +10,10 @@ export declare function createRandom(seed: number): () => number;
 /** FNV-1a hash of a string, for seeding. */
 export declare function hashString(value: string): number;
 /**
- * Money is stored as integer minor units (cents). A field is money when it is
- * an integer whose name says so; everything else numeric is a plain number.
+ * Money is stored as integer minor units (cents). An integer field is money
+ * when the manifest says so (`ui.format === 'money'`); a field that declares
+ * any other format is not, and neither is a framework-managed one. With no
+ * declared format the field's name decides.
  */
 export declare function isMoneyField(field: CatalogField): boolean;
 /**
@@ -25,18 +27,53 @@ export declare const PRODUCT_CATALOG: readonly {
 }[];
 /** Fixed clock so seeded timestamps never change between runs. */
 export declare const EPOCH: number;
+/** Sample rows per model unless a pack or {@link SAMPLE_ROW_COUNTS} says otherwise. */
+export declare const DEFAULT_SAMPLE_ROWS = 8;
 /** A UUID-shaped id derived from a seed string. */
 export declare function fakeId(seed: string): string;
 /** Fractions a tax rate takes: 0%, 5%, 8.25%, 13% and 20%. */
 export declare const TAX_RATES: readonly [0, 0.05, 0.0825, 0.13, 0.2];
+/**
+ * The sample tax rate when neither the app's setting nor the pack names one:
+ * every line of every document is taxed at it, so a document's tax is one
+ * rate of its subtotal, as on a real invoice.
+ */
+export declare const DEFAULT_SAMPLE_TAX_RATE = 0.05;
 export declare const SAMPLE_ROW_COUNTS: Readonly<Record<string, number>>;
-/** Sample rows for a model: the pack's count, else the shared one, else `fallback`. */
+/**
+ * How many rows of each customer-linked model (orders, quotes, invoices,
+ * payments: any model with a FK to a Customer) point at each sample customer:
+ * 3 to 6, uneven, seeded by the customer's index so it never changes. The
+ * slots interleave (every customer once, then again...), so a list's first
+ * rows still show different customers and row `n < customers` points at
+ * customer `n`.
+ */
+export declare function customerSlots(customers: number): readonly number[];
+/**
+ * Sample rows for a model: the pack's count, else the shared one, else, for a
+ * customer-linked model, one per {@link customerSlots} slot, else `fallback`.
+ */
 export declare function sampleRowCount(modelId: string, fallback: number): number;
-/** One fake value for a field. Money is an integer number of minor units. */
-export declare function fakeValue(field: CatalogField, random: () => number, context: {
+/**
+ * Which row of the target a sample relation points at. Rows are seeded with
+ * ids from `(model, index)`, so pointing at index `n` points at a real row;
+ * spread over every row of the target, so each sample record has related
+ * records (a customer several orders, quotes and invoices), not just the
+ * first few.
+ */
+export declare function relatedIndex(field: CatalogField, context: FakeContext): number;
+/**
+ * Where a fake value is made: the model, the row's index and the data
+ * source's rows per model (default {@link DEFAULT_SAMPLE_ROWS}), so a
+ * reference points at a row the source actually made.
+ */
+export interface FakeContext {
     modelId: string;
     index: number;
-}): unknown;
+    rows?: number;
+}
+/** One fake value for a field. Money is an integer number of minor units. */
+export declare function fakeValue(field: CatalogField, random: () => number, context: FakeContext): unknown;
 /** Fields a person edits: everything the framework does not manage. */
 export declare function editableFields(model: CatalogModel): CatalogField[];
 export declare const DAY: number;
@@ -47,6 +84,8 @@ export declare const DAY: number;
  */
 export declare function packLine(index: number): PackLine | undefined;
 /** A single seeded record for a model. */
-export declare function fakeRecord(model: CatalogModel, index: number, seed: number): ModelRecord;
-/** `count` seeded records for a model. */
-export declare function fakeRecords(model: CatalogModel, count: number, seed?: number): ModelRecord[];
+export declare function fakeRecord(model: CatalogModel, index: number, seed: number, rows?: number): ModelRecord;
+/** Every `EXEMPT_EVERY`th sample customer does not pay sales tax. */
+export declare const EXEMPT_EVERY = 8;
+/** `count` seeded records for a model; `rows` is the source's rows per model. */
+export declare function fakeRecords(model: CatalogModel, count: number, seed?: number, rows?: number): ModelRecord[];