@freighttech/ui 0.13.18

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

@@ -0,0 +1,237 @@
+import * as React from 'react'
+import type { ColumnDef } from '../types/index'
+import type {
+  FormulaCellResult,
+  FormulaColumnRef,
+  FormulaErrorCode,
+  FormulaFieldMeta,
+  FormulaResultType,
+} from '../formula/types'
+import { compileFormulaColumns, createFormulaRowEvaluator } from '../formula/evaluate'
+import { formulaIssueI18nKey } from '../formula/types'
+
+/**
+ * Row field / column data key for a calculated column. Mirrors
+ * `lookupColumnDataKey`'s `<prefix>__<tail>` convention so the two virtual
+ * column kinds are told apart by prefix alone, on client and server both.
+ */
+export function formulaColumnDataKey(slug: string): string {
+  return `formula__${slug}`
+}
+
+/** True when a column data key belongs to a calculated column. */
+export function isFormulaColumnKey(key: string): boolean {
+  return key.startsWith('formula__')
+}
+
+/**
+ * Derive a stable slug from the user's label. Diacritics are stripped so a
+ * Polish label (`Marża`) yields an ASCII key the server and URL params can
+ * carry unescaped.
+ */
+export function slugifyFormulaLabel(label: string): string {
+  const ascii = label
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .replace(/ł/g, 'l')
+    .replace(/Ł/g, 'L')
+  return (
+    ascii
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '_')
+      .replace(/^_+|_+$/g, '')
+      .slice(0, 40) || 'calc'
+  )
+}
+
+/**
+ * A key not already taken by another formula column. Two columns both called
+ * "Margin" must not collide into one, so the second gets a numeric suffix.
+ */
+export function uniqueFormulaColumnKey(label: string, taken: readonly string[]): string {
+  const base = formulaColumnDataKey(slugifyFormulaLabel(label))
+  if (!taken.includes(base)) return base
+  let n = 2
+  while (taken.includes(`${base}_${n}`)) n += 1
+  return `${base}_${n}`
+}
+
+/**
+ * Excel's error tokens, because Excel's error tokens are what users already
+ * read. Inventing our own vocabulary here would be a novel UX for no gain.
+ */
+const ERROR_TOKENS: Record<FormulaErrorCode, string> = {
+  divide_by_zero: '#DIV/0!',
+  type_mismatch: '#VALUE!',
+  unknown_field: '#REF!',
+  cycle: '#REF!',
+  unknown_function: '#NAME?',
+  syntax: '#NAME?',
+  arity: '#NAME?',
+}
+
+/** The short token shown inside an errored formula cell. */
+export function formulaErrorToken(code: FormulaErrorCode): string {
+  return ERROR_TOKENS[code]
+}
+
+/**
+ * Render a computed value as text. Floating-point noise (`0.1 + 0.2`) is
+ * trimmed at the 10th decimal — enough to keep money and rates exact, short of
+ * the precision where trimming would be a lie.
+ */
+export function formatFormulaValue(result: FormulaCellResult): string {
+  if (result.state === 'empty') return ''
+  if (result.state === 'error') return formulaErrorToken(result.issue.code)
+  const value = result.value
+  if (typeof value === 'number') {
+    if (Number.isInteger(value)) return String(value)
+    return String(Number(value.toFixed(10)))
+  }
+  if (typeof value === 'boolean') return value ? 'TRUE' : 'FALSE'
+  if (value instanceof Date) {
+    const pad = (n: number) => String(n).padStart(2, '0')
+    return `${value.getFullYear()}-${pad(value.getMonth() + 1)}-${pad(value.getDate())}`
+  }
+  return String(value)
+}
+
+/** `ColumnDef.type` for a declared result type — drives alignment and sort UI. */
+function columnTypeFor(resultType: FormulaResultType): ColumnDef['type'] {
+  switch (resultType) {
+    case 'number':
+      return 'numeric'
+    case 'date':
+      return 'date'
+    case 'boolean':
+      return 'boolean'
+    default:
+      return 'text'
+  }
+}
+
+export interface BuildFormulaColumnDefsOptions {
+  /** Every column a formula may reference (native + linked). */
+  fields: readonly FormulaFieldMeta[]
+  /**
+   * Translator for the per-cell error tooltip. Given the issue's i18n key, its
+   * English fallback and its params. Defaults to the English fallback so the
+   * util stays usable outside a React tree (tests, exports).
+   */
+  translate?: (key: string, fallback: string, params?: Record<string, string | number>) => string
+  /** Injectable clock, so `TODAY()` is deterministic under test. */
+  now?: () => Date
+}
+
+/**
+ * Build read-only `ColumnDef`s for a perspective's calculated columns,
+ * following `buildLookupColumnDefs`.
+ *
+ * The value is NOT attached to the row: it is computed by the renderer from the
+ * row it is handed, through one shared evaluator whose cache guarantees each row
+ * is walked at most once per change to the inputs the formulas actually read.
+ *
+ * Every column is `readOnly` and `disableFill` — a derived value has nowhere to
+ * be written back to, so inline edit is refused rather than silently discarded.
+ */
+export function buildFormulaColumnDefs(
+  refs: readonly FormulaColumnRef[],
+  options: BuildFormulaColumnDefsOptions,
+): ColumnDef[] {
+  const translate = options.translate ?? ((_key, fallback) => fallback)
+  const set = compileFormulaColumns(refs, options.fields)
+  const evaluate = createFormulaRowEvaluator(set, { now: options.now })
+
+  const resultFor = (ref: FormulaColumnRef, rowData: unknown): FormulaCellResult => {
+    if (!rowData || typeof rowData !== 'object') return { state: 'empty', value: null }
+    const results = evaluate(rowData as Record<string, unknown>)
+    return results.get(ref.key) ?? { state: 'empty', value: null }
+  }
+
+  return refs.map((ref) => ({
+    data: ref.key,
+    title: ref.label,
+    type: columnTypeFor(ref.resultType),
+    align: ref.resultType === 'number' ? ('right' as const) : undefined,
+    mono: ref.resultType === 'number',
+    readOnly: true,
+    disableFill: true,
+    renderer: (_value: unknown, rowData: unknown) => {
+      const result = resultFor(ref, rowData)
+      if (result.state === 'error') {
+        const title = translate(
+          formulaIssueI18nKey(result.issue),
+          result.issue.message,
+          result.issue.params,
+        )
+        return (
+          <span
+            className="text-body-regular-sm text-destructive-v2"
+            data-formula-key={ref.key}
+            data-formula-state="error"
+            data-formula-error={result.issue.code}
+            title={title}
+          >
+            {formulaErrorToken(result.issue.code)}
+          </span>
+        )
+      }
+      if (result.state === 'empty') {
+        return (
+          <span
+            className="text-body-regular-sm text-m3-on-surface-variant"
+            data-formula-key={ref.key}
+            data-formula-state="empty"
+          >
+            —
+          </span>
+        )
+      }
+      return (
+        <span
+          className="text-body-regular-sm"
+          data-formula-key={ref.key}
+          data-formula-state="ok"
+        >
+          {formatFormulaValue(result)}
+        </span>
+      )
+    },
+    // Exports carry the computed value, not the (absent) stored one. An errored
+    // cell exports its Excel token so a spreadsheet reader sees the same thing
+    // the grid showed rather than a silent blank.
+    exportValue: (_value: unknown, rowData: unknown) => {
+      const result = resultFor(ref, rowData)
+      if (result.state === 'empty') return null
+      if (result.state === 'ok' && typeof result.value === 'number') return result.value
+      return formatFormulaValue(result)
+    },
+  }))
+}
+
+/**
+ * Defensively parse the `_formulas` 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`.
+ */
+export function parseFormulaColumns(raw: unknown): FormulaColumnRef[] {
+  if (!Array.isArray(raw)) return []
+  const valid: FormulaResultType[] = ['number', 'text', 'boolean', 'date']
+  const out: FormulaColumnRef[] = []
+  for (const entry of raw) {
+    if (!entry || typeof entry !== 'object') continue
+    const { key, label, expression, resultType } = entry as Record<string, unknown>
+    if (typeof key !== 'string' || !isFormulaColumnKey(key)) continue
+    if (typeof expression !== 'string' || !expression.trim()) continue
+    if (out.some((r) => r.key === key)) continue
+    out.push({
+      key,
+      label: typeof label === 'string' && label ? label : key,
+      expression,
+      resultType: valid.includes(resultType as FormulaResultType)
+        ? (resultType as FormulaResultType)
+        : 'text',
+    })
+  }
+  return out
+}

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

