@freighttech/ui 0.13.18

package/src/backend/dynamic-table/utils/lookupColumns.tsx

@@ -0,0 +1,47 @@
+import * as React from 'react'
+import type { ColumnDef } from '../types/index'
+import type { LookupColumnRef } from '../types/perspective'
+
+/**
+ * Row field / column data key for a linked (lookup) column. The server enriches
+ * each row with this key (see `@freighttech/table-lookups` resolver), and the
+ * grid renders a read-only column for it. Keeping the `lookup__` prefix matches
+ * the shipped convention; the `<source>__<field>` tail makes the key derivable on
+ * both client and server with no stored column key.
+ */
+export function lookupColumnDataKey(ref: { source: string; field: string }): string {
+  return `lookup__${ref.source}__${ref.field}`
+}
+
+/** True when a column data key belongs to a linked (lookup) column. */
+export function isLookupColumnKey(key: string): boolean {
+  return key.startsWith('lookup__')
+}
+
+/**
+ * Build read-only DynamicTable column defs for a perspective's linked columns.
+ * The cell value lives at `row[lookup__<source>__<field>]`, attached server-side.
+ * Linked columns are never editable (editing would write back to the source,
+ * breaking the unidirectional rule), so every column is `readOnly`.
+ */
+export function buildLookupColumnDefs(refs: LookupColumnRef[]): ColumnDef[] {
+  return refs.map((r) => ({
+    data: lookupColumnDataKey(r),
+    title: r.label,
+    readOnly: true,
+    renderer: (value: unknown) => {
+      const isEmpty = value == null || value === ''
+      return (
+        <span className={isEmpty ? 'text-m3-on-surface-variant' : undefined}>
+          {isEmpty ? '—' : String(value)}
+        </span>
+      )
+    },
+  }))
+}
+
+/** Serialize a perspective's linked columns into the `lookups` query param value
+ *  (`source:field,source:field`). Empty when there are no linked columns. */
+export function lookupColumnsToParam(refs: LookupColumnRef[]): string {
+  return refs.map((r) => `${r.source}:${r.field}`).join(',')
+}

package/src/backend/dynamic-table/utils/perspectiveTransforms.ts

