@freighttech/ui 0.13.18

package/src/backend/dynamic-table/components/ImportPanel.tsx

@@ -0,0 +1,445 @@
+'use client';
+
+/**
+ * Import from a file: choose → inspect → commit → (undo).
+ *
+ * The panel is deliberately thin. It uploads bytes and renders whatever the
+ * server made of them; it does NOT parse the file, because a client parse plus
+ * a server parse is how a preview and its commit drift apart. `importParse.ts`
+ * is server-only and is never imported here.
+ *
+ * The inspection point is mandatory, not a toggle: there is no code path from
+ * "file chosen" to "records written" that skips the preview. Import is the
+ * highest-blast-radius write in the product, and "nothing is saved yet" is the
+ * property that makes it safe to use.
+ */
+import React, { useCallback, useMemo, useRef, useState } from 'react';
+import { AlertTriangle, FileSpreadsheet, Undo2, Upload } from 'lucide-react';
+import { useT } from '@open-mercato/shared/lib/i18n/context';
+import { Button } from '../../../primitives/button';
+import { apiCall } from '../../utils/apiCall';
+import { flash } from '../../FlashMessages';
+import ImportPreviewGrid from './ImportPreviewGrid';
+import type {
+  ImportCommitResponse,
+  ImportMapping,
+  ImportMode,
+  ImportPreviewResponse,
+  ImportRevertResponse,
+} from '../types/import';
+
+export interface ImportPanelProps {
+  /** `POST` multipart endpoint that returns an `ImportPreviewResponse`. */
+  previewUrl: string;
+  /** Given a batch id, the endpoint that commits it. */
+  commitUrl: (importBatchId: string) => string;
+  /** Given a batch id, the endpoint that reverts it. */
+  revertUrl: (importBatchId: string) => string;
+  /** Modes to offer. Defaults to both. */
+  modes?: ImportMode[];
+  /** Called after a successful commit (and after a revert) so the list refetches. */
+  onChanged?: () => void;
+  /** Called when the user cancels out of the panel. */
+  onClose?: () => void;
+}
+
+type Phase = 'choose' | 'preview' | 'committed';
+
+const ACCEPT = '.csv,.xlsx,text/csv,application/vnd.openxmlformats-officedocument.spreadsheetml.sheet';
+
+interface ServerError {
+  error?: string;
+  messageKey?: string;
+  details?: Record<string, unknown>;
+}
+
+const ImportPanel: React.FC<ImportPanelProps> = ({
+  previewUrl,
+  commitUrl,
+  revertUrl,
+  modes = ['create', 'upsert_id'],
+  onChanged,
+  onClose,
+}) => {
+  const t = useT();
+  const fileInputRef = useRef<HTMLInputElement | null>(null);
+
+  const [phase, setPhase] = useState<Phase>('choose');
+  const [busy, setBusy] = useState(false);
+  const [file, setFile] = useState<File | null>(null);
+  const [mode, setMode] = useState<ImportMode>(modes[0] ?? 'create');
+  const [preview, setPreview] = useState<ImportPreviewResponse | null>(null);
+  const [commitResult, setCommitResult] = useState<ImportCommitResponse | null>(null);
+  const [errorText, setErrorText] = useState<string | null>(null);
+
+  const modeLabels: Record<ImportMode, string> = useMemo(
+    () => ({
+      create: t('dynamicTable.import.modeCreate', 'Add new rows'),
+      upsert_id: t('dynamicTable.import.modeUpsertId', 'Update rows matched by id'),
+    }),
+    [t],
+  );
+
+  /** Turn a server error body into something a person can act on. */
+  const describeError = useCallback(
+    (body: ServerError | null, fallback: string): string => {
+      if (!body) return fallback;
+      if (body.messageKey === 'dynamicTable.import.tooManyRows') {
+        return t(
+          'dynamicTable.import.tooManyRows',
+          'This file has {count} rows; the limit is {limit}. Split it and import in parts.',
+          body.details as Record<string, string | number> | undefined,
+        );
+      }
+      if (body.messageKey) {
+        return t(
+          body.messageKey,
+          body.error ?? fallback,
+          body.details as Record<string, string | number> | undefined,
+        );
+      }
+      return body.error ?? fallback;
+    },
+    [t],
+  );
+
+  const runPreview = useCallback(
+    async (nextFile: File, nextMode: ImportMode, mapping?: ImportMapping) => {
+      setBusy(true);
+      setErrorText(null);
+      try {
+        const form = new FormData();
+        form.append('file', nextFile);
+        form.append('mode', nextMode);
+        if (mapping) form.append('mapping', JSON.stringify(mapping));
+
+        const { ok, result } = await apiCall<ImportPreviewResponse & ServerError>(previewUrl, {
+          method: 'POST',
+          body: form,
+        });
+        if (!ok || !result || !('importBatchId' in result)) {
+          setErrorText(
+            describeError(
+              result as ServerError | null,
+              t('dynamicTable.import.previewFailed', 'The file could not be read'),
+            ),
+          );
+          return;
+        }
+        setPreview(result as ImportPreviewResponse);
+        setPhase('preview');
+      } finally {
+        setBusy(false);
+      }
+    },
+    [previewUrl, describeError, t],
+  );
+
+  const onFileChosen = useCallback(
+    (chosen: File | null) => {
+      if (!chosen) return;
+      setFile(chosen);
+      setCommitResult(null);
+      void runPreview(chosen, mode);
+    },
+    [mode, runPreview],
+  );
+
+  const onModeChange = useCallback(
+    (next: ImportMode) => {
+      setMode(next);
+      // Re-previewing is the whole point: a different mode is a different set
+      // of decisions, and showing the old preview beside the new mode would be
+      // a lie.
+      if (file) void runPreview(file, next, preview?.mapping);
+    },
+    [file, preview, runPreview],
+  );
+
+  const onCommit = useCallback(async () => {
+    if (!preview) return;
+    setBusy(true);
+    setErrorText(null);
+    try {
+      const { ok, result } = await apiCall<ImportCommitResponse & ServerError>(
+        commitUrl(preview.importBatchId),
+        { method: 'POST' },
+      );
+      if (!ok || !result || !('created' in result)) {
+        setErrorText(
+          describeError(
+            result as ServerError | null,
+            t('dynamicTable.import.commitFailed', 'The import could not be completed'),
+          ),
+        );
+        return;
+      }
+      setCommitResult(result as ImportCommitResponse);
+      setPhase('committed');
+      flash(
+        t('dynamicTable.import.summary', '{created} new, {updated} updated, {skipped} skipped, {failed} with errors', {
+          created: result.created,
+          updated: result.updated,
+          skipped: preview.summary.skipped,
+          failed: result.failed,
+        }),
+        'success',
+      );
+      onChanged?.();
+    } finally {
+      setBusy(false);
+    }
+  }, [preview, commitUrl, describeError, onChanged, t]);
+
+  const onRevert = useCallback(async () => {
+    if (!commitResult) return;
+    setBusy(true);
+    setErrorText(null);
+    try {
+      const { ok, result } = await apiCall<ImportRevertResponse & ServerError>(
+        revertUrl(commitResult.importBatchId),
+        { method: 'POST' },
+      );
+      if (!ok || !result || !('restored' in result)) {
+        setErrorText(
+          describeError(
+            result as ServerError | null,
+            t('dynamicTable.import.revertFailed', 'The import could not be undone'),
+          ),
+        );
+        return;
+      }
+      const reverted = result.restored + result.deleted;
+      flash(t('dynamicTable.import.reverted', 'Reverted {count} rows', { count: reverted }), 'success');
+      if (result.refused.length) {
+        // Refusals are surfaced, never swallowed: a partial revert the user
+        // does not know about is worse than no revert.
+        flash(
+          t(
+            'dynamicTable.import.revertRefused',
+            '{count} rows were changed since the import and were left alone',
+            { count: result.refused.length },
+          ),
+          'error',
+        );
+      }
+      onChanged?.();
+      onClose?.();
+    } finally {
+      setBusy(false);
+    }
+  }, [commitResult, revertUrl, describeError, onChanged, onClose, t]);
+
+  const reset = useCallback(() => {
+    setPhase('choose');
+    setFile(null);
+    setPreview(null);
+    setCommitResult(null);
+    setErrorText(null);
+    if (fileInputRef.current) fileInputRef.current.value = '';
+  }, []);
+
+  return (
+    <div className="flex flex-col gap-4" data-testid="import-panel">
+      <div>
+        <h3 className="text-heading-bold-lg">{t('dynamicTable.import.title', 'Import from file')}</h3>
+      </div>
+
+      {errorText ? (
+        <div
+          className="flex items-start gap-2 rounded-md border border-destructive/40 bg-destructive/10 p-3"
+          role="alert"
+          data-testid="import-error"
+        >
+          <AlertTriangle className="mt-0.5 size-4 text-destructive" aria-hidden />
+          <p className="text-body-regular-sm text-destructive">{errorText}</p>
+        </div>
+      ) : null}
+
+      {/* ── Choose ─────────────────────────────────────────────────── */}
+      {phase === 'choose' ? (
+        <div className="flex flex-col gap-3">
+          {/* A `<span>`, not a `<label htmlFor>`. `htmlFor` only binds to a form
+              control, and the target here is a `<div>` of buttons — so the
+              caption was announced as loose text and the group had no name at
+              all. `aria-labelledby` on a `role="group"` is the binding that
+              actually works. */}
+          <span className="text-label-medium-md" id="import-mode-label">
+            {t('dynamicTable.import.mode', 'What should this file do?')}
+          </span>
+          <div
+            className="flex flex-wrap gap-2"
+            role="group"
+            aria-labelledby="import-mode-label"
+          >
+            {modes.map((m) => (
+              <Button
+                key={m}
+                type="button"
+                size="sm"
+                variant={m === mode ? 'default' : 'outline'}
+                // Which mode is chosen was carried by fill colour alone, so it
+                // did not survive a screen reader (or greyscale). `aria-pressed`
+                // states it.
+                aria-pressed={m === mode}
+                onClick={() => setMode(m)}
+                data-testid={`import-mode-${m}`}
+              >
+                {modeLabels[m]}
+              </Button>
+            ))}
+          </div>
+
+          <button
+            type="button"
+            className="flex flex-col items-center justify-center gap-2 rounded-lg border border-dashed border-border p-8 hover:bg-accent"
+            onClick={() => fileInputRef.current?.click()}
+            disabled={busy}
+            data-testid="import-dropzone"
+          >
+            <Upload className="size-6 text-muted-foreground" aria-hidden />
+            <span className="text-body-regular-sm text-muted-foreground">
+              {t('dynamicTable.import.dropFile', 'Drop a CSV or Excel file, or browse')}
+            </span>
+          </button>
+          <input
+            ref={fileInputRef}
+            type="file"
+            accept={ACCEPT}
+            className="sr-only"
+            data-testid="import-file-input"
+            onChange={(e) => onFileChosen(e.target.files?.[0] ?? null)}
+          />
+        </div>
+      ) : null}
+
+      {/* ── Preview — nothing is written yet ───────────────────────── */}
+      {phase === 'preview' && preview ? (
+        <div className="flex flex-col gap-3">
+          <div className="flex flex-wrap items-center gap-2">
+            <FileSpreadsheet className="size-4 text-muted-foreground" aria-hidden />
+            <span className="text-body-medium-sm">{preview.sourceFileName}</span>
+            <span className="text-body-regular-xs text-muted-foreground">{modeLabels[preview.mode]}</span>
+          </div>
+
+          <h4 className="text-heading-semibold-md" data-testid="import-preview-heading">
+            {t('dynamicTable.import.previewHeading', 'Review {count} rows before importing', {
+              count: preview.rows.length,
+            })}
+          </h4>
+          <p className="text-body-regular-sm text-muted-foreground" data-testid="import-summary">
+            {t(
+              'dynamicTable.import.summary',
+              '{created} new, {updated} updated, {skipped} skipped, {failed} with errors',
+              {
+                created: preview.summary.created,
+                updated: preview.summary.updated,
+                skipped: preview.summary.skipped,
+                failed: preview.summary.failed,
+              },
+            )}
+          </p>
+
+          {preview.mappingIssues.length ? (
+            <ul className="flex flex-col gap-1" data-testid="import-mapping-issues">
+              {preview.mappingIssues.map((issue, i) => (
+                <li key={`${issue.code}-${issue.label}-${i}`} className="text-body-regular-xs text-muted-foreground">
+                  {issue.code === 'relation_unsupported'
+                    ? t(
+                        'dynamicTable.import.relationUnsupported',
+                        '{column} links to another record and cannot be imported here',
+                        { column: issue.label },
+                      )
+                    : issue.code === 'missing_required'
+                      ? t('dynamicTable.import.missingRequired', '{column} is required and is not in this file', {
+                          column: issue.label,
+                        })
+                      : issue.code === 'duplicate_field'
+                        ? t('dynamicTable.import.duplicateField', 'Two columns both map to {column}', {
+                            column: issue.label,
+                          })
+                        : t('dynamicTable.import.unknownField', '{column} does not match any field', {
+                            column: issue.label,
+                          })}
+                </li>
+              ))}
+            </ul>
+          ) : null}
+
+          <ImportPreviewGrid rows={preview.rows} fields={preview.fields} mapping={preview.mapping} />
+
+          <p className="text-body-regular-xs text-muted-foreground" data-testid="import-cancel-safe">
+            {t('dynamicTable.import.cancelSafe', 'Nothing has been saved yet')}
+          </p>
+
+          <div className="flex flex-wrap gap-2">
+            <Button
+              type="button"
+              onClick={onCommit}
+              disabled={busy || preview.summary.created + preview.summary.updated === 0}
+              data-testid="import-commit"
+            >
+              {t('dynamicTable.import.commit', 'Import {count} rows', {
+                count: preview.summary.created + preview.summary.updated,
+              })}
+            </Button>
+            <Button type="button" variant="outline" onClick={reset} disabled={busy} data-testid="import-cancel">
+              {t('dynamicTable.import.cancel', 'Cancel')}
+            </Button>
+            {modes.length > 1
+              ? modes
+                  .filter((m) => m !== preview.mode)
+                  .map((m) => (
+                    <Button
+                      key={m}
+                      type="button"
+                      variant="ghost"
+                      onClick={() => onModeChange(m)}
+                      disabled={busy}
+                      data-testid={`import-switch-mode-${m}`}
+                    >
+                      {modeLabels[m]}
+                    </Button>
+                  ))
+              : null}
+          </div>
+        </div>
+      ) : null}
+
+      {/* ── Committed — undo is offered right here, while it still matters ── */}
+      {phase === 'committed' && commitResult ? (
+        <div className="flex flex-col gap-3" data-testid="import-result">
+          <p className="text-body-regular-sm">
+            {t(
+              'dynamicTable.import.summary',
+              '{created} new, {updated} updated, {skipped} skipped, {failed} with errors',
+              {
+                created: commitResult.created,
+                updated: commitResult.updated,
+                skipped: preview?.summary.skipped ?? 0,
+                failed: commitResult.failed,
+              },
+            )}
+          </p>
+          <div className="flex flex-wrap gap-2">
+            <Button
+              type="button"
+              variant="outline"
+              onClick={onRevert}
+              disabled={busy}
+              data-testid="import-revert"
+            >
+              <Undo2 className="size-4" aria-hidden />
+              {t('dynamicTable.import.revert', 'Undo this import')}
+            </Button>
+            <Button type="button" variant="ghost" onClick={() => { reset(); onClose?.(); }} disabled={busy}>
+              {t('dynamicTable.import.done', 'Done')}
+            </Button>
+          </div>
+        </div>
+      ) : null}
+    </div>
+  );
+};
+
+export default ImportPanel;

