@freighttech/ui 0.13.18

package/src/backend/document-viewer/RegionOverlay.tsx

@@ -0,0 +1,150 @@
+'use client'
+
+/**
+ * Rectangles drawn ON a rendered page — "this value was read HERE".
+ *
+ * PURE GEOMETRY. It takes normalised boxes, the size the page is currently
+ * rendered at, and which one is active. It knows nothing about PDFs, documents
+ * or provenance, so it works over an `<img>` the day somebody wires it up.
+ *
+ * ═══════════════════════════════════════════════════════════════════════════
+ * THE RULES ENCODED HERE WERE EACH PAID FOR WITH A SHIPPED DEFECT
+ * ═══════════════════════════════════════════════════════════════════════════
+ *
+ * **Frame the text, do not clip it.** 3px horizontal and 2px vertical padding.
+ * A box drawn at exactly the measured extent sits on the glyphs and reads as a
+ * strikethrough.
+ *
+ * **The fill is real alpha, never `mix-blend-mode`.** `multiply` is the nicer
+ * mechanism and cannot be used: the box carries an entrance animation, a
+ * transform creates a stacking context, and the blend then isolates from the
+ * page behind it and degrades to a flat opaque fill that hides the very line it
+ * points at.
+ *
+ * **A double stroke.** One coloured border vanishes when it lands on dark ink or
+ * a table rule. The outer white ring separates the box from whatever it crosses.
+ *
+ * **`measured` is solid, `region` is dashed.** A word-level rectangle from the
+ * text layer and an OCR block covering a paragraph are different claims, and
+ * drawing them identically tells the reader the coarse one is exact.
+ *
+ * **Dark mode changes nothing.** The page is white paper either way.
+ */
+
+import * as React from 'react'
+
+export type OverlayRegion = {
+  /** Normalised to the page, top-left origin: `[x0, y0, x1, y1]`, each 0..1. */
+  box: [number, number, number, number]
+  /** `measured` — from the text layer. `region` — an OCR block, visibly coarser. */
+  precision?: 'measured' | 'region'
+  /** Free-form grouping key; the overlay only compares it with `activeKey`. */
+  key?: string
+  /** Drawn beside the frame when `showLabels` is on. */
+  label?: string
+}
+
+export type RegionOverlayProps = {
+  regions: OverlayRegion[]
+  /** The size the page is CURRENTLY rendered at, in CSS pixels. */
+  width: number
+  height: number
+  /** Which region group is selected. Others dim rather than disappear. */
+  activeKey?: string | null
+  /** Draw each frame's label. The "sweep the document" view. */
+  showLabels?: boolean
+  onRegionClick?: (key: string | undefined, index: number) => void
+  className?: string
+}
+
+/** Frame the text, do not clip it. */
+const PAD_X = 3
+const PAD_Y = 2
+
+export const RegionOverlay: React.FC<RegionOverlayProps> = ({
+  regions,
+  width,
+  height,
+  activeKey,
+  showLabels = false,
+  onRegionClick,
+  className,
+}) => {
+  // Nothing to anchor to yet — a page that has not been measured would put every
+  // box at 0×0 in the corner, which reads as a rendering bug.
+  if (!width || !height || regions.length === 0) return null
+
+  return (
+    <div
+      className={className}
+      data-testid="region-overlay"
+      style={{ position: 'absolute', inset: 0, pointerEvents: 'none' }}
+    >
+      {regions.map((region, index) => {
+        const [x0, y0, x1, y1] = region.box
+        const left = x0 * width - PAD_X
+        const top = y0 * height - PAD_Y
+        const w = (x1 - x0) * width + PAD_X * 2
+        const h = (y1 - y0) * height + PAD_Y * 2
+        const isActive = activeKey != null && region.key === activeKey
+        // Something is selected and it is not this one. Dimmed, not hidden: the
+        // point of drawing them all is to see the shape of what was read.
+        const isDimmed = activeKey != null && !isActive
+        const dashed = region.precision === 'region'
+
+        return (
+          <div
+            key={`${region.key ?? 'r'}-${index}`}
+            data-testid="region-overlay-box"
+            data-active={isActive ? 'true' : undefined}
+            data-precision={region.precision ?? 'measured'}
+            onClick={onRegionClick ? () => onRegionClick(region.key, index) : undefined}
+            style={{
+              position: 'absolute',
+              left, top, width: w, height: h,
+              borderRadius: 3,
+              border: `2px ${dashed ? 'dashed' : 'solid'} ${isActive ? 'rgb(214 122 0)' : 'rgb(255 193 7)'}`,
+              backgroundColor: isActive ? 'rgb(255 193 7 / 0.42)' : 'rgb(255 193 7 / 0.22)',
+              // The white ring must hug the box, so it comes first.
+              boxShadow: '0 0 0 1.5px rgb(255 255 255 / 0.95), 0 1px 4px rgb(0 0 0 / 0.28)',
+              opacity: isDimmed ? 0.45 : 1,
+              transition: 'opacity 150ms ease, background-color 150ms ease',
+              pointerEvents: onRegionClick ? 'auto' : 'none',
+              cursor: onRegionClick ? 'pointer' : undefined,
+            }}
+          >
+            {showLabels && region.label ? (
+              <span
+                data-testid="region-overlay-label"
+                style={{
+                  position: 'absolute',
+                  // ABOVE the box, not inside it: a label inside covers the
+                  // words the frame exists to point at.
+                  bottom: '100%',
+                  left: -1,
+                  marginBottom: 2,
+                  maxWidth: 220,
+                  overflow: 'hidden',
+                  textOverflow: 'ellipsis',
+                  whiteSpace: 'nowrap',
+                  padding: '1px 4px',
+                  borderRadius: 3,
+                  backgroundColor: isActive ? 'rgb(120 66 0)' : 'rgb(64 51 20 / 0.92)',
+                  color: '#fff',
+                  fontSize: 10,
+                  lineHeight: '14px',
+                  fontWeight: 600,
+                  pointerEvents: 'none',
+                }}
+              >
+                {region.label}
+              </span>
+            ) : null}
+          </div>
+        )
+      })}
+    </div>
+  )
+}
+
+export default RegionOverlay

