@freighttech/ui 0.13.18

package/src/backend/dynamic-table/hooks/useAbbreviations.ts

@@ -0,0 +1,67 @@
+'use client'
+
+/**
+ * DynamicTable — ABBREVIATION DICTIONARY SUBSCRIPTION
+ * ═══════════════════════════════════════════════════════════════════════════
+ *
+ * `utils/abbreviations.ts` is a process-local registry populated ONCE at app
+ * boot from the `facilities` and `contractors` tables. That import order is the
+ * whole problem this file exists to solve:
+ *
+ *   1. the grid mounts and renders every cell — dictionary still empty,
+ *   2. the boot fetch resolves and `registerAbbreviations` fills the registry,
+ *   3. …and nothing re-renders, so the user keeps looking at "Port Gdańsk"
+ *      until they happen to sort, filter or page.
+ *
+ * The registry's own doc says consumers "must include `abbreviationsVersion()`
+ * in their dependency list", but a plain module-level integer is not something
+ * React can observe — reading it inside a `useMemo` captures whatever it was at
+ * mount and never notices the bump. `useSyncExternalStore` is the correct
+ * primitive: `subscribeAbbreviations` is the subscribe half, and
+ * `abbreviationsVersion` is the snapshot half.
+ *
+ * ── Usage ──────────────────────────────────────────────────────────────────
+ * Put the returned number in the dependency list of whatever memoizes derived
+ * label output — the column definitions, a precomputed initials index:
+ *
+ *     const abbrevVersion = useAbbreviationsVersion()
+ *     const columns = React.useMemo(() => buildColumns(), [cfg, abbrevVersion])
+ *
+ * ── Why the version and not the dictionary itself ──────────────────────────
+ * The renderers read the registry directly at render time (one `Map.get`), so
+ * they never need the dictionary threaded through props. All that is missing is
+ * the SIGNAL that a re-render is now worth doing, and an integer is the
+ * cheapest possible carrier for it — it changes at most twice in the lifetime
+ * of a page, so nothing downstream is re-computed on any other pass.
+ *
+ * ── SSR ────────────────────────────────────────────────────────────────────
+ * The server snapshot is a constant `0` rather than `abbreviationsVersion()`.
+ * On the server the registry only ever holds the static seed, and returning a
+ * value that could differ between the server render and the client's first
+ * render is precisely the hydration mismatch `getServerSnapshot` exists to
+ * prevent.
+ * ═══════════════════════════════════════════════════════════════════════════
+ */
+
+import * as React from 'react'
+
+import { abbreviationsVersion, subscribeAbbreviations } from '../utils/abbreviations'
+
+/** Constant across every server render — see the SSR note above. */
+function getServerSnapshot(): number {
+  return 0
+}
+
+/**
+ * The current abbreviation-dictionary version, re-rendering the caller whenever
+ * a dictionary is registered.
+ */
+export function useAbbreviationsVersion(): number {
+  return React.useSyncExternalStore(
+    subscribeAbbreviations,
+    abbreviationsVersion,
+    getServerSnapshot,
+  )
+}
+
+export default useAbbreviationsVersion

package/src/backend/dynamic-table/hooks/useAnnotations.ts