package/src/backend/dynamic-table/components/ImportPreviewGrid.tsx

@@ -0,0 +1,155 @@
+'use client';
+
+/**
+ * The dry-run preview, rendered in a DynamicTable.
+ *
+ * Deliberately the same grid the user already reads their data in: an import
+ * preview is a table of rows, and inventing a bespoke preview widget would
+ * mean a second set of column, scroll and selection behaviours to learn.
+ * `options.root` on `GridHarness` exists precisely so a nested grid like this
+ * one can be driven independently of the page's main table.
+ */
+import React, { useMemo, useRef } from 'react';
+import { useT } from '@open-mercato/shared/lib/i18n/context';
+import DynamicTable from '../DynamicTable';
+import type { ColumnDef, DynamicTableBadgeVariant } from '../types/index';
+import type {
+  ImportFieldDef,
+  ImportMapping,
+  ImportPreviewRow,
+} from '../types/import';
+
+export interface ImportPreviewGridProps {
+  rows: ImportPreviewRow[];
+  fields: ImportFieldDef[];
+  /** The mapping actually applied — decides which field columns are shown. */
+  mapping: ImportMapping;
+  height?: number;
+}
+
+/** Internal row shape: the grid needs flat, string-keyed data. */
+const ROW_NUMBER_KEY = '__sourceRowNumber';
+const ACTION_KEY = '__action';
+const ERRORS_KEY = '__errors';
+
+const ACTION_BADGES: Record<string, DynamicTableBadgeVariant> = {
+  created: 'success',
+  updated: 'info',
+  skipped: 'neutral',
+  failed: 'error',
+};
+
+const ImportPreviewGrid: React.FC<ImportPreviewGridProps> = ({
+  rows,
+  fields,
+  mapping,
+  height = 360,
+}) => {
+  const t = useT();
+  const tableRef = useRef<HTMLDivElement | null>(null);
+
+  // Only the fields this file actually maps onto get a column. Showing all
+  // forty importable fields for a three-column CSV buries the three that matter.
+  const mappedFields = useMemo(() => {
+    const targets = new Set(Object.values(mapping));
+    return fields.filter((f) => targets.has(f.field));
+  }, [fields, mapping]);
+
+  const data = useMemo(
+    () =>
+      rows.map((row) => {
+        const errorsByField = new Map(row.errors.map((e) => [e.field, e.message]));
+        const flat: Record<string, unknown> = {
+          id: String(row.sourceRowNumber),
+          [ROW_NUMBER_KEY]: row.sourceRowNumber,
+          [ACTION_KEY]: row.action,
+          [ERRORS_KEY]: row.errors.map((e) => e.message).join('; '),
+        };
+        for (const field of mappedFields) {
+          flat[field.field] = row.values[field.field] ?? '';
+        }
+        // Per-cell error lookup, consumed by `cellClassName` below.
+        flat.__errorFields = errorsByField;
+        return flat;
+      }),
+    [rows, mappedFields],
+  );
+
+  const columns = useMemo<ColumnDef[]>(() => {
+    const cols: ColumnDef[] = [
+      {
+        data: ROW_NUMBER_KEY,
+        title: t('dynamicTable.import.columnRow', 'Row'),
+        type: 'numeric',
+        width: 70,
+        align: 'right',
+        mono: true,
+        readOnly: true,
+      },
+      {
+        data: ACTION_KEY,
+        title: t('dynamicTable.import.columnOutcome', 'Outcome'),
+        type: 'text',
+        width: 110,
+        badge: true,
+        badgeVariant: (value: unknown) => ACTION_BADGES[String(value)] ?? 'neutral',
+        readOnly: true,
+      },
+    ];
+
+    for (const field of mappedFields) {
+      cols.push({
+        data: field.field,
+        title: field.label,
+        type: field.type === 'numeric' ? 'numeric' : 'text',
+        align: field.type === 'numeric' ? 'right' : 'left',
+        mono: field.type === 'numeric' || field.type === 'date',
+        readOnly: true,
+        // A failing cell is marked where the failure is, not just on the row —
+        // "row 43 is invalid" sends the user hunting across forty columns.
+        cellClassName: (_value: unknown, rowData: any) =>
+          (rowData?.__errorFields as Map<string, string> | undefined)?.has(field.field)
+            ? 'bg-destructive/10'
+            : undefined,
+      });
+    }
+
+    cols.push({
+      data: ERRORS_KEY,
+      title: t('dynamicTable.import.columnProblem', 'Problem'),
+      type: 'text',
+      width: 280,
+      readOnly: true,
+    });
+
+    return cols;
+  }, [mappedFields, t]);
+
+  return (
+    <div data-testid="import-preview-grid">
+      <DynamicTable
+        tableRef={tableRef}
+        data={data}
+        // Rows are the in-memory import preview the caller already parsed —
+        // there is no fetch here that could fail. HEDGE-123.
+        loadError={false}
+        columns={columns}
+        colHeaders
+        idColumnName="id"
+        tableName={t('dynamicTable.import.previewTableName', 'Import preview')}
+        height={height}
+        emptyMessage={t('dynamicTable.import.previewEmpty', 'No rows to preview')}
+        uiConfig={{
+          hideToolbar: true,
+          hidePerspectiveTabs: true,
+          hidePagination: true,
+          hideActionsColumn: true,
+          hideAddRowButton: true,
+          hideExportButton: true,
+        }}
+      />
+    </div>
+  );
+};
+
+export default ImportPreviewGrid;