package/src/backend/document-viewer/index.ts

@@ -0,0 +1,2 @@
+export { RegionOverlay, default as RegionOverlayDefault } from './RegionOverlay'
+export type { OverlayRegion, RegionOverlayProps } from './RegionOverlay'

package/src/backend/dynamic-grid/DynamicGrid.tsx

@@ -0,0 +1,161 @@
+import React, { useMemo, useEffect, useCallback, useRef } from 'react';
+import { createCellStore } from '../dynamic-table/store/index';
+import { CellStoreContext } from '../dynamic-table/hooks/index';
+import { useEventHandlers } from '../dynamic-table/events/events';
+import { TableEvents } from '../dynamic-table/types/index';
+import type {
+  CellSaveStartEvent,
+  CellSaveSuccessEvent,
+  CellSaveErrorEvent,
+} from '../dynamic-table/types/index';
+import { gridCellDefToColumnDef, buildStoreData } from './adapters';
+import { useGridKeyboardNav } from './hooks/useGridKeyboardNav';
+import type { DynamicGridProps } from './types';
+import GridRow from './components/GridRow';
+
+const DynamicGrid: React.FC<DynamicGridProps> = ({
+  data,
+  rows,
+  gridRef,
+  idField = 'id',
+  columns,
+  className,
+  enableKeyboardNav = true,
+}) => {
+  const gridColumns = columns ?? Math.max(...rows.map((r) => r.cells.length));
+
+  // Build per-row ColumnDef arrays for GridCell to use
+  const columnDefsByRow = useMemo(
+    () => rows.map((row) => row.cells.map(gridCellDefToColumnDef)),
+    [rows],
+  );
+
+  // Build a flat columns array for store initialization (use the widest row)
+  const storeColumns = useMemo(() => {
+    const widestRowIndex = rows.reduce(
+      (maxIdx, row, idx, arr) => (row.cells.length > arr[maxIdx].cells.length ? idx : maxIdx),
+      0,
+    );
+    return columnDefsByRow[widestRowIndex] ?? [];
+  }, [rows, columnDefsByRow]);
+
+  // Build store data: each row gets a copy of the full entity
+  const storeData = useMemo(() => buildStoreData(data, rows), [data, rows]);
+
+  // Create cell store once
+  const storeRef = useRef(createCellStore(storeData, storeColumns));
+  const store = storeRef.current;
+
+  // Set the table ref so store.focusTable() works
+  useEffect(() => {
+    store.setTableRef(gridRef);
+  }, [store, gridRef]);
+
+  // Sync data changes into the store
+  useEffect(() => {
+    store.setData(storeData);
+  }, [store, storeData]);
+
+  // Sync column changes into the store
+  useEffect(() => {
+    store.setColumns(storeColumns);
+  }, [store, storeColumns]);
+
+  // Internal save state event handlers
+  const saveTimeouts = useRef(new Map<string, ReturnType<typeof setTimeout>>());
+
+  const clearSaveTimeout = useCallback((key: string) => {
+    const existing = saveTimeouts.current.get(key);
+    if (existing) {
+      clearTimeout(existing);
+      saveTimeouts.current.delete(key);
+    }
+  }, []);
+
+  useEventHandlers(
+    {
+      [TableEvents.CELL_SAVE_START]: (payload: CellSaveStartEvent) => {
+        const key = `${payload.rowIndex}:${payload.colIndex}`;
+        clearSaveTimeout(key);
+        store.setSaveState(payload.rowIndex, payload.colIndex, 'saving');
+      },
+      [TableEvents.CELL_SAVE_SUCCESS]: (payload: CellSaveSuccessEvent) => {
+        const key = `${payload.rowIndex}:${payload.colIndex}`;
+        clearSaveTimeout(key);
+        store.setSaveState(payload.rowIndex, payload.colIndex, 'success');
+        saveTimeouts.current.set(
+          key,
+          setTimeout(() => {
+            store.setSaveState(payload.rowIndex, payload.colIndex, null);
+            saveTimeouts.current.delete(key);
+          }, 2000),
+        );
+      },
+      [TableEvents.CELL_SAVE_ERROR]: (payload: CellSaveErrorEvent) => {
+        const key = `${payload.rowIndex}:${payload.colIndex}`;
+        clearSaveTimeout(key);
+        store.setSaveState(payload.rowIndex, payload.colIndex, 'error');
+        saveTimeouts.current.set(
+          key,
+          setTimeout(() => {
+            store.setSaveState(payload.rowIndex, payload.colIndex, null);
+            saveTimeouts.current.delete(key);
+          }, 3000),
+        );
+      },
+    },
+    gridRef,
+    { stopPropagation: false },
+  );
+
+  // Cleanup timeouts on unmount
+  useEffect(() => {
+    const timeouts = saveTimeouts.current;
+    return () => {
+      timeouts.forEach((timeout) => clearTimeout(timeout));
+      timeouts.clear();
+    };
+  }, []);
+
+  // Keyboard navigation
+  const handleKeyDown = useGridKeyboardNav(store, rows);
+
+  // Clear selection/editing when focus leaves the grid
+  const handleBlur = useCallback(
+    (e: React.FocusEvent) => {
+      // If focus moves to another element inside the grid, ignore
+      if (gridRef.current?.contains(e.relatedTarget as Node)) return;
+      store.clearEditing();
+      store.setSelection({ type: null, anchor: null, focus: null });
+    },
+    [store, gridRef],
+  );
+
+  return (
+    <CellStoreContext.Provider value={store}>
+      <div
+        ref={gridRef}
+        className={['dynamic-grid outline-none', className].filter(Boolean).join(' ')}
+        tabIndex={enableKeyboardNav ? 0 : undefined}
+        onKeyDown={enableKeyboardNav ? handleKeyDown : undefined}
+        onBlur={handleBlur}
+      >
+        {rows.map((rowDef, rowIndex) => (
+          <GridRow
+            key={rowIndex}
+            rowIndex={rowIndex}
+            rowDef={rowDef}
+            columnDefs={columnDefsByRow[rowIndex]}
+            gridColumns={gridColumns}
+            gridRef={gridRef}
+            idField={idField}
+          />
+        ))}
+      </div>
+    </CellStoreContext.Provider>
+  );
+};
+
+DynamicGrid.displayName = 'DynamicGrid';
+
+export default DynamicGrid;

