@freighttech/ui 0.13.18

package/src/backend/dynamic-table/__tests__/formulaColumns.test.tsx

@@ -0,0 +1,213 @@
+import * as React from 'react'
+import { render } from '@testing-library/react'
+import {
+  buildFormulaColumnDefs,
+  formatFormulaValue,
+  formulaColumnDataKey,
+  formulaErrorToken,
+  isFormulaColumnKey,
+  parseFormulaColumns,
+  slugifyFormulaLabel,
+  uniqueFormulaColumnKey,
+} from '../utils/formulaColumns'
+import { fieldMetaFromColumns } from '../formula/check'
+import type { ColumnDef } from '../types/index'
+import type { FormulaColumnRef } from '../formula/types'
+
+const columns: ColumnDef[] = [
+  { data: 'revenue', title: 'Revenue', type: 'numeric' },
+  { data: 'cost', title: 'Cost', type: 'numeric' },
+  { data: 'qty', title: 'Qty', type: 'numeric' },
+  { data: 'ref_no', title: 'Reference', type: 'text' },
+]
+const fields = fieldMetaFromColumns(columns)
+
+const margin: FormulaColumnRef = {
+  key: 'formula__margin',
+  label: 'Margin',
+  expression: 'revenue - cost',
+  resultType: 'number',
+}
+
+/** Render a column's cell for one row and return the rendered element. */
+function renderCell(def: ColumnDef, row: Record<string, unknown>): HTMLElement {
+  const { container } = render(<>{def.renderer!(undefined, row, null, 0, 0)}</>)
+  return container.firstElementChild as HTMLElement
+}
+
+describe('column keys', () => {
+  it('prefixes calculated columns so they are told apart by prefix alone', () => {
+    expect(formulaColumnDataKey('margin')).toBe('formula__margin')
+    expect(isFormulaColumnKey('formula__margin')).toBe(true)
+    expect(isFormulaColumnKey('lookup__contractor__tax_id')).toBe(false)
+  })
+
+  it('slugifies a label to ASCII, including Polish diacritics', () => {
+    expect(slugifyFormulaLabel('Margin')).toBe('margin')
+    expect(slugifyFormulaLabel('Marża brutto')).toBe('marza_brutto')
+    expect(slugifyFormulaLabel('Zysk / szt.')).toBe('zysk_szt')
+    expect(slugifyFormulaLabel('€€€')).toBe('calc')
+  })
+
+  it('never collides two columns with the same label into one', () => {
+    expect(uniqueFormulaColumnKey('Margin', [])).toBe('formula__margin')
+    expect(uniqueFormulaColumnKey('Margin', ['formula__margin'])).toBe('formula__margin_2')
+    expect(uniqueFormulaColumnKey('Margin', ['formula__margin', 'formula__margin_2'])).toBe(
+      'formula__margin_3',
+    )
+  })
+})
+
+describe('buildFormulaColumnDefs — the ColumnDef contract', () => {
+  it('produces a read-only, non-fillable column typed from the declared result', () => {
+    const [def] = buildFormulaColumnDefs([margin], { fields })
+    expect(def.data).toBe('formula__margin')
+    expect(def.title).toBe('Margin')
+    expect(def.readOnly).toBe(true)
+    expect(def.disableFill).toBe(true)
+    expect(def.type).toBe('numeric')
+    expect(def.align).toBe('right')
+  })
+
+  it('types a text / boolean / date result correctly', () => {
+    const [text] = buildFormulaColumnDefs([{ ...margin, expression: 'ref_no', resultType: 'text' }], { fields })
+    expect(text.type).toBe('text')
+    expect(text.align).toBeUndefined()
+    const [bool] = buildFormulaColumnDefs(
+      [{ ...margin, expression: 'revenue > cost', resultType: 'boolean' }],
+      { fields },
+    )
+    expect(bool.type).toBe('boolean')
+  })
+})
+
+describe('buildFormulaColumnDefs — rendering', () => {
+  it('computes for every row it is handed', () => {
+    const [def] = buildFormulaColumnDefs([margin], { fields })
+    expect(renderCell(def, { revenue: 1000, cost: 620 }).textContent).toBe('380')
+    expect(renderCell(def, { revenue: 50, cost: 20 }).textContent).toBe('30')
+  })
+
+  it('shows an em dash, not 0 or NaN, when an input is blank', () => {
+    const [def] = buildFormulaColumnDefs([margin], { fields })
+    const cell = renderCell(def, { revenue: null, cost: 620 })
+    expect(cell.getAttribute('data-formula-state')).toBe('empty')
+    expect(cell.textContent).toBe('—')
+  })
+
+  it('shows the error IN THE CELL and leaves the rest of the grid rendering', () => {
+    const [def] = buildFormulaColumnDefs(
+      [{ ...margin, expression: 'revenue / qty' }],
+      { fields },
+    )
+    const bad = renderCell(def, { revenue: 100, qty: 0 })
+    expect(bad.getAttribute('data-formula-state')).toBe('error')
+    expect(bad.getAttribute('data-formula-error')).toBe('divide_by_zero')
+    expect(bad.textContent).toBe('#DIV/0!')
+    expect(bad.getAttribute('title')).toBe('Cannot divide by zero')
+
+    const good = renderCell(def, { revenue: 100, qty: 4 })
+    expect(good.getAttribute('data-formula-state')).toBe('ok')
+    expect(good.textContent).toBe('25')
+  })
+
+  it('translates the error tooltip when a translator is supplied', () => {
+    const [def] = buildFormulaColumnDefs([{ ...margin, expression: 'revenue / qty' }], {
+      fields,
+      translate: (key) => `translated:${key}`,
+    })
+    expect(renderCell(def, { revenue: 1, qty: 0 }).getAttribute('title')).toBe(
+      'translated:dynamicTable.formula.error.divideByZero',
+    )
+  })
+
+  it('recomputes after the row object is mutated in place by an inline edit', () => {
+    const [def] = buildFormulaColumnDefs([margin], { fields })
+    const row: Record<string, unknown> = { revenue: 1000, cost: 620 }
+    expect(renderCell(def, row).textContent).toBe('380')
+    row.cost = 500
+    expect(renderCell(def, row).textContent).toBe('500')
+  })
+
+  it('renders a boolean and a date in a stable, locale-free form', () => {
+    const [bool] = buildFormulaColumnDefs(
+      [{ ...margin, expression: 'revenue > cost', resultType: 'boolean' }],
+      { fields },
+    )
+    expect(renderCell(bool, { revenue: 2, cost: 1 }).textContent).toBe('TRUE')
+
+    const [date] = buildFormulaColumnDefs(
+      [{ ...margin, expression: 'TODAY()', resultType: 'date' }],
+      { fields, now: () => new Date(2026, 7, 3) },
+    )
+    expect(renderCell(date, {}).textContent).toBe('2026-08-03')
+  })
+
+  it('trims floating-point noise instead of showing 0.30000000000000004', () => {
+    const [def] = buildFormulaColumnDefs([{ ...margin, expression: 'revenue + cost' }], { fields })
+    expect(renderCell(def, { revenue: 0.1, cost: 0.2 }).textContent).toBe('0.3')
+  })
+})
+
+describe('buildFormulaColumnDefs — export', () => {
+  it('exports the computed value, not the (absent) stored one', () => {
+    const [def] = buildFormulaColumnDefs([margin], { fields })
+    expect(def.exportValue!(undefined, { revenue: 1000, cost: 620 })).toBe(380)
+  })
+
+  it('exports blank as null and an error as its Excel token', () => {
+    const [def] = buildFormulaColumnDefs([{ ...margin, expression: 'revenue / qty' }], { fields })
+    expect(def.exportValue!(undefined, { revenue: null, qty: 2 })).toBeNull()
+    expect(def.exportValue!(undefined, { revenue: 1, qty: 0 })).toBe('#DIV/0!')
+  })
+})
+
+describe('formatting helpers', () => {
+  it('maps each error code to the Excel token users already read', () => {
+    expect(formulaErrorToken('divide_by_zero')).toBe('#DIV/0!')
+    expect(formulaErrorToken('type_mismatch')).toBe('#VALUE!')
+    expect(formulaErrorToken('unknown_field')).toBe('#REF!')
+    expect(formulaErrorToken('syntax')).toBe('#NAME?')
+  })
+
+  it('formats each value kind', () => {
+    expect(formatFormulaValue({ state: 'ok', value: 12 })).toBe('12')
+    expect(formatFormulaValue({ state: 'ok', value: true })).toBe('TRUE')
+    expect(formatFormulaValue({ state: 'ok', value: 'x' })).toBe('x')
+    expect(formatFormulaValue({ state: 'empty', value: null })).toBe('')
+  })
+})
+
+describe('parseFormulaColumns', () => {
+  it('round-trips a well-formed definition', () => {
+    expect(parseFormulaColumns([margin])).toEqual([margin])
+  })
+
+  it('drops anything malformed rather than crashing the table', () => {
+    expect(parseFormulaColumns(undefined)).toEqual([])
+    expect(parseFormulaColumns('nope')).toEqual([])
+    expect(
+      parseFormulaColumns([
+        null,
+        { key: 'not_a_formula_key', expression: 'a' },
+        { key: 'formula__x' },
+        { key: 'formula__y', expression: '   ' },
+      ]),
+    ).toEqual([])
+  })
+
+  it('defaults a missing label and an unknown result type', () => {
+    expect(parseFormulaColumns([{ key: 'formula__x', expression: 'a', resultType: 'money' }])).toEqual(
+      [{ key: 'formula__x', label: 'formula__x', expression: 'a', resultType: 'text' }],
+    )
+  })
+
+  it('keeps the first of two definitions sharing a key', () => {
+    expect(
+      parseFormulaColumns([
+        { key: 'formula__x', label: 'First', expression: 'a', resultType: 'number' },
+        { key: 'formula__x', label: 'Second', expression: 'b', resultType: 'number' },
+      ]),
+    ).toEqual([{ key: 'formula__x', label: 'First', expression: 'a', resultType: 'number' }])
+  })
+})