@@ -0,0 +1,368 @@
+import type { PerspectiveConfig, FilterRow, SortRule, LookupColumnRef } from '../types/index'
+import type {
+  PerspectiveOrigin,
+  PerspectivePublication,
+  PerspectiveTemplate,
+} from '../types/perspective'
+import { BASE_VIEW_PERSPECTIVE_NAME, isTableViewMode } from '../types/perspective'
+import type { TableViewMode } from '../types/perspective'
+import type { GroupRule, AggregationRule, AggregationFn } from '../types/grouping'
+import { isAggregationFn } from '../types/grouping'
+import { parseConditionalFormats } from './conditionalFormat'
+import { parseFormulaColumns } from './formulaColumns'
+import { parseRollupColumns } from './rollupColumns'
+import type {
+  PerspectiveDto,
+  PerspectiveSettings,
+  RolePerspectiveDto,
+} from '@open-mercato/shared/modules/perspectives/types'
+
+/**
+ * @deprecated Collapsed: `PerspectiveConfig` now carries `conditionalFormats`
+ * itself, so this is a plain alias. Use `PerspectiveConfig`.
+ */
+export type DynamicTablePerspectiveConfig = PerspectiveConfig
+
+/**
+ * Defensively parse the `_lookups` smuggled inside `settings.filters`. Drops
+ * anything that isn't a well-formed `{ source, field, label }` so a malformed or
+ * legacy value can never crash the table.
+ */
+function parseLookupColumns(raw: unknown): LookupColumnRef[] {
+  if (!Array.isArray(raw)) return []
+  const out: LookupColumnRef[] = []
+  for (const entry of raw) {
+    if (!entry || typeof entry !== 'object') continue
+    const { source, field, label } = entry as Record<string, unknown>
+    if (typeof source !== 'string' || !source) continue
+    if (typeof field !== 'string' || !field) continue
+    out.push({ source, field, label: typeof label === 'string' && label ? label : field })
+  }
+  return out
+}
+
+/**
+ * Defensively parse the `_aggregations` smuggled inside `settings.filters`.
+ * Drops anything that isn't a well-formed rule so a malformed/legacy value
+ * can never crash the table.
+ *
+ * The function whitelist is `isAggregationFn` — i.e. `AGGREGATION_FNS` in
+ * `types/grouping.ts`, the single source of truth. It used to be a local
+ * `['sum']` literal, which meant a view saved with any other function silently
+ * lost its rules on reload. That is also the forward-compatibility contract:
+ * a view saved by a NEWER client carrying an unknown `fn` degrades to dropping
+ * that one rule instead of throwing.
+ */
+function parseAggregations(raw: unknown): AggregationRule[] {
+  if (!Array.isArray(raw)) return []
+  const out: AggregationRule[] = []
+  for (const entry of raw) {
+    if (!entry || typeof entry !== 'object') continue
+    const { id, field, fn, dimension } = entry as Record<string, unknown>
+    if (typeof field !== 'string' || !field) continue
+    if (!isAggregationFn(fn)) continue
+    const rule: AggregationRule = {
+      id: typeof id === 'string' && id ? id : `agg-${field}`,
+      field,
+      fn: fn as AggregationFn,
+    }
+    // Carry the partition column through the round-trip. Dropping it would
+    // turn a saved per-currency breakdown back into a single cross-currency
+    // number on the next page load — silently, and looking correct.
+    if (typeof dimension === 'string' && dimension) rule.dimension = dimension
+    out.push(rule)
+  }
+  return out
+}
+
+/**
+ * Defensively parse the `_viewMode` smuggled inside `settings.filters`.
+ *
+ * Same forward-compatibility contract as `parseAggregations`: a value written
+ * by a NEWER client that we do not recognise degrades to `'table'` rather than
+ * throwing. A saved view is data a user relies on; it must never be able to
+ * break the page that reads it.
+ *
+ * `undefined` in ⇒ `undefined` out, so "never chosen" survives a round-trip and
+ * a host's own default (if it has one) still applies.
+ */
+export function parseViewMode(raw: unknown): TableViewMode | undefined {
+  if (raw === undefined || raw === null) return undefined;
+  return isTableViewMode(raw) ? raw : 'table';
+}
+
+/**
+ * Defensively parse `_origin` — the record of which shared template a view was
+ * copied from, and at which version. A malformed or partial value is dropped
+ * rather than half-trusted: a wrong `version` would later claim "the template
+ * changed" (or hide that it did), which is worse than not knowing.
+ */
+export function parsePerspectiveOrigin(raw: unknown): PerspectiveOrigin | undefined {
+  if (!raw || typeof raw !== 'object') return undefined
+  const { templateId, version, name, copiedAt } = raw as Record<string, unknown>
+  if (typeof templateId !== 'string' || !templateId) return undefined
+  if (typeof version !== 'string' || !version) return undefined
+  return {
+    templateId,
+    version,
+    name: typeof name === 'string' ? name : '',
+    copiedAt: typeof copiedAt === 'string' ? copiedAt : '',
+  }
+}
+
+/** Defensively parse `_published` — which roles this view is shared with. */
+export function parsePerspectivePublication(raw: unknown): PerspectivePublication | undefined {
+  if (!raw || typeof raw !== 'object') return undefined
+  const { roleIds, publishedAt } = raw as Record<string, unknown>
+  if (!Array.isArray(roleIds)) return undefined
+  const ids = roleIds.filter((id): id is string => typeof id === 'string' && id.length > 0)
+  if (!ids.length) return undefined
+  return { roleIds: ids, publishedAt: typeof publishedAt === 'string' ? publishedAt : '' }
+}
+
+/**
+ * The version stamp a copy records. `updatedAt` when the template has been
+ * re-published, else `createdAt` — never empty, so "has it changed since I
+ * copied it?" is always answerable.
+ */
+export function templateVersionOf(dto: { updatedAt?: string | null; createdAt: string }): string {
+  return dto.updatedAt || dto.createdAt
+}
+
+/**
+ * Convert a ROLE-scoped perspective DTO into a shared template.
+ *
+ * Same settings shape as a personal view — a template IS a view someone
+ * published — plus the role it is published to and the version stamp a copy
+ * records. Deliberately reuses `apiToDynamicTable` so a template can never
+ * decode differently from the view it was made from.
+ */
+export function apiTemplateToDynamicTable(
+  dto: RolePerspectiveDto,
+  allColumns: string[],
+  defaultHiddenColumns: string[] = [],
+): PerspectiveTemplate {
+  const base = apiToDynamicTable(dto, allColumns, defaultHiddenColumns)
+  return {
+    ...base,
+    // A template is a thing to copy, never a thing that is your default or your
+    // base view — drop both flags rather than carrying them into someone's space.
+    isDefault: false,
+    isBaseView: false,
+    publication: undefined,
+    roleId: dto.roleId,
+    roleName: dto.roleName ?? null,
+    version: templateVersionOf(dto),
+  }
+}
+
+/**
+ * Convert a perspective DTO from the API into a DynamicTable PerspectiveConfig.
+ * Handles the mapping between API format (columnOrder, columnVisibility, etc.)
+ * and DynamicTable format (visible/hidden arrays, FilterRow[], SortRule[]).
+ */
+export function apiToDynamicTable(
+  dto: PerspectiveDto,
+  allColumns: string[],
+  defaultHiddenColumns: string[] = [],
+): DynamicTablePerspectiveConfig {
+  const { columnOrder = [], columnVisibility = {} } = dto.settings
+
+  // A perspective saved before column config was persisted (or migrated from a
+  // legacy shape) has an empty `columnOrder`. Falling back to `allColumns` there
+  // would reveal every column the table declares hidden by default — the
+  // "phantom fields in my saved view" report. Honour the table's defaults
+  // instead; an explicit `columnOrder` still wins outright.
+  const visible =
+    columnOrder.length > 0
+      ? columnOrder.filter((col) => columnVisibility[col] !== false)
+      : allColumns.filter((col) => !defaultHiddenColumns.includes(col))
+  const hidden = allColumns.filter((col) => !visible.includes(col))
+
+  /**
+   * Columns this saved view has NEVER EXPRESSED AN OPINION ABOUT.
+   *
+   * `hidden` above cannot answer that question — it is DERIVED, "everything the
+   * table declares that is not visible", so a column added to the table config
+   * after this row was written is indistinguishable from one the user hid on
+   * purpose. The only place the difference survives is the raw stored maps: a
+   * key absent from BOTH `columnOrder` and `columnVisibility` was never decided,
+   * because saving writes an entry for every column either way
+   * (`dynamicTableToApi` below).
+   *
+   * Computed here rather than in `resolvePerspectiveState` for exactly that
+   * reason: by the time the config reaches the resolver the raw maps are gone.
+   * An empty `columnOrder` (a legacy row) means the view has no column opinions
+   * at all, and its defaults are already being honoured above — so nothing is
+   * "unseen" there either.
+   */
+  const unseenColumns =
+    columnOrder.length > 0
+      ? allColumns.filter(
+          (col) => !columnOrder.includes(col) && !(col in columnVisibility),
+        )
+      : []
+
+  const apiFilters = dto.settings.filters as Record<string, unknown> | undefined
+  const filters: FilterRow[] = Array.isArray(apiFilters)
+    ? (apiFilters as FilterRow[])
+    : ((apiFilters?.rows as FilterRow[]) ?? [])
+  const color = apiFilters?._color as PerspectiveConfig['color']
+
+  const sorting: SortRule[] = (dto.settings.sorting ?? []).map((s) => ({
+    id: s.id,
+    field: s.id,
+    direction: (s.desc ? 'desc' : 'asc') as 'asc' | 'desc',
+  }))
+
+  const grouping: GroupRule[] = (dto.settings.grouping ?? []).map((g) => ({
+    id: g.id,
+    field: g.field,
+    direction: (g.desc ? 'desc' : 'asc') as 'asc' | 'desc',
+  }))
+
+  // Aggregations ride inside `filters._aggregations` — the upstream settings
+  // schema strips unknown top-level keys, but `filters` is a passthrough record
+  // (same channel as `_color`).
+  const aggregations = parseAggregations(apiFilters?._aggregations)
+
+  // Linked (lookup) columns ride the same `filters` passthrough channel as
+  // `_aggregations`/`_color`.
+  const lookupColumns = parseLookupColumns(apiFilters?._lookups)
+
+  // Rollup ("summarised") columns — the one-to-many direction — ride the same
+  // channel. A top-level `rollups` key would be stripped by the settings schema
+  // and the columns would vanish on the first reload.
+  const rollupColumns = parseRollupColumns(apiFilters?._rollups)
+
+  // View-scoped date/time format rides the same passthrough channel. Opaque to
+  // the table; only a well-formed string survives (anything else → undefined,
+  // so renderers keep their default).
+  const rawDateFormat = apiFilters?._dateFormat
+  const dateFormat = typeof rawDateFormat === 'string' && rawDateFormat ? rawDateFormat : undefined
+
+  // View-scoped conditional formatting ("Highlighting") rides the same
+  // passthrough channel. Same trap as `_aggregations`: a top-level key would be
+  // stripped by the settings schema and the rules would vanish on reload.
+  const conditionalFormats = parseConditionalFormats(apiFilters?._conditionalFormats)
+
+  // Frozen (pinned sticky-left) columns ride the same passthrough channel, and
+  // for the same reason — measured, not assumed: saving a TOP-LEVEL
+  // `frozenColumns` against the running API returns 200 OK and the key never
+  // reaches the database, because the upstream settings schema is a bare
+  // `z.object` whose vocabulary is columnOrder/columnVisibility/filters/
+  // sorting/grouping/pageSize/searchValue, and Zod strips the rest (HEDGE-102).
+  //
+  // Defensive by construction, like the parsers around it: a legacy or
+  // hand-edited view that stored a non-array, or an array with non-string
+  // entries, loses the malformed parts rather than pinning `undefined` and
+  // wedging the sticky-offset maths.
+  const frozenColumns = Array.isArray(apiFilters?._frozenColumns)
+    ? (apiFilters._frozenColumns as unknown[]).filter(
+        (k): k is string => typeof k === 'string' && k.length > 0,
+      )
+    : undefined
+
+  // Calculated ("formula") columns ride the same passthrough channel. The
+  // parser is defensive by construction — a legacy or hand-edited view drops
+  // the malformed entries rather than crashing the table. Do not hand-roll a
+  // second one.
+  const formulas = parseFormulaColumns(apiFilters?._formulas)
+
+  // Personalization metadata rides the same passthrough channel, for the same
+  // reason: the upstream settings schema strips unknown TOP-LEVEL keys, so a
+  // `origin`/`published` field alongside `columnOrder` would be silently
+  // dropped on the way to the database and the view would forget where it came
+  // from on the very first reload.
+  // How this view draws its rows. Same passthrough channel, same trap: a
+  // top-level `viewMode` would be stripped by the settings schema and the view
+  // would open as a table every time.
+  const viewMode = parseViewMode(apiFilters?._viewMode)
+
+  const origin = parsePerspectiveOrigin(apiFilters?._origin)
+  const publication = parsePerspectivePublication(apiFilters?._published)
+  // Two independent signals for the base row, and BOTH must hold. The flag is
+  // authoritative; the reserved name is the belt-and-braces guard so a
+  // hand-edited settings blob cannot make an ordinary named view disappear from
+  // the tab strip.
+  const isBaseView = apiFilters?._baseView === true && dto.name === BASE_VIEW_PERSPECTIVE_NAME
+
+  return {
+    id: dto.id,
+    name: dto.name,
+    color,
+    columns: { visible, hidden },
+    unseenColumns,
+    filters,
+    sorting,
+    grouping,
+    aggregations,
+    lookupColumns,
+    rollupColumns,
+    formulas,
+    dateFormat,
+    conditionalFormats,
+    frozenColumns,
+    viewMode,
+    isDefault: dto.isDefault,
+    isBaseView,
+    origin,
+    publication,
+  }
+}
+
+/**
+ * Convert a DynamicTable PerspectiveConfig into the API format (PerspectiveSettings).
+ * Used when saving perspectives via the API.
+ */
+export function dynamicTableToApi(config: DynamicTablePerspectiveConfig): PerspectiveSettings {
+  const columnVisibility: Record<string, boolean> = {}
+  config.columns.visible.forEach((col) => (columnVisibility[col] = true))
+  config.columns.hidden.forEach((col) => (columnVisibility[col] = false))
+
+  return {
+    columnOrder: config.columns.visible,
+    columnVisibility,
+    // `v: 2` marks the current filter shape. The upstream perspectives service
+    // (`maybeMigrateLegacyFilterValues`) DROPS any `filters` object that lacks
+    // either `v === 2` or a `root` key, treating it as a legacy value it can't
+    // migrate — so without this marker the saved filters silently vanish on load.
+    // `_aggregations` rides here too (passthrough record), since the settings
+    // schema would strip it as an unknown top-level key.
+    filters: {
+      v: 2,
+      rows: config.filters,
+      _color: config.color,
+      _aggregations: config.aggregations ?? [],
+      _lookups: config.lookupColumns ?? [],
+      _rollups: config.rollupColumns ?? [],
+      _dateFormat: config.dateFormat,
+      _conditionalFormats: config.conditionalFormats ?? [],
+      _formulas: config.formulas ?? [],
+      // Written only when the view actually pins something, so a view that has
+      // never used the feature does not grow an empty key — same rule as
+      // `_viewMode` below.
+      ...(config.frozenColumns && config.frozenColumns.length > 0
+        ? { _frozenColumns: config.frozenColumns }
+        : {}),
+      // Written only when the view has a mode, so a table-only view does not
+      // grow a key. `parseViewMode` treats absent and 'table' identically.
+      ...(config.viewMode ? { _viewMode: config.viewMode } : {}),
+      // Personalization metadata — see `apiToDynamicTable` for why it cannot
+      // live at the top level. Written only when set, so a plain personal view
+      // does not grow three null keys.
+      ...(config.origin ? { _origin: config.origin } : {}),
+      ...(config.publication ? { _published: config.publication } : {}),
+      ...(config.isBaseView ? { _baseView: true } : {}),
+    },
+    sorting: config.sorting.map((s) => ({
+      id: s.field,
+      desc: s.direction === 'desc',
+    })),
+    grouping: (config.grouping ?? []).map((g) => ({
+      id: g.id,
+      field: g.field,
+      desc: g.direction === 'desc',
+    })),
+  }
+}