package/src/backend/dynamic-grid/adapters.ts

@@ -0,0 +1,57 @@
+import type { ColumnDef } from '../dynamic-table/types/index';
+import type { GridCellDef, GridRowDef } from './types';
+
+/**
+ * Converts a GridCellDef to a DynamicTable ColumnDef so we can reuse
+ * getCellEditor / getCellRenderer from the DynamicTable component.
+ */
+export function gridCellDefToColumnDef(cellDef: GridCellDef): ColumnDef {
+  return {
+    data: cellDef.field,
+    title: cellDef.label,
+    type: cellDef.type,
+    readOnly: cellDef.readOnly,
+    source: cellDef.source,
+    renderer: cellDef.renderer
+      ? (value: any, rowData: any) => cellDef.renderer!(value, rowData, cellDef)
+      : undefined,
+    editor: cellDef.editor
+      ? (
+          value: any,
+          onChange: (v: any) => void,
+          onSave: () => void,
+          onCancel: () => void,
+          rowData: any,
+        ) => cellDef.editor!(value, onChange, onSave, onCancel, rowData, cellDef)
+      : undefined,
+    cellClassName: cellDef.cellClassName
+      ? (value: any, rowData: any) => cellDef.cellClassName!(value, rowData)
+      : undefined,
+  };
+}
+
+/**
+ * Builds per-row data arrays for the CellStore from a single entity.
+ * Each row gets the full entity data so any cell can read any field.
+ */
+export function buildStoreData(data: Record<string, any>, rows: GridRowDef[]): any[] {
+  return rows.map(() => ({ ...data }));
+}
+
+/**
+ * Builds a flat ColumnDef array from the row with the most cells.
+ * Used to initialize the CellStore (it needs a columns array).
+ */
+export function buildStoreColumns(rows: GridRowDef[]): ColumnDef[] {
+  const maxCols = Math.max(...rows.map((r) => r.cells.length));
+  const defs: ColumnDef[] = [];
+  for (let i = 0; i < maxCols; i++) {
+    for (const row of rows) {
+      if (row.cells[i]) {
+        defs.push(gridCellDefToColumnDef(row.cells[i]));
+        break;
+      }
+    }
+  }
+  return defs;
+}

