@freighttech/ui 0.13.18

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

@@ -0,0 +1,108 @@
+import type { ColumnDef } from '../types/index';
+
+/**
+ * Badge auto-fit — the MODEL half.
+ *
+ * Status/type pills must never be clipped (unlike text, which ellipses), so a
+ * badge column grows to fit its widest pill. The measurement itself has to
+ * touch the DOM — a consumer's custom renderer can emit any label it likes, so
+ * there is no string in the model to measure — but the *decision* must not.
+ *
+ * Why this module exists (anchor Defect 6 / range-operation contract rule 6):
+ * the original effect compared `badge.scrollWidth` against `td.clientWidth` and
+ * wrote `store.setColumnWidth` for whatever happened to be mounted. Two things
+ * are wrong with that under column virtualization:
+ *
+ *  1. It is *geometry-coupled*: the answer depended on how wide the cell
+ *     currently is, so widening a column could change what the next pass
+ *     decided — a column widening as it scrolls into view shifts every later
+ *     offset, changes the mounted window, and mounts another badge column.
+ *     That is a scroll-coupled layout feedback loop, and it visibly jitters.
+ *  2. It was *index-keyed and mount-scoped*: a column that was not mounted had
+ *     no fit at all, and a perspective reorder moved a fitted width onto a
+ *     different column.
+ *
+ * The fix, in two halves:
+ *
+ *  - Measurement is INTRINSIC and one-shot per pill: `badge.scrollWidth` is the
+ *    pill's own content width, which does not depend on the cell's width, the
+ *    scroll position or the mounted window. It is never re-derived from the
+ *    column's current width.
+ *  - The result is cached by the STABLE `col.data` key (never the index, same
+ *    rule as `frozenColumns` and width persistence) and re-applied to whatever
+ *    index that key currently occupies. So `store.getColumnWidth(i)` answers
+ *    for every `i`, mounted or not, and survives reorder/hide/show.
+ *
+ * The cache is grow-only, which makes the whole thing idempotent: a column that
+ * is already wide enough produces no write, so no write can trigger another
+ * measurement pass.
+ */
+
+/** Hard cap so one freak value cannot blow out the layout. */
+export const BADGE_FIT_MAX_WIDTH = 360;
+
+/**
+ * Horizontal padding to reserve around a pill. A commented cell keeps 28px on
+ * the right for the comment indicator; without counting that the column fits
+ * the pill alone and the pill ends up sitting under the icon.
+ */
+export const BADGE_FIT_PADDING = 16;
+export const BADGE_FIT_PADDING_WITH_COMMENT = 36;
+
+/**
+ * Stored width that shows a pill of `contentWidth` in full: intrinsic content
+ * + padding + a 2px buffer, capped. Depends on nothing but the pill itself —
+ * no cell width, no scroll offset, no mounted window.
+ */
+export function badgeFitWidth(contentWidth: number, hasComment: boolean): number {
+  const pad = hasComment ? BADGE_FIT_PADDING_WITH_COMMENT : BADGE_FIT_PADDING;
+  return Math.min(Math.ceil(contentWidth) + pad + 2, BADGE_FIT_MAX_WIDTH);
+}
+
+/**
+ * Record a measurement against the stable column key, grow-only.
+ * Returns true when the cache actually changed.
+ */
+export function recordBadgeFit(
+  cache: Map<string, number>,
+  columnKey: string,
+  width: number,
+): boolean {
+  if (!Number.isFinite(width) || width <= 0) return false;
+  const current = cache.get(columnKey);
+  if (current != null && current >= width) return false;
+  cache.set(columnKey, width);
+  return true;
+}
+
+export interface BadgeWidthWrite {
+  /** Index into the CURRENT view-order column array. */
+  col: number;
+  width: number;
+}
+
+/**
+ * Turn the key-keyed cache into the set of width writes to apply, for the
+ * column order as it stands now. Every cached key is considered — including
+ * columns that are not mounted — so a fitted width follows its column through
+ * a reorder and is already correct when the column scrolls back into view.
+ *
+ * Grow-only, and never fights a width the user set by hand.
+ */
+export function planBadgeWidths(
+  cache: Map<string, number>,
+  cols: ColumnDef[],
+  getColumnWidth: (col: number) => number,
+  isUserResized: (col: number) => boolean,
+): BadgeWidthWrite[] {
+  if (cache.size === 0) return [];
+  const writes: BadgeWidthWrite[] = [];
+  for (let col = 0; col < cols.length; col++) {
+    const fit = cache.get(cols[col].data);
+    if (fit == null) continue;
+    if (isUserResized(col)) continue;
+    if (getColumnWidth(col) >= fit) continue;
+    writes.push({ col, width: fit });
+  }
+  return writes;
+}

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