@@ -0,0 +1,215 @@
+import { useState, useEffect, useCallback, useMemo, useRef } from 'react';
+import { apiCall } from '../../utils/apiCall';
+
+/** Who a comment is written for — see `packages/annotations` (workshop B8c). */
+export type CellCommentAudience = 'internal' | 'carrier';
+
+export interface AnnotationComment {
+  id: string;
+  content: string;
+  userName?: string;
+  userId?: string;
+  createdAt?: string;
+  /** `carrier` = printed on the waybill; `internal` = a note between colleagues. */
+  audience?: CellCommentAudience;
+}
+
+export interface CellAnnotationInfo {
+  id: string;
+  color: string | null;
+  commentCount: number;
+  /** The comment thread for this cell — used by the hover preview popup. */
+  comments: AnnotationComment[];
+  assignees: Array<{ userId: string }>;
+}
+
+export type AnnotationMap = Map<string, CellAnnotationInfo>;
+
+/**
+ * One cell's annotation target (workshop B8a).
+ *
+ * A grid row is not always one record. On the transport list a row is a
+ * unit-LEG: the truck plate belongs to the leg, the container number belongs to
+ * the container that travels on both legs. Keying every comment by the row's id
+ * column made a container note appear on both legs — "on się teraz powiela w
+ * innych miejscach". A cell therefore names its own target.
+ */
+export interface AnnotationTarget {
+  entityType: string;
+  rowId: string;
+}
+
+/** Map key. `entityType` is part of it precisely so two scopes cannot collide. */
+export function annotationKey(target: AnnotationTarget, columnKey: string): string {
+  return `${target.entityType}:${target.rowId}:${columnKey}`;
+}
+
+interface UseAnnotationsOptions {
+  enabled: boolean;
+  /**
+   * Every (entityType, rowId) pair on screen, already de-duplicated by the
+   * caller. One request per distinct `entityType`.
+   */
+  targets?: AnnotationTarget[];
+  /**
+   * @deprecated Pass `targets` instead. Still read so a consumer compiled
+   * against the pre-`targets` signature keeps its annotations — see the note
+   * on `resolvedTargets` below.
+   */
+  entityType?: string;
+  /** @deprecated Pass `targets` instead. */
+  data?: Array<Record<string, unknown>>;
+  /** @deprecated Pass `targets` instead. Defaults to `id`, as it always did. */
+  idColumnName?: string;
+}
+
+/** Stable identity, so "nothing to annotate" does not re-key the fetch memo. */
+const NO_TARGETS: AnnotationTarget[] = [];
+
+export function useAnnotations({
+  enabled,
+  targets,
+  entityType,
+  data,
+  idColumnName,
+}: UseAnnotationsOptions) {
+  const [annotations, setAnnotations] = useState<AnnotationMap>(new Map());
+  const [loading, setLoading] = useState(false);
+  const abortControllerRef = useRef<AbortController | null>(null);
+
+  /**
+   * Walkthrough 2026-08-27 bug 27 — why the legacy option shape is still read.
+   *
+   * `targets` replaced `{ entityType, data, idColumnName }` (workshop B8a: a
+   * grid row is not always one record). The rename shipped on a PUBLISHED
+   * surface with no bridge, and `targets.map(...)` below ran unguarded — so a
+   * consumer built against the old signature did not lose its comments, it
+   * threw a TypeError on the FIRST render, before any request was made.
+   *
+   * That is not hypothetical. `@freighttech/invoicing` declares
+   * `"@freighttech/ui": "0.13.0"` as a peer, so the INF deployment resolved ui
+   * 0.13.15 alongside invoicing 0.13.2 — old caller, new hook. Every
+   * `/backend/invoicing/<id>/allocate` answered 500, for every id, including
+   * ids that match no invoice: the crash is in the render, not the data. Cost
+   * allocation was unreachable and the release walkthrough stopped there.
+   *
+   * A missing or renamed option must cost the annotations, never the page. An
+   * absent `targets` therefore resolves to "nothing to annotate", and the
+   * legacy trio is mapped forward rather than dropped so an un-republished
+   * consumer keeps working until it is rebuilt.
+   */
+  const resolvedTargets = useMemo(() => {
+    if (targets) return targets;
+    if (!entityType || !data) return NO_TARGETS;
+    const idKey = idColumnName || 'id';
+    return data
+      .map((row) => ({ entityType, rowId: String(row?.[idKey] ?? '') }))
+      .filter((target) => target.rowId);
+  }, [targets, entityType, data, idColumnName]);
+
+  // Refetch on CONTENT, not identity: `targets` is rebuilt whenever the data
+  // page or the column set changes, and a column reorder must not re-request
+  // every annotation on the page.
+  const targetsKey = useMemo(
+    () => resolvedTargets.map((t) => `${t.entityType}\u0000${t.rowId}`).sort().join('\u0001'),
+    [resolvedTargets],
+  );
+  const targetsRef = useRef(resolvedTargets);
+  targetsRef.current = resolvedTargets;
+
+  const fetchAnnotations = useCallback(async () => {
+    const current = targetsRef.current;
+    if (!enabled || current.length === 0) {
+      setAnnotations(new Map());
+      return;
+    }
+
+    // Abort previous request
+    if (abortControllerRef.current) {
+      abortControllerRef.current.abort();
+    }
+    abortControllerRef.current = new AbortController();
+    const signal = abortControllerRef.current.signal;
+
+    setLoading(true);
+    try {
+      const groups = new Map<string, Set<string>>();
+      for (const target of current) {
+        if (!target.entityType || !target.rowId) continue;
+        const existing = groups.get(target.entityType);
+        if (existing) existing.add(target.rowId);
+        else groups.set(target.entityType, new Set([target.rowId]));
+      }
+
+      if (groups.size === 0) {
+        setAnnotations(new Map());
+        return;
+      }
+
+      const fetches = Array.from(groups.entries()).map(async ([entityType, rowIds]) => {
+        const params = new URLSearchParams({
+          entityType,
+          rowIds: Array.from(rowIds).join(','),
+        });
+        const { ok, result } = await apiCall<any>(`/api/annotations/annotations?${params}`, { signal });
+        if (!ok || !result) return [] as any[];
+        const items: any[] = result.items || result.data || result || [];
+        // The endpoint echoes `entityType`, but fall back to the group's key so
+        // an older response shape still lands in the right bucket.
+        return items.map((item) => ({ ...item, entityType: item.entityType ?? entityType }));
+      });
+
+      const results = await Promise.all(fetches);
+      const allItems = results.flat();
+
+      const map: AnnotationMap = new Map();
+      for (const annotation of allItems) {
+        const key = annotationKey(
+          {
+            entityType: annotation.entityType ?? annotation.entity_type ?? '',
+            rowId: String(annotation.rowId ?? annotation.row_id ?? ''),
+          },
+          annotation.columnKey || annotation.column_key,
+        );
+        const comments: AnnotationComment[] = (annotation.comments || []).map((c: any) => ({
+          id: c.id,
+          content: c.content ?? '',
+          userName: c.userName ?? c.user_name ?? undefined,
+          userId: c.userId ?? c.user_id ?? undefined,
+          createdAt: c.createdAt ?? c.created_at ?? undefined,
+          audience: (c.audience as CellCommentAudience) ?? 'internal',
+        }));
+        map.set(key, {
+          id: annotation.id,
+          color: annotation.color || null,
+          commentCount: comments.length || annotation.commentCount || 0,
+          comments,
+          assignees: (annotation.assignees || []).map((a: any) => ({ userId: a.userId || a.user_id })),
+        });
+      }
+      setAnnotations(map);
+    } catch (error) {
+      if (error instanceof Error && error.name === 'AbortError') return;
+      console.error('Failed to fetch annotations:', error);
+      setAnnotations(new Map());
+    } finally {
+      setLoading(false);
+    }
+    // `targetsKey` is the real dependency — see the note on the memo above.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [enabled, targetsKey]);
+
+  // Fetch when the target set changes
+  useEffect(() => {
+    fetchAnnotations();
+    return () => {
+      abortControllerRef.current?.abort();
+    };
+  }, [fetchAnnotations]);
+
+  return {
+    annotations,
+    loading,
+    refresh: fetchAnnotations,
+  };
+}

package/src/backend/dynamic-table/hooks/useColumnVirtualizer.ts

@@ -0,0 +1,303 @@
+/**
+ * HORIZONTAL (COLUMN) VIRTUALIZATION — REACT WRAPPER
+ * ==================================================
+ *
+ * A thin wrapper. All correctness lives in `../utils/columnWindow.ts`, which is
+ * pure and unit-tested; this file only owns the three things that need React
+ * and the DOM:
+ *
+ *   1. subscribing to scroll/resize (delegated to `@tanstack/react-virtual`,
+ *      which already does the rAF batching, passive listeners, `scrollend`
+ *      handling and `ResizeObserver` teardown correctly),
+ *   2. rebuilding geometry when the user resizes a column,
+ *   3. writing `scrollLeft` for scroll-into-view.
+ *
+ * WHY THE UNDERLYING VIRTUALIZER RUNS AT `overscan: 0`
+ * ----------------------------------------------------
+ * We apply overscan ourselves in `buildColumnWindow`, because our mounted set is
+ * `window ∪ pinned ∪ forced` and the library has no concept of a force-mounted
+ * item. Our window is a pure function of the library's base range, so it changes
+ * exactly when the base range changes — running the library at `overscan: 0`
+ * therefore costs no extra re-renders and gives us the earliest possible commit
+ * (one full column before the viewport edge).
+ *
+ * WHY WE NEVER CALL `measureElement`
+ * ----------------------------------
+ * Column widths are already fully model-held: `store.getColumnWidth(i)` answers
+ * for every `i` whether or not the column is mounted, resizing writes straight
+ * to that map without touching the DOM, and widths persist by `col.data`.
+ * Measuring the DOM instead would make geometry depend on what happens to be
+ * mounted, which is the exact feedback loop that makes a virtualized grid
+ * jitter. `estimateSize` reads the model and is authoritative.
+ *
+ * OPT-IN, NOT OPT-OUT
+ * -------------------
+ * `enabled` defaults to FALSE. 56 consumer files pass 231 renderer functions
+ * into this grid and the renderer contract must not change; column
+ * virtualization ships behind `uiConfig.enableColumnVirtualization` so the
+ * stress fixture and the container table can adopt it first. When disabled this
+ * hook still runs (hook order is fixed) but returns a full window — every column
+ * mounted, no spacers, `virtualized: false` — which is byte-for-byte the render
+ * the grid produces today.
+ */
+import * as React from 'react';
+import { useVirtualizer } from '@tanstack/react-virtual';
+import {
+  DEFAULT_COLUMN_OVERSCAN,
+  buildColumnWindow,
+  computeColumnGeometry,
+  computeScrollLeftToReveal,
+  createFullColumnWindow,
+  getAriaColCount,
+  getAriaColIndex,
+  type ColumnGeometry,
+  type ColumnRange,
+  type ColumnScrollAlign,
+  type ColumnWindow,
+} from '../utils/columnWindow';
+
+export interface UseColumnVirtualizerOptions {
+  /**
+   * Master switch. Default FALSE — see the module comment. Wire it to
+   * `uiConfig.enableColumnVirtualization`.
+   */
+  enabled?: boolean;
+  /** Length of the FULL, view-ordered column array (`cols.length`). */
+  columnCount: number;
+  /**
+   * MUST be `store.getColumnWidth`, i.e. must answer for every index whether or
+   * not the column is mounted. Never a DOM measurement.
+   */
+  getColumnWidth: (index: number) => number;
+  /** The horizontally scrolling element — the same node the row virtualizer uses. */
+  getScrollElement: () => HTMLElement | null;
+  /**
+   * Indices of columns pinned to the LEFT: `sticky === 'left'` plus the runtime
+   * frozen set. Always mounted — `position: sticky` needs an element to exist.
+   * Derive with `getPinnedColumnIndices(cols, frozenColumns)`.
+   */
+  pinnedLeftIndices?: readonly number[];
+  /** Indices of columns pinned to the RIGHT (`sticky === 'right'`). Always mounted. */
+  pinnedRightIndices?: readonly number[];
+  /**
+   * Extra always-mounted indices: the selection anchor, the selection focus and
+   * the editing cell. Without these, moving the caret onto an off-window column
+   * paints nothing and `setEditingCell` mounts no editor.
+   */
+  forcedIndices?: readonly number[];
+  /** @default DEFAULT_COLUMN_OVERSCAN (3) — justification lives with the constant. */
+  overscan?: number;
+  /** Width of the row-header gutter (0 when `rowHeaders` is false). */
+  leadingWidth?: number;
+  /** Width of the sticky Actions column (0 when it is not rendered). */
+  trailingWidth?: number;
+  /**
+   * Bumped whenever ANY column width changes. Column widths are user-resizable
+   * and live in a mutable store map, so nothing else can tell React the prefix
+   * sums went stale. Pass the store revision, or better a width-only revision so
+   * a resize drag does not also re-render every row (Defect 6).
+   */
+  widthRevision?: number;
+  /** Stable per-column key, normally `(i) => cols[i].data`. */
+  getColumnKey?: (index: number) => string | number;
+  /** Whether a row-header column is rendered — affects `aria-colcount`/`-colindex`. */
+  hasRowHeader?: boolean;
+  /** Whether the Actions column is rendered — affects `aria-colcount`. */
+  hasActionsColumn?: boolean;
+}
+
+export interface ColumnVirtualizer extends ColumnWindow {
+  /** `aria-colcount` for the grid element. Counts ALL columns, not the mounted ones. */
+  ariaColCount: number;
+  /** `aria-colindex` (1-based) for a data column index. */
+  getAriaColIndex: (columnIndex: number) => number;
+  /**
+   * Scrolls `columnIndex` into view. No-op when it is pinned or already visible.
+   * MUST be called in the same commit as a selection/edit move onto an
+   * off-window column, BEFORE any focus attempt.
+   */
+  scrollToColumn: (
+    columnIndex: number,
+    options?: { align?: ColumnScrollAlign; behavior?: ScrollBehavior }
+  ) => void;
+  /** Invalidates the virtualizer's cached sizes. Called for you on `widthRevision`. */
+  measure: () => void;
+  /** Prefix-sum geometry — the model answer to "where is column i?". */
+  geometry: ColumnGeometry;
+}
+
+/** Stable dependency key for an index list without depending on array identity. */
+function useIndexListKey(list: readonly number[] | undefined): string {
+  return React.useMemo(() => (list && list.length ? list.join(',') : ''), [list]);
+}
+
+export function useColumnVirtualizer(
+  options: UseColumnVirtualizerOptions
+): ColumnVirtualizer {
+  const {
+    enabled = false,
+    columnCount,
+    getColumnWidth,
+    getScrollElement,
+    pinnedLeftIndices,
+    pinnedRightIndices,
+    forcedIndices,
+    overscan = DEFAULT_COLUMN_OVERSCAN,
+    leadingWidth = 0,
+    trailingWidth = 0,
+    widthRevision = 0,
+    getColumnKey,
+    hasRowHeader = false,
+    hasActionsColumn = false,
+  } = options;
+
+  // Callbacks read through refs so the virtualizer options keep a stable
+  // identity: `estimateSize` changing identity does NOT invalidate the library's
+  // measurement memo (it is keyed on count/paddingStart/getItemKey/enabled), so
+  // relying on identity here would be a silent staleness bug. `measure()` on
+  // `widthRevision` is the real invalidation path.
+  const getColumnWidthRef = React.useRef(getColumnWidth);
+  getColumnWidthRef.current = getColumnWidth;
+  const getColumnKeyRef = React.useRef(getColumnKey);
+  getColumnKeyRef.current = getColumnKey;
+  const getScrollElementRef = React.useRef(getScrollElement);
+  getScrollElementRef.current = getScrollElement;
+
+  const estimateSize = React.useCallback(
+    (index: number) => getColumnWidthRef.current(index),
+    []
+  );
+  const getItemKey = React.useCallback(
+    (index: number) => getColumnKeyRef.current?.(index) ?? index,
+    []
+  );
+  const getScrollElementStable = React.useCallback(() => getScrollElementRef.current(), []);
+
+  const geometry = React.useMemo(
+    () => computeColumnGeometry(columnCount, (i) => getColumnWidthRef.current(i), {
+      leadingWidth,
+      trailingWidth,
+    }),
+    // getColumnWidth is read through a ref, so `widthRevision` is what makes the
+    // prefix sums recompute after a resize.
+    [columnCount, leadingWidth, trailingWidth, widthRevision]
+  );
+
+  const virtualizer = useVirtualizer({
+    count: columnCount,
+    getScrollElement: getScrollElementStable,
+    estimateSize,
+    getItemKey,
+    horizontal: true,
+    // We own overscan (see module comment) — the library gives us the bare
+    // intersecting range.
+    overscan: 0,
+    enabled,
+  });
+
+  // Widths are model-held and mutable, so a resize must invalidate the library's
+  // size cache explicitly. `measure()` clears it and re-reads `estimateSize`.
+  React.useEffect(() => {
+    if (!enabled) return;
+    virtualizer.measure();
+  }, [enabled, widthRevision, columnCount, virtualizer]);
+
+  const virtualItems = enabled ? virtualizer.getVirtualItems() : [];
+  const baseRange: ColumnRange | null =
+    virtualItems.length > 0
+      ? {
+          startIndex: virtualItems[0].index,
+          endIndex: virtualItems[virtualItems.length - 1].index,
+        }
+      : null;
+
+  const pinnedLeftKey = useIndexListKey(pinnedLeftIndices);
+  const pinnedRightKey = useIndexListKey(pinnedRightIndices);
+  const forcedKey = useIndexListKey(forcedIndices);
+
+  const columnWindow = React.useMemo<ColumnWindow>(() => {
+    const getKey = getColumnKeyRef.current;
+    // Disabled, or enabled but not measured yet (SSR, first paint, a zero-width
+    // scroller). FAIL OPEN: mount everything. Correct-but-slow is the only
+    // acceptable failure direction — the alternative paints an empty grid.
+    if (!enabled || baseRange === null) {
+      return createFullColumnWindow(geometry, {
+        pinnedLeftIndices,
+        pinnedRightIndices,
+        getColumnKey: getKey,
+      });
+    }
+    return buildColumnWindow({
+      geometry,
+      range: baseRange,
+      overscan,
+      pinnedLeftIndices,
+      pinnedRightIndices,
+      forcedIndices,
+      getColumnKey: getKey,
+    });
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [
+    enabled,
+    geometry,
+    baseRange?.startIndex,
+    baseRange?.endIndex,
+    baseRange === null,
+    overscan,
+    pinnedLeftKey,
+    pinnedRightKey,
+    forcedKey,
+  ]);
+
+  const scrollToColumn = React.useCallback(
+    (
+      columnIndex: number,
+      scrollOptions?: { align?: ColumnScrollAlign; behavior?: ScrollBehavior }
+    ) => {
+      const element = getScrollElementRef.current();
+      if (!element) return;
+      const target = computeScrollLeftToReveal(geometry, columnIndex, {
+        scrollLeft: element.scrollLeft,
+        viewportWidth: element.clientWidth,
+        pinnedLeftWidth: columnWindow.pinnedLeftWidth,
+        pinnedRightWidth: columnWindow.pinnedRightWidth,
+        align: scrollOptions?.align,
+        pinnedIndices: columnWindow.mountedIndices.length
+          ? [...(pinnedLeftIndices ?? []), ...(pinnedRightIndices ?? [])]
+          : undefined,
+      });
+      if (target === null) return;
+      if (typeof element.scrollTo === 'function') {
+        element.scrollTo({ left: target, behavior: scrollOptions?.behavior ?? 'auto' });
+      } else {
+        element.scrollLeft = target;
+      }
+    },
+    [geometry, columnWindow, pinnedLeftIndices, pinnedRightIndices]
+  );
+
+  const measure = React.useCallback(() => virtualizer.measure(), [virtualizer]);
+
+  const ariaColCount = React.useMemo(
+    () => getAriaColCount(columnCount, { hasRowHeader, hasActionsColumn }),
+    [columnCount, hasRowHeader, hasActionsColumn]
+  );
+  const ariaColIndexFor = React.useCallback(
+    (columnIndex: number) => getAriaColIndex(columnIndex, { hasRowHeader }),
+    [hasRowHeader]
+  );
+
+  return React.useMemo<ColumnVirtualizer>(
+    () => ({
+      ...columnWindow,
+      ariaColCount,
+      getAriaColIndex: ariaColIndexFor,
+      scrollToColumn,
+      measure,
+      geometry,
+    }),
+    [columnWindow, ariaColCount, ariaColIndexFor, scrollToColumn, measure, geometry]
+  );
+}
+
+export default useColumnVirtualizer;