package/src/backend/dynamic-grid/components/GridCell.tsx

@@ -0,0 +1,194 @@
+import React, { memo, useRef, useEffect, useCallback } from 'react';
+import { useCellStore, useCellState } from '../../dynamic-table/hooks/index';
+import { getCellRenderer } from '../../dynamic-table/components/renderers';
+import { getCellEditor } from '../../dynamic-table/components/editors';
+import { dispatch } from '../../dynamic-table/events/events';
+import { TableEvents } from '../../dynamic-table/types/index';
+import type { ColumnDef, CellEditSaveEvent } from '../../dynamic-table/types/index';
+import type { GridCellDef } from '../types';
+
+export interface GridCellProps {
+  gridRow: number;
+  gridCol: number;
+  cellDef: GridCellDef;
+  columnDef: ColumnDef;
+  gridRef: React.RefObject<HTMLDivElement | null>;
+  idField: string;
+}
+
+/**
+ * Strip DynamicTable editor visual styles so the editor is an invisible
+ * typing surface over the value text. The grid cell itself shows selection state.
+ */
+function neutralizeEditorStyles(container: HTMLElement | null) {
+  if (!container) return;
+  const editors = container.querySelectorAll<HTMLElement>('.hot-cell-editor, .hot-boolean-editor-wrapper');
+  editors.forEach((el) => {
+    el.style.background = 'transparent';
+    el.style.boxShadow = 'none';
+    el.style.padding = '0';
+    el.style.fontSize = 'inherit';
+    el.style.color = 'inherit';
+  });
+}
+
+const GridCell: React.FC<GridCellProps> = memo(
+  ({ gridRow, gridCol, cellDef, columnDef, gridRef, idField }) => {
+    const store = useCellStore();
+    const state = useCellState(gridRow, gridCol);
+    const inputRef = useRef<any>(null);
+    const valueRef = useRef<HTMLDivElement>(null);
+    const rowData = store.getRowData(gridRow);
+    const cellValue = rowData?.[cellDef.field];
+
+    const isEmpty = cellValue == null || cellValue === '';
+
+    const handleSave = useCallback(
+      (value?: any, clearEditing: boolean = true) => {
+        const newValue = value !== undefined ? value : cellValue;
+        const oldValue = rowData?.[cellDef.field];
+
+        if (String(oldValue ?? '') === String(newValue ?? '')) {
+          if (clearEditing) {
+            store.clearEditing();
+            store.focusTable();
+          }
+          return;
+        }
+
+        store.setCellValue(gridRow, gridCol, newValue);
+        if (clearEditing) {
+          store.clearEditing();
+          store.focusTable();
+        }
+
+        if (gridRef.current) {
+          dispatch<CellEditSaveEvent>(gridRef.current, TableEvents.CELL_EDIT_SAVE, {
+            rowIndex: gridRow,
+            colIndex: gridCol,
+            oldValue,
+            newValue,
+            prop: cellDef.field,
+            rowData,
+            id: rowData?.[idField],
+          });
+        }
+      },
+      [cellValue, rowData, cellDef.field, gridRow, gridCol, store, gridRef, idField],
+    );
+
+    const handleCancel = useCallback(() => {
+      store.clearEditing();
+      store.focusTable();
+    }, [store]);
+
+    const handleChange = useCallback(() => {
+      // Editor holds its own local state — no store update during editing
+    }, []);
+
+    // Focus input and neutralize editor visuals when editing starts
+    useEffect(() => {
+      if (!state.isEditing) return;
+
+      // Strip DynamicTable editor visual styles
+      neutralizeEditorStyles(valueRef.current);
+
+      // Use rAF to run after React commits the controlled value to the DOM,
+      // then set cursor to end of text
+      requestAnimationFrame(() => {
+        if (!inputRef.current) return;
+        inputRef.current.focus();
+        const el = inputRef.current;
+        const supportsSelection =
+          el.type === undefined ||
+          ['text', 'password', 'search', 'tel', 'url', 'number'].includes(el.type);
+        if (supportsSelection && el.setSelectionRange) {
+          const length = el.value?.length || 0;
+          try {
+            el.setSelectionRange(length, length);
+          } catch {
+            // Some input types may throw, ignore
+          }
+        }
+      });
+    }, [state.isEditing]);
+
+    const handleClick = useCallback(() => {
+      store.setSelection({
+        type: 'cell',
+        anchor: { row: gridRow, col: gridCol },
+        focus: { row: gridRow, col: gridCol },
+      });
+    }, [store, gridRow, gridCol]);
+
+    const handleDoubleClick = useCallback(() => {
+      if (!cellDef.readOnly) {
+        store.setEditingCell(gridRow, gridCol);
+      }
+    }, [store, gridRow, gridCol, cellDef.readOnly]);
+
+    const renderer = getCellRenderer(columnDef);
+    const renderedValue = renderer(cellValue, rowData, columnDef, gridRow, gridCol);
+    const conditionalClassName = cellDef.cellClassName?.(cellValue, rowData ?? {}) || '';
+
+    const saveStateBg =
+      state.saveState === 'saving'
+        ? 'bg-blue-50/50 dark:bg-blue-950/30'
+        : state.saveState === 'success'
+          ? 'bg-green-50/50 dark:bg-green-950/30'
+          : state.saveState === 'error'
+            ? 'bg-red-50/50 dark:bg-red-950/30'
+            : '';
+
+    return (
+      <div
+        className={[
+          'dynamic-grid-cell',
+          'border border-border px-3 py-2 rounded-sm transition-colors duration-150',
+          cellDef.readOnly ? 'bg-muted/30' : 'cursor-pointer',
+          state.isSelected ? 'ring-2 ring-primary ring-inset' : '',
+          saveStateBg,
+          conditionalClassName,
+        ]
+          .filter(Boolean)
+          .join(' ')}
+        style={cellDef.colSpan ? { gridColumn: `span ${cellDef.colSpan}` } : undefined}
+        data-grid-row={gridRow}
+        data-grid-col={gridCol}
+        data-save-state={state.saveState}
+        onClick={handleClick}
+        onDoubleClick={handleDoubleClick}
+      >
+        <div
+          className={[
+            'text-[10px] uppercase tracking-wider mb-1 select-none',
+            cellDef.required && isEmpty
+              ? 'text-destructive font-medium'
+              : 'text-muted-foreground',
+          ].join(' ')}
+        >
+          {cellDef.label}
+        </div>
+        <div ref={valueRef} className="relative text-sm min-h-[1.25rem]">
+          <span className="whitespace-pre-wrap">{renderedValue}</span>
+          {state.isEditing &&
+            getCellEditor(
+              columnDef,
+              cellValue,
+              handleChange,
+              handleSave,
+              handleCancel,
+              rowData,
+              gridRow,
+              gridCol,
+              inputRef,
+            )}
+        </div>
+      </div>
+    );
+  },
+);
+
+GridCell.displayName = 'GridCell';
+
+export default GridCell;