package/src/backend/dynamic-table/utils/rollupColumns.ts

@@ -0,0 +1,162 @@
+// utils/rollupColumns.ts
+//
+// Client half of rollup ("summarised") columns. The server attaches the value
+// to each row under an opaque key; this module builds the `ColumnDef` that
+// reads it, and serialises the active view's rollups into the `rollups` query
+// param the host route parses.
+//
+// Sibling of `utils/lookupColumns.tsx` (many-to-one) and
+// `utils/formulaColumns.tsx` (computed in the browser). All three are told
+// apart by key prefix alone, on client and server both.
+
+import type { ColumnDef } from '../types/index';
+import type { RollupColumnRef, RollupFn } from '../types/rollup';
+import { ROLLUP_COUNT_FIELD, isRollupFn } from '../types/rollup';
+import { formatAggregate } from './formatAggregate';
+
+const KEY_PREFIX = 'rollup__';
+
+/**
+ * Row field / column data key for a rollup column.
+ *
+ * MUST stay byte-identical to `rollupColumnDataKey` on the server side (today:
+ * `packages/projects/src/modules/folders/lib/rollups/resolver.ts`). The server
+ * writes that key onto the row; a `ColumnDef.data` that differs by one
+ * character renders an empty column with no error anywhere.
+ */
+export function rollupColumnDataKey(r: { source: string; field: string; fn: RollupFn }): string {
+  return `${KEY_PREFIX}${r.source}__${r.field}__${r.fn}`;
+}
+
+/** True when a column data key belongs to a rollup column. */
+export function isRollupColumnKey(key: string): boolean {
+  return key.startsWith(KEY_PREFIX);
+}
+
+/** Inverse of {@link rollupColumnDataKey}; undefined when the key is not one. */
+export function parseRollupColumnKey(
+  key: string,
+): { source: string; field: string; fn: RollupFn } | undefined {
+  if (!isRollupColumnKey(key)) return undefined;
+  const parts = key.slice(KEY_PREFIX.length).split('__');
+  if (parts.length !== 3) return undefined;
+  const [source, field, fn] = parts;
+  if (!source || !field || !isRollupFn(fn)) return undefined;
+  return { source, field, fn };
+}
+
+/**
+ * Serialise a view's rollup columns into the `rollups` query param value
+ * (`source:field:fn,source:field:fn`). Empty when the view has none — and an
+ * empty param is what makes the feature free: the host route then behaves
+ * byte-identically to before rollups existed.
+ *
+ * De-duplicated, because two refs that differ only in `label` are one aggregate
+ * to the server and asking twice buys a second `GROUP BY` for nothing.
+ */
+export function rollupColumnsToParam(refs: readonly RollupColumnRef[]): string {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const r of refs) {
+    const triple = `${r.source}:${r.field}:${r.fn}`;
+    if (seen.has(triple)) continue;
+    seen.add(triple);
+    out.push(triple);
+  }
+  return out.join(',');
+}
+
+/**
+ * Defensively parse the `_rollups` smuggled inside the perspective's `filters`
+ * passthrough. Drops anything malformed so a legacy or hand-edited view can
+ * never crash the table — the same contract as `parseLookupColumns` and
+ * `parseFormulaColumns`.
+ *
+ * A ref whose `fn` this client does not know is DROPPED rather than half-kept:
+ * that is the forward-compatibility rule the aggregations parser already
+ * follows, and it degrades to one missing column instead of a thrown render.
+ */
+export function parseRollupColumns(raw: unknown): RollupColumnRef[] {
+  if (!Array.isArray(raw)) return [];
+  const out: RollupColumnRef[] = [];
+  const seen = new Set<string>();
+  for (const entry of raw) {
+    if (!entry || typeof entry !== 'object') continue;
+    const { source, field, fn, label } = entry as Record<string, unknown>;
+    if (typeof source !== 'string' || !source) continue;
+    if (typeof field !== 'string' || !field) continue;
+    if (!isRollupFn(fn)) continue;
+    // COUNT is only ever over the child's id — the server enforces the same
+    // rule, so a ref that disagrees would render a permanently empty column.
+    if (fn === 'count' && field !== ROLLUP_COUNT_FIELD) continue;
+    const key = rollupColumnDataKey({ source, field, fn });
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push({
+      source,
+      field,
+      fn,
+      label: typeof label === 'string' && label ? label : key,
+    });
+  }
+  return out;
+}
+
+/** Default column width. Counts are short; money needs room for `1 234 567,89`. */
+function widthFor(fn: RollupFn): number {
+  return fn === 'count' ? 90 : 140;
+}
+
+export interface BuildRollupColumnDefsOptions {
+  /** Locale for number formatting. Same formatter as group subtotals. */
+  locale?: string;
+}
+
+/**
+ * Build read-only `ColumnDef`s for a perspective's rollup columns.
+ *
+ * Presentation is fixed rather than configurable, and every part of it is
+ * load-bearing:
+ *
+ * - `type: 'numeric'` — grouping's `AggregationRule` refuses to total a column
+ *   that is not numeric, and `getSortDirectionLabels` would otherwise offer
+ *   "A → Z" for a column of amounts.
+ * - `align: 'right'` + `mono` — a column of numbers is read by scanning the
+ *   decimal point; the house rule for every amount column in this product.
+ * - `readOnly` + `disableFill` — a rollup is computed from OTHER rows. There is
+ *   nothing on this row to write it back to, so every write path refuses it
+ *   rather than silently discarding the edit.
+ * - `formatAggregate` — **the same formatter the group-subtotal and
+ *   footer-total rows use**, so a rollup cell and a `SUM` subtotal of that same
+ *   column can never disagree about decimals. It also coerces the STRINGS raw
+ *   SQL returns (`COUNT` → `"7"`, `SUM numeric` → `"18400.0000"`); the old
+ *   `Number.isFinite(value) ? value : 0` path rendered every one of those as
+ *   `0,00`.
+ * - a genuinely absent value renders `—` rather than `0`, which keeps "no
+ *   children" (the server sends `0`) visually distinct from "this rollup did
+ *   not resolve" (key absent).
+ *
+ * `exportValue` returns the raw number so a spreadsheet gets `18400`, not the
+ * locale-formatted `18 400,00`.
+ */
+export function buildRollupColumnDefs(
+  refs: readonly RollupColumnRef[],
+  options: BuildRollupColumnDefsOptions = {},
+): ColumnDef[] {
+  return refs.map((ref) => {
+    const col: ColumnDef = {
+      data: rollupColumnDataKey(ref),
+      title: ref.label,
+      headerTooltip: ref.label,
+      width: widthFor(ref.fn),
+      type: 'numeric',
+      align: 'right',
+      mono: true,
+      readOnly: true,
+      disableFill: true,
+      exportValue: (value: unknown) => (value == null ? '' : (value as string | number)),
+    };
+    col.renderer = (value: unknown) => formatAggregate(value, col, options.locale, ref.fn);
+    return col;
+  });
+}