package/src/backend/dynamic-table/components/LoadErrorState.tsx

@@ -0,0 +1,70 @@
+'use client'
+
+import React from 'react';
+import { AlertTriangle } from 'lucide-react';
+import { useT } from '@open-mercato/shared/lib/i18n/context';
+import { Button } from '../../../primitives-v2';
+
+export interface LoadErrorStateProps {
+  /** Host label for the dataset, e.g. "Invoices". Used to name what failed. */
+  tableName?: string;
+  /** Re-runs the list request. Omit only when the host cannot refetch. */
+  onRetry?: () => void;
+}
+
+/**
+ * What a DynamicTable shows when the list request FAILED (HEDGE-119).
+ *
+ * THE POINT IS THAT THIS IS NOT `EmptyState`. Until this component existed the
+ * two situations were rendered by the same branch — `rowCount === 0` — because
+ * a failed query leaves `dataQuery.data` undefined and `data` therefore `[]`.
+ * An HTTP 500 and a genuinely empty table were byte-identical on screen, down
+ * to the Inbox icon and the words "Nothing here yet".
+ *
+ * That is not a cosmetic problem. The reported case was the invoice queue: the
+ * endpoint 500'd, the accountant read "Nothing here yet" as "no invoices are
+ * waiting for me", and 17 unpaid documents sat unbooked. A table that cannot
+ * reach the server must never claim to know what the server contains — the
+ * honest statement is "I do not know", and that is what this renders.
+ *
+ * So the wording is deliberately about the FETCH, not about the data: it says
+ * the rows could not be loaded, states outright that this does not mean the
+ * table is empty, and offers the only action that can help (retry). No icon or
+ * phrasing is shared with `EmptyState`; the two states must not be mistakable
+ * for each other at a glance, which is precisely how this defect survived.
+ *
+ * Rendered UNDER the column headers, exactly like `EmptyState` — the headers
+ * are the context that says which table you are looking at, and they are still
+ * true when the body could not load.
+ */
+const LoadErrorState: React.FC<LoadErrorStateProps> = ({ tableName, onRetry }) => {
+  const t = useT();
+
+  const title = tableName
+    ? t('dynamicTable.loadError.titleNamed', 'Could not load {name}', { name: tableName })
+    : t('dynamicTable.loadError.title', 'Could not load these rows');
+
+  return (
+    <div className="hot-empty-message" role="alert" data-load-error="">
+      <div className="hot-empty-state hot-load-error-state">
+        <AlertTriangle className="hot-empty-state-icon hot-load-error-icon" aria-hidden="true" />
+        <p className="hot-empty-state-title text-body-medium-md">{title}</p>
+        <p className="hot-empty-state-detail text-body-regular-sm">
+          {t(
+            'dynamicTable.loadError.detail',
+            'The server did not answer this request, so the rows below are unknown — this does NOT mean the table is empty. Retry, and if it keeps failing report it rather than treating the list as complete.',
+          )}
+        </p>
+        {onRetry && (
+          <div className="hot-empty-state-actions">
+            <Button variant="outline" size="sm" onClick={onRetry} data-load-error-retry="">
+              {t('dynamicTable.loadError.retry', 'Try again')}
+            </Button>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+};
+
+export default LoadErrorState;