@multiplatform.one/table 7.7.4 → 7.8.0

package/types/utils/money.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Money — exact decimal arithmetic on the wire strings (MPO-252).
+ *
+ * A Currency field arrives as a decimal STRING ("-455.87"). That is
+ * deliberate: a float would round it, and money that rounds is money that
+ * disagrees with the ledger. The consequence is that money is not `number`
+ * and it is not `text` either, and treating it as text is silently wrong in
+ * one specific way that nothing on screen reveals:
+ *
+ *     "9.00" > "10.00"   // true, for strings
+ *
+ * So a table sorted on an amount column is not approximately right, it is
+ * nonsense. The answer downstream was to make NO money column sortable
+ * anywhere, which gives up a real capability to avoid a wrong answer. These
+ * helpers exist so the kit can offer the capability instead: a comparator
+ * that orders decimal strings numerically, and exact add/sum so anything
+ * folding money client-side (a running balance, a tree rolling leaves into
+ * parents, a per-currency total) never touches a float.
+ *
+ * ─── The mixed-currency rule ──────────────────────────────────────────────
+ *
+ * TWO CURRENCIES ARE TWO FIGURES, AND NEITHER CONVERTS. There is no rate in
+ * the table, no rate on the row, and a sum that silently added USD to INR
+ * would produce a number that is wrong in a way nobody can see. So:
+ *
+ *  - `addMoney` and `sumMoney` take amounts ONLY. They do not know about
+ *    currency and will happily add two figures — it is the caller's job not
+ *    to hand them different currencies.
+ *  - `sumMoneyByCurrency` is the safe total: it returns one exact figure PER
+ *    currency code. A ledger that genuinely mixes currencies gets N figures
+ *    and prints them all.
+ *  - `compareMoney` orders by magnitude only. Sorting a mixed-currency column
+ *    by amount is meaningful only if the reader can see the codes differ,
+ *    which is why a money column formats from the row's own currency.
+ *
+ * ─── Implementation ───────────────────────────────────────────────────────
+ *
+ * Each operand is scaled to an integer of its own fraction length, the two
+ * are combined as BigInt at the wider scale, and the result renders back at
+ * that scale: "10.50" + "0.125" is "10.625", never 10.625000000000002.
+ * BigInt is ES2020 and Hermes has shipped it since RN 0.70. The `BigInt()`
+ * call form is used instead of `10n` literals so no transform in the chain
+ * has to know the syntax.
+ *
+ * Malformed input throws. A NaN folded quietly into a running balance is the
+ * one outcome worse than a crash.
+ */
+/** True when `raw` is a decimal string these helpers can operate on. */
+export declare function isMoneyString(raw: unknown): raw is string;
+/** `a + b`, exact, at the wider of the two scales. Amounts only — see the mixed-currency rule. */
+export declare function addMoney(a: string, b: string): string;
+/** `a - b`, exact, at the wider of the two scales. */
+export declare function subtractMoney(a: string, b: string): string;
+/**
+ * Exact sum of decimal strings, at the widest scale present. `[]` sums to
+ * `"0"`. Amounts only: this does not look at currency, so do not hand it two.
+ */
+export declare function sumMoney(values: readonly string[]): string;
+/**
+ * One exact total PER currency code — the safe total for a ledger that mixes
+ * currencies, because two currencies are two figures and neither converts.
+ * Rows whose amount is not a decimal string are skipped, not coerced.
+ *
+ * @param rows - Anything carrying an amount and a currency
+ * @param amountOf - Reads the decimal-string amount off a row
+ * @param currencyOf - Reads the currency code off a row. Rows carrying none
+ *   group under "—", so an unlabelled figure is never merged into a labelled
+ *   one.
+ */
+export declare function sumMoneyByCurrency<TRow>(rows: readonly TRow[], amountOf: (row: TRow) => unknown, currencyOf: (row: TRow) => unknown): Record<string, string>;
+/**
+ * Numeric ordering of two money strings: negative, zero or positive.
+ * `compareMoney("9.00", "10.00")` is negative — which string comparison gets
+ * backwards, and which is the whole reason this type exists.
+ */
+export declare function compareMoney(a: string, b: string): number;
+/**
+ * Sort comparator for a money column: `compareMoney`, but total over anything
+ * a row can hold. Blanks and non-decimal values sort BEFORE every real figure
+ * rather than throwing, because a sort must not crash the table on one bad
+ * row; the value is still visible in its own cell.
+ */
+export declare function moneyComparator(a: unknown, b: unknown): number;
+/** True when the money string is negative — for colour, not for arithmetic. */
+export declare function isNegativeMoney(raw: unknown): boolean;
+/**
+ * Locale-formatted money for DISPLAY. Parsing here goes one way only: the
+ * parsed number is never written back into the data.
+ *
+ * A non-decimal value comes back as its own string rather than as "NaN" or
+ * "0.00", so a bad row reads as bad instead of as zero.
+ */
+export declare function formatMoney(raw: unknown, currency?: string, locale?: string): string;
+//# sourceMappingURL=money.d.ts.map

