@freighttech/ui 0.13.18

package/src/backend/dynamic-table/types/density.ts

@@ -0,0 +1,179 @@
+/**
+ * DynamicTable density scale — the USER-SETTABLE row/type density preference.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * WHY THIS EXISTS
+ *
+ * Logistics users read a whole working picture off one screen. The 3 Aug 2026
+ * INF workshops recorded the complaint verbatim (A16): "on a normal monitor
+ * roughly half the needed columns fit". The same workshops recorded the exact
+ * opposite need — two users (Agnieszka, Klaudiusz) work completely differently
+ * and both asked for their own defaults, and the product owner has repeatedly
+ * flagged FMS tables as "fonts too small".
+ *
+ * Those two facts do not reconcile into one number. They reconcile into a
+ * PREFERENCE. So:
+ *
+ *   - `comfortable` is the DEFAULT and is pixel-identical to how the grid
+ *     renders today. Opting out of the feature is a no-op.
+ *   - `compact` and `dense` are opt-in, per user, and persist for that user.
+ *   - Nothing here shrinks type globally. There is no global default change.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * WHY IT IS AN ATTRIBUTE, NOT A PROP THREADED INTO CELLS
+ *
+ * The grid virtualizes ROWS ONLY (one `useVirtualizer`, `overscan: 10`, no
+ * `horizontal: true`). `VirtualRow` does a plain `columns.map`, so EVERY column
+ * of EVERY mounted row renders. Denser tables mount MORE cells, so anything
+ * per-cell gets multiplied by thousands.
+ *
+ * Therefore density is delivered as ONE attribute on the container
+ * (`data-density-level`) which flips a block of CSS custom properties consumed
+ * by existing selectors in `styles/density.css`. Switching density re-styles
+ * the entire grid with:
+ *
+ *   - zero per-cell React work,
+ *   - zero cell re-renders,
+ *   - zero extra props threaded through `Cell` / `VirtualRow`.
+ *
+ * The browser recalculates style for the subtree; React does nothing.
+ *
+ * THE ONE EXCEPTION, stated honestly: ROW HEIGHT cannot be CSS-only. Rows are
+ * absolutely positioned by the virtualizer (`transform: translateY(...)`, plus
+ * an inline `height`), so the height must be a number JS knows. That is what
+ * `DENSITY_METRICS[level].rowHeight` is for — the virtualizer's `estimateSize`
+ * reads it, and `density.css` restates the SAME number for the box model.
+ * Changing density therefore costs exactly one virtualizer re-measure, not a
+ * per-cell pass. Do NOT try to force row height from CSS with `!important`:
+ * it would win over the inline style and immediately desynchronise the fill
+ * from the `translateY` offsets, overlapping the rows.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * NAMING TRAP — `data-density-level`, NOT `data-density`
+ *
+ * `data-density` is ALREADY TAKEN. `DynamicTable.tsx` emits it from a legacy
+ * DEVELOPER-facing prop (`density?: 'sm' | 'md'` → 36px / 44px rows), and
+ * `DynamicTable.v2.css` carries rules keyed on `:not([data-density])` that
+ * define part of today's default rendering. Reusing the attribute would
+ * silently switch those rules off the moment a user picked `comfortable` —
+ * which is precisely the "opting out must be a no-op" guarantee, broken.
+ *
+ * So this scale uses a distinct attribute. The two are orthogonal today; see
+ * the migration note at the bottom of this file.
+ */
+
+/**
+ * The three density levels, coarsest to tightest.
+ *
+ * - `comfortable` — today's sizing, exactly. The default.
+ * - `compact`     — same 12px type, tighter geometry. ~24% more rows.
+ * - `dense`       — the maximum-information setting: 11px data / 10px headers,
+ *                   hairline row rules. ~67% more rows. For a power user on a
+ *                   wide monitor who is scanning, not reading.
+ */
+export type DensityLevel = 'comfortable' | 'compact' | 'dense'
+
+/** Every level, in scale order. Safe to render as a picker. */
+export const DENSITY_LEVELS: readonly DensityLevel[] = ['comfortable', 'compact', 'dense'] as const
+
+/**
+ * The default. MUST stay `comfortable`: it is defined as pixel-identical to
+ * pre-density rendering, which is what makes shipping this feature a visual
+ * no-op for every user who never opens the setting.
+ */
+export const DEFAULT_DENSITY: DensityLevel = 'comfortable'
+
+/**
+ * The container attribute that carries the level.
+ *
+ * Deliberately NOT `data-density` — see the naming trap above.
+ */
+export const DENSITY_ATTRIBUTE = 'data-density-level' as const
+
+/**
+ * Geometry each level needs on the JS side.
+ *
+ * ONLY the numbers that CSS cannot own live here. Padding, borders, and the
+ * type ramp are pure CSS (`styles/density.css`) and are intentionally absent —
+ * duplicating them in TS would create two sources of truth for values nothing
+ * in JS reads.
+ *
+ * `rowHeight` MUST equal `--dt-row-height` for the same level in
+ * `styles/density.css`. They are asserted equal by the unit test
+ * `__tests__/density.test.ts`, which parses the stylesheet.
+ */
+export type DensityMetrics = {
+  /**
+   * Data-row height in px, border-box, INCLUDING the inter-row gap borders.
+   * Feeds the virtualizer's `estimateSize`.
+   */
+  rowHeight: number
+  /**
+   * Column-header row height in px, border-box. `null` = content-driven
+   * (`height: auto`), which is what today's grid does — pinning a number for
+   * `comfortable` would be a 1–2px visual change, and `comfortable` is not
+   * allowed to change anything.
+   */
+  headerHeight: number | null
+}
+
+export const DENSITY_METRICS: Readonly<Record<DensityLevel, DensityMetrics>> = {
+  // Today's values, verified against DynamicTable.tsx:708 (`dataRowHeight`
+  // default 32) and DynamicTable.v2.css (header height is content-driven).
+  comfortable: { rowHeight: 32, headerHeight: null },
+  compact: { rowHeight: 26, headerHeight: 24 },
+  dense: { rowHeight: 20, headerHeight: 20 },
+}
+
+/**
+ * Narrow an untrusted value (localStorage, an API response, a URL param) to a
+ * `DensityLevel`. Pure; no allocation.
+ */
+export function isDensityLevel(value: unknown): value is DensityLevel {
+  return value === 'comfortable' || value === 'compact' || value === 'dense'
+}
+
+/**
+ * Resolve a density level to the value of the container's density attribute.
+ *
+ * Pure, total, allocation-free — it returns one of three interned string
+ * literals, so it is safe to call inside a render body.
+ *
+ * TOTAL BY DESIGN: an absent, `null`, or corrupt input (a stale localStorage
+ * value, a hand-edited URL param) resolves to `DEFAULT_DENSITY` rather than
+ * `null` or a throw. A broken preference must degrade to today's rendering,
+ * never to an unstyled or missing grid.
+ *
+ * NOTE: `comfortable` DOES emit its attribute value rather than dropping the
+ * attribute. That is deliberate. Every consuming rule in `density.css` is
+ * guarded by `:not([data-density-level="comfortable"])`, so the attribute's
+ * presence at the default level changes nothing — and having it always present
+ * means the level is inspectable in DevTools and assertable from `GridHarness`
+ * without a special "absent means comfortable" case in every test.
+ */
+export function resolveDensityAttribute(level: DensityLevel | null | undefined): DensityLevel {
+  return isDensityLevel(level) ? level : DEFAULT_DENSITY
+}
+
+/**
+ * Row height for a level. Falls back to the default for unknown input rather
+ * than throwing — a corrupt stored preference must never break the grid.
+ */
+export function resolveDensityRowHeight(level: DensityLevel | null | undefined): number {
+  return DENSITY_METRICS[isDensityLevel(level) ? level : DEFAULT_DENSITY].rowHeight
+}
+
+/*
+ * ─────────────────────────────────────────────────────────────────────────────
+ * MIGRATION NOTE — folding in the legacy `density?: 'sm' | 'md'` prop
+ *
+ * The legacy prop is a per-table DEVELOPER choice (36px / 44px rows); this
+ * scale is a per-user preference. They are independent axes today and a table
+ * may carry both attributes without conflict, because `density.css` never
+ * keys off `[data-density]`.
+ *
+ * The eventual cleanup — one axis, user-owned — is a separate change and needs
+ * its own spec, because `'md'` (44px) is LOOSER than `comfortable` (32px), so
+ * there is no honest 1:1 mapping. Do not "simplify" it in passing.
+ * ─────────────────────────────────────────────────────────────────────────────
+ */