@@ -0,0 +1,294 @@
+// utils/clipboard.ts
+//
+// Clipboard payload <-> rectangular grid. PURE: no `ClipboardEvent`, no store,
+// no React. The caller reads `text/html` and `text/plain` off the event and
+// hands the strings in; everything below is testable without a browser.
+//
+// Why HTML first: Excel, Google Sheets and LibreOffice all put a real
+// `text/html` `<table>` on the clipboard AND a `text/plain` TSV. The HTML
+// preserves cell boundaries unambiguously — a cell containing a tab or a
+// newline is still one `<td>`, where the TSV has to quote it and hope the
+// reader unquotes the same way. TSV stays as the fallback because plenty of
+// sources (a text editor, a terminal, our own copy handler) emit only that.
+
+/** Which clipboard flavour produced the grid. `'empty'` means nothing usable. */
+export type ClipboardGridSource = 'html' | 'text' | 'empty';
+
+export interface ClipboardGrid {
+  /** Rectangular: every row has `colCount` entries, short rows padded with ''. */
+  rows: string[][];
+  rowCount: number;
+  colCount: number;
+  source: ClipboardGridSource;
+}
+
+export interface ClipboardPayload {
+  html?: string | null;
+  text?: string | null;
+}
+
+const EMPTY_GRID: ClipboardGrid = { rows: [], rowCount: 0, colCount: 0, source: 'empty' };
+
+// ============================================
+// TSV
+// ============================================
+
+/**
+ * Parse a TSV block into a rectangular grid.
+ *
+ * Handles the three line endings (`\r\n`, `\n`, `\r`), one trailing newline
+ * (Excel appends one), and RFC4180-style quoting — which Excel uses on the
+ * `text/plain` flavour whenever a cell contains a tab, a newline or a quote:
+ * the cell is wrapped in `"` and internal `"` are doubled.
+ */
+export function parseTsv(text: string): string[][] {
+  if (!text) return [];
+
+  const rows: string[][] = [];
+  let row: string[] = [];
+  let field = '';
+  let inQuotes = false;
+  let fieldWasQuoted = false;
+
+  const endField = () => {
+    row.push(field);
+    field = '';
+    fieldWasQuoted = false;
+  };
+  const endRow = () => {
+    endField();
+    rows.push(row);
+    row = [];
+  };
+
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+
+    if (inQuotes) {
+      if (ch === '"') {
+        if (text[i + 1] === '"') {
+          field += '"';
+          i++;
+        } else {
+          inQuotes = false;
+        }
+      } else {
+        field += ch;
+      }
+      continue;
+    }
+
+    if (ch === '"' && field === '' && !fieldWasQuoted) {
+      inQuotes = true;
+      fieldWasQuoted = true;
+      continue;
+    }
+    if (ch === '\t') {
+      endField();
+      continue;
+    }
+    if (ch === '\r') {
+      // `\r\n` counts once; a lone `\r` is an old-Mac line ending.
+      if (text[i + 1] === '\n') i++;
+      endRow();
+      continue;
+    }
+    if (ch === '\n') {
+      endRow();
+      continue;
+    }
+    field += ch;
+  }
+
+  // Anything still buffered is the last row; a payload ending in a newline has
+  // nothing buffered and must NOT gain a phantom empty row.
+  if (field !== '' || fieldWasQuoted || row.length > 0) endRow();
+
+  return padGrid(rows);
+}
+
+/**
+ * Serialise a grid to TSV, quoting exactly the cells that need it. Round-trips
+ * through `parseTsv`.
+ */
+export function serialiseTsv(rows: readonly (readonly unknown[])[]): string {
+  return rows
+    .map((row) =>
+      row
+        .map((cell) => {
+          const value = cell === null || cell === undefined ? '' : String(cell);
+          if (/[\t\r\n"]/.test(value)) return `"${value.replace(/"/g, '""')}"`;
+          return value;
+        })
+        .join('\t'),
+    )
+    .join('\n');
+}
+
+/**
+ * Lay a flat list of selected cells back out as a rectangle and serialise it.
+ *
+ * THE serializer for everything that puts the grid's own selection on the
+ * clipboard — `Ctrl+C`, the context-menu Copy and `Ctrl+X`. Cut must place
+ * byte-identical text to Copy (a user who cuts, panics and pastes back has to
+ * get exactly what was there), which is only guaranteed while there is one of
+ * these.
+ *
+ * `cells` is `store.getCellsInSelection()`: already index-addressed and already
+ * tolerant of unmounted columns. Missing cells stay empty rather than shifting
+ * their neighbours left.
+ */
+export function selectionToTsv(
+  cells: readonly { row: number; col: number; value: unknown }[],
+  bounds: { startRow: number; endRow: number; startCol: number; endCol: number },
+): string {
+  const rowCount = bounds.endRow - bounds.startRow + 1;
+  const colCount = bounds.endCol - bounds.startCol + 1;
+  if (rowCount <= 0 || colCount <= 0) return '';
+  const grid: unknown[][] = Array.from({ length: rowCount }, () =>
+    Array.from({ length: colCount }, () => ''),
+  );
+  for (const cell of cells) {
+    const r = cell.row - bounds.startRow;
+    const c = cell.col - bounds.startCol;
+    if (r < 0 || r >= rowCount || c < 0 || c >= colCount) continue;
+    grid[r][c] = cell.value ?? '';
+  }
+  return serialiseTsv(grid);
+}
+
+// ============================================
+// HTML TABLE
+// ============================================
+
+/**
+ * Parse the `text/html` flavour Excel/Sheets put on the clipboard.
+ *
+ * Returns `null` — never an empty grid — when there is no usable table, so the
+ * caller can fall through to TSV rather than pasting nothing.
+ *
+ * Merged cells: a `colspan`/`rowspan` cell contributes its text to its
+ * top-left position and empty strings to the rest of the span, which is what
+ * Excel itself pastes out of a merged block.
+ */
+export function parseClipboardHtml(html: string | null | undefined): string[][] | null {
+  if (!html || !html.trim()) return null;
+  // Server-side rendering and non-DOM test environments have no parser; the
+  // TSV fallback covers them.
+  if (typeof DOMParser === 'undefined') return null;
+
+  let doc: Document;
+  try {
+    doc = new DOMParser().parseFromString(html, 'text/html');
+  } catch {
+    return null;
+  }
+
+  const table = doc.querySelector('table');
+  if (!table) return null;
+
+  const trs = Array.from(
+    table.querySelectorAll(':scope > tr, :scope > thead > tr, :scope > tbody > tr, :scope > tfoot > tr'),
+  );
+  if (trs.length === 0) return null;
+
+  const grid: string[][] = [];
+  // Cells claimed by a rowspan from an earlier row, keyed `row:col`.
+  const spanned = new Map<string, string>();
+
+  trs.forEach((tr, r) => {
+    const out: string[] = grid[r] ?? (grid[r] = []);
+    const cells = Array.from(tr.querySelectorAll(':scope > td, :scope > th'));
+    let c = 0;
+    for (const cell of cells) {
+      while (spanned.has(`${r}:${c}`)) {
+        out[c] = spanned.get(`${r}:${c}`) ?? '';
+        spanned.delete(`${r}:${c}`);
+        c++;
+      }
+      const text = cellText(cell);
+      const colSpan = spanCount(cell.getAttribute('colspan'));
+      const rowSpan = spanCount(cell.getAttribute('rowspan'));
+      for (let dc = 0; dc < colSpan; dc++) {
+        out[c + dc] = dc === 0 ? text : '';
+        for (let dr = 1; dr < rowSpan; dr++) {
+          spanned.set(`${r + dr}:${c + dc}`, '');
+        }
+      }
+      c += colSpan;
+    }
+    // Trailing cells claimed by a rowspan with no `td` after them.
+    while (spanned.has(`${r}:${c}`)) {
+      out[c] = spanned.get(`${r}:${c}`) ?? '';
+      spanned.delete(`${r}:${c}`);
+      c++;
+    }
+  });
+
+  const filled = grid.map((row) => Array.from(row, (cell) => cell ?? ''));
+  if (filled.length === 0) return null;
+  return padGrid(filled);
+}
+
+function spanCount(raw: string | null): number {
+  const n = raw ? parseInt(raw, 10) : 1;
+  if (!Number.isFinite(n) || n < 1) return 1;
+  // Excel writes real spans; anything absurd is a malformed payload, and
+  // allocating for it would be a denial-of-service on a paste.
+  return Math.min(n, 1000);
+}
+
+/**
+ * A cell's text as a spreadsheet sees it: `<br>` becomes a newline, non-breaking
+ * spaces become ordinary ones (Excel fills empty cells with `&nbsp;`), and the
+ * source's pretty-printing whitespace is trimmed off the ends.
+ */
+function cellText(cell: Element): string {
+  const clone = cell.cloneNode(true) as Element;
+  clone.querySelectorAll('br').forEach((br) => {
+    br.replaceWith(clone.ownerDocument!.createTextNode('\n'));
+  });
+  return (clone.textContent ?? '')
+    .replace(/[\u00a0\u202f]/g, ' ')
+    .replace(/^[ \t\r\n]+|[ \t\r\n]+$/g, '');
+}
+
+// ============================================
+// ENTRY POINT
+// ============================================
+
+/**
+ * Turn a clipboard payload into a rectangular grid: HTML table first, TSV
+ * fallback, `source: 'empty'` when neither yields anything.
+ *
+ * A grid of exactly one empty cell counts as empty — pasting it would clear a
+ * cell the user did not ask to clear.
+ */
+export function parseClipboardGrid(payload: ClipboardPayload): ClipboardGrid {
+  const fromHtml = parseClipboardHtml(payload.html);
+  if (fromHtml && !isBlankGrid(fromHtml)) return toGrid(fromHtml, 'html');
+
+  const fromText = payload.text ? parseTsv(payload.text) : [];
+  if (fromText.length > 0 && !isBlankGrid(fromText)) return toGrid(fromText, 'text');
+
+  return EMPTY_GRID;
+}
+
+function toGrid(rows: string[][], source: ClipboardGridSource): ClipboardGrid {
+  return { rows, rowCount: rows.length, colCount: rows[0]?.length ?? 0, source };
+}
+
+function isBlankGrid(rows: string[][]): boolean {
+  return rows.length === 0 || rows.every((row) => row.every((cell) => cell === ''));
+}
+
+/** Pad every row out to the widest, so callers can index without holes. */
+export function padGrid(rows: string[][]): string[][] {
+  const width = rows.reduce((max, row) => Math.max(max, row.length), 0);
+  return rows.map((row) => {
+    if (row.length === width) return row;
+    const padded = row.slice();
+    while (padded.length < width) padded.push('');
+    return padded;
+  });
+}

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

@@ -0,0 +1,96 @@
+// utils/coerceCellValue.ts
+//
+// THE coercion table: "can this raw value become this column's type, and if so
+// what exactly gets stored?"
+//
+// It used to be `parseValueByType`, a private function inside
+// `handlers/index.ts` reachable only from the inline-edit path. Paste, fill,
+// find-&-replace and import all need the same answer, and a second table is how
+// a pasted date ends up stored differently from a typed one. So it moved here,
+// and it now RETURNS A VERDICT rather than a value: a multi-cell write must be
+// able to say "3 cells were not numbers" instead of silently blanking them.
+//
+// Pure: no store, no React, no DOM.
+
+import type { ColumnDef } from '../types/index';
+import type { CoerceResult } from '../handlers/cellWrites';
+
+/** Empty in the "user cleared the cell" sense. Clearing is always allowed. */
+function isEmptyInput(value: unknown): boolean {
+  return value === '' || value === null || value === undefined;
+}
+
+/** `col.source` entries may be plain scalars or `{ value | id }` objects. */
+function sourceValues(col: ColumnDef): string[] | null {
+  const src = col.source;
+  if (!Array.isArray(src) || src.length === 0) return null;
+  return src.map((o) =>
+    o && typeof o === 'object'
+      ? String((o as Record<string, unknown>).value ?? (o as Record<string, unknown>).id ?? '')
+      : String(o),
+  );
+}
+
+/**
+ * Coerce one raw value for one column.
+ *
+ * Structurally identical to `CellValueCoercer`, so it can be handed straight to
+ * `applyCellWrites({ coerce: coerceCellValue, ... })`.
+ *
+ * Verdicts:
+ *  - `readOnly`      the column refuses writes outright;
+ *  - `notCoercible`  a non-empty value that cannot become the column's type
+ *                    (`'abc'` into a numeric column, `'32/13'` into a date);
+ *  - `notInSource`   a `dropdown` / `multiselect` value outside `col.source`.
+ *
+ * Emptying is never a rejection here — `ColumnDef.required` is enforced one
+ * level up, in `applyCellWrites`, where the row is known.
+ */
+export function coerceCellValue(value: unknown, column: ColumnDef): CoerceResult {
+  if (column.readOnly) return { ok: false, reason: 'readOnly' };
+  if (!column.type) return { ok: true, value };
+  if (isEmptyInput(value)) return { ok: true, value: null };
+
+  switch (column.type) {
+    case 'numeric': {
+      // Accept the Polish decimal comma users actually type; `parseFloat` alone
+      // reads "1,5" as 1.
+      const raw = typeof value === 'number' ? value : String(value).trim().replace(',', '.');
+      const parsed = typeof raw === 'number' ? raw : parseFloat(raw);
+      if (!Number.isFinite(parsed)) return { ok: false, reason: 'notCoercible' };
+      return { ok: true, value: parsed };
+    }
+
+    case 'date': {
+      const date = value instanceof Date ? value : new Date(value as string);
+      if (Number.isNaN(date.getTime())) return { ok: false, reason: 'notCoercible' };
+      // ISO date string (YYYY-MM-DD) so a Date round-tripped through a string
+      // stays the same day. LOCAL parts, not UTC: `toISOString()` would shift a
+      // Warsaw midnight back to the previous day.
+      const year = date.getFullYear();
+      const month = String(date.getMonth() + 1).padStart(2, '0');
+      const day = String(date.getDate()).padStart(2, '0');
+      return { ok: true, value: `${year}-${month}-${day}` };
+    }
+
+    case 'boolean': {
+      if (typeof value === 'boolean') return { ok: true, value };
+      const s = String(value).trim().toLowerCase();
+      if (s === 'true' || s === '1' || s === 'yes' || s === 'tak') return { ok: true, value: true };
+      if (s === 'false' || s === '0' || s === 'no' || s === 'nie') return { ok: true, value: false };
+      return { ok: false, reason: 'notCoercible' };
+    }
+
+    case 'dropdown':
+    case 'multiselect': {
+      const allowed = sourceValues(column);
+      if (!allowed) return { ok: true, value };
+      const wanted = Array.isArray(value) ? value.map(String) : [String(value)];
+      if (wanted.some((v) => !allowed.includes(v))) return { ok: false, reason: 'notInSource' };
+      return { ok: true, value };
+    }
+
+    default:
+      return { ok: true, value };
+  }
+}

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

@@ -0,0 +1,87 @@
+import type { ColumnDef } from '../types/index';
+import type { AnnotationMap } from '../hooks/useAnnotations';
+
+/**
+ * Colour-block adjacency — the MODEL replacement for anchor Defect 7.
+ *
+ * A 2-D block of same-coloured annotated cells must read as ONE shape: rounded
+ * only on its outer corners, with the inter-row gap painted through. CSS cannot
+ * see across `<tr>`s, so each cell is told about its four neighbours via
+ * `data-cb-{above,below,left,right}`.
+ *
+ * The old implementation discovered those neighbours by running
+ * `querySelectorAll('td.hot-cell[...][class*="cell-color-"]')` over the grid on
+ * every scroll event and comparing `data-row` / `data-col`. That is wrong twice:
+ *
+ *  1. It can only see MOUNTED cells. The row virtualizer already made the top
+ *    and bottom rows of the window falsely report "no neighbour"; column
+ *    virtualization adds the same lie on the left/right edges, mid-block, where
+ *    users see it — a painted gap and a rounded corner in the middle of a
+ *    colour run, moving as you scroll.
+ *  2. It ran a full-grid DOM query inside the scroll handler, at the moment the
+ *    browser is already committing a frame.
+ *
+ * Throttling would fix neither. Adjacency is a fact about the DATA, so it is
+ * computed here from the annotation map, the row order and the column order,
+ * and passed down as props (range-operation contract rule 7: an unmounted
+ * neighbour is still a neighbour).
+ *
+ * Vertical adjacency is by DATA row index (`row ± 1`), which is what the DOM
+ * scan compared too — a group header rendered between two data rows does not
+ * break a colour block.
+ */
+
+export interface ColorAdjacency {
+  above: boolean;
+  below: boolean;
+  left: boolean;
+  right: boolean;
+}
+
+export const NO_COLOR_ADJACENCY: ColorAdjacency = {
+  above: false,
+  below: false,
+  left: false,
+  right: false,
+};
+
+/**
+ * @param color       This cell's annotation colour (`null`/`undefined` = uncoloured).
+ * @param row         Data row index.
+ * @param col         Index into the FULL view-order column array.
+ * @param cols        The full view-order column array — never a virtualization window.
+ * @param annotations Map keyed `"<entityType>:<rowId>:<columnKey>"`.
+ * @param keyAt       Builds that key for a (data row index, column). Returns
+ *                    `null` when the cell has no annotation target — a row that
+ *                    does not exist, or a column outside the scope. Supplied by
+ *                    the grid so adjacency uses the SAME target resolver the
+ *                    fetch and the dialog use (workshop B8a).
+ */
+export function computeColorAdjacency(
+  color: string | null | undefined,
+  row: number,
+  col: number,
+  cols: ColumnDef[],
+  annotations: AnnotationMap | undefined,
+  keyAt: (row: number, column: ColumnDef) => string | null,
+): ColorAdjacency {
+  // An uncoloured cell has no block to join, so it never needs the four
+  // attributes. Bailing here keeps the whole thing free for the overwhelming
+  // majority of cells.
+  if (!color || !annotations || annotations.size === 0) return NO_COLOR_ADJACENCY;
+
+  const sameColorAt = (r: number, c: number): boolean => {
+    const column = cols[c];
+    if (!column) return false;
+    const key = keyAt(r, column);
+    if (key == null) return false;
+    return annotations.get(key)?.color === color;
+  };
+
+  return {
+    above: sameColorAt(row - 1, col),
+    below: sameColorAt(row + 1, col),
+    left: sameColorAt(row, col - 1),
+    right: sameColorAt(row, col + 1),
+  };
+}

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

@@ -0,0 +1,93 @@
+/**
+ * FILL THE CONTAINER — the arithmetic behind "a narrow table has no dead strip
+ * to its right".
+ *
+ * Two regimes, and only two:
+ *
+ *   declared total  <  container → EXPAND the flexible columns until the row
+ *                                  ends exactly at the container's right edge.
+ *   declared total  >= container → nothing to do; the grid scrolls horizontally
+ *                                  at its declared widths.
+ *
+ * WHY THIS IS ARITHMETIC AND NOT `width: 100%`.
+ *
+ * Handing the row to the layout engine (`table { width: 100% }` + `flex-grow`)
+ * fills the strip, but a stretched column's PAINTED width stops being its
+ * DECLARED width — and column virtualization is built on declared widths: the
+ * spacer that stands in for a run of unmounted columns has to be exactly as
+ * wide as they would have been, or every mounted column lands at the wrong x.
+ * That is why stretching used to force virtualization off, which made "fills
+ * the width" and "virtualized" mutually exclusive on the widest lists — the
+ * precise complaint this module answers.
+ *
+ * Resolving the surplus to PIXELS keeps every column's declared width honest,
+ * so the spacers stay correct and both properties hold at once.
+ *
+ * WHAT IS RIGID (never touched):
+ *  • pinned / frozen columns and the sticky checkbox + Actions columns — their
+ *    widths are load-bearing for `position: sticky` offsets;
+ *  • any column the user has resized by hand. Their number is their answer;
+ *    growing it would silently overrule them.
+ */
+
+export interface ColumnFillInput {
+  /** DECLARED width of every column, in view order. Never a painted width. */
+  widths: readonly number[];
+  /** Indices that must keep their declared width exactly. */
+  rigid: ReadonlySet<number>;
+  /** Row furniture outside `widths`: the row-header gutter + Actions column. */
+  furnitureWidth: number;
+  /** The scroll container's inner width (`clientWidth`). */
+  containerWidth: number;
+}
+
+/**
+ * Surplus pixels per column index. Only positive entries appear; an empty map
+ * means "declared widths already fill (or overflow) the container".
+ */
+export function computeColumnFill({
+  widths,
+  rigid,
+  furnitureWidth,
+  containerWidth,
+}: ColumnFillInput): Map<number, number> {
+  const result = new Map<number, number>();
+  if (!(containerWidth > 0) || widths.length === 0) return result;
+
+  let declaredTotal = furnitureWidth;
+  for (const w of widths) declaredTotal += w;
+
+  // Floor the container: a fractional target would leave a sub-pixel sliver of
+  // dead strip or provoke a 1px horizontal scrollbar, and both read as a bug.
+  const surplus = Math.floor(containerWidth) - declaredTotal;
+  if (surplus < 1) return result;
+
+  const flexible: number[] = [];
+  let flexibleTotal = 0;
+  for (let i = 0; i < widths.length; i++) {
+    if (rigid.has(i)) continue;
+    flexible.push(i);
+    flexibleTotal += widths[i];
+  }
+  // Every column is pinned or hand-sized: there is nothing we are allowed to
+  // grow, so the strip stays. Deliberate — the alternative is overruling the
+  // user's own widths to win back some pixels.
+  if (flexible.length === 0 || flexibleTotal <= 0) return result;
+
+  // Proportional to declared width, so a wide description column takes more of
+  // the surplus than a narrow date one and the row keeps its rhythm.
+  let assigned = 0;
+  for (let n = 0; n < flexible.length - 1; n++) {
+    const idx = flexible[n];
+    const extra = Math.floor((surplus * widths[idx]) / flexibleTotal);
+    if (extra > 0) result.set(idx, extra);
+    assigned += extra;
+  }
+  // The last flexible column absorbs the rounding remainder, so the row lands
+  // on the container's edge to the pixel rather than 1–3px short of it.
+  const last = flexible[flexible.length - 1];
+  const remainder = surplus - assigned;
+  if (remainder > 0) result.set(last, remainder);
+
+  return result;
+}