package/src/backend/dynamic-table/validators/index.ts

@@ -0,0 +1,40 @@
+// validators/index.ts
+
+export type CellValidatorFunction = (
+    value: any,
+    rowData: any,
+    columnConfig: any
+) => { valid: boolean; error?: string };
+
+export const defaultValidator: CellValidatorFunction = (value, rowData, columnConfig) => {
+    return { valid: true, error: undefined };
+};
+
+export const requiredValidator: CellValidatorFunction = (value, rowData, columnConfig) => {
+    if (value === null || value === undefined || value === '') {
+        return { valid: false, error: 'Value is required' };
+    }
+    return { valid: true, error: undefined };
+};
+
+export const emailValidator: CellValidatorFunction = (value, rowData, columnConfig) => {
+    if (!value || !value.includes('@')) {
+        return { valid: false, error: 'Invalid email address' };
+    }
+    return { valid: true, error: undefined };
+};
+
+export const numberValidator: CellValidatorFunction = (value, rowData, columnConfig) => {
+    if (typeof value !== 'number' || isNaN(value)) {
+        return { valid: false, error: 'Value is not a number' };
+    }
+    return { valid: true, error: undefined };
+};
+
+export const dateValidator: CellValidatorFunction = (value, rowData, columnConfig) => {
+    const isValidDate = isNaN(new Date(value).getTime());
+    if (typeof value !== 'string' || isValidDate) {
+        return { valid: false, error: 'Invalid date' };
+    }
+    return { valid: true, error: undefined };
+};