package/types/utils/money.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"money.d.ts","sourceRoot":"","sources":["../../src/utils/money.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAiCH,wEAAwE;AACxE,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,MAAM,CAIzD;AAED,kGAAkG;AAClG,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAKrD;AAED,sDAAsD;AACtD,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAK1D;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAQ1D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EACrC,IAAI,EAAE,SAAS,IAAI,EAAE,EACrB,QAAQ,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,OAAO,EAChC,UAAU,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,OAAO,GACjC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAWxB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAQzD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,MAAM,CAO9D;AAED,+EAA+E;AAC/E,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAErD;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAepF"}

package/types/utils/rowAccumulator.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Row accumulator — a column that is a function of every row BEFORE it
+ * (MPO-250).
+ *
+ * A running balance is the canonical case, and it is the default column in
+ * the oldest data view there is: every register, statement, ledger,
+ * reconciliation and audit trail needs one. It is a FOLD over the rows in a
+ * total order, and the value on row N depends on rows 1..N-1, so it has to be
+ * computed before the table paginates, sorts or filters — otherwise page two
+ * starts from zero and a sort by payee scrambles every figure on screen.
+ *
+ * A column `cell` renderer sees ONE row and never the rows before it, so this
+ * is a separate seam: the table folds the whole row set once, merges the
+ * derived fields onto each row, and hands the finished rows to the row model.
+ * Everything downstream (filter, sort, group, paginate) then operates on rows
+ * that already carry the derived value.
+ *
+ * ─── The ordering contract ────────────────────────────────────────────────
+ *
+ * 1. The fold runs over the FULL row set the table was handed, before
+ *    filtering, sorting and pagination. In infinite/loader mode that is the
+ *    pages loaded so far, not the whole server-side table.
+ *
+ * 2. `order` establishes the fold order, and the rows come out IN it — a fold
+ *    order is the order the derived column reads down, so it is also the
+ *    table's default row order. Omit `order` and the rows fold in the order
+ *    they arrived (typically the server's `order_by`).
+ *
+ * 3. When the user sorts on ANOTHER column, the table reorders rows for
+ *    display and does NOT refold. The derived value stays attached to its row
+ *    and keeps meaning "the fold value at this row's position in the fold
+ *    order". So a running balance under a payee sort is still a correct
+ *    per-row figure, but it no longer reads down the column as a progression.
+ *    That is deliberate: recomputing a running balance in payee order would
+ *    produce a number that means nothing. Say so in the column header, or
+ *    mark the derived column `sortable: false` and let the reader sort
+ *    elsewhere.
+ *
+ * 4. Filtering hides rows without refolding. A balance on a visible row still
+ *    counts the rows the filter hid — which is what a statement filter does,
+ *    and the only answer that stays consistent with the account's real total.
+ *
+ * 5. Server-side mode (`manualPagination`) folds only the page the server
+ *    sent, because that is the only row set the client has. A running balance
+ *    over a server-paginated table therefore needs the server to send the
+ *    running figure, or the table to hold every row. The fold cannot invent
+ *    rows it was never given.
+ *
+ * ─── Totals ───────────────────────────────────────────────────────────────
+ *
+ * `total` reads the finished accumulator once, after every row. Its result is
+ * published on the table state as `computed.foldTotal`, which a column's
+ * TanStack `footer` renderer reads through `useDataTableState()` — the table
+ * already renders a footer row whenever any column defines `footer`, so a
+ * total row needs no new chrome. Same fold, read once at the end.
+ */
+import type { DataTableData } from "../types";
+/**
+ * A fold over the ordered row set, run once before the table's row model.
+ *
+ * The object must be a STABLE reference (module constant or `useMemo`) — the
+ * fold re-runs and produces new row objects whenever its identity changes,
+ * the same contract `loadPage` and `getSubRows` already carry.
+ *
+ * @typeParam TData - The row type
+ * @typeParam TAcc - The accumulator carried between rows
+ */
+export interface RowAccumulator<TData extends DataTableData = DataTableData, TAcc = any> {
+    /**
+     * Seed value. Pass a factory when the seed is mutable, so one accumulator
+     * object can be reused across folds without leaking state between them.
+     */
+    initial: TAcc | (() => TAcc);
+    /** Fold step: the accumulator so far, this row, its index in fold order. */
+    reduce: (accumulator: TAcc, row: TData, index: number) => TAcc;
+    /**
+     * Fields merged onto the row from the accumulator AFTER this row has been
+     * folded in. Declare them on the row type so a column can name one in
+     * `accessorKey`. Return `{}` (or nothing) to leave the row untouched.
+     */
+    derive: (accumulator: TAcc, row: TData, index: number) => Record<string, unknown> | undefined;
+    /**
+     * Comparator establishing the fold order. The rows come out in this order —
+     * see the ordering contract above. Omit to fold in the incoming order.
+     */
+    order?: (a: TData, b: TData) => number;
+    /**
+     * Read the finished accumulator once, after every row. Published as
+     * `computed.foldTotal` for a footer cell.
+     */
+    total?: (accumulator: TAcc, rowCount: number) => unknown;
+}
+export interface RowAccumulatorResult<TData> {
+    /** Rows in fold order, each carrying its derived fields. */
+    rows: TData[];
+    /** `total(finalAccumulator, rowCount)`, or undefined when no `total`. */
+    total: unknown;
+}
+/**
+ * Run a {@link RowAccumulator} over rows.
+ *
+ * Returns the input array untouched (same identity) when there is no
+ * accumulator, so a table without a fold pays nothing and its row model is
+ * not invalidated.
+ */
+export declare function accumulateRows<TData extends DataTableData>(data: TData[], accumulator?: RowAccumulator<TData>): RowAccumulatorResult<TData>;
+//# sourceMappingURL=rowAccumulator.d.ts.map

package/types/utils/rowAccumulator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rowAccumulator.d.ts","sourceRoot":"","sources":["../../src/utils/rowAccumulator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE9C;;;;;;;;;GASG;AACH,MAAM,WAAW,cAAc,CAAC,KAAK,SAAS,aAAa,GAAG,aAAa,EAAE,IAAI,GAAG,GAAG;IACrF;;;OAGG;IACH,OAAO,EAAE,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,CAAC;IAC7B,4EAA4E;IAC5E,MAAM,EAAE,CAAC,WAAW,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/D;;;;OAIG;IACH,MAAM,EAAE,CAAC,WAAW,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAC9F;;;OAGG;IACH,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,KAAK,MAAM,CAAC;IACvC;;;OAGG;IACH,KAAK,CAAC,EAAE,CAAC,WAAW,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC;CAC1D;AAED,MAAM,WAAW,oBAAoB,CAAC,KAAK;IACzC,4DAA4D;IAC5D,IAAI,EAAE,KAAK,EAAE,CAAC;IACd,yEAAyE;IACzE,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,SAAS,aAAa,EACxD,IAAI,EAAE,KAAK,EAAE,EACb,WAAW,CAAC,EAAE,cAAc,CAAC,KAAK,CAAC,GAClC,oBAAoB,CAAC,KAAK,CAAC,CAuB7B"}