@@ -0,0 +1,202 @@
+/**
+ * Headers → fields. Pure, dependency-free, shared by the server (which builds
+ * the default mapping) and the panel (which lets a user override it).
+ *
+ * The default mapping is what makes **export → edit → re-import** work with
+ * zero configuration: `utils/exportTable.ts` writes `col.title ?? col.data` as
+ * the header, so a field whose `labels` include that title round-trips without
+ * the user touching the mapping UI.
+ */
+import type {
+  ImportFieldDef,
+  ImportMapping,
+  ImportMappingIssue,
+} from '../types/import';
+import type { ColumnDef } from '../types/index';
+
+/**
+ * Fold a header down to a comparison key: lowercase, diacritics stripped,
+ * punctuation and whitespace collapsed. "Numer faktury", "numer_faktury" and
+ * "Numer Faktury " all land on `numerfaktury`, which is the tolerance a user
+ * pasting a colleague's spreadsheet actually needs.
+ */
+export function normalizeHeader(header: string): string {
+  return header
+    .normalize('NFD')
+    // Combining marks — ł has no decomposition, so it is handled below.
+    .replace(/[\u0300-\u036f]/g, '')
+    .replace(/ł/gi, 'l')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '');
+}
+
+/** Every accepted spelling of a field, normalized. */
+function fieldKeys(field: ImportFieldDef): string[] {
+  const raw = [field.field, field.label, ...(field.labels ?? [])];
+  const keys = new Set<string>();
+  for (const value of raw) {
+    const key = normalizeHeader(value);
+    if (key) keys.add(key);
+  }
+  return [...keys];
+}
+
+/**
+ * Auto-map file headers onto target fields by normalized label.
+ *
+ * First match wins per field: a file with both "Net amount" and "netAmount"
+ * maps the first and leaves the second unmapped rather than silently letting
+ * the later column overwrite the earlier one.
+ */
+export function buildDefaultMapping(
+  headers: string[],
+  fields: ImportFieldDef[],
+): ImportMapping {
+  const index = new Map<string, string>();
+  for (const field of fields) {
+    for (const key of fieldKeys(field)) {
+      if (!index.has(key)) index.set(key, field.field);
+    }
+  }
+
+  const mapping: ImportMapping = {};
+  const claimed = new Set<string>();
+  for (const header of headers) {
+    const target = index.get(normalizeHeader(header));
+    if (!target || claimed.has(target)) continue;
+    mapping[header] = target;
+    claimed.add(target);
+  }
+  return mapping;
+}
+
+/**
+ * Check a mapping against the file's headers and the module's fields.
+ *
+ * Relation fields are reported as `relation_unsupported` rather than resolved:
+ * the generic path cannot know whether "Maersk" is contractor `a1b2…` and a
+ * wrong guess writes the wrong record (spec A1).
+ */
+export function validateMapping(
+  mapping: ImportMapping,
+  headers: string[],
+  fields: ImportFieldDef[],
+  options: { requireRequired?: boolean } = {},
+): ImportMappingIssue[] {
+  const byField = new Map(fields.map((f) => [f.field, f]));
+  const headerSet = new Set(headers);
+  const issues: ImportMappingIssue[] = [];
+  const usedFields = new Map<string, number>();
+
+  for (const [header, target] of Object.entries(mapping)) {
+    if (!headerSet.has(header)) continue;
+    const field = byField.get(target);
+    if (!field) {
+      issues.push({ code: 'unknown_field', header, field: target, label: header });
+      continue;
+    }
+    if (field.relation) {
+      issues.push({
+        code: 'relation_unsupported',
+        header,
+        field: field.field,
+        label: header,
+      });
+      continue;
+    }
+    usedFields.set(target, (usedFields.get(target) ?? 0) + 1);
+  }
+
+  for (const [target, count] of usedFields) {
+    if (count > 1) {
+      const field = byField.get(target);
+      issues.push({
+        code: 'duplicate_field',
+        field: target,
+        label: field?.label ?? target,
+      });
+    }
+  }
+
+  if (options.requireRequired !== false) {
+    for (const field of fields) {
+      if (!field.required || field.relation) continue;
+      if (!usedFields.has(field.field)) {
+        issues.push({ code: 'missing_required', field: field.field, label: field.label });
+      }
+    }
+  }
+
+  return issues;
+}
+
+/**
+ * Drop mappings that `validateMapping` rejected, so a preview can still run on
+ * the columns that ARE sound. A relation column being refused must not take the
+ * other forty columns down with it.
+ */
+export function pruneMapping(
+  mapping: ImportMapping,
+  issues: ImportMappingIssue[],
+): ImportMapping {
+  const badHeaders = new Set(
+    issues.filter((i) => i.header && i.code !== 'missing_required').map((i) => i.header as string),
+  );
+  const pruned: ImportMapping = {};
+  for (const [header, target] of Object.entries(mapping)) {
+    if (badHeaders.has(header)) continue;
+    pruned[header] = target;
+  }
+  return pruned;
+}
+
+/**
+ * Apply a mapping to one parsed row. Unmapped headers are dropped; an empty
+ * cell yields `null` so "the user cleared this" is distinguishable from "the
+ * column was not in the file at all" (absent key).
+ */
+export function applyMapping(
+  values: Record<string, string>,
+  mapping: ImportMapping,
+): Record<string, string | null> {
+  const out: Record<string, string | null> = {};
+  for (const [header, target] of Object.entries(mapping)) {
+    if (!(header in values)) continue;
+    const raw = values[header];
+    out[target] = raw === '' ? null : raw;
+  }
+  return out;
+}
+
+/**
+ * Derive importable field defs from a table's own `ColumnDef`s.
+ *
+ * This is the generic path's default: whatever the grid shows and exports is
+ * what it can read back. Columns that carry an `exportValue` hook are treated
+ * as relation-shaped — a column whose stored cell value needs a projection to
+ * become text cannot be reversed by parsing that text back (spec A1).
+ */
+export function fieldsFromColumns(
+  columns: ColumnDef[],
+  options: { idColumn?: string } = {},
+): ImportFieldDef[] {
+  const idColumn = options.idColumn ?? 'id';
+  const fields: ImportFieldDef[] = [];
+  for (const col of columns) {
+    const label = col.title ?? col.data;
+    const type: ImportFieldDef['type'] =
+      col.type === 'numeric' ? 'numeric'
+      : col.type === 'date' ? 'date'
+      : col.type === 'boolean' ? 'boolean'
+      : 'text';
+    fields.push({
+      field: col.data,
+      label,
+      labels: label === col.data ? undefined : [col.data],
+      type,
+      relation: Boolean(col.exportValue),
+      matchKey: col.data === idColumn,
+    });
+  }
+  return fields;
+}

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

