@freighttech/ui 0.13.18

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

@@ -0,0 +1,300 @@
+// utils/conditionalFormat.ts
+//
+// User-authored conditional formatting ("Highlighting"). Rules are view-scoped:
+// they ride inside the perspective's `settings.filters._conditionalFormats`
+// passthrough, so switching views switches the highlighting.
+//
+// The rule type is declared HERE rather than in `types/perspective.ts` so this
+// feature owns its own vocabulary; `PerspectiveConfig` picks it up through
+// `ConditionalFormatCarrier` below.
+
+/** Palette variants. Each maps 1:1 onto an existing `cell-*` class in DynamicTable.css. */
+export type ConditionalFormatStyle =
+  | 'green'
+  | 'yellow'
+  | 'red'
+  | 'green-subtle'
+  | 'yellow-subtle'
+  | 'red-subtle';
+
+export const CONDITIONAL_FORMAT_STYLES: readonly ConditionalFormatStyle[] = [
+  'green',
+  'yellow',
+  'red',
+  'green-subtle',
+  'yellow-subtle',
+  'red-subtle',
+] as const;
+
+export type ConditionalFormatOperator =
+  | 'eq'
+  | 'neq'
+  | 'gt'
+  | 'gte'
+  | 'lt'
+  | 'lte'
+  | 'contains'
+  | 'isEmpty'
+  | 'isNotEmpty'
+  /** `field` is chronologically before `compareField` — the ETA-vs-ATA delay case. */
+  | 'beforeField'
+  /** `field` is chronologically after `compareField`. */
+  | 'afterField';
+
+export const CONDITIONAL_FORMAT_OPERATORS: readonly ConditionalFormatOperator[] = [
+  'eq',
+  'neq',
+  'gt',
+  'gte',
+  'lt',
+  'lte',
+  'contains',
+  'isEmpty',
+  'isNotEmpty',
+  'beforeField',
+  'afterField',
+] as const;
+
+/** Operators that compare against another column instead of a literal. */
+export const RELATIVE_OPERATORS: readonly ConditionalFormatOperator[] = ['beforeField', 'afterField'];
+
+/** Operators that need no comparand at all. */
+export const UNARY_OPERATORS: readonly ConditionalFormatOperator[] = ['isEmpty', 'isNotEmpty'];
+
+export function operatorNeedsValue(op: ConditionalFormatOperator): boolean {
+  return !UNARY_OPERATORS.includes(op) && !RELATIVE_OPERATORS.includes(op);
+}
+
+export function operatorNeedsCompareField(op: ConditionalFormatOperator): boolean {
+  return RELATIVE_OPERATORS.includes(op);
+}
+
+export interface ConditionalFormatRule {
+  /** `cf-<something unique>`. */
+  id: string;
+  /** `ColumnDef.data` key the rule paints. */
+  field: string;
+  operator: ConditionalFormatOperator;
+  /** Literal comparand. Ignored by unary and relative operators. */
+  value?: string | number | null;
+  /** Other column's `data` key, for `beforeField` / `afterField`. */
+  compareField?: string;
+  style: ConditionalFormatStyle;
+}
+
+/**
+ * Mixin that carries view-scoped highlighting rules on a `PerspectiveConfig`.
+ * Declared here so `types/perspective.ts` does not have to change; once the
+ * field is folded into `PerspectiveConfig` itself the intersection becomes a
+ * harmless no-op.
+ */
+export interface ConditionalFormatCarrier {
+  conditionalFormats?: ConditionalFormatRule[];
+}
+
+/**
+ * Hard cap. Rules are evaluated on the cell render path, so an unbounded rule
+ * set is a scroll-performance hazard. 20 is the spec's number.
+ */
+export const MAX_CONDITIONAL_FORMAT_RULES = 20;
+
+export function generateConditionalFormatRuleId(): string {
+  return `cf-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+}
+
+// ─── Parsing (persistence boundary) ──────────────────────────────────────────
+
+/**
+ * Defensively parse `_conditionalFormats` out of the perspective settings
+ * passthrough. Anything malformed is dropped rather than allowed to crash the
+ * grid, and the list is capped.
+ */
+export function parseConditionalFormats(raw: unknown): ConditionalFormatRule[] {
+  if (!Array.isArray(raw)) return [];
+  const out: ConditionalFormatRule[] = [];
+  for (const entry of raw) {
+    if (!entry || typeof entry !== 'object') continue;
+    const { id, field, operator, value, compareField, style } = entry as Record<string, unknown>;
+    if (typeof field !== 'string' || !field) continue;
+    if (
+      typeof operator !== 'string' ||
+      !(CONDITIONAL_FORMAT_OPERATORS as readonly string[]).includes(operator)
+    )
+      continue;
+    if (typeof style !== 'string' || !(CONDITIONAL_FORMAT_STYLES as readonly string[]).includes(style))
+      continue;
+    const op = operator as ConditionalFormatOperator;
+    if (operatorNeedsCompareField(op) && (typeof compareField !== 'string' || !compareField)) continue;
+    out.push({
+      id: typeof id === 'string' && id ? id : generateConditionalFormatRuleId(),
+      field,
+      operator: op,
+      value:
+        typeof value === 'string' || typeof value === 'number' ? value : value === null ? null : undefined,
+      compareField: typeof compareField === 'string' && compareField ? compareField : undefined,
+      style: style as ConditionalFormatStyle,
+    });
+    if (out.length >= MAX_CONDITIONAL_FORMAT_RULES) break;
+  }
+  return out;
+}
+
+// ─── Evaluation ──────────────────────────────────────────────────────────────
+
+type Predicate = (value: unknown, rowData: any) => boolean;
+
+interface CompiledRule {
+  test: Predicate;
+  className: string;
+}
+
+/** Pre-compiled rule set: field -> ordered predicates. */
+export interface CompiledConditionalFormats {
+  byField: Map<string, CompiledRule[]>;
+  /** `true` when there is nothing to evaluate — lets callers skip entirely. */
+  isEmpty: boolean;
+}
+
+export const EMPTY_CONDITIONAL_FORMATS: CompiledConditionalFormats = {
+  byField: new Map(),
+  isEmpty: true,
+};
+
+function isBlank(v: unknown): boolean {
+  return v === null || v === undefined || (typeof v === 'string' && v.trim() === '');
+}
+
+function asNumber(v: unknown): number | null {
+  if (typeof v === 'number') return Number.isFinite(v) ? v : null;
+  if (typeof v === 'boolean') return v ? 1 : 0;
+  if (typeof v !== 'string') return null;
+  const s = v.trim();
+  if (!s) return null;
+  const n = Number(s);
+  return Number.isFinite(n) ? n : null;
+}
+
+/** Comparable ordering key: a date if both sides parse as dates, else a number. */
+function asComparable(v: unknown): number | null {
+  if (v instanceof Date) {
+    const t = v.getTime();
+    return Number.isNaN(t) ? null : t;
+  }
+  const n = asNumber(v);
+  if (n !== null) return n;
+  if (typeof v === 'string') {
+    const t = Date.parse(v.trim());
+    if (!Number.isNaN(t)) return t;
+  }
+  return null;
+}
+
+function compileRule(rule: ConditionalFormatRule): CompiledRule | null {
+  const className = `cell-${rule.style}`;
+  const literal = rule.value;
+
+  switch (rule.operator) {
+    case 'isEmpty':
+      return { test: (v) => isBlank(v), className };
+    case 'isNotEmpty':
+      return { test: (v) => !isBlank(v), className };
+    case 'contains': {
+      const needle = String(literal ?? '').toLowerCase();
+      if (!needle) return null;
+      return { test: (v) => !isBlank(v) && String(v).toLowerCase().includes(needle), className };
+    }
+    case 'eq':
+    case 'neq': {
+      const wantNumber = asNumber(literal);
+      const wantText = String(literal ?? '').toLowerCase();
+      const eq: Predicate = (v) => {
+        if (wantNumber !== null) {
+          const n = asNumber(v);
+          if (n !== null) return n === wantNumber;
+        }
+        if (isBlank(v)) return isBlank(literal);
+        return String(v).toLowerCase() === wantText;
+      };
+      return rule.operator === 'eq'
+        ? { test: eq, className }
+        : { test: (v, row) => !eq(v, row), className };
+    }
+    case 'gt':
+    case 'gte':
+    case 'lt':
+    case 'lte': {
+      const bound = asComparable(literal);
+      if (bound === null) return null;
+      const op = rule.operator;
+      return {
+        test: (v) => {
+          const n = asComparable(v);
+          if (n === null) return false;
+          if (op === 'gt') return n > bound;
+          if (op === 'gte') return n >= bound;
+          if (op === 'lt') return n < bound;
+          return n <= bound;
+        },
+        className,
+      };
+    }
+    case 'beforeField':
+    case 'afterField': {
+      const other = rule.compareField;
+      if (!other) return null;
+      const wantBefore = rule.operator === 'beforeField';
+      return {
+        test: (v, rowData) => {
+          const a = asComparable(v);
+          const b = asComparable(rowData?.[other]);
+          if (a === null || b === null) return false;
+          return wantBefore ? a < b : a > b;
+        },
+        className,
+      };
+    }
+    default:
+      return null;
+  }
+}
+
+/**
+ * Compile a rule set ONCE per change, not once per cell. Rules that cannot
+ * produce a meaningful predicate (a `gt` with no comparand, a `beforeField`
+ * with no target) are dropped rather than matching everything.
+ */
+export function compileConditionalFormats(
+  rules: ConditionalFormatRule[] | undefined | null,
+): CompiledConditionalFormats {
+  if (!rules || rules.length === 0) return EMPTY_CONDITIONAL_FORMATS;
+  const byField = new Map<string, CompiledRule[]>();
+  for (const rule of rules.slice(0, MAX_CONDITIONAL_FORMAT_RULES)) {
+    const compiled = compileRule(rule);
+    if (!compiled) continue;
+    const list = byField.get(rule.field);
+    if (list) list.push(compiled);
+    else byField.set(rule.field, [compiled]);
+  }
+  return { byField, isEmpty: byField.size === 0 };
+}
+
+/**
+ * Resolve the highlight class for one cell. First matching rule wins (Excel's
+ * precedence: rules are ordered and the first one that fires paints the cell).
+ * Returns `undefined` when nothing matches, so the caller can fall through to
+ * the code-level `cellClassName` hook.
+ */
+export function conditionalFormatClassName(
+  compiled: CompiledConditionalFormats,
+  field: string,
+  value: unknown,
+  rowData: any,
+): string | undefined {
+  if (compiled.isEmpty) return undefined;
+  const rules = compiled.byField.get(field);
+  if (!rules) return undefined;
+  for (const rule of rules) {
+    if (rule.test(value, rowData)) return rule.className;
+  }
+  return undefined;
+}

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

@@ -0,0 +1,140 @@
+import type { ColumnDef } from '../types/index';
+import type { CellStore } from '../store/index';
+
+export type ExportFormat = 'csv' | 'xlsx';
+
+export interface ExtractedTable {
+  /** Column header labels, in view order. */
+  headers: string[];
+  /** Body rows; each is an array of cell strings aligned to `headers`. */
+  rows: string[][];
+}
+
+function cellToString(value: unknown): string {
+  if (value === null || value === undefined) return '';
+  return String(value);
+}
+
+/**
+ * Pull the visible columns for the chosen rows out of the cell store — the same
+ * extraction the Copy button uses (`store.getCellValue` over `cols` in view
+ * order, which projects `rowData[col.data]`, the one value source the grid also
+ * renders from). When `selectedRowIds` is non-empty, only those rows are
+ * exported; otherwise every loaded (current-page) row is included.
+ *
+ * Columns may declare `exportValue(value, row)` to override the stringified raw
+ * cell value (e.g. relation columns that store JSON in the cell).
+ */
+export function extractExportRows(
+  store: CellStore,
+  cols: ColumnDef[],
+  selectedRowIds: Set<string>,
+  selectionColumnName: string,
+): ExtractedTable {
+  const headers = cols.map((c) => c.title ?? c.data);
+  const rows: string[][] = [];
+  const rowCount = store.getRowCount();
+  const exportSelectionOnly = selectedRowIds.size > 0;
+
+  for (let r = 0; r < rowCount; r++) {
+    const rowData = store.getRowData(r);
+    if (!rowData) continue;
+    if (exportSelectionOnly) {
+      const id = String(rowData[selectionColumnName] ?? '');
+      if (!id || !selectedRowIds.has(id)) continue;
+    }
+    rows.push(
+      cols.map((col, c) => {
+        const raw = store.getCellValue(r, c);
+        if (col.exportValue) return cellToString(col.exportValue(raw, rowData));
+        return cellToString(raw);
+      }),
+    );
+  }
+
+  return { headers, rows };
+}
+
+/**
+ * Build an export table directly from plain row objects (not the cell store).
+ * Used for the whole-table export, where rows are re-fetched from the server
+ * across all pages and every column is included regardless of perspective
+ * visibility. Reads `row[col.data]`, applying `col.exportValue` when present.
+ */
+export function extractExportRowsFromData(
+  data: any[],
+  cols: ColumnDef[],
+): ExtractedTable {
+  const headers = cols.map((c) => c.title ?? c.data);
+  const rows = data.map((row) =>
+    cols.map((col) => {
+      const raw = row?.[col.data];
+      if (col.exportValue) return cellToString(col.exportValue(raw, row));
+      // Objects/arrays have no useful default string form — leave blank rather
+      // than emit "[object Object]". Columns that store them must use exportValue.
+      if (raw !== null && typeof raw === 'object') return '';
+      return cellToString(raw);
+    }),
+  );
+  return { headers, rows };
+}
+
+function escapeCsvField(field: string): string {
+  // RFC 4180: quote fields containing comma, quote, CR or LF; double interior quotes.
+  if (/[",\r\n]/.test(field)) {
+    return `"${field.replace(/"/g, '""')}"`;
+  }
+  return field;
+}
+
+/**
+ * Serialize an extracted table to a CSV string. Prepends a UTF-8 BOM so Excel
+ * opens it with the correct encoding (Polish characters survive).
+ */
+export function toCsv({ headers, rows }: ExtractedTable): string {
+  const lines = [headers, ...rows].map((row) => row.map(escapeCsvField).join(','));
+  return '' + lines.join('\r\n');
+}
+
+/**
+ * Serialize an extracted table to an .xlsx Blob via SheetJS. The `xlsx`
+ * dependency is imported lazily by the caller and passed in, so CSV-only paths
+ * never load it.
+ */
+export function toXlsxBlob(
+  table: ExtractedTable,
+  XLSX: typeof import('xlsx'),
+): Blob {
+  const aoa = [table.headers, ...table.rows];
+  const sheet = XLSX.utils.aoa_to_sheet(aoa);
+  const book = XLSX.utils.book_new();
+  XLSX.utils.book_append_sheet(book, sheet, 'Export');
+  const out = XLSX.write(book, { type: 'array', bookType: 'xlsx' }) as ArrayBuffer;
+  return new Blob([out], {
+    type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  });
+}
+
+/** Slugify a table/file name into a safe file-name stem. */
+export function slugifyFileName(name: string): string {
+  const slug = name
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return slug || 'export';
+}
+
+/** Trigger a browser download of `blob` as `filename` (no-op when no document). */
+export function downloadBlob(blob: Blob, filename: string): void {
+  if (typeof document === 'undefined') return;
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement('a');
+  a.href = url;
+  a.download = filename;
+  document.body.appendChild(a);
+  a.click();
+  a.remove();
+  // Revoke on the next tick so the click has consumed the URL.
+  setTimeout(() => URL.revokeObjectURL(url), 0);
+}

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

