@burdenoff/microfe-movethewheels 2026.1031.2 → 2026.1031.3

package/src/movethewheels/hooks/useEntityImport.ts

@@ -0,0 +1,108 @@
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
+import { executeGraphQL } from '../utils/graphqlClient';
+import {
+  MTW_IMPORT_MAX_BYTES,
+  MTW_IMPORT_SPEC_QUERY,
+  importEntity,
+  importMutation,
+  type MtwImportEntitySpec,
+  type MtwImportEntityType,
+  type MtwImportFormat,
+  type MtwImportResult,
+} from '../utils/entityImport';
+
+function useGraphQLOptions() {
+  const { apiGatewayUrl, authToken, workspaceToken, workspaceId, tenantId, currentUser } =
+    useMoveTheWheels();
+  return useMemo(
+    () => ({
+      apiGatewayUrl,
+      authToken,
+      workspaceToken,
+      workspaceId,
+      tenantId,
+      actorId: currentUser?.id,
+    }),
+    [apiGatewayUrl, authToken, workspaceToken, workspaceId, tenantId, currentUser?.id]
+  );
+}
+
+/** Column specification for every importable entity. */
+export function useImportSpec() {
+  const graphQLOptions = useGraphQLOptions();
+  const [specs, setSpecs] = useState<MtwImportEntitySpec[]>([]);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  useEffect(() => {
+    if (!graphQLOptions.workspaceId) return;
+    let cancelled = false;
+    setIsLoading(true);
+    executeGraphQL<{ mtwImportSpec: MtwImportEntitySpec[] }>(graphQLOptions, MTW_IMPORT_SPEC_QUERY)
+      .then((data) => {
+        if (cancelled) return;
+        setSpecs(data.mtwImportSpec);
+        setError(null);
+      })
+      .catch((caught: unknown) => {
+        if (!cancelled)
+          setError(caught instanceof Error ? caught : new Error('Could not load import columns'));
+      })
+      .finally(() => {
+        if (!cancelled) setIsLoading(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [graphQLOptions]);
+
+  return { specs, isLoading, error };
+}
+
+export interface ImportRequest {
+  entityType: MtwImportEntityType;
+  format: MtwImportFormat;
+  content: string;
+  dryRun: boolean;
+  allowPartial: boolean;
+}
+
+/** Runs a validation or an import. Writes are sent once: a retry could create rows twice. */
+export function useEntityImport() {
+  const graphQLOptions = useGraphQLOptions();
+  const [isRunning, setIsRunning] = useState(false);
+
+  const run = useCallback(
+    async (request: ImportRequest): Promise<MtwImportResult> => {
+      if (new Blob([request.content]).size > MTW_IMPORT_MAX_BYTES) {
+        throw new Error('The file is larger than 2 MB. Split it into smaller files.');
+      }
+      const { field } = importEntity(request.entityType);
+      setIsRunning(true);
+      try {
+        const data = await executeGraphQL<Record<string, MtwImportResult>>(
+          graphQLOptions,
+          importMutation(request.entityType),
+          {
+            input: {
+              format: request.format,
+              content: request.content,
+              dryRun: request.dryRun,
+              allowPartial: request.allowPartial,
+            },
+          },
+          request.dryRun ? 'RETRY_TRANSIENT' : 'SINGLE_ATTEMPT'
+        );
+        const result = data[field];
+        if (!result) throw new Error('The import returned no result');
+        return result;
+      } finally {
+        setIsRunning(false);
+      }
+    },
+    [graphQLOptions]
+  );
+
+  return { run, isRunning };
+}

package/src/movethewheels/pages/CustomersPage.tsx

@@ -3,7 +3,7 @@
  */
 
 import { useState } from 'react';
-import { Users, Plus, RefreshCw, Download, Star, Building2 } from 'lucide-react';
+import { Users, Plus, RefreshCw, Download, Star, Building2, Upload } from 'lucide-react';
 import { PageLayout } from '../components/PageLayout';
 import { MetricCard, MetricGrid } from '../components/MetricCard';
 import { DataTable, type Column } from '../components/DataTable';
@@ -111,6 +111,11 @@ export default function CustomersPage() {
           }}
           actions={[
             { label: 'Refresh', icon: <RefreshCw size={16} />, onSelect: () => refetch() },
+            {
+              label: 'Import',
+              icon: <Upload size={16} />,
+              onSelect: () => goTo('import-export?entity=CUSTOMER'),
+            },
             {
               label: isExporting ? 'Exporting…' : 'Export',
               icon: <Download size={16} />,

package/src/movethewheels/pages/DriversPage.tsx

@@ -14,6 +14,7 @@ import {
   UserMinus,
   Filter,
   Truck,
+  Upload,
 } from 'lucide-react';
 import { PageLayout } from '../components/PageLayout';
 import { MetricCard, MetricGrid } from '../components/MetricCard';
@@ -231,6 +232,11 @@ export default function DriversPage() {
           }}
           actions={[
             { label: 'Refresh', icon: <RefreshCw size={16} />, onSelect: () => refetch() },
+            {
+              label: 'Import',
+              icon: <Upload size={16} />,
+              onSelect: () => goTo('import-export?entity=DRIVER'),
+            },
             {
               label: isExporting ? 'Exporting…' : 'Export',
               icon: <Download size={16} />,

package/src/movethewheels/pages/ImportExportPage.tsx

@@ -0,0 +1,483 @@
+/**
+ * Import / Export Page (BOFF-3990)
+ *
+ * Bulk data in and out of MoveTheWheels. Import validates a CSV or JSON file
+ * row by row on the server (dry run first, then import) for customers,
+ * vehicles, drivers, warehouses and products. Export starts the same
+ * `exportMtwEntities` job the list pages use and downloads the archive.
+ */
+
+import { useMemo, useRef, useState, type ChangeEvent } from 'react';
+import { useSearchParams } from 'react-router';
+import {
+  AlertCircle,
+  ArrowDownUp,
+  CheckCircle,
+  Download,
+  FileSpreadsheet,
+  FileUp,
+  Info,
+  Loader2,
+  ShieldCheck,
+  Upload,
+} from 'lucide-react';
+import { EmphasisPanel, PagePurpose } from '@burdenoff/fe-libs/ui';
+import { PageLayout } from '../components/PageLayout';
+import { ExportStatusBanner } from '../components/ExportStatusBanner';
+import {
+  Badge,
+  Button,
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+  Checkbox,
+  Label,
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+  Skeleton,
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '../components/ui';
+import { useEntityExport } from '../hooks/useEntityExport';
+import { useEntityImport, useImportSpec } from '../hooks/useEntityImport';
+import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
+import {
+  MTW_IMPORT_ENTITIES,
+  MTW_IMPORT_MAX_ROWS,
+  buildCsvTemplate,
+  detectImportFormat,
+  importEntity,
+  isImportEntityType,
+  summariseImport,
+  type MtwImportColumn,
+  type MtwImportEntityType,
+  type MtwImportFormat,
+  type MtwImportResult,
+} from '../utils/entityImport';
+import type { MtwExportEntity } from '../utils/entityExport';
+import { joinPath } from '../utils/navigation';
+
+/** Where each imported entity is listed, relative to the MFE base path. */
+const LIST_PATHS: Record<MtwImportEntityType, string> = {
+  CUSTOMER: 'customers',
+  VEHICLE: 'fleet/vehicles',
+  DRIVER: 'fleet/drivers',
+  WAREHOUSE: 'inventory/warehouses',
+  CARGO_ITEM: 'inventory/products',
+};
+
+const EXPORT_OPTIONS: Array<{ entity: MtwExportEntity; label: string; noun: string }> = [
+  { entity: 'orders', label: 'Orders', noun: 'order' },
+  { entity: 'customers', label: 'Customers', noun: 'customer' },
+  { entity: 'vehicles', label: 'Vehicles', noun: 'vehicle' },
+  { entity: 'drivers', label: 'Drivers', noun: 'driver' },
+  { entity: 'products', label: 'Products', noun: 'product' },
+];
+
+interface SelectedFile {
+  name: string;
+  format: MtwImportFormat;
+  content: string;
+}
+
+function downloadText(fileName: string, text: string, type: string): void {
+  const url = URL.createObjectURL(new Blob([text], { type }));
+  const anchor = document.createElement('a');
+  anchor.href = url;
+  anchor.download = fileName;
+  document.body.appendChild(anchor);
+  anchor.click();
+  anchor.remove();
+  URL.revokeObjectURL(url);
+}
+
+function columnRule(column: MtwImportColumn): string {
+  if (column.allowedValues?.length) return column.allowedValues.join(', ');
+  const parts: string[] = [column.type.toLowerCase()];
+  if (column.maxLength !== null) parts.push(`max ${column.maxLength} chars`);
+  if (column.min !== null && column.max !== null) parts.push(`${column.min} to ${column.max}`);
+  else if (column.min !== null) parts.push(`at least ${column.min}`);
+  return parts.join(', ');
+}
+
+function ImportResultPanel({
+  result,
+  noun,
+  onOpenList,
+}: {
+  result: MtwImportResult;
+  noun: string;
+  onOpenList: () => void;
+}) {
+  const failed = result.status === 'REJECTED' || (result.dryRun && result.failedRows > 0);
+  const tone = failed
+    ? 'border-status-error-border bg-status-error-bg-subtle text-status-error-text'
+    : result.status === 'PARTIAL'
+      ? 'border-status-warning-border bg-status-warning-bg-subtle text-status-warning-text'
+      : 'border-status-success-border bg-status-success-bg-subtle text-status-success-text';
+  const Icon = failed ? AlertCircle : CheckCircle;
+
+  return (
+    <div className="space-y-3" data-testid="mtw-import-result" data-status={result.status}>
+      <div
+        role={failed ? 'alert' : 'status'}
+        className={`flex items-start gap-2 rounded-lg border px-4 py-3 text-sm ${tone}`}
+      >
+        <Icon size={18} className="mt-0.5 shrink-0" />
+        <span className="flex-1">{summariseImport(result, noun)}</span>
+        {result.importedRows > 0 ? (
+          <button
+            type="button"
+            className="font-medium underline underline-offset-2"
+            onClick={onOpenList}
+          >
+            View {noun}s
+          </button>
+        ) : null}
+      </div>
+      <div className="flex flex-wrap gap-2 text-sm">
+        <Badge variant="outline">Rows: {result.totalRows}</Badge>
+        <Badge variant="outline">Valid: {result.validRows}</Badge>
+        <Badge variant="outline">Imported: {result.importedRows}</Badge>
+        <Badge variant={result.failedRows > 0 ? 'destructive' : 'outline'}>
+          Problems: {result.failedRows}
+        </Badge>
+      </div>
+      {result.errors.length > 0 ? (
+        <div className="max-h-80 overflow-auto rounded-lg border border-border-default">
+          <Table>
+            <TableHeader>
+              <TableRow>
+                <TableHead className="w-20">Row</TableHead>
+                <TableHead className="w-40">Column</TableHead>
+                <TableHead>Problem</TableHead>
+              </TableRow>
+            </TableHeader>
+            <TableBody>
+              {result.errors.map((error, index) => (
+                <TableRow key={`${error.row}-${error.field ?? ''}-${index}`}>
+                  <TableCell>{error.row}</TableCell>
+                  <TableCell className="font-mono text-xs">{error.field ?? '—'}</TableCell>
+                  <TableCell>{error.message}</TableCell>
+                </TableRow>
+              ))}
+            </TableBody>
+          </Table>
+        </div>
+      ) : null}
+      {result.errorsTruncated ? (
+        <p className="text-sm text-text-secondary">
+          Only the first {result.errors.length} problems are listed. Fix these and validate again to
+          see the rest.
+        </p>
+      ) : null}
+    </div>
+  );
+}
+
+function ExportRow({
+  entity,
+  label,
+  noun,
+}: {
+  entity: MtwExportEntity;
+  label: string;
+  noun: string;
+}) {
+  const { state, isExporting, startExport, dismiss } = useEntityExport(entity, noun);
+  return (
+    <div className="space-y-2 rounded-lg border border-border-default p-4">
+      <div className="flex items-center justify-between gap-3">
+        <div>
+          <p className="font-medium text-text-primary">{label}</p>
+          <p className="text-sm text-text-secondary">Every {noun} in this workspace, as CSV</p>
+        </div>
+        <Button
+          variant="outline"
+          size="sm"
+          disabled={isExporting}
+          aria-label={`Export ${label}`}
+          onClick={startExport}
+        >
+          {isExporting ? <Loader2 size={14} className="animate-spin" /> : <Download size={14} />}
+          <span className="ml-1">{isExporting ? 'Exporting…' : 'Export'}</span>
+        </Button>
+      </div>
+      <ExportStatusBanner state={state} onDismiss={dismiss} />
+    </div>
+  );
+}
+
+export default function ImportExportPage() {
+  const { basePath, navigate } = useMoveTheWheels();
+  const { specs, isLoading: specLoading, error: specError } = useImportSpec();
+  const { run, isRunning } = useEntityImport();
+  const [searchParams] = useSearchParams();
+  // List pages link here with ?entity=VEHICLE etc. to preselect what to import.
+  const [entityType, setEntityType] = useState<MtwImportEntityType>(() => {
+    const requested = searchParams.get('entity');
+    return isImportEntityType(requested) ? requested : 'CUSTOMER';
+  });
+  const [file, setFile] = useState<SelectedFile | null>(null);
+  const [allowPartial, setAllowPartial] = useState(false);
+  const [result, setResult] = useState<MtwImportResult | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [lastRun, setLastRun] = useState<'validate' | 'import' | null>(null);
+  const fileInputRef = useRef<HTMLInputElement | null>(null);
+
+  const entity = importEntity(entityType);
+  const spec = useMemo(
+    () => specs.find((candidate) => candidate.entityType === entityType) ?? null,
+    [specs, entityType]
+  );
+
+  const resetOutcome = () => {
+    setResult(null);
+    setError(null);
+    setLastRun(null);
+  };
+
+  const chooseEntity = (value: string) => {
+    if (!isImportEntityType(value)) return;
+    setEntityType(value);
+    setFile(null);
+    resetOutcome();
+  };
+
+  const onFileSelected = async (event: ChangeEvent<HTMLInputElement>) => {
+    const selected = event.target.files?.[0];
+    event.target.value = '';
+    resetOutcome();
+    if (!selected) return;
+    const format = detectImportFormat(selected.name, selected.type);
+    if (!format) {
+      setFile(null);
+      setError('Choose a .csv or .json file.');
+      return;
+    }
+    setFile({ name: selected.name, format, content: await selected.text() });
+  };
+
+  const submit = async (dryRun: boolean) => {
+    if (!file) return;
+    setError(null);
+    setLastRun(dryRun ? 'validate' : 'import');
+    try {
+      setResult(
+        await run({ entityType, format: file.format, content: file.content, dryRun, allowPartial })
+      );
+    } catch (caught) {
+      setResult(null);
+      setError(caught instanceof Error ? caught.message : 'The import could not be completed.');
+    }
+  };
+
+  const downloadTemplate = () => {
+    if (!spec) return;
+    downloadText(
+      `${entity.label.toLowerCase()}-import-template.csv`,
+      buildCsvTemplate(spec),
+      'text/csv'
+    );
+  };
+
+  const canImport = file !== null && !isRunning && result?.status !== 'COMPLETED';
+
+  return (
+    <PageLayout
+      title="Import / Export"
+      subtitle="Bring master data in from a file, or take a full copy out"
+      icon={<ArrowDownUp size={24} />}
+    >
+      <PagePurpose icon={<ArrowDownUp size={18} />}>
+        Onboard or migrate without re-keying: import customers, vehicles, drivers, warehouses or
+        products from CSV or JSON. Every row is checked before anything is saved, so you can fix a
+        file and try again. Export any dataset for accounting, BI tools or backups.
+      </PagePurpose>
+
+      <input
+        ref={fileInputRef}
+        type="file"
+        accept=".csv,.json,text/csv,application/json"
+        className="hidden"
+        data-testid="mtw-import-file"
+        onChange={(event) => void onFileSelected(event)}
+      />
+
+      <div className="grid grid-cols-1 gap-6 xl:grid-cols-3">
+        <EmphasisPanel className="space-y-5 xl:col-span-2">
+          <div className="flex flex-wrap items-center justify-between gap-3">
+            <h2 className="flex items-center gap-2 text-base font-semibold text-text-primary">
+              <Upload size={18} /> Import data
+            </h2>
+            <Badge variant="outline">CSV or JSON · up to {MTW_IMPORT_MAX_ROWS} rows · 2 MB</Badge>
+          </div>
+
+          <div className="grid grid-cols-1 gap-4 md:grid-cols-2">
+            <div className="space-y-2">
+              <Label htmlFor="mtw-import-entity">What are you importing?</Label>
+              <Select value={entityType} onValueChange={chooseEntity}>
+                <SelectTrigger id="mtw-import-entity" aria-label="Import type">
+                  <SelectValue />
+                </SelectTrigger>
+                <SelectContent>
+                  {MTW_IMPORT_ENTITIES.map((option) => (
+                    <SelectItem key={option.entityType} value={option.entityType}>
+                      {option.label}
+                    </SelectItem>
+                  ))}
+                </SelectContent>
+              </Select>
+            </div>
+            <div className="space-y-2">
+              <Label>File</Label>
+              <div className="flex flex-wrap items-center gap-2">
+                <Button variant="outline" onClick={() => fileInputRef.current?.click()}>
+                  <FileUp size={16} />
+                  <span className="ml-1">{file ? 'Choose another file' : 'Choose file'}</span>
+                </Button>
+                <Button
+                  variant="ghost"
+                  disabled={!spec}
+                  onClick={downloadTemplate}
+                  aria-label={`Download ${entity.label} CSV template`}
+                >
+                  <FileSpreadsheet size={16} />
+                  <span className="ml-1">Template</span>
+                </Button>
+              </div>
+              {file ? (
+                <p className="text-sm text-text-secondary" data-testid="mtw-import-file-name">
+                  {file.name} ({file.format})
+                </p>
+              ) : null}
+            </div>
+          </div>
+
+          <div className="flex items-start gap-2">
+            <Checkbox
+              id="mtw-import-partial"
+              checked={allowPartial}
+              onCheckedChange={(checked) => {
+                setAllowPartial(checked === true);
+                if (result && !result.dryRun) resetOutcome();
+              }}
+            />
+            <Label htmlFor="mtw-import-partial" className="text-sm font-normal leading-snug">
+              Import the valid rows even if some rows have problems. When this is off, a file with
+              any problem imports nothing.
+            </Label>
+          </div>
+
+          <div className="flex flex-wrap gap-2">
+            <Button
+              variant="outline"
+              disabled={!file || isRunning}
+              onClick={() => void submit(true)}
+            >
+              {isRunning && lastRun === 'validate' ? (
+                <Loader2 size={16} className="animate-spin" />
+              ) : (
+                <ShieldCheck size={16} />
+              )}
+              <span className="ml-1">Validate</span>
+            </Button>
+            <Button disabled={!canImport} onClick={() => void submit(false)}>
+              {isRunning && lastRun === 'import' ? (
+                <Loader2 size={16} className="animate-spin" />
+              ) : (
+                <Upload size={16} />
+              )}
+              <span className="ml-1">Import {entity.label.toLowerCase()}</span>
+            </Button>
+          </div>
+
+          {error ? (
+            <div
+              role="alert"
+              data-testid="mtw-import-error"
+              className="flex items-start gap-2 rounded-lg border border-status-error-border bg-status-error-bg-subtle px-4 py-3 text-sm text-status-error-text"
+            >
+              <AlertCircle size={18} className="mt-0.5 shrink-0" />
+              <span>{error}</span>
+            </div>
+          ) : null}
+          {result ? (
+            <ImportResultPanel
+              result={result}
+              noun={entity.noun}
+              onOpenList={() => navigate?.(joinPath(basePath, LIST_PATHS[entityType]))}
+            />
+          ) : null}
+        </EmphasisPanel>
+
+        <Card>
+          <CardHeader>
+            <CardTitle className="flex items-center gap-2 text-base">
+              <Info size={18} /> {entity.label} columns
+            </CardTitle>
+            <CardDescription>
+              Use these column names as the CSV header or JSON keys. Values are not case-sensitive
+              for lists.
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            {specLoading ? (
+              <div className="space-y-2">
+                <Skeleton className="h-6 w-full" />
+                <Skeleton className="h-6 w-full" />
+                <Skeleton className="h-6 w-2/3" />
+              </div>
+            ) : specError ? (
+              <p className="text-sm text-status-error-text">
+                The column guide could not be loaded. Imports still work.
+              </p>
+            ) : spec ? (
+              <ul className="space-y-3" data-testid="mtw-import-columns">
+                {spec.columns.map((column) => (
+                  <li key={column.name} className="text-sm">
+                    <div className="flex flex-wrap items-center gap-2">
+                      <code className="font-mono text-text-primary">{column.name}</code>
+                      {column.required ? <Badge variant="default">required</Badge> : null}
+                      {spec.keyColumn === column.name ? (
+                        <Badge variant="outline">unique</Badge>
+                      ) : null}
+                    </div>
+                    <p className="text-text-secondary">{column.description}</p>
+                    <p className="text-xs text-text-tertiary">{columnRule(column)}</p>
+                  </li>
+                ))}
+              </ul>
+            ) : null}
+          </CardContent>
+        </Card>
+      </div>
+
+      <Card>
+        <CardHeader>
+          <CardTitle className="flex items-center gap-2 text-base">
+            <Download size={18} /> Export data
+          </CardTitle>
+          <CardDescription>
+            Exports run in the background and download as a ZIP. Large exports stay available on the
+            Exports page.
+          </CardDescription>
+        </CardHeader>
+        <CardContent className="grid grid-cols-1 gap-3 md:grid-cols-2">
+          {EXPORT_OPTIONS.map((option) => (
+            <ExportRow key={option.entity} {...option} />
+          ))}
+        </CardContent>
+      </Card>
+    </PageLayout>
+  );
+}

package/src/movethewheels/pages/ProductsPage.tsx

@@ -3,7 +3,15 @@
  */
 
 import { useState } from 'react';
-import { Package, Plus, RefreshCw, Download, AlertTriangle, Thermometer } from 'lucide-react';
+import {
+  Package,
+  Plus,
+  RefreshCw,
+  Download,
+  AlertTriangle,
+  Thermometer,
+  Upload,
+} from 'lucide-react';
 import { PageLayout } from '../components/PageLayout';
 import { MetricCard, MetricGrid } from '../components/MetricCard';
 import { DataTable, type Column } from '../components/DataTable';
@@ -134,6 +142,11 @@ export default function ProductsPage() {
           }}
           actions={[
             { label: 'Refresh', icon: <RefreshCw size={16} />, onSelect: () => refetch() },
+            {
+              label: 'Import',
+              icon: <Upload size={16} />,
+              onSelect: () => goTo('import-export?entity=CARGO_ITEM'),
+            },
             {
               label: isExporting ? 'Exporting…' : 'Export',
               icon: <Download size={16} />,

package/src/movethewheels/pages/VehiclesPage.tsx

@@ -12,6 +12,7 @@ import {
   Route as RouteIcon,
   Wrench,
   Filter,
+  Upload,
 } from 'lucide-react';
 import { PageLayout } from '../components/PageLayout';
 import { MetricCard, MetricGrid } from '../components/MetricCard';
@@ -163,6 +164,11 @@ export default function VehiclesPage() {
           }}
           actions={[
             { label: 'Refresh', icon: <RefreshCw size={16} />, onSelect: () => refetch() },
+            {
+              label: 'Import',
+              icon: <Upload size={16} />,
+              onSelect: () => goTo('import-export?entity=VEHICLE'),
+            },
             {
               label: isExporting ? 'Exporting…' : 'Export',
               icon: <Download size={16} />,