package/src/backend/dynamic-table/types/filters.ts

@@ -0,0 +1,156 @@
+// types/filters.ts
+
+export type FilterOperator =
+  | 'is_any_of'
+  | 'is_not_any_of'
+  | 'contains'
+  | 'is_empty'
+  | 'is_not_empty'
+  | 'equals'
+  | 'not_equals'
+  | 'greater_than'
+  | 'less_than'
+  | 'is_true'
+  | 'is_false'
+  | 'is_before'
+  | 'is_after'
+  | 'is_on_or_before'
+  | 'is_on_or_after'
+  | 'is_between'
+  | 'is_in_next'
+  | 'is_in_last'
+  | 'is_overdue'
+  | 'is_today'
+  | 'is_tomorrow'
+  | 'is_this_week'
+  | 'is_next_week';
+
+export const getOperatorsForType = (type?: 'text' | 'numeric' | 'boolean'| "date" | "dropdown" | "multiselect"): { value: FilterOperator; label: string }[] => {
+  const common = [
+    { value: 'is_any_of' as FilterOperator, label: 'is any of' },
+    { value: 'is_not_any_of' as FilterOperator, label: 'is not any of' },
+    { value: 'is_empty' as FilterOperator, label: 'is empty' },
+    { value: 'is_not_empty' as FilterOperator, label: 'is not empty' },
+  ];
+
+  if (type === 'numeric') {
+    return [
+      ...common,
+      { value: 'equals' as FilterOperator, label: 'equals' },
+      { value: 'not_equals' as FilterOperator, label: 'not equals' },
+      { value: 'greater_than' as FilterOperator, label: 'greater than' },
+      { value: 'less_than' as FilterOperator, label: 'less than' },
+    ];
+  }
+
+  if (type === 'boolean') {
+    return [
+      { value: 'is_true' as FilterOperator, label: 'is true' },
+      { value: 'is_false' as FilterOperator, label: 'is false' },
+    ];
+  }
+
+  if (type === 'date') {
+    return [
+      // Now-relative presets first — the most-used for "due today / this week".
+      { value: 'is_today' as FilterOperator, label: 'today' },
+      { value: 'is_tomorrow' as FilterOperator, label: 'tomorrow' },
+      { value: 'is_this_week' as FilterOperator, label: 'this week' },
+      { value: 'is_next_week' as FilterOperator, label: 'next week' },
+      { value: 'is_overdue' as FilterOperator, label: 'overdue' },
+      { value: 'is_between' as FilterOperator, label: 'is between' },
+      { value: 'is_before' as FilterOperator, label: 'is before' },
+      { value: 'is_after' as FilterOperator, label: 'is after' },
+      { value: 'is_on_or_before' as FilterOperator, label: 'is on or before' },
+      { value: 'is_on_or_after' as FilterOperator, label: 'is on or after' },
+      { value: 'is_in_next' as FilterOperator, label: 'next' },
+      { value: 'is_in_last' as FilterOperator, label: 'last' },
+      { value: 'equals' as FilterOperator, label: 'equals' },
+      { value: 'is_empty' as FilterOperator, label: 'is empty' },
+      { value: 'is_not_empty' as FilterOperator, label: 'is not empty' },
+    ];
+  }
+
+  return [
+    ...common,
+    { value: 'contains' as FilterOperator, label: 'contains' },
+  ];
+};
+
+// Now-relative preset operators — value-less; resolved to a today-anchored
+// window server-side (see filterParser). Like is_empty, they render no value
+// editor.
+export const PRESET_DATE_OPERATORS: FilterOperator[] = [
+  'is_overdue', 'is_today', 'is_tomorrow', 'is_this_week', 'is_next_week',
+];
+
+export const needsValueInput = (operator: FilterOperator): boolean => {
+  return !['is_empty', 'is_not_empty', 'is_true', 'is_false', ...PRESET_DATE_OPERATORS].includes(operator);
+};
+
+export const needsMultipleValues = (operator: FilterOperator): boolean => {
+  return ['is_any_of', 'is_not_any_of'].includes(operator);
+};
+
+// `is_between` takes two scalar values (from + to), shown as two date inputs.
+// Distinct from `needsMultipleValues` which is a multi-pill "any of" set.
+export const needsRangeValues = (operator: FilterOperator): boolean => {
+  return operator === 'is_between';
+};
+
+// Date-operator predicate — used by ConfigureViewFilters to render
+// <input type="date"> instead of a plain text box.
+// NB: the relative operators (`is_in_next`/`is_in_last`) are deliberately
+// excluded — they take a count + unit, not a calendar date, so they render the
+// relative editor (see `needsRelativeInput`) rather than the FilterDatePicker.
+export const DATE_OPERATORS: FilterOperator[] = [
+  'is_before', 'is_after', 'is_on_or_before', 'is_on_or_after', 'is_between', 'equals',
+];
+export const isDateOperator = (operator: FilterOperator): boolean => DATE_OPERATORS.includes(operator);
+
+// Relative ("moving") date operators — value is a [count, unit] pair, resolved
+// to a today-anchored window server-side. Rendered as a number input + unit
+// select (dni / tygodnie / miesiące) in ConfigureViewFilters.
+export type RelativeDateUnit = 'days' | 'weeks' | 'months';
+export const RELATIVE_DATE_UNITS: RelativeDateUnit[] = ['days', 'weeks', 'months'];
+export const RELATIVE_DATE_OPERATORS: FilterOperator[] = ['is_in_next', 'is_in_last'];
+export const needsRelativeInput = (operator: FilterOperator): boolean =>
+  RELATIVE_DATE_OPERATORS.includes(operator);
+
+export const applyFilters = (data: any[], filters: { field: string; operator: FilterOperator; values: string[] }[], columns: any[]): any[] => {
+  if (filters.length === 0) return data;
+
+  return data.filter(row => {
+    return filters.every(filter => {
+      const value = row[filter.field];
+      const stringValue = String(value ?? '').toLowerCase();
+
+      switch (filter.operator) {
+        case 'is_any_of':
+          return filter.values.some(v => String(value) === v);
+        case 'is_not_any_of':
+          return !filter.values.some(v => String(value) === v);
+        case 'contains':
+          return filter.values.some(v => stringValue.includes(v.toLowerCase()));
+        case 'is_empty':
+          return !value || stringValue === '';
+        case 'is_not_empty':
+          return !!value && stringValue !== '';
+        case 'equals':
+          return Number(value) === Number(filter.values[0]);
+        case 'not_equals':
+          return Number(value) !== Number(filter.values[0]);
+        case 'greater_than':
+          return Number(value) > Number(filter.values[0]);
+        case 'less_than':
+          return Number(value) < Number(filter.values[0]);
+        case 'is_true':
+          return value === true || value === 'true';
+        case 'is_false':
+          return value === false || value === 'false';
+        default:
+          return true;
+      }
+    });
+  });
+};