@@ -0,0 +1,187 @@
+// utils/fillGeometry.ts
+//
+// Where a fill drag is pointing. PURE: no DOM, no store, no React.
+//
+// This is the single most important testability move in the rectangle-fill
+// work: axis lock and back-drag are the two rules users notice, and neither can
+// be proven inside a `mousemove` callback. Both live here instead, so a jest
+// test can assert "a diagonal drag picks the dominant axis" without a browser.
+//
+// Excel's fill is SINGLE-AXIS. The axis is chosen by the larger overshoot from
+// the source block's edge; the other axis is clamped to the source's extent.
+// Dragging back INSIDE the source clears the part you dragged back over.
+
+import type { FillAxis, FillPreview, SelectionBounds } from '../types/index';
+import type { FillMode } from './fillPatterns';
+import { invertFillMode } from './fillPatterns';
+
+export interface FillPointer {
+  row: number;
+  col: number;
+}
+
+export interface ComputeFillPreviewOptions {
+  /** `Ctrl`/`Alt` held. Inverts the pattern's default copy <-> series. */
+  modifier: boolean;
+  /** The mode the detected pattern would use with no modifier held. */
+  defaultMode: FillMode;
+}
+
+/** Inclusive cell count of a rectangle. */
+export function rectSize(bounds: SelectionBounds): number {
+  return (
+    (bounds.endRow - bounds.startRow + 1) * (bounds.endCol - bounds.startCol + 1)
+  );
+}
+
+export function isCellInRect(row: number, col: number, bounds: SelectionBounds): boolean {
+  return (
+    row >= bounds.startRow &&
+    row <= bounds.endRow &&
+    col >= bounds.startCol &&
+    col <= bounds.endCol
+  );
+}
+
+/** How far outside `[lo, hi]` a coordinate sits. 0 when inside. */
+function overshoot(value: number, lo: number, hi: number): number {
+  if (value < lo) return lo - value;
+  if (value > hi) return value - hi;
+  return 0;
+}
+
+/**
+ * The whole fill gesture, as data.
+ *
+ * Extending (pointer outside the source):
+ *   axis      = the larger overshoot wins; a tie goes VERTICAL, because a fill
+ *               drag is overwhelmingly a "drag down" and a 1px sideways wobble
+ *               must not flip it;
+ *   backwards = the pointer is above / left of the source;
+ *   bounds    = source stretched along `axis` to the pointer, the other axis
+ *               clamped to the source's own extent.
+ *
+ * Clearing (pointer inside the source): Excel empties everything past the
+ * pointer along the shrink axis. A 1-row source has `shrinkRows === 0` and falls
+ * to the horizontal branch on its own — there is no special case for it.
+ */
+export function computeFillPreview(
+  source: SelectionBounds,
+  pointer: FillPointer,
+  opts: ComputeFillPreviewOptions,
+): FillPreview {
+  const mode = opts.modifier ? invertFillMode(opts.defaultMode) : opts.defaultMode;
+
+  const dRow = overshoot(pointer.row, source.startRow, source.endRow);
+  const dCol = overshoot(pointer.col, source.startCol, source.endCol);
+
+  if (dRow > 0 || dCol > 0) {
+    const axis: FillAxis = dRow >= dCol ? 'vertical' : 'horizontal';
+    const backwards =
+      axis === 'vertical' ? pointer.row < source.startRow : pointer.col < source.startCol;
+    const bounds: SelectionBounds =
+      axis === 'vertical'
+        ? {
+            startRow: Math.min(source.startRow, pointer.row),
+            endRow: Math.max(source.endRow, pointer.row),
+            startCol: source.startCol,
+            endCol: source.endCol,
+          }
+        : {
+            startRow: source.startRow,
+            endRow: source.endRow,
+            startCol: Math.min(source.startCol, pointer.col),
+            endCol: Math.max(source.endCol, pointer.col),
+          };
+    return { source, bounds, axis, backwards, clearing: false, cleared: null, mode };
+  }
+
+  // Pointer is inside the source → back-drag. Everything BEYOND the pointer
+  // along the dominant shrink axis is about to be emptied.
+  const shrinkRows = source.endRow - pointer.row;
+  const shrinkCols = source.endCol - pointer.col;
+  const axis: FillAxis = shrinkRows >= shrinkCols ? 'vertical' : 'horizontal';
+  const cleared: SelectionBounds =
+    axis === 'vertical'
+      ? { ...source, startRow: pointer.row + 1 }
+      : { ...source, startCol: pointer.col + 1 };
+  const clearing =
+    axis === 'vertical' ? cleared.startRow <= cleared.endRow : cleared.startCol <= cleared.endCol;
+
+  return {
+    source,
+    bounds: source,
+    axis,
+    backwards: false,
+    clearing,
+    cleared: clearing ? cleared : null,
+    mode,
+  };
+}
+
+/**
+ * The cells a fill will WRITE, grouped into the independent series lines Excel
+ * fills them with.
+ *
+ * Vertical fill: one line per source COLUMN, seeded by that column's rows in
+ * row order. Horizontal fill: one line per source ROW, seeded by that row's
+ * columns in column order. That is the rule that makes a multi-column drag
+ * continue each column's own series instead of smearing one series sideways.
+ *
+ * Every line's `targets` are ordered ADJACENT-TO-SOURCE FIRST, which is exactly
+ * the order `generateFill` returns values in — so the caller zips the two
+ * without ever reversing an array.
+ */
+export interface FillLine {
+  /** Cells of the SOURCE block for this line, in fill order. */
+  seedCells: Array<{ row: number; col: number }>;
+  /** Cells to write, nearest the source first. */
+  targets: Array<{ row: number; col: number }>;
+  /** The column whose `type` / `source` / `fillSeries` governs this line. */
+  seedCol: number;
+}
+
+export function buildFillLines(preview: FillPreview): FillLine[] {
+  const { source, bounds, axis, backwards } = preview;
+  const lines: FillLine[] = [];
+
+  if (axis === 'vertical') {
+    for (let col = source.startCol; col <= source.endCol; col++) {
+      const seedCells: Array<{ row: number; col: number }> = [];
+      for (let row = source.startRow; row <= source.endRow; row++) seedCells.push({ row, col });
+      const targets: Array<{ row: number; col: number }> = [];
+      if (backwards) {
+        for (let row = source.startRow - 1; row >= bounds.startRow; row--) targets.push({ row, col });
+      } else {
+        for (let row = source.endRow + 1; row <= bounds.endRow; row++) targets.push({ row, col });
+      }
+      lines.push({ seedCells, targets, seedCol: col });
+    }
+    return lines;
+  }
+
+  for (let row = source.startRow; row <= source.endRow; row++) {
+    const seedCells: Array<{ row: number; col: number }> = [];
+    for (let col = source.startCol; col <= source.endCol; col++) seedCells.push({ row, col });
+    const targets: Array<{ row: number; col: number }> = [];
+    if (backwards) {
+      for (let col = source.startCol - 1; col >= bounds.startCol; col--) targets.push({ row, col });
+    } else {
+      for (let col = source.endCol + 1; col <= bounds.endCol; col++) targets.push({ row, col });
+    }
+    // Horizontal fill crosses columns, so no single column governs the line.
+    // The SEED's own column supplies the pattern rules; the TARGET column
+    // decides whether the value is acceptable (see coerceCellValue).
+    lines.push({ seedCells, targets, seedCol: source.startCol });
+  }
+  return lines;
+}
+
+/** Every cell of a rectangle, row-major. Shared by the preview repaint and the commit. */
+export function cellsInRect(bounds: SelectionBounds): Array<{ row: number; col: number }> {
+  const cells: Array<{ row: number; col: number }> = [];
+  for (let row = bounds.startRow; row <= bounds.endRow; row++) {
+    for (let col = bounds.startCol; col <= bounds.endCol; col++) cells.push({ row, col });
+  }
+  return cells;
+}