@@ -0,0 +1,220 @@
+/**
+ * File → rows. **SERVER-SIDE ONLY.**
+ *
+ * The browser uploads bytes; this runs in the route handler. Parsing in both
+ * places is how a preview and its commit drift apart, so there is deliberately
+ * no client entry point — `components/ImportPanel.tsx` does not import this
+ * file, and a test asserts that it never starts to.
+ *
+ * `xlsx` (vendored as `@freighttech/xlsx@0.20.3`) reads BOTH formats: `XLSX.read`
+ * sniffs a CSV buffer just as happily as a ZIP workbook, and `sheet_to_json`
+ * flattens either into rows. No second CSV parser is needed.
+ *
+ * Precedent: `packages/facilities/.../services/excel-parse.service.ts`.
+ */
+import * as XLSX from 'xlsx';
+import { IMPORT_MAX_FILE_BYTES, IMPORT_MAX_ROWS } from '../types/import';
+
+export type ImportParseErrorCode =
+  | 'file_too_large'
+  | 'too_many_rows'
+  | 'empty_file'
+  | 'no_headers'
+  | 'unreadable';
+
+/**
+ * A parse failure the user can act on. Route handlers map `code` onto a
+ * message; nothing here is localized, because `packages/ui` server code has no
+ * request locale.
+ */
+export class ImportParseError extends Error {
+  readonly code: ImportParseErrorCode;
+  /** Interpolation values for the caller's i18n string (e.g. `{ count, limit }`). */
+  readonly details: Record<string, unknown>;
+
+  constructor(code: ImportParseErrorCode, message: string, details: Record<string, unknown> = {}) {
+    super(message);
+    this.name = 'ImportParseError';
+    this.code = code;
+    this.details = details;
+  }
+}
+
+export interface ParsedImportFile {
+  /** Header labels in file order, blanks dropped, duplicates suffixed. */
+  headers: string[];
+  /** Data rows keyed by header. `sourceRowNumber` is the 1-based data row. */
+  rows: Array<{ sourceRowNumber: number; values: Record<string, string> }>;
+  sheetName: string;
+}
+
+export interface ParseImportFileOptions {
+  /** Max data rows accepted. Defaults to `IMPORT_MAX_ROWS` (1,000). */
+  maxRows?: number;
+  /** Max byte length accepted. Defaults to `IMPORT_MAX_FILE_BYTES` (10 MB). */
+  maxBytes?: number;
+  /** Sheet to read. Defaults to the first. */
+  sheetIndex?: number;
+}
+
+type ParseInput = ArrayBuffer | Uint8Array | string;
+
+function byteLength(input: ParseInput): number {
+  if (typeof input === 'string') {
+    // A rough upper bound is fine — the cap exists to stop pathological files,
+    // not to be byte-exact on a string that was already fully materialized.
+    return input.length * 2;
+  }
+  if (input instanceof Uint8Array) return input.byteLength;
+  return input.byteLength;
+}
+
+/**
+ * Turn a SheetJS cell value into the string the mapper works with.
+ *
+ * Everything downstream is string-shaped because that is what a spreadsheet
+ * cell *is* to the user, and because the module's own zod validators already
+ * own coercion. Dates are the one exception worth normalizing here: SheetJS
+ * hands back a `Date` for a real date cell, and `String(date)` would produce a
+ * locale-dependent blob that no validator accepts.
+ */
+function cellToString(value: unknown): string {
+  if (value === null || value === undefined) return '';
+  if (value instanceof Date) {
+    // ISO date (no time) — the shape every date validator in the codebase takes.
+    const iso = value.toISOString();
+    return Number.isNaN(value.getTime()) ? '' : iso.slice(0, 10);
+  }
+  if (typeof value === 'boolean') return value ? 'true' : 'false';
+  return String(value).trim();
+}
+
+/**
+ * Normalize the header row: trim, drop trailing blanks, and suffix duplicates
+ * so `{ header: field }` mapping stays a total function. Two columns both
+ * called "Amount" become "Amount" and "Amount (2)".
+ */
+function normalizeHeaders(raw: unknown[]): string[] {
+  const trimmed = raw.map((h) => cellToString(h));
+  // Drop trailing empties — spreadsheets routinely carry phantom columns.
+  let end = trimmed.length;
+  while (end > 0 && trimmed[end - 1] === '') end -= 1;
+
+  const seen = new Map<string, number>();
+  const headers: string[] = [];
+  for (let i = 0; i < end; i++) {
+    const base = trimmed[i] || `Column ${i + 1}`;
+    const count = (seen.get(base) ?? 0) + 1;
+    seen.set(base, count);
+    headers.push(count === 1 ? base : `${base} (${count})`);
+  }
+  return headers;
+}
+
+/**
+ * Parse an uploaded `.xlsx` or `.csv` into headers + string-valued rows.
+ *
+ * Caps are checked BEFORE and immediately AFTER the read: the byte cap stops a
+ * 50 MB workbook from expanding into 400 MB of heap, and the row cap is
+ * enforced on the parsed sheet because a small file can still declare a huge
+ * range.
+ *
+ * @throws {ImportParseError}
+ */
+export function parseImportFile(
+  input: ParseInput,
+  options: ParseImportFileOptions = {},
+): ParsedImportFile {
+  const maxRows = options.maxRows ?? IMPORT_MAX_ROWS;
+  const maxBytes = options.maxBytes ?? IMPORT_MAX_FILE_BYTES;
+  const sheetIndex = options.sheetIndex ?? 0;
+
+  const size = byteLength(input);
+  if (size > maxBytes) {
+    throw new ImportParseError('file_too_large', 'File exceeds the size limit', {
+      bytes: size,
+      limit: maxBytes,
+    });
+  }
+  if (size === 0) {
+    throw new ImportParseError('empty_file', 'File is empty');
+  }
+
+  let workbook: XLSX.WorkBook;
+  try {
+    if (typeof input === 'string') {
+      // Strip a UTF-8 BOM — our own CSV export writes one so Excel picks the
+      // encoding up, and SheetJS would otherwise fold it into header one.
+      const text = input.charCodeAt(0) === 0xfeff ? input.slice(1) : input;
+      // `raw: true` on a CSV read stops SheetJS type-sniffing every cell:
+      // without it an invoice number like `FV/1/2026` is helpfully turned into
+      // a date. Everything arrives as a string, which is what a CSV cell is.
+      workbook = XLSX.read(text, { type: 'string', raw: true });
+    } else {
+      const bytes = input instanceof Uint8Array ? input : new Uint8Array(input);
+      // A real XLSX carries typed cells, so `cellDates` gives us `Date`
+      // objects rather than serial numbers; `cellToString` renders them ISO.
+      workbook = XLSX.read(bytes, { type: 'array', cellDates: true });
+    }
+  } catch (err) {
+    throw new ImportParseError('unreadable', 'File could not be read as CSV or Excel', {
+      cause: err instanceof Error ? err.message : String(err),
+    });
+  }
+
+  const sheetName = workbook.SheetNames[sheetIndex];
+  const sheet = sheetName ? workbook.Sheets[sheetName] : undefined;
+  if (!sheet) {
+    throw new ImportParseError('empty_file', 'Workbook contains no readable sheet');
+  }
+
+  const matrix = XLSX.utils.sheet_to_json<unknown[]>(sheet, {
+    header: 1,
+    blankrows: false,
+    defval: '',
+    // Raw values, NOT the display text: a date cell must reach us as a `Date`
+    // (so it becomes `2026-08-03`) rather than as whatever `8/3/26` format the
+    // author happened to apply.
+    raw: true,
+  });
+
+  if (!matrix.length) {
+    throw new ImportParseError('empty_file', 'Sheet contains no rows');
+  }
+
+  const headers = normalizeHeaders(matrix[0] ?? []);
+  if (!headers.length) {
+    throw new ImportParseError('no_headers', 'First row carries no column headers');
+  }
+
+  const body = matrix.slice(1);
+  const rows: ParsedImportFile['rows'] = [];
+  for (const line of body) {
+    const values: Record<string, string> = {};
+    let hasData = false;
+    for (let c = 0; c < headers.length; c++) {
+      const cell = cellToString((line as unknown[])[c]);
+      values[headers[c]] = cell;
+      if (cell !== '') hasData = true;
+    }
+    // A wholly blank line is spreadsheet padding, not a record.
+    if (!hasData) continue;
+    rows.push({ sourceRowNumber: rows.length + 1, values });
+
+    if (rows.length > maxRows) {
+      throw new ImportParseError('too_many_rows', 'File exceeds the row limit', {
+        // Report what the file actually holds so "split it in parts" is actionable.
+        count: body.filter((l) =>
+          (l as unknown[]).some((v) => cellToString(v) !== ''),
+        ).length,
+        limit: maxRows,
+      });
+    }
+  }
+
+  if (!rows.length) {
+    throw new ImportParseError('empty_file', 'File has headers but no data rows');
+  }
+
+  return { headers, rows, sheetName: sheetName as string };
+}