@happyvertical/smrt-planner 0.0.0-stage → 0.0.1

package/dist/data/derived.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Amounts the commerce models derive rather than take as input, mirrored from
+ * `ContractLineItem` / `InvoiceLineItem` / `Invoice` in smrt-commerce:
+ *
+ *   line subtotal = round(quantity * unitPrice) - discount   (minor units)
+ *   line tax      = round(line subtotal * taxRate)           (taxRate is a fraction)
+ *   line amount   = line subtotal + line tax
+ *
+ * and a parent with line items takes `subtotal`, `taxAmount` and `totalAmount`
+ * from the sum of its lines, ignoring what a form sent.
+ */
+import type { CatalogModel } from '../catalog/types.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;
+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;
+/** 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. */
+export declare function allocationPaymentField(model: CatalogModel): import("../catalog/types.ts").CatalogField | undefined;
+/** The field of a payment allocation that points at the invoice it pays. */
+export declare function allocationInvoiceField(model: CatalogModel): import("../catalog/types.ts").CatalogField | undefined;
+/** A payment applied to an invoice: one payment, one invoice, an amount. */
+export declare function isAllocationModel(model: CatalogModel): boolean;
+/** What counts as money in: only a completed payment pays an invoice. */
+export declare const PAID_PAYMENT_STATUS = "completed";
+export interface Settlement {
+    amountPaid: number;
+    status: string;
+    paidDate: string | null;
+}
+/**
+ * An invoice's payment state from the allocations of completed payments
+ * (`counted`): `amountPaid` is their sum, the status is paid once the total is
+ * covered, otherwise overdue after the due date and sent before it. A draft or
+ * cancelled invoice keeps its status; `paidDate` is set only when fully paid,
+ * to the last allocation.
+ */
+export declare function settleInvoice(invoice: Row, counted: readonly {
+    amount: number;
+    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.
+ */
+export declare function derivedFieldNames(model: CatalogModel, hasLineChildren: boolean, hasPaymentChildren?: boolean): ReadonlySet<string>;
+/** Does the field of a line item point at a product? */
+export declare function isProductField(field: {
+    name: string;
+    type: string;
+    related?: string;
+}): boolean;
+/**
+ * What picking a product fills in on a line item: its name as the description
+ * and its price as the unit price, for the fields the line has. Both stay
+ * 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

@@ -0,0 +1,139 @@
+const num = (value) => {
+    const n = Number(value ?? 0);
+    return Number.isFinite(n) ? n : 0;
+};
+const has = (model, name) => model.fields.some((f) => f.name === name);
+/** A line item: it prices a quantity of something. */
+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 };
+}
+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 };
+}
+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);
+    const next = { ...row };
+    for (const name of TOTAL_FIELDS) {
+        if (has(model, name))
+            next[name] = totals[name];
+    }
+    return next;
+}
+/** A record that tracks what has been paid against it (an Invoice). */
+export function tracksPayments(model) {
+    return ['totalAmount', 'amountPaid', 'status'].every((n) => has(model, n));
+}
+const isRef = (f) => f.type === 'foreignKey' || f.type === 'crossPackageRef';
+/** The field of a payment allocation that points at its payment. */
+export function allocationPaymentField(model) {
+    return model.fields.find((f) => isRef(f) && /^payment/i.test(f.name));
+}
+/** The field of a payment allocation that points at the invoice it pays. */
+export function allocationInvoiceField(model) {
+    return model.fields.find((f) => isRef(f) && /^invoice/i.test(f.name));
+}
+/** A payment applied to an invoice: one payment, one invoice, an amount. */
+export function isAllocationModel(model) {
+    return (has(model, 'amount') &&
+        Boolean(allocationPaymentField(model)) &&
+        Boolean(allocationInvoiceField(model)));
+}
+/** What counts as money in: only a completed payment pays an invoice. */
+export const PAID_PAYMENT_STATUS = 'completed';
+/**
+ * An invoice's payment state from the allocations of completed payments
+ * (`counted`): `amountPaid` is their sum, the status is paid once the total is
+ * covered, otherwise overdue after the due date and sent before it. A draft or
+ * cancelled invoice keeps its status; `paidDate` is set only when fully paid,
+ * to the last allocation.
+ */
+export function settleInvoice(invoice, counted, now) {
+    const amountPaid = counted.reduce((sum, a) => sum + num(a.amount), 0);
+    const total = num(invoice.totalAmount);
+    const current = String(invoice.status ?? 'draft');
+    const fullyPaid = total > 0 && amountPaid >= total;
+    let status = current;
+    if (fullyPaid)
+        status = 'paid';
+    else if (current !== 'draft' && current !== 'cancelled') {
+        const due = Date.parse(String(invoice.dueDate ?? ''));
+        if (Number.isFinite(due) && due < now)
+            status = 'overdue';
+        else
+            status = current === 'viewed' ? 'viewed' : 'sent';
+    }
+    const last = counted
+        .map((a) => a.at)
+        .sort()
+        .at(-1);
+    return {
+        amountPaid,
+        status,
+        paidDate: fullyPaid ? (last ?? String(invoice.issueDate ?? '')) : null,
+    };
+}
+/**
+ * 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.
+ */
+export function derivedFieldNames(model, hasLineChildren, hasPaymentChildren = false) {
+    const names = new Set();
+    if (isLineModel(model))
+        names.add('amount');
+    if (hasLineChildren) {
+        for (const name of TOTAL_FIELDS)
+            if (has(model, name))
+                names.add(name);
+    }
+    if (hasPaymentChildren && tracksPayments(model)) {
+        for (const name of ['amountPaid', 'paidDate']) {
+            if (has(model, name))
+                names.add(name);
+        }
+    }
+    return names;
+}
+/** Does the field of a line item point at a product? */
+export function isProductField(field) {
+    return (isRef(field) &&
+        (field.related?.endsWith(':Product') === true ||
+            /^product(Id)?$/i.test(field.name)));
+}
+/**
+ * What picking a product fills in on a line item: its name as the description
+ * and its price as the unit price, for the fields the line has. Both stay
+ * editable. A product with no name or price fills nothing.
+ */
+export function productPrefill(line, product) {
+    const fill = {};
+    if (!product)
+        return fill;
+    if (has(line, 'description') &&
+        typeof product.name === 'string' &&
+        product.name) {
+        fill.description = product.name;
+    }
+    if (has(line, 'unitPrice') && typeof product.price === 'number') {
+        fill.unitPrice = product.price;
+    }
+    return fill;
+}

