@multiplatform.one/table 7.7.6 → 7.10.0

package/src/hooks/useDataTable.ts

@@ -171,6 +171,7 @@ export const createUrlStrategy = {
 import React, { useMemo, useState, useCallback, useEffect, useRef } from "react";
 import type {
   DataTableData,
+  DataTableField,
   DataTableInfiniteState,
   DataTableState,
   UseDataTableOptions,
@@ -183,6 +184,8 @@ import {
   resolveFilterFields,
 } from "../utils/filterFields";
 import { applyFilterToValue } from "../utils/filterUtils";
+import { accumulateRows } from "../utils/rowAccumulator";
+import { moneyComparator } from "../utils/money";
 import { DEFAULT_PAGE_SIZE } from "../utils/paginationDefaults";
 import { deserializeTableState, serializeTableState } from "../utils/urlStateUtils";
 import { useInfiniteRows } from "./useInfiniteRows";
@@ -190,6 +193,13 @@ import { useTableFiltering } from "./useTableFiltering";
 import { useTableSorting } from "./useTableSorting";
 import { useTableViews } from "./useTableViews";
 
+/**
+ * TanStack sort for a `money` column: exact decimal-string ordering, so
+ * "9.00" sorts below "10.00" (MPO-252).
+ */
+const moneySortingFn = (rowA: any, rowB: any, columnId: string): number =>
+  moneyComparator(rowA.getValue(columnId), rowB.getValue(columnId));
+
 export function useDataTable<TData extends DataTableData = DataTableData>({
   data = [],
   columns = [],
@@ -208,6 +218,7 @@ export function useDataTable<TData extends DataTableData = DataTableData>({
   enablePagination: _enablePagination = true,
   paginationMode = "pages",
   loadPage,
+  rowAccumulator,
   enableColumnVisibility = true,
   enableColumnOrdering: _enableColumnOrdering = false,
   enableColumnResizing = false,
@@ -360,6 +371,21 @@ export function useDataTable<TData extends DataTableData = DataTableData>({
   // pre-filtered/sorted, so manual modes are forced on. In infinite mode the
   // pagination row model is never applied (rows accumulate instead of slice).
   const effectiveData = isLoaderMode ? infiniteRows.rows : data;
+
+  // ---- Row accumulator (MPO-250) ----
+  //
+  // The fold runs HERE — over the whole row set, before the advanced filters
+  // below and before TanStack's filter/sort/paginate models — because a
+  // derived column like a running balance depends on every row before it and
+  // would restart on page two otherwise. `order` (when given) is also the
+  // order the rows reach the table in: a fold order is the order its column
+  // reads down. Sorting on another column reorders for display and does NOT
+  // refold; see the contract on RowAccumulator.
+  const { rows: accumulatedData, total: foldTotal } = useMemo(
+    () => accumulateRows(effectiveData, rowAccumulator),
+    [effectiveData, rowAccumulator],
+  );
+
   const effectiveManualFiltering = manualFiltering || isLoaderMode;
   const effectiveManualSorting = manualSorting || isLoaderMode;
   const effectiveManualPagination = manualPagination || infiniteEnabled;
@@ -375,9 +401,9 @@ export function useDataTable<TData extends DataTableData = DataTableData>({
   // including hidden / non-column fields. Server-side tables (manualFiltering)
   // map the same filters to query params instead.
   const preFilteredData = useMemo(() => {
-    if (effectiveManualFiltering) return effectiveData;
-    return applyFiltersToData(effectiveData, filtering.advancedFilters, filterFields);
-  }, [effectiveData, effectiveManualFiltering, filtering.advancedFilters, filterFields]);
+    if (effectiveManualFiltering) return accumulatedData;
+    return applyFiltersToData(accumulatedData, filtering.advancedFilters, filterFields);
+  }, [accumulatedData, effectiveManualFiltering, filtering.advancedFilters, filterFields]);
 
   // Column-funnel filters store FilterValue objects ({operator, value}) —
   // interpret them with the shared operator semantics instead of TanStack's
@@ -455,13 +481,20 @@ export function useDataTable<TData extends DataTableData = DataTableData>({
   const normalizedColumns = useMemo(
     () =>
       columns.map((column) => {
-        const { sortable, filterable } = column as {
+        const { sortable, filterable, field } = column as {
           sortable?: boolean;
           filterable?: boolean;
+          field?: DataTableField;
         };
-        if (sortable === undefined && filterable === undefined) return column;
+        // A money column holds a decimal STRING, and TanStack's auto sort
+        // would compare it as text — "9.00" above "10.00", silently wrong on
+        // every amount column (MPO-252). Give it the exact comparator so
+        // `sortable: true` is safe to turn on. An explicit sortingFn wins.
+        const needsMoneySort = field === "money" && column.sortingFn === undefined;
+        if (sortable === undefined && filterable === undefined && !needsMoneySort) return column;
         return {
           ...column,
+          ...(needsMoneySort ? { sortingFn: moneySortingFn } : {}),
           ...(sortable !== undefined && column.enableSorting === undefined
             ? { enableSorting: sortable }
             : {}),
@@ -596,9 +629,9 @@ export function useDataTable<TData extends DataTableData = DataTableData>({
   // ---- Computed Values ----
 
   const filteredData = useMemo(() => {
-    if (effectiveManualFiltering) return effectiveData;
+    if (effectiveManualFiltering) return accumulatedData;
     return table.getFilteredRowModel().rows.map((row) => row.original);
-  }, [effectiveData, table, effectiveManualFiltering]);
+  }, [accumulatedData, table, effectiveManualFiltering]);
 
   const paginatedData = useMemo(() => {
     if (effectiveManualPagination) return filteredData;
@@ -708,6 +741,9 @@ export function useDataTable<TData extends DataTableData = DataTableData>({
     activeFilterCount: filtering.activeFilterCount,
     filterFields,
     infinite,
+    // The fold read once at the end — a footer cell renders it through
+    // useDataTableState() (MPO-250).
+    foldTotal,
   };
 
   // ---- State Change Callback ----

package/src/index.ts

@@ -157,6 +157,19 @@ export {
   resolveFilterFields,
 } from "./utils/filterFields";
 export * from "./utils/urlStateUtils";
+export {
+  addMoney,
+  compareMoney,
+  formatMoney,
+  isMoneyString,
+  isNegativeMoney,
+  moneyComparator,
+  subtractMoney,
+  sumMoney,
+  sumMoneyByCurrency,
+} from "./utils/money";
+export { accumulateRows } from "./utils/rowAccumulator";
+export type { RowAccumulator, RowAccumulatorResult } from "./utils/rowAccumulator";
 export {
   getDefaultColumnAlign,
   alignToFlex,

package/src/shared/devWarn.ts

@@ -0,0 +1,97 @@
+/**
+ * Table DEV guardrails — same shape as the `@multiplatform.one/theme` §5
+ * catalog (`devWarn` / `warnBareDisabled` / `warnSizeRecipeEscape`): a
+ * module-level seen set, a `NODE_ENV === "production"` no-op, and helpers
+ * called inline during render.
+ *
+ * The prefix is `[table]`, not `[theme]`: the codes here are table-local and
+ * the story-hygiene harvester (`p-results/story-hygiene/verify.mjs`) collects
+ * on the `[theme]` prefix.
+ */
+
+import type { DataTableProps } from "../types";
+
+export type TableDevWarnCode =
+  /**
+   * A column declares a width (`width` or TanStack `size`) that the resolved
+   * `columnLayout` discards before it reaches the cell box.
+   */
+  "column-width-ignored";
+
+export type TableDevWarnDetail = {
+  component?: string;
+  id?: string;
+  columns?: string;
+  columnLayout?: string;
+  suggest?: string;
+};
+
+const seen = new Set<string>();
+
+function isDev(): boolean {
+  return process.env.NODE_ENV !== "production";
+}
+
+/** Emit a once-per-key console warning in non-production builds. */
+export function tableDevWarn(code: TableDevWarnCode, detail: TableDevWarnDetail = {}): void {
+  if (!isDev()) return;
+  const key = [code, detail.component ?? "", detail.id ?? "", detail.columns ?? ""].join(":");
+  if (seen.has(key)) return;
+  seen.add(key);
+  const bits = [
+    detail.component ? `component=${detail.component}` : undefined,
+    detail.id ? `id=${detail.id}` : undefined,
+    detail.columns ? `columns=${detail.columns}` : undefined,
+    detail.columnLayout ? `columnLayout=${detail.columnLayout}` : undefined,
+    detail.suggest ? `suggest=${detail.suggest}` : undefined,
+  ].filter(Boolean);
+  const suffix = bits.length ? ` (${bits.join(", ")})` : "";
+  console.warn(`[table] ${code}${suffix}`);
+}
+
+/** @internal test helper */
+export function __resetTableDevWarnSeen(): void {
+  seen.clear();
+}
+
+type WidthBearingColumn = {
+  id?: unknown;
+  accessorKey?: unknown;
+  width?: unknown;
+  size?: unknown;
+};
+
+function columnKey(column: WidthBearingColumn, index: number): string {
+  if (typeof column.id === "string" && column.id) return column.id;
+  if (typeof column.accessorKey === "string" && column.accessorKey) return column.accessorKey;
+  return `#${index}`;
+}
+
+/**
+ * MPO-236 — `columnLayout: "equal"` (the default) flexes every column to the
+ * same width, so a per-column `width` / `size` never reaches the cell box and
+ * the render is byte-identical to one with no widths at all.
+ *
+ * `enableColumnResizing` is the exemption: it swaps the cell flex to
+ * `flexBasis: "auto"`, under which a declared width does survive.
+ */
+export function warnColumnWidthIgnored(args: {
+  columnLayout?: DataTableProps["columnLayout"];
+  enableColumnResizing?: boolean;
+  columns: readonly WidthBearingColumn[];
+  component?: string;
+}): void {
+  if (!isDev()) return;
+  if (args.columnLayout !== "equal" || args.enableColumnResizing) return;
+  const offenders = args.columns
+    .map((column, index) => ({ column, index }))
+    .filter(({ column }) => typeof column.width === "number" || typeof column.size === "number")
+    .map(({ column, index }) => columnKey(column, index));
+  if (!offenders.length) return;
+  tableDevWarn("column-width-ignored", {
+    component: args.component ?? "DataTable",
+    columns: offenders.join(","),
+    columnLayout: "equal",
+    suggest: 'columnLayout="auto" or "scroll", or enableColumnResizing',
+  });
+}

package/src/types.ts

@@ -1,4 +1,5 @@
 import type { ColumnDef, ColumnFiltersState, Row } from "@tanstack/react-table";
+import type { RowAccumulator } from "./utils/rowAccumulator";
 import type { UrlStateStrategy } from "./hooks/useDataTable";
 import type { AnyFormApi } from "@multiplatform.one/forms";
 import type React from "react";
@@ -50,6 +51,12 @@ export type DataTableField =
   // Numeric inputs
   | "stepper"
   | "slider"
+  /**
+   * A Currency field: a decimal STRING, formatted for display and ordered
+   * numerically. Read-only presentation — money is edited through the form
+   * surfaces, not typed into a grid cell (MPO-252).
+   */
+  | "money"
   // Selection inputs
   | "select"
   | "combobox"
@@ -113,8 +120,17 @@ export interface DataTableFieldProps {
   step?: number;
   /** Precision for numeric fields */
   precision?: number;
-  /** Currency code for currency fields */
+  /** Currency code for currency fields. A column-level constant. */
   currency?: string;
+  /**
+   * Row-data key holding this row's currency code, for a `money` column
+   * (MPO-252). A ledger genuinely mixes currencies row by row, so the row's
+   * own code WINS over the column-level `currency` constant; `currency` is
+   * the fallback for the rows that carry none.
+   */
+  currencyField?: string;
+  /** BCP-47 locale for money formatting. Defaults to the runtime's. */
+  locale?: string;
   /** Doctype for link fields (Frappe) */
   doctype?: string;
   /** Default country for phone input (ISO 3166-1 alpha-2) */
@@ -164,6 +180,12 @@ export type DataTableColumn<TData extends DataTableData = DataTableData> = Colum
   sortable?: boolean;
   searchable?: boolean;
   hidden?: boolean;
+  /**
+   * Column width intent, in px. Read by the view-options width slider and by
+   * saved views; the RENDERED cell box comes from TanStack `size`. Under the
+   * default `columnLayout: "equal"` neither one survives, and declaring
+   * either warns (see `columnLayout`).
+   */
   width?: number;
   minWidth?: number;
   maxWidth?: number;
@@ -423,9 +445,27 @@ export interface DataTableState {
 
 // Component Props Types
 
+export type { RowAccumulator, RowAccumulatorResult } from "./utils/rowAccumulator";
+
 export interface DataTableProps<TData extends DataTableData = DataTableData> {
   data: TData[];
   columns: DataTableColumn<TData>[];
+  /**
+   * A fold over the ordered row set, run ONCE before filtering, sorting and
+   * pagination — the seam a running balance needs, because the value on row N
+   * depends on rows 1..N-1 and a column `cell` renderer only ever sees one
+   * row (MPO-250).
+   *
+   * The derived fields are merged onto each row, so a column names one in
+   * `accessorKey` like any other. Declare them on the row type. `total` is
+   * published as `computed.foldTotal` for a footer cell.
+   *
+   * Must be a STABLE reference (module constant or `useMemo`) — the fold
+   * re-runs when its identity changes. The full ordering contract, including
+   * what happens when the user sorts on another column, is documented on
+   * `RowAccumulator` in utils/rowAccumulator.ts.
+   */
+  rowAccumulator?: RowAccumulator<TData>;
 
   // State Management
   initialState?: Partial<DataTableState>;
@@ -528,6 +568,14 @@ export interface DataTableProps<TData extends DataTableData = DataTableData> {
    * - 'equal': All columns equal width, no horizontal scroll (default)
    * - 'auto': Content-based width, last column fills remainder, squishes if needed
    * - 'scroll': Content-based width, horizontal scroll when content exceeds container
+   *
+   * Under 'equal' a PER-COLUMN WIDTH IS IGNORED. Every cell gets
+   * `flexGrow: 1, flexBasis: 0`, so a column's `width` / `size` never reaches
+   * the cell box and the render is identical to one that declared no widths.
+   * Use 'auto' or 'scroll' when the widths must hold, or turn on
+   * `enableColumnResizing`, which switches the cells to `flexBasis: "auto"`.
+   * Declaring a width under 'equal' emits the `[table] column-width-ignored`
+   * dev warning rather than failing silently (MPO-236).
    */
   columnLayout?: "equal" | "auto" | "scroll";
 
@@ -762,12 +810,33 @@ export interface UseDataTableReturn<TData extends DataTableData = DataTableData>
     filterFields: ResolvedFilterField[];
     /** Present when paginationMode="infinite" */
     infinite?: DataTableInfiniteState;
+    /**
+     * `rowAccumulator.total(finalAccumulator, rowCount)` — the fold read once
+     * at the end, for a footer/total row. Undefined when the table has no
+     * accumulator or the accumulator declares no `total` (MPO-250).
+     */
+    foldTotal?: unknown;
   };
 }
 
 // Utility Types
 
-export type DataTableColumnType = "text" | "number" | "date" | "boolean" | "select";
+/**
+ * Filter-editor / comparison type for a column.
+ *
+ * `"money"` (MPO-252) is a decimal STRING, not a number: a Frappe Currency
+ * field arrives as "-455.87" because a float would round it. It sorts and
+ * filters through the exact BigInt helpers in utils/money.ts, so `"9.00"`
+ * orders BELOW `"10.00"` — which the `"text"` fallback got backwards, in
+ * silence, on every amount column in the kit.
+ *
+ * The mixed-currency rule rides this type: TWO CURRENCIES ARE TWO FIGURES AND
+ * NEITHER CONVERTS. A money column formats from the row's own currency
+ * (`fieldProps.currencyField`), comparison is by magnitude only, and a total
+ * over mixed rows is `sumMoneyByCurrency` — one figure per code, never one
+ * number. There is no rate in the table and the kit will not invent one.
+ */
+export type DataTableColumnType = "text" | "number" | "money" | "date" | "boolean" | "select";
 
 export interface DataTableColumnConfig {
   type: DataTableColumnType;

package/src/utils/columnAlign.ts

@@ -17,7 +17,15 @@ export type ColumnAlignInput = {
   meta?: { align?: ColumnAlign; role?: string };
 };
 
-const NUMERIC_FIELDS = new Set<DataTableField>(["stepper", "slider", "progress", "duration"]);
+const NUMERIC_FIELDS = new Set<DataTableField>([
+  "stepper",
+  "slider",
+  "progress",
+  "duration",
+  // A money column right-aligns on its own, without needing a column-level
+  // `currency` constant — a ledger reads its code off each row (MPO-252).
+  "money",
+]);
 
 /** Booleans + icon-like metrics (EUI: center symbols). */
 const CENTER_FIELDS = new Set<DataTableField>(["checkbox", "switch", "rating"]);

package/src/utils/filterFields.ts

@@ -41,6 +41,8 @@ export function mapFieldToFilterType(field?: DataTableField): DataTableColumnTyp
     case "rating":
     case "duration":
       return "number";
+    case "money":
+      return "money";
     case "datepicker":
     case "datetimepicker":
     case "timepicker":
@@ -117,7 +119,9 @@ export function getFilterFieldType(
 // ── Client-side application ───────────────────────────────────
 
 /** "select" fields compare as text; the others map 1:1. */
-function comparisonType(type: DataTableColumnType): "text" | "number" | "date" | "boolean" {
+function comparisonType(
+  type: DataTableColumnType,
+): "text" | "number" | "money" | "date" | "boolean" {
   return type === "select" ? "text" : type;
 }
 
@@ -167,6 +171,22 @@ const NUMBER_OPERATORS: FilterOperator[] = [
   "isGreaterThanOrEqual",
 ];
 
+/**
+ * Money takes the numeric operators PLUS the range pair — "every posting over
+ * 500" and "between 100 and 500" are the two questions asked of an amount
+ * column, and typing it "text" offered `contains` instead (MPO-252).
+ */
+const MONEY_OPERATORS: FilterOperator[] = [
+  "is",
+  "isNot",
+  "isLessThan",
+  "isGreaterThan",
+  "isLessThanOrEqual",
+  "isGreaterThanOrEqual",
+  "isBetween",
+  "isNotBetween",
+];
+
 const DATE_OPERATORS: FilterOperator[] = [
   "is",
   "isNot",
@@ -185,6 +205,8 @@ export function operatorsForFilterType(type: DataTableColumnType): FilterOperato
   switch (type) {
     case "number":
       return NUMBER_OPERATORS;
+    case "money":
+      return MONEY_OPERATORS;
     case "date":
       return DATE_OPERATORS;
     case "boolean":

package/src/utils/filterUtils.ts

@@ -1,4 +1,5 @@
 import { parseCalendarDate, type DateInput } from "@multiplatform.one/theme";
+import { isMoneyString, moneyComparator } from "./money";
 import { t } from "../shared/t";
 import type { FilterValue, TableFilter } from "../types";
 
@@ -51,10 +52,28 @@ export function deserializeFilters(filterString: string): TableFilter[] {
 
 // Filter Application Logic
 
+/**
+ * Order a money cell against a money comparand (MPO-252).
+ *
+ * Money is a decimal STRING, so `Number()` would round it and `<` would
+ * compare it lexically — "9.00" above "10.00". Both sides go through the
+ * exact BigInt comparator. A comparand that is not a decimal string matches
+ * nothing, the way a NaN numeric comparison already did.
+ */
+function compareMoneyValues(
+  value: unknown,
+  filterValue: unknown,
+  ordered: (delta: number) => boolean,
+): boolean {
+  const right = typeof filterValue === "number" ? String(filterValue) : filterValue;
+  if (!isMoneyString(value) || !isMoneyString(right)) return false;
+  return ordered(moneyComparator(value, right));
+}
+
 export function applyFilterToValue(
   value: any,
   filterValue: FilterValue,
-  columnType: "text" | "number" | "date" | "boolean" = "text",
+  columnType: "text" | "number" | "money" | "date" | "boolean" = "text",
 ): boolean {
   const { operator, value: filterVal, values } = filterValue;
 
@@ -83,6 +102,9 @@ export function applyFilterToValue(
 
     // Equality operators - handle different types
     case "is":
+      if (columnType === "money") {
+        return compareMoneyValues(value, filterVal, (delta) => delta === 0);
+      }
       if (columnType === "number") {
         return Number(value) === Number(filterVal);
       }
@@ -91,6 +113,9 @@ export function applyFilterToValue(
       }
       return stringValue === filterStringValue;
     case "isNot":
+      if (columnType === "money") {
+        return !compareMoneyValues(value, filterVal, (delta) => delta === 0);
+      }
       if (columnType === "number") {
         return Number(value) !== Number(filterVal);
       }
@@ -98,23 +123,41 @@ export function applyFilterToValue(
 
     // Number/Date Filters
     case "isLessThan":
+      if (columnType === "money") {
+        return compareMoneyValues(value, filterVal, (delta) => delta < 0);
+      }
       return columnType === "number"
         ? Number(value) < Number(filterVal)
         : stringValue < filterStringValue;
     case "isGreaterThan":
+      if (columnType === "money") {
+        return compareMoneyValues(value, filterVal, (delta) => delta > 0);
+      }
       return columnType === "number"
         ? Number(value) > Number(filterVal)
         : stringValue > filterStringValue;
     case "isLessThanOrEqual":
+      if (columnType === "money") {
+        return compareMoneyValues(value, filterVal, (delta) => delta <= 0);
+      }
       return columnType === "number"
         ? Number(value) <= Number(filterVal)
         : stringValue <= filterStringValue;
     case "isGreaterThanOrEqual":
+      if (columnType === "money") {
+        return compareMoneyValues(value, filterVal, (delta) => delta >= 0);
+      }
       return columnType === "number"
         ? Number(value) >= Number(filterVal)
         : stringValue >= filterStringValue;
     case "isBetween":
       if (values && values.length >= 2) {
+        if (columnType === "money") {
+          return (
+            compareMoneyValues(value, values[0], (delta) => delta >= 0) &&
+            compareMoneyValues(value, values[1], (delta) => delta <= 0)
+          );
+        }
         const numValue = Number(value);
         const min = Number(values[0]);
         const max = Number(values[1]);
@@ -123,6 +166,12 @@ export function applyFilterToValue(
       return false;
     case "isNotBetween":
       if (values && values.length >= 2) {
+        if (columnType === "money") {
+          return (
+            compareMoneyValues(value, values[0], (delta) => delta < 0) ||
+            compareMoneyValues(value, values[1], (delta) => delta > 0)
+          );
+        }
         const numValue = Number(value);
         const min = Number(values[0]);
         const max = Number(values[1]);