package/src/backend/dynamic-table/__tests__/handlerIdentity.test.ts

@@ -0,0 +1,77 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+/**
+ * Anchor Defect 5 — `VirtualRow`'s `React.memo` only holds if every prop it
+ * receives keeps its identity between renders. Four of those props come from
+ * the handler factories in `handlers/index.ts` (`onCellSave`, `onSaveNewRow`,
+ * `onCancelNewRow`, `onRowHeaderDoubleClick`). For a long time they were
+ * constructed in `DynamicTable`'s render body, which handed every mounted row a
+ * fresh callback on EVERY render — so a keystroke in the filter box re-rendered
+ * every mounted row and therefore every mounted cell.
+ *
+ * The failure is invisible in a behaviour test (everything still works, it is
+ * merely 50× more expensive) and a render-count check needs a browser and the
+ * perf harness. So the invariant is mechanised here instead: a factory call
+ * that is not wrapped in `useMemo` fails the build. Precedent in this package:
+ * `formula.noEval.test.ts`.
+ *
+ * If you need to move one of these out of a `useMemo`, you are re-opening
+ * Defect 5 — measure it with `apps/web/.ai/qa/perf/dt-perf.mjs` first.
+ */
+
+const SOURCE = path.join(__dirname, '..', 'DynamicTable.tsx')
+
+const FACTORIES = [
+  'createCellHandlers',
+  'createRowHandlers',
+  'createDragHandlers',
+  'createMouseHandlers',
+  'createPerspectiveHandlers',
+  'createColumnHeaderHandlers',
+  'createRowHeaderHandlers',
+  'createContextMenuHandlers',
+  'createResizeHandlers',
+]
+
+const source = fs.readFileSync(SOURCE, 'utf8')
+
+/**
+ * True when this call site sits inside a `useMemo(...)` — i.e. walking back
+ * from the call to the start of its statement passes a `useMemo(`.
+ */
+function isMemoized(callIndex: number): boolean {
+  const statementStart = source.lastIndexOf(';', callIndex)
+  const prefix = source.slice(statementStart + 1, callIndex)
+  return prefix.includes('useMemo(')
+}
+
+describe('DynamicTable — handler factory identity', () => {
+  it.each(FACTORIES)('%s is called, and only inside useMemo', (factory) => {
+    // The import line is not a call site.
+    const callSites: number[] = []
+    const re = new RegExp(`\\b${factory}\\s*\\(`, 'g')
+    let m: RegExpExecArray | null
+    while ((m = re.exec(source)) !== null) callSites.push(m.index)
+
+    expect(callSites.length).toBeGreaterThan(0)
+    for (const index of callSites) {
+      const line = source.slice(0, index).split('\n').length
+      expect({ factory, line, memoized: isMemoized(index) }).toEqual({
+        factory,
+        line,
+        memoized: true,
+      })
+    }
+  })
+
+  it('does not discover colour adjacency from the DOM', () => {
+    // Anchor Defect 7: the scroll-coupled `querySelectorAll('… cell-color-…')`
+    // that wrote `data-cb-*` is gone for good. Adjacency now comes from
+    // `utils/colorAdjacency.ts` and reaches the cell as props. (The remaining
+    // scroll listener in this file drives the frozen-column shadow, which is a
+    // legitimate pixels→state read on an always-mounted pinned element.)
+    expect(source).not.toContain('cell-color-')
+    expect(source).not.toMatch(/(set|remove)Attribute\(\s*['"`]data-cb-/)
+  })
+})

package/src/backend/dynamic-table/__tests__/importMapping.test.ts

@@ -0,0 +1,174 @@
+import type { ImportFieldDef } from '../types/import';
+import type { ColumnDef } from '../types/index';
+import {
+  applyMapping,
+  buildDefaultMapping,
+  fieldsFromColumns,
+  normalizeHeader,
+  pruneMapping,
+  validateMapping,
+} from '../utils/importMapping';
+
+const FIELDS: ImportFieldDef[] = [
+  { field: 'id', label: 'Id', type: 'text', matchKey: true },
+  {
+    field: 'invoiceNumber',
+    label: 'Invoice number',
+    labels: ['Numer faktury'],
+    type: 'text',
+    required: true,
+  },
+  { field: 'netAmount', label: 'Net amount', labels: ['Kwota netto'], type: 'numeric' },
+  { field: 'contractorId', label: 'Contractor', type: 'text', relation: true },
+];
+
+describe('normalizeHeader', () => {
+  it('folds case, punctuation and whitespace', () => {
+    expect(normalizeHeader('Invoice number')).toBe('invoicenumber');
+    expect(normalizeHeader(' invoice_number ')).toBe('invoicenumber');
+    expect(normalizeHeader('Invoice-Number')).toBe('invoicenumber');
+  });
+
+  it('folds Polish diacritics, including ł which has no decomposition', () => {
+    expect(normalizeHeader('Kwota nettoś')).toBe(normalizeHeader('Kwota nettos'));
+    expect(normalizeHeader('Załącznik')).toBe('zalacznik');
+  });
+});
+
+describe('buildDefaultMapping', () => {
+  it('maps the export’s own headers with zero configuration', () => {
+    const mapping = buildDefaultMapping(['Invoice number', 'Net amount'], FIELDS);
+    expect(mapping).toEqual({
+      'Invoice number': 'invoiceNumber',
+      'Net amount': 'netAmount',
+    });
+  });
+
+  it('maps a Polish export just as well (locale-dependent headers)', () => {
+    const mapping = buildDefaultMapping(['Numer faktury', 'Kwota netto'], FIELDS);
+    expect(mapping).toEqual({
+      'Numer faktury': 'invoiceNumber',
+      'Kwota netto': 'netAmount',
+    });
+  });
+
+  it('maps a raw field key too, so a hand-written file works', () => {
+    expect(buildDefaultMapping(['invoiceNumber'], FIELDS)).toEqual({
+      invoiceNumber: 'invoiceNumber',
+    });
+  });
+
+  it('claims each target field once — the later duplicate is left unmapped', () => {
+    const mapping = buildDefaultMapping(['Net amount', 'netAmount'], FIELDS);
+    expect(mapping).toEqual({ 'Net amount': 'netAmount' });
+  });
+
+  it('ignores headers it does not recognise rather than guessing', () => {
+    expect(buildDefaultMapping(['Something else'], FIELDS)).toEqual({});
+  });
+});
+
+describe('validateMapping', () => {
+  it('refuses a relation column instead of silently mis-resolving it', () => {
+    const issues = validateMapping(
+      { Contractor: 'contractorId', 'Invoice number': 'invoiceNumber' },
+      ['Contractor', 'Invoice number'],
+      FIELDS,
+    );
+    expect(issues).toEqual([
+      {
+        code: 'relation_unsupported',
+        header: 'Contractor',
+        field: 'contractorId',
+        label: 'Contractor',
+      },
+    ]);
+  });
+
+  it('reports a missing required field', () => {
+    const issues = validateMapping({ 'Net amount': 'netAmount' }, ['Net amount'], FIELDS);
+    expect(issues).toContainEqual({
+      code: 'missing_required',
+      field: 'invoiceNumber',
+      label: 'Invoice number',
+    });
+  });
+
+  it('skips the required check when the caller is updating, not creating', () => {
+    const issues = validateMapping({ 'Net amount': 'netAmount' }, ['Net amount'], FIELDS, {
+      requireRequired: false,
+    });
+    expect(issues).toEqual([]);
+  });
+
+  it('reports two headers pointed at one field', () => {
+    const issues = validateMapping(
+      { A: 'netAmount', B: 'netAmount' },
+      ['A', 'B'],
+      FIELDS,
+      { requireRequired: false },
+    );
+    expect(issues).toEqual([{ code: 'duplicate_field', field: 'netAmount', label: 'Net amount' }]);
+  });
+
+  it('reports a mapping onto a field the module does not accept', () => {
+    const issues = validateMapping({ A: 'nope' }, ['A'], FIELDS, { requireRequired: false });
+    expect(issues).toEqual([{ code: 'unknown_field', header: 'A', field: 'nope', label: 'A' }]);
+  });
+});
+
+describe('pruneMapping', () => {
+  it('drops only the offending header, so a refused relation does not block the rest', () => {
+    const mapping = { Contractor: 'contractorId', 'Invoice number': 'invoiceNumber' };
+    const issues = validateMapping(mapping, Object.keys(mapping), FIELDS);
+    expect(pruneMapping(mapping, issues)).toEqual({ 'Invoice number': 'invoiceNumber' });
+  });
+
+  it('keeps everything when the only issue is a missing required field', () => {
+    const mapping = { 'Net amount': 'netAmount' };
+    const issues = validateMapping(mapping, ['Net amount'], FIELDS);
+    expect(pruneMapping(mapping, issues)).toEqual(mapping);
+  });
+});
+
+describe('applyMapping', () => {
+  it('re-keys a parsed row onto target fields', () => {
+    const out = applyMapping(
+      { 'Invoice number': 'FV/1', 'Net amount': '100.00', Ignored: 'x' },
+      { 'Invoice number': 'invoiceNumber', 'Net amount': 'netAmount' },
+    );
+    expect(out).toEqual({ invoiceNumber: 'FV/1', netAmount: '100.00' });
+  });
+
+  it('turns an empty cell into null — "cleared" is not the same as "absent"', () => {
+    const out = applyMapping({ Notes: '' }, { Notes: 'notes' });
+    expect(out).toEqual({ notes: null });
+    expect('notes' in out).toBe(true);
+  });
+});
+
+describe('fieldsFromColumns', () => {
+  const columns: ColumnDef[] = [
+    { data: 'id', title: 'Id' },
+    { data: 'invoiceNumber', title: 'Invoice number', type: 'text' },
+    { data: 'netAmount', title: 'Net amount', type: 'numeric' },
+    { data: 'contractor', title: 'Contractor', exportValue: (v: any) => String(v?.name ?? '') },
+  ];
+
+  it('carries the column key as an alias so both spellings map', () => {
+    const fields = fieldsFromColumns(columns);
+    const invoiceNumber = fields.find((f) => f.field === 'invoiceNumber');
+    expect(invoiceNumber?.labels).toEqual(['invoiceNumber']);
+  });
+
+  it('marks a column with an exportValue projection as a relation', () => {
+    const fields = fieldsFromColumns(columns);
+    expect(fields.find((f) => f.field === 'contractor')?.relation).toBe(true);
+    expect(fields.find((f) => f.field === 'netAmount')?.relation).toBe(false);
+  });
+
+  it('marks the id column as the match key', () => {
+    const fields = fieldsFromColumns(columns);
+    expect(fields.find((f) => f.field === 'id')?.matchKey).toBe(true);
+  });
+});

package/src/backend/dynamic-table/__tests__/importParse.test.ts

@@ -0,0 +1,130 @@
+import * as XLSX from 'xlsx';
+import { parseImportFile, ImportParseError } from '../utils/importParse';
+import { toCsv } from '../utils/exportTable';
+
+function xlsxBytes(aoa: unknown[][]): Uint8Array {
+  const sheet = XLSX.utils.aoa_to_sheet(aoa);
+  const book = XLSX.utils.book_new();
+  XLSX.utils.book_append_sheet(book, sheet, 'Export');
+  return new Uint8Array(XLSX.write(book, { type: 'array', bookType: 'xlsx' }));
+}
+
+describe('parseImportFile — CSV', () => {
+  it('reads headers and rows from a CSV string', () => {
+    const csv = 'Invoice number,Net amount\nFV/1,100.00\nFV/2,250.50\n';
+    const parsed = parseImportFile(csv);
+
+    expect(parsed.headers).toEqual(['Invoice number', 'Net amount']);
+    expect(parsed.rows).toHaveLength(2);
+    expect(parsed.rows[0]).toEqual({
+      sourceRowNumber: 1,
+      values: { 'Invoice number': 'FV/1', 'Net amount': '100.00' },
+    });
+    expect(parsed.rows[1].sourceRowNumber).toBe(2);
+  });
+
+  it('strips the UTF-8 BOM our own CSV export writes', () => {
+    // Round-trip the exporter's own output — this is the export→edit→re-import path.
+    const csv = toCsv({
+      headers: ['Numer faktury', 'Kwota netto'],
+      rows: [['FV/1', '100.00']],
+    });
+    expect(csv.charCodeAt(0)).toBe(0xfeff);
+
+    const parsed = parseImportFile(csv);
+    expect(parsed.headers).toEqual(['Numer faktury', 'Kwota netto']);
+    expect(parsed.rows[0].values['Numer faktury']).toBe('FV/1');
+  });
+
+  it('survives quoted fields containing commas and quotes', () => {
+    const csv = toCsv({
+      headers: ['Seller', 'Notes'],
+      rows: [['Maersk A/S, Kopenhaga', 'said "ok"']],
+    });
+    const parsed = parseImportFile(csv);
+    expect(parsed.rows[0].values.Seller).toBe('Maersk A/S, Kopenhaga');
+    expect(parsed.rows[0].values.Notes).toBe('said "ok"');
+  });
+
+  it('skips wholly blank padding rows without consuming a row number', () => {
+    const csv = 'A,B\n1,2\n,\n3,4\n';
+    const parsed = parseImportFile(csv);
+    expect(parsed.rows.map((r) => r.sourceRowNumber)).toEqual([1, 2]);
+    expect(parsed.rows[1].values).toEqual({ A: '3', B: '4' });
+  });
+});
+
+describe('parseImportFile — XLSX', () => {
+  it('reads an .xlsx workbook into the same shape as the CSV path', () => {
+    const bytes = xlsxBytes([
+      ['Invoice number', 'Net amount'],
+      ['FV/1', '100.00'],
+      ['FV/2', '250.50'],
+    ]);
+    const parsed = parseImportFile(bytes);
+
+    expect(parsed.headers).toEqual(['Invoice number', 'Net amount']);
+    expect(parsed.rows).toHaveLength(2);
+    expect(parsed.rows[0].values).toEqual({
+      'Invoice number': 'FV/1',
+      'Net amount': '100.00',
+    });
+  });
+
+  it('normalizes a real date cell to an ISO date rather than a locale blob', () => {
+    const bytes = xlsxBytes([
+      ['Invoice date'],
+      [new Date(Date.UTC(2026, 7, 3))],
+    ]);
+    const parsed = parseImportFile(bytes);
+    expect(parsed.rows[0].values['Invoice date']).toBe('2026-08-03');
+  });
+
+  it('suffixes duplicate headers so the mapping stays a total function', () => {
+    const bytes = xlsxBytes([
+      ['Amount', 'Amount'],
+      ['1', '2'],
+    ]);
+    const parsed = parseImportFile(bytes);
+    expect(parsed.headers).toEqual(['Amount', 'Amount (2)']);
+    expect(parsed.rows[0].values).toEqual({ Amount: '1', 'Amount (2)': '2' });
+  });
+});
+
+describe('parseImportFile — caps and refusals', () => {
+  it('rejects a file over the row cap and reports the real row count', () => {
+    const lines = ['A'];
+    for (let i = 0; i < 12; i++) lines.push(String(i));
+    expect.assertions(3);
+    try {
+      parseImportFile(lines.join('\n'), { maxRows: 10 });
+    } catch (err) {
+      expect(err).toBeInstanceOf(ImportParseError);
+      expect((err as ImportParseError).code).toBe('too_many_rows');
+      expect((err as ImportParseError).details).toEqual({ count: 12, limit: 10 });
+    }
+  });
+
+  it('rejects an oversized file BEFORE parsing it', () => {
+    const big = 'A\n' + 'x\n'.repeat(50);
+    expect(() => parseImportFile(big, { maxBytes: 8 })).toThrow(ImportParseError);
+    try {
+      parseImportFile(big, { maxBytes: 8 });
+    } catch (err) {
+      expect((err as ImportParseError).code).toBe('file_too_large');
+    }
+  });
+
+  it('rejects an empty file', () => {
+    expect(() => parseImportFile('')).toThrow(/empty/i);
+  });
+
+  it('rejects a file with headers but no data rows', () => {
+    try {
+      parseImportFile('A,B\n');
+      throw new Error('should have thrown');
+    } catch (err) {
+      expect((err as ImportParseError).code).toBe('empty_file');
+    }
+  });
+});

package/src/backend/dynamic-table/__tests__/importServerOnly.test.ts

@@ -0,0 +1,37 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const componentsDir = path.join(__dirname, '..', 'components');
+
+/**
+ * The import parser is server-only by construction, not by convention.
+ *
+ * If a client component ever imports it, two things break at once: the browser
+ * bundle grows a spreadsheet reader, and — far worse — the file gets parsed
+ * twice, once for the preview and once for the commit, which is exactly how a
+ * preview stops describing what the commit will do. This test is the tripwire.
+ */
+describe('importParse stays server-side', () => {
+  const clientFiles = ['ImportPanel.tsx', 'ImportPreviewGrid.tsx'];
+
+  it.each(clientFiles)('%s does not import the parser', (file) => {
+    const source = fs.readFileSync(path.join(componentsDir, file), 'utf8');
+    // Match a real import statement, not the word in a comment.
+    expect(source).not.toMatch(/^\s*import[^;]*from\s+['"][^'"]*importParse['"]/m);
+  });
+
+  it.each(clientFiles)('%s does not import xlsx', (file) => {
+    const source = fs.readFileSync(path.join(componentsDir, file), 'utf8');
+    expect(source).not.toMatch(/^\s*import[^;]*from\s+['"]xlsx['"]/m);
+  });
+
+  it('the panel is a client component and the parser is not', () => {
+    const panel = fs.readFileSync(path.join(componentsDir, 'ImportPanel.tsx'), 'utf8');
+    const parser = fs.readFileSync(
+      path.join(__dirname, '..', 'utils', 'importParse.ts'),
+      'utf8',
+    );
+    expect(panel.startsWith("'use client'")).toBe(true);
+    expect(parser).not.toMatch(/^['"]use client['"]/m);
+  });
+});