@happyvertical/smrt-planner 0.0.0-stage → 0.0.2

package/dist/data/columns.js

@@ -0,0 +1,150 @@
+import { isRelation } from "../fields/renderer.js";
+import { recordName } from "./display.js";
+import { labelKey } from "./format.js";
+const num = (v) => typeof v === 'number' && Number.isFinite(v) ? v : 0;
+/** Lower is shown first: what names a row, who it is for, its state, its money, its dates. */
+function columnRank(f) {
+    const name = f.name;
+    if (f.type === 'json')
+        return 99;
+    if (/^(name|title|label|code)$|Number$|^number$/.test(name))
+        return 0;
+    if (name === 'reference' && f.type === 'text')
+        return 0.5;
+    // Long free text is the first thing a list can do without.
+    if (name === 'description' && f.type === 'text')
+        return 5.9;
+    if (isRelation(f)) {
+        if (/^(customer|vendor|profile)/i.test(name))
+            return 1;
+        // The contract and ledger links are bookkeeping, not what a row is about.
+        return /^(contract|.*(journal|account))/i.test(name) ? 7 : 2;
+    }
+    if ((f.enum?.length ?? 0) > 0 && /(status|state|stage)$/i.test(name))
+        return 3;
+    if (/^(totalAmount|amount|total)$/.test(name))
+        return 4;
+    if (f.type === 'datetime') {
+        // When a scheduled thing starts is what its row is about.
+        if (/^start(date|at)?$/i.test(name))
+            return 1.2;
+        if (/^due/i.test(name))
+            return 5;
+        if (/(issue|paid|allocated|^date$)/i.test(name))
+            return 5.2;
+    }
+    return 6;
+}
+/**
+ * The columns of a list: what names the row, who it is for, its status, its
+ * money and its dates first; then the other numeric/boolean/date fields and
+ * choices so a row reads like a record, not a wall of text. A record that
+ * tracks payments (`totalAmount` and `amountPaid`) also gets "Amount due".
+ */
+export function listColumns(fields, max = 6) {
+    const shown = fields.filter((f) => f.type !== 'json');
+    const lead = new Set(shown.slice(0, 3));
+    const candidates = shown.filter((f) => lead.has(f) ||
+        columnRank(f) < 6 ||
+        ['integer', 'decimal', 'boolean', 'datetime'].includes(f.type) ||
+        (f.enum?.length ?? 0) > 0 ||
+        isRelation(f));
+    const ranked = candidates
+        .map((f, i) => ({ f, i, rank: columnRank(f) }))
+        .sort((x, y) => x.rank - y.rank || x.i - y.i)
+        .map((x) => x.f);
+    const total = shown.find((f) => f.name === 'totalAmount');
+    if (total && shown.some((f) => f.name === 'amountPaid')) {
+        const due = {
+            ...total,
+            name: 'amountDue',
+            label: 'Amount due',
+            required: false,
+            derive: (row) => num(row.totalAmount) - num(row.amountPaid),
+        };
+        const at = ranked.findIndex((f) => f.name === 'totalAmount');
+        ranked.splice(at < 0 ? ranked.length : at + 1, 0, due);
+    }
+    // Records that are scheduled (an `allDay` flag) show when they start to the minute.
+    const scheduled = shown.some((f) => f.name === 'allDay');
+    return ranked
+        .slice(0, max)
+        .map((f) => scheduled &&
+        f.type === 'datetime' &&
+        /^(start|end)(date|at)$/i.test(f.name)
+        ? { ...f, showTime: true }
+        : f);
+}
+/** The value a list cell shows for a row. */
+export function cellValue(column, row) {
+    return column.derive ? column.derive(row) : row[column.name];
+}
+/** The rows whose foreign key points at the parent record. */
+export function rowsOf(rows, fk, parentId) {
+    return rows.filter((r) => r[fk] === parentId);
+}
+/**
+ * The value a new record starts with: the field's default; an enumeration with
+ * none (a `status`, or a required choice) starts at "draft" or its first value
+ * rather than empty.
+ */
+export function blankValue(field) {
+    if (field.default !== undefined && field.default !== null) {
+        return field.default;
+    }
+    const choices = field.enum ?? [];
+    if (choices.length > 0 &&
+        (field.required || /(status|state|stage)$/i.test(field.name))) {
+        return choices.includes('draft') ? 'draft' : choices[0];
+    }
+    if (field.type === 'boolean')
+        return false;
+    return field.type === 'text' ? '' : null;
+}
+/** Starting values for a new record of the fields shown. */
+export function blankRecord(fields) {
+    const blank = {};
+    for (const field of fields)
+        blank[field.name] = blankValue(field);
+    return blank;
+}
+/** Starting values for a new child row: field defaults, the foreign key preset. */
+export function blankChild(fields, fk, parentId) {
+    return { ...blankRecord(fields), [fk]: parentId };
+}
+const isEmpty = (value) => value === null ||
+    value === undefined ||
+    (typeof value === 'string' && value.trim() === '');
+/**
+ * Required fields without a value, as `{ name: message }`. A switch always has
+ * a value; fields in `skip` (derived or preset ones) are not asked for.
+ */
+export function missingRequired(fields, values, skip = new Set()) {
+    const errors = {};
+    for (const field of fields) {
+        if (!field.required || field.type === 'boolean' || skip.has(field.name)) {
+            continue;
+        }
+        if (isEmpty(values[field.name]))
+            errors[field.name] = `${field.label} is required.`;
+    }
+    return errors;
+}
+/**
+ * One line for near the Save button: which fields still need a value.
+ * Empty when nothing is missing, so it clears itself as the errors do.
+ */
+export function errorSummary(fields, errors) {
+    const labels = fields.filter((f) => errors[f.name]).map((f) => f.label);
+    if (labels.length === 0)
+        return '';
+    return `Cannot save yet: ${labels.join(', ')} ${labels.length === 1 ? 'is' : 'are'} required.`;
+}
+/**
+ * What names a record to a person (see `recordName`): its label, else its
+ * number and who it is for ("WIL-1133 · Lantern Collective"), else the record
+ * it points at plus its reference.
+ */
+export function recordTitle(model, fields, row, labels) {
+    return (recordName(model, row, (field, id) => field.related ? labels.get(labelKey(field.related, id)) : undefined, fields) ?? '');
+}

package/dist/data/context.d.ts

@@ -0,0 +1,8 @@
+import type { DataSource } from './source.ts';
+/** The context key, for tests that render a component without the layout. */
+export declare const DATA_SOURCE_KEY: symbol;
+/** Provide the data source for every generated view below the caller. */
+export declare function provideDataSource(source: DataSource): DataSource;
+export declare function useDataSource(): DataSource;
+/** The data source below the caller, or null when none was provided. */
+export declare function tryUseDataSource(): DataSource | null;

package/dist/data/context.js

@@ -0,0 +1,19 @@
+import { getContext, setContext } from 'svelte';
+const KEY = Symbol('smrt-planner:data-source');
+/** The context key, for tests that render a component without the layout. */
+export const DATA_SOURCE_KEY = KEY;
+/** Provide the data source for every generated view below the caller. */
+export function provideDataSource(source) {
+    setContext(KEY, source);
+    return source;
+}
+export function useDataSource() {
+    const source = getContext(KEY);
+    if (!source)
+        throw new Error('No DataSource provided; see +layout.svelte');
+    return source;
+}
+/** The data source below the caller, or null when none was provided. */
+export function tryUseDataSource() {
+    return getContext(KEY) ?? null;
+}

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[];