package/src/backend/fields/registry.generated.ts

@@ -0,0 +1,8 @@
+// Auto-registered field components loaded at runtime.
+// This file can be regenerated by module generators. Keep imports side-effectful.
+import '@open-mercato/core/modules/attachments/fields/attachment'
+import '@open-mercato/core/modules/dictionaries/fields/dictionary'
+
+export function loadAll() {
+  // No-op: imports above perform registration via side effects
+}

package/src/backend/fields/registry.ts

@@ -0,0 +1,38 @@
+import * as React from 'react'
+import type { CrudCustomFieldRenderProps } from '../CrudForm'
+
+export type FieldInputComponent = (props: CrudCustomFieldRenderProps & { def?: any }) => React.ReactNode
+export type FieldDefEditorComponent = (props: { def: any; onChange: (patch: any) => void }) => React.ReactNode
+
+type Entry = { input?: FieldInputComponent; defEditor?: FieldDefEditorComponent }
+
+class FieldRegistryImpl {
+  private map = new Map<string, Entry>()
+
+  register(kind: string, entry: Entry) {
+    const k = kind.toLowerCase()
+    const prev = this.map.get(k) || {}
+    this.map.set(k, { ...prev, ...entry })
+  }
+
+  getInput(kind: string): FieldInputComponent | undefined {
+    return this.map.get(kind.toLowerCase())?.input
+  }
+
+  getDefEditor(kind: string): FieldDefEditorComponent | undefined {
+    return this.map.get(kind.toLowerCase())?.defEditor
+  }
+}
+
+export const FieldRegistry = new FieldRegistryImpl()
+
+// Placeholder for generator to auto-register fields from modules
+// eslint-disable-next-line @typescript-eslint/no-empty-function
+export async function loadGeneratedFieldRegistrations(): Promise<void> {
+  try {
+    const gen = await import('./registry.generated')
+    if (typeof gen.loadAll === 'function') gen.loadAll()
+  } catch {
+    // ignore when not present
+  }
+}