package/src/backend/dynamic-table/types/grouping.ts

@@ -0,0 +1,189 @@
+// types/grouping.ts
+
+import type { ColumnDataType } from './perspective';
+
+export interface GroupRule {
+  id: string;
+  field: string;
+  direction: 'asc' | 'desc';
+}
+
+/**
+ * Aggregation function applied to a column within each group (and, once the
+ * footer is wired, over the filtered dataset).
+ *
+ * Semantics deliberately mirror SQL / Excel so the client-side fold and the
+ * server-side `GROUP BY`-less aggregate agree on the same numbers:
+ *
+ * - `sum`            — `SUM(col)`; non-numeric cells are ignored, empty set → 0
+ * - `avg`            — `AVG(col)`; non-numeric ignored, empty set → null
+ * - `min` / `max`    — `MIN(col)` / `MAX(col)`; empty set → null. Date columns
+ *                      compare chronologically and yield epoch milliseconds.
+ * - `count`          — `COUNT(col)`: non-empty cells (NOT the row count)
+ * - `countDistinct`  — `COUNT(DISTINCT col)`
+ */
+export type AggregationFn = 'sum' | 'avg' | 'min' | 'max' | 'count' | 'countDistinct';
+
+/**
+ * THE single source of truth for the supported functions.
+ *
+ * There used to be three independent `['sum']` literals — this type, the
+ * `perspectiveTransforms` whitelist (which SILENTLY DROPPED any rule it did not
+ * recognise, so a saved view could lose its rules on reload) and the Configure
+ * View picker. They must widen in lockstep, so they now all read this constant.
+ */
+export const AGGREGATION_FNS: readonly AggregationFn[] = [
+  'sum',
+  'avg',
+  'min',
+  'max',
+  'count',
+  'countDistinct',
+] as const;
+
+export function isAggregationFn(value: unknown): value is AggregationFn {
+  return typeof value === 'string' && (AGGREGATION_FNS as readonly string[]).includes(value);
+}
+
+/**
+ * Which functions make sense for a column of this type.
+ *
+ * `count` / `countDistinct` are valid on *every* column (Excel's COUNTA works
+ * on text); `sum` / `avg` need numbers; `min` / `max` additionally work on
+ * dates, which is how "earliest / latest" is expressed.
+ */
+export function aggregationFnsForColumnType(type?: ColumnDataType): AggregationFn[] {
+  if (type === 'numeric') return ['sum', 'avg', 'min', 'max', 'count', 'countDistinct'];
+  if (type === 'date') return ['min', 'max', 'count', 'countDistinct'];
+  return ['count', 'countDistinct'];
+}
+
+/** The first function that is valid for a column type — used when a rule's column changes. */
+export function defaultAggregationFnForColumnType(type?: ColumnDataType): AggregationFn {
+  return aggregationFnsForColumnType(type)[0] ?? 'count';
+}
+
+export interface AggregationRule {
+  /** Stable id — one rule per column, so `agg-<field>`. */
+  id: string;
+  /** Column `data` key. */
+  field: string;
+  fn: AggregationFn;
+  /**
+   * OPTIONAL partition column (`data` key). When set, the aggregate is not one
+   * number but ONE NUMBER PER DISTINCT VALUE of this column, and the UI renders
+   * the breakdown instead of a single figure.
+   *
+   * This exists because a scalar `sum` over a column whose rows are not
+   * commensurable is not merely imprecise — it is FALSE, and it looks fine.
+   * `SUM(grossAmount)` over 6 150 PLN + 1 000 EUR + 8 600 USD rendered
+   * `15 750,00`, unlabelled, as the only summary figure on the screen an
+   * accountant closes the month from (HEDGE-147).
+   *
+   * The honest fix is a per-dimension breakdown rather than a conversion to a
+   * base currency: a breakdown needs no exchange rate, so unlike a converted
+   * total it CANNOT be wrong. (A converted total would additionally have to
+   * show rate + date + source to be readable at all — HEDGE-39/43/81 — and
+   * would have to source a rate that most rows simply do not carry.)
+   *
+   * Omitted on every pre-existing rule, so behaviour is unchanged wherever it
+   * is not set.
+   */
+  dimension?: string;
+}
+
+/**
+ * One slice of a dimensioned aggregate: the partition value and its figure.
+ *
+ * `key` is the raw cell value of the dimension column, stringified (`'PLN'`),
+ * or `''` when the row had none — the renderer decides how to label that.
+ */
+export interface AggregateBreakdownEntry {
+  key: string;
+  value: number | null;
+}
+
+/**
+ * What set of rows an aggregate actually describes.
+ *
+ * This is not decoration. Client-side grouping folds over ONE server page
+ * (`pageSize <= 100`), so a subtotal presented as "the group total" is wrong
+ * whenever the dataset spans more than one page. Every aggregate therefore
+ * carries its scope and the UI is required to render it.
+ */
+export type AggregateScope = 'dataset' | 'page';
+
+/**
+ * Transport shape for a server-computed aggregate (`?aggregate=` response).
+ * Not persisted.
+ */
+export interface AggregateResult {
+  /** MANDATORY. An unlabelled number is the defect this exists to prevent. */
+  scope: AggregateScope;
+  /** Row count in scope. */
+  total: number;
+  /** `${field}:${fn}` -> value. `null` means "no value in scope" (e.g. MIN of nothing). */
+  values: Record<string, number | null>;
+  /**
+   * `${field}:${fn}` -> per-dimension slices, present only for rules that
+   * carry a `dimension`. Optional, so a route that has not adopted it (and
+   * every already-published response) stays valid.
+   */
+  breakdowns?: Record<string, AggregateBreakdownEntry[]>;
+}
+
+export interface GroupHeaderVisualRow {
+  type: 'groupHeader';
+  groupKey: string;
+  field: string;
+  value: string;
+  count: number;
+  depth: number;
+  collapsed: boolean;
+  /** Data indices of every row in this group (incl. nested descendants),
+   * regardless of collapse state — drives the group select-all checkbox. */
+  memberDataIndices: number[];
+}
+
+export interface DataVisualRow {
+  type: 'dataRow';
+  dataIndex: number;
+}
+
+/** Subtotal row rendered after a group's rows (one per group level). */
+export interface GroupSummaryVisualRow {
+  type: 'groupSummary';
+  /** Ties the summary to its group header. */
+  groupKey: string;
+  /** Nesting depth — parity with the group header for left-indent. */
+  depth: number;
+  /** field -> aggregated value. Only aggregated fields are present.
+   *  `null` = the function had nothing to work with (e.g. MIN over no numbers). */
+  values: Record<string, number | null>;
+  /** field -> the function that produced `values[field]`, so the renderer can
+   *  format a count as an integer and a date MIN as a date. */
+  fns: Record<string, AggregationFn>;
+  /** field -> per-dimension slices, for the fields whose rule set a
+   *  `dimension`. When present the renderer shows these INSTEAD of
+   *  `values[field]`, because for those fields the scalar is not meaningful. */
+  breakdowns?: Record<string, AggregateBreakdownEntry[]>;
+  /**
+   * What these numbers actually cover. `'page'` whenever the loaded rows are
+   * only part of the filtered dataset (or when coverage is unknown) — the UI
+   * MUST say so rather than presenting a page fold as a group total.
+   */
+  scope: AggregateScope;
+  /** How many rows on the loaded page fed this subtotal. */
+  rowsCovered: number;
+}
+
+export type VisualRow = GroupHeaderVisualRow | DataVisualRow | GroupSummaryVisualRow;
+
+export function generateGroupRuleId(): string {
+  return `group-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+}
+
+/** One aggregation rule per column, so a field-derived id keeps it unique. */
+export function generateAggregationRuleId(field: string): string {
+  return `agg-${field}`;
+}

package/src/backend/dynamic-table/types/import.ts

@@ -0,0 +1,132 @@
+/**
+ * Wire types for the reversible file-import pipeline (Spec 3, Phases 1-3).
+ *
+ * This module is deliberately **dependency-free** — no `xlsx`, no React, no
+ * server APIs — so both the browser panel (`components/ImportPanel.tsx`) and
+ * the server parser (`utils/importParse.ts`) can share one vocabulary without
+ * the client ever pulling the spreadsheet reader into its bundle.
+ *
+ * The parse itself is SERVER-SIDE ONLY. A client+server double parse is
+ * exactly how a preview and its commit drift apart, so the browser never sees
+ * a workbook — it uploads bytes and renders whatever the server made of them.
+ */
+
+/** Hard caps enforced BEFORE parsing (see spec A6 / "Memory blow-up" risk). */
+export const IMPORT_MAX_ROWS = 1000;
+export const IMPORT_MAX_FILE_BYTES = 10 * 1024 * 1024;
+
+/** v1 import modes. `upsert_key` is per-module opt-in and not offered here. */
+export type ImportMode = 'create' | 'upsert_id';
+
+/** What a preview decided to do with one source row. */
+export type ImportRowAction = 'created' | 'updated' | 'skipped' | 'failed';
+
+/**
+ * One importable target field, declared by the adopting module.
+ *
+ * `labels` carries EVERY header spelling that should auto-map onto this field:
+ * the export's own column title (per locale), the field key, and any legacy
+ * spelling. Round-tripping an export must need zero manual mapping, and the
+ * export header is locale-dependent, so a single label is not enough.
+ */
+export interface ImportFieldDef {
+  /** Target field key on the module's create/update input. */
+  field: string;
+  /** Primary human label, shown in the mapping UI. */
+  label: string;
+  /** Additional accepted header spellings (locales, snake_case, aliases). */
+  labels?: string[];
+  type?: 'text' | 'numeric' | 'date' | 'boolean';
+  /** Required for a `create`; a blank value fails the row. */
+  required?: boolean;
+  /**
+   * True when the field points at another record. Relation fields are REFUSED
+   * on the generic path rather than silently mis-resolved (spec A1): a header
+   * mapping onto one produces `relation_unsupported`, never a lookup guess.
+   */
+  relation?: boolean;
+  /** Marks the field used to match an existing record in `upsert_id` mode. */
+  matchKey?: boolean;
+}
+
+/** File header → target field key. Headers absent from the map are ignored. */
+export type ImportMapping = Record<string, string>;
+
+export type ImportMappingIssueCode =
+  | 'relation_unsupported'
+  | 'unknown_field'
+  | 'duplicate_field'
+  | 'missing_required';
+
+export interface ImportMappingIssue {
+  code: ImportMappingIssueCode;
+  /** The file header at fault, when the issue is header-shaped. */
+  header?: string;
+  /** The target field at fault, when the issue is field-shaped. */
+  field?: string;
+  /** Human label for whichever of the two the message should name. */
+  label: string;
+}
+
+/** A per-cell validation failure on a previewed row. */
+export interface ImportCellError {
+  field: string;
+  message: string;
+}
+
+/** One row of the dry-run preview. Nothing here has been written. */
+export interface ImportPreviewRow {
+  /** 1-based data row in the uploaded file (header row excluded). */
+  sourceRowNumber: number;
+  action: ImportRowAction;
+  /** Mapped + coerced values, keyed by target field. */
+  values: Record<string, unknown>;
+  /** Existing record this row would update (`upsert_id` only). */
+  recordId: string | null;
+  errors: ImportCellError[];
+}
+
+export interface ImportSummary {
+  created: number;
+  updated: number;
+  skipped: number;
+  failed: number;
+}
+
+/** `POST …/import/preview` response. */
+export interface ImportPreviewResponse {
+  importBatchId: string;
+  mode: ImportMode;
+  sourceFileName: string;
+  /** The mapping actually applied — echoed so the panel can show + edit it. */
+  mapping: ImportMapping;
+  /** Headers found in the file, in file order. */
+  headers: string[];
+  /** Target fields the module accepts, for the mapping UI. */
+  fields: ImportFieldDef[];
+  mappingIssues: ImportMappingIssue[];
+  rows: ImportPreviewRow[];
+  summary: ImportSummary;
+}
+
+/** `POST …/import/:id/commit` response. */
+export interface ImportCommitResponse {
+  importBatchId: string;
+  created: number;
+  updated: number;
+  failed: number;
+  rows: Array<{
+    sourceRowNumber: number;
+    action: ImportRowAction;
+    recordId: string | null;
+    errorMessage: string | null;
+  }>;
+}
+
+/** `POST …/import/:id/revert` response. */
+export interface ImportRevertResponse {
+  importBatchId: string;
+  restored: number;
+  deleted: number;
+  refused: Array<{ sourceRowNumber: number; reason: string }>;
+}