package/src/backend/dynamic-grid/components/GridRow.tsx

@@ -0,0 +1,40 @@
+import React, { memo } from 'react';
+import type { ColumnDef } from '../../dynamic-table/types/index';
+import type { GridRowDef } from '../types';
+import GridCell from './GridCell';
+
+export interface GridRowProps {
+  rowIndex: number;
+  rowDef: GridRowDef;
+  columnDefs: ColumnDef[];
+  gridColumns: number;
+  gridRef: React.RefObject<HTMLDivElement | null>;
+  idField: string;
+}
+
+const GridRow: React.FC<GridRowProps> = memo(
+  ({ rowIndex, rowDef, columnDefs, gridColumns, gridRef, idField }) => {
+    return (
+      <div
+        className={['grid gap-0', rowDef.className].filter(Boolean).join(' ')}
+        style={{ gridTemplateColumns: `repeat(${gridColumns}, minmax(0, 1fr))` }}
+      >
+        {rowDef.cells.map((cellDef, colIndex) => (
+          <GridCell
+            key={cellDef.field}
+            gridRow={rowIndex}
+            gridCol={colIndex}
+            cellDef={cellDef}
+            columnDef={columnDefs[colIndex]}
+            gridRef={gridRef}
+            idField={idField}
+          />
+        ))}
+      </div>
+    );
+  },
+);
+
+GridRow.displayName = 'GridRow';
+
+export default GridRow;