package/dist/data/display.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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. */
+export declare function labelFields(model: CatalogModel): string[];
+/** The first non-empty label field of a record, or undefined. */
+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;
+/** 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.
+ */
+export declare function recordName(model: CatalogModel, record: Readonly<Record<string, unknown>>, related: RelatedLabel, fields?: readonly CatalogField[]): string | undefined;

package/dist/data/display.js

@@ -0,0 +1,84 @@
+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. */
+export function labelFields(model) {
+    const declared = model.display?.label;
+    const names = new Set(model.fields.map((f) => f.name));
+    return [...(declared ? [declared] : []), ...DEFAULT_LABEL_FIELDS].filter((name, index, all) => names.has(name) && all.indexOf(name) === index);
+}
+/** The first non-empty label field of a record, or undefined. */
+export function displayLabel(model, record) {
+    for (const name of labelFields(model)) {
+        const value = record[name];
+        if (typeof value === 'string' && value.trim() !== '')
+            return value;
+    }
+    return undefined;
+}
+const isRef = (f) => f.type === 'foreignKey' || f.type === 'crossPackageRef';
+/** Relations that say what a record is about, best first. */
+const PARTY_ORDER = [
+    /^customer/i,
+    /^vendor/i,
+    /^profile/i,
+    /^product/i,
+    /^invoice/i,
+    /^order/i,
+    /^payment/i,
+    /^contract/i,
+];
+/** 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) &&
+        typeof record[f.name] === 'string' &&
+        String(record[f.name]).trim() !== '');
+    return field ? String(record[field.name]) : undefined;
+}
+/** The relation field that best says what a record is about, if it has one. */
+export function partyField(fields, record) {
+    const set = fields.filter((f) => isRef(f) && typeof record[f.name] === 'string' && record[f.name] !== '');
+    for (const pattern of PARTY_ORDER) {
+        const found = set.find((f) => pattern.test(f.name));
+        if (found)
+            return found;
+    }
+    return undefined;
+}
+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.
+ */
+export function recordName(model, record, related, fields = model.fields) {
+    const own = displayLabel(model, record);
+    if (own)
+        return own;
+    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]);
+        return unique([
+            party,
+            formatMoney(record.amount),
+            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]);
+}
+function unique(parts) {
+    const kept = parts.filter((p) => Boolean(p));
+    const text = kept.filter((p, i) => kept.indexOf(p) === i).join(' · ');
+    return text || undefined;
+}

package/dist/data/fakes.d.ts

@@ -0,0 +1,52 @@
+import type { CatalogField, CatalogModel } from '../catalog/types.ts';
+import { type PackLine } from './packs.ts';
+/** A row of sample data. `id` is always present. */
+export interface ModelRecord {
+    id: string;
+    [field: string]: unknown;
+}
+/** Deterministic PRNG (mulberry32): the same seed always yields the same run. */
+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.
+ */
+export declare function isMoneyField(field: CatalogField): boolean;
+/**
+ * Things a shop sells, with a price in cents. Sample products and SKUs take
+ * their names from here by row index, and a line item pointing at product `n`
+ * reads as that product, so a picked product and a sample line agree.
+ */
+export declare const PRODUCT_CATALOG: readonly {
+    name: string;
+    price: number;
+}[];
+/** Fixed clock so seeded timestamps never change between runs. */
+export declare const EPOCH: number;
+/** 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];
+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`. */
+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: {
+    modelId: string;
+    index: number;
+}): unknown;
+/** Fields a person edits: everything the framework does not manage. */
+export declare function editableFields(model: CatalogModel): CatalogField[];
+export declare const DAY: number;
+/**
+ * The line a sample line item reads as when the pack describes lines apart
+ * from products (labour, fabrication, passes); `undefined` for packs whose
+ * lines are their products.
+ */
+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[];