@burdenoff/microfe-movethewheels 2026.726.1 → 2026.731.1

package/src/movethewheels/pages/MultiModalShipmentPage.tsx

@@ -0,0 +1,552 @@
+/**
+ * Multi-Modal Freight Shipment Page (BOFF-4398)
+ *
+ * Lets an operator plan a shipment composed of multiple real transport legs
+ * across ROAD/AIR/OCEAN/RAIL, previewing each leg's real mode-specific rate
+ * before booking, then lists previously planned multi-modal shipments.
+ */
+
+import { useState } from 'react';
+import { Ship, Plane, Truck, TrainFront, Plus, Trash2, Calculator } from 'lucide-react';
+import { PageLayout, PageSection, EmptyState, LoadingState } from '../components/PageLayout';
+import { FormError } from '../components/FormError';
+import {
+  Card,
+  CardContent,
+  CardHeader,
+  CardTitle,
+  Button,
+  Badge,
+  Input,
+  Label,
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+  Separator,
+} from '../components/ui';
+import { PagePurpose, EmphasisPanel } from '@burdenoff/fe-libs/ui';
+import {
+  useMultiModalShipments,
+  type FreightRateQuote,
+  type OceanContainerType,
+  type ShipmentLegDraft,
+  type TransportMode,
+} from '../hooks/useMultiModalShipments';
+
+const MODE_ICON: Record<TransportMode, typeof Truck> = {
+  ROAD: Truck,
+  AIR: Plane,
+  OCEAN: Ship,
+  RAIL: TrainFront,
+};
+
+const MODE_LABEL: Record<TransportMode, string> = {
+  ROAD: 'Road',
+  AIR: 'Air',
+  OCEAN: 'Ocean',
+  RAIL: 'Rail',
+};
+
+function emptyLeg(mode: TransportMode = 'ROAD'): ShipmentLegDraft {
+  return { mode, origin: {}, destination: {} };
+}
+
+function formatMoney(
+  amount: number | null | undefined,
+  currency: string | null | undefined
+): string {
+  if (amount == null) return '—';
+  try {
+    return new Intl.NumberFormat('en-US', {
+      style: 'currency',
+      currency: currency ?? 'USD',
+    }).format(amount);
+  } catch {
+    return `${amount.toFixed(2)} ${currency ?? 'USD'}`;
+  }
+}
+
+export default function MultiModalShipmentPage() {
+  const { shipments, isLoading, error, calculateFreightRate, planMultiModalShipment } =
+    useMultiModalShipments();
+
+  const [shipmentNumber, setShipmentNumber] = useState('');
+  const [originAddress, setOriginAddress] = useState('');
+  const [destinationAddress, setDestinationAddress] = useState('');
+  const [legs, setLegs] = useState<ShipmentLegDraft[]>([emptyLeg()]);
+  const [quotes, setQuotes] = useState<Record<number, FreightRateQuote | null>>({});
+  const [quoteErrors, setQuoteErrors] = useState<Record<number, string | null>>({});
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const [formError, setFormError] = useState<string | null>(null);
+  const [successMessage, setSuccessMessage] = useState<string | null>(null);
+
+  const updateLeg = (index: number, patch: Partial<ShipmentLegDraft>) => {
+    setLegs((previous) => previous.map((leg, i) => (i === index ? { ...leg, ...patch } : leg)));
+    setQuotes((previous) => ({ ...previous, [index]: null }));
+  };
+
+  const addLeg = () => setLegs((previous) => [...previous, emptyLeg()]);
+
+  const removeLeg = (index: number) => {
+    setLegs((previous) => previous.filter((_, i) => i !== index));
+    setQuotes((previous) => {
+      const next = { ...previous };
+      delete next[index];
+      return next;
+    });
+  };
+
+  const previewLeg = async (index: number) => {
+    const leg = legs[index];
+    if (!leg) return;
+    setQuoteErrors((previous) => ({ ...previous, [index]: null }));
+    try {
+      const quote = await calculateFreightRate(leg);
+      setQuotes((previous) => ({ ...previous, [index]: quote }));
+    } catch (previewError) {
+      setQuoteErrors((previous) => ({
+        ...previous,
+        [index]: previewError instanceof Error ? previewError.message : 'Failed to calculate rate',
+      }));
+    }
+  };
+
+  const estimatedTotal = Object.values(quotes).reduce(
+    (sum, quote) => sum + (quote?.calculatedCost ?? 0),
+    0
+  );
+  const modesUsed = new Set(legs.map((leg) => leg.mode));
+
+  const handleSubmit = async (event: React.FormEvent) => {
+    event.preventDefault();
+    setFormError(null);
+    setSuccessMessage(null);
+
+    if (!shipmentNumber.trim()) {
+      setFormError('Shipment number is required.');
+      return;
+    }
+    if (legs.length === 0) {
+      setFormError('Add at least one transport leg.');
+      return;
+    }
+
+    setIsSubmitting(true);
+    try {
+      const created = await planMultiModalShipment({
+        shipmentNumber: shipmentNumber.trim(),
+        origin: { address: originAddress },
+        destination: { address: destinationAddress },
+        legs,
+      });
+      setSuccessMessage(
+        `Shipment ${created.shipmentNumber} planned with ${created.legs.length} leg(s).`
+      );
+      setShipmentNumber('');
+      setOriginAddress('');
+      setDestinationAddress('');
+      setLegs([emptyLeg()]);
+      setQuotes({});
+    } catch (submitError) {
+      setFormError(submitError instanceof Error ? submitError.message : 'Failed to plan shipment');
+    } finally {
+      setIsSubmitting(false);
+    }
+  };
+
+  return (
+    <PageLayout
+      hero
+      titleAccent="Multi-Modal Freight"
+      title="Multi-Modal Freight"
+      subtitle="Plan a shipment across road, air, ocean and rail legs with real per-mode rate calculation"
+      icon={<Ship size={24} />}
+    >
+      <PagePurpose icon={<Ship size={18} />}>
+        Compose a single shipment from multiple real transport legs — each leg picks its own mode
+        (road/air/ocean/rail) and gets priced with that mode's real pricing driver (air: chargeable
+        weight; ocean: revenue-ton or per-container; rail: tonne-km; road: distance + weight).
+        Calculate a leg's rate before booking, then plan the full multi-leg shipment in one step.
+      </PagePurpose>
+
+      <EmphasisPanel>
+        Live carrier booking/API integration is out of scope for this core (it needs named-carrier
+        partnership agreements) — this plans the shipment and its legs with real calculated costs
+        that your ops team can then execute against your chosen carriers.
+      </EmphasisPanel>
+
+      <PageSection title="Plan a New Multi-Modal Shipment">
+        <Card>
+          <CardContent>
+            <form onSubmit={handleSubmit} className="space-y-6 pt-4">
+              <FormError message={formError} />
+              {successMessage && (
+                <div className="rounded-lg border border-status-success-border bg-status-success-bg-subtle px-4 py-3 text-sm text-status-success-text">
+                  {successMessage}
+                </div>
+              )}
+
+              <div className="grid grid-cols-1 gap-4 sm:grid-cols-3">
+                <div>
+                  <Label htmlFor="shipmentNumber">Shipment Number</Label>
+                  <Input
+                    id="shipmentNumber"
+                    value={shipmentNumber}
+                    onChange={(e) => setShipmentNumber(e.target.value)}
+                    placeholder="SHP-MM-0001"
+                    required
+                  />
+                </div>
+                <div>
+                  <Label htmlFor="originAddress">Origin</Label>
+                  <Input
+                    id="originAddress"
+                    value={originAddress}
+                    onChange={(e) => setOriginAddress(e.target.value)}
+                    placeholder="Shanghai, CN"
+                  />
+                </div>
+                <div>
+                  <Label htmlFor="destinationAddress">Destination</Label>
+                  <Input
+                    id="destinationAddress"
+                    value={destinationAddress}
+                    onChange={(e) => setDestinationAddress(e.target.value)}
+                    placeholder="Los Angeles, US"
+                  />
+                </div>
+              </div>
+
+              <Separator />
+
+              <div className="space-y-4">
+                {legs.map((leg, index) => {
+                  const Icon = MODE_ICON[leg.mode];
+                  const quote = quotes[index];
+                  const quoteError = quoteErrors[index];
+                  return (
+                    <Card key={index} className="border-border-subtle">
+                      <CardHeader className="flex flex-row items-center justify-between">
+                        <CardTitle className="flex items-center gap-2 text-base">
+                          <Icon size={16} /> Leg {index + 1}
+                        </CardTitle>
+                        {legs.length > 1 && (
+                          <Button
+                            type="button"
+                            variant="ghost"
+                            size="sm"
+                            onClick={() => removeLeg(index)}
+                            aria-label={`Remove leg ${index + 1}`}
+                          >
+                            <Trash2 size={14} />
+                          </Button>
+                        )}
+                      </CardHeader>
+                      <CardContent className="space-y-4">
+                        <div className="grid grid-cols-1 gap-4 sm:grid-cols-3">
+                          <div>
+                            <Label>Mode</Label>
+                            <Select
+                              value={leg.mode}
+                              onValueChange={(value) =>
+                                updateLeg(index, { mode: value as TransportMode })
+                              }
+                            >
+                              <SelectTrigger>
+                                <SelectValue />
+                              </SelectTrigger>
+                              <SelectContent>
+                                {(['ROAD', 'AIR', 'OCEAN', 'RAIL'] as TransportMode[]).map(
+                                  (mode) => (
+                                    <SelectItem key={mode} value={mode}>
+                                      {MODE_LABEL[mode]}
+                                    </SelectItem>
+                                  )
+                                )}
+                              </SelectContent>
+                            </Select>
+                          </div>
+                          <div>
+                            <Label>Leg Origin</Label>
+                            <Input
+                              value={leg.origin.address ?? ''}
+                              onChange={(e) =>
+                                updateLeg(index, { origin: { address: e.target.value } })
+                              }
+                              placeholder="Origin port/airport/terminal"
+                            />
+                          </div>
+                          <div>
+                            <Label>Leg Destination</Label>
+                            <Input
+                              value={leg.destination.address ?? ''}
+                              onChange={(e) =>
+                                updateLeg(index, { destination: { address: e.target.value } })
+                              }
+                              placeholder="Destination port/airport/terminal"
+                            />
+                          </div>
+                        </div>
+
+                        {(leg.mode === 'ROAD' || leg.mode === 'RAIL') && (
+                          <div className="grid grid-cols-1 gap-4 sm:grid-cols-2">
+                            <div>
+                              <Label>Distance (km)</Label>
+                              <Input
+                                type="number"
+                                min={0}
+                                value={leg.distanceKm ?? ''}
+                                onChange={(e) =>
+                                  updateLeg(index, {
+                                    distanceKm: Number(e.target.value) || undefined,
+                                  })
+                                }
+                              />
+                            </div>
+                            <div>
+                              <Label>Weight (kg)</Label>
+                              <Input
+                                type="number"
+                                min={0}
+                                value={leg.weightKg ?? ''}
+                                onChange={(e) =>
+                                  updateLeg(index, {
+                                    weightKg: Number(e.target.value) || undefined,
+                                  })
+                                }
+                              />
+                            </div>
+                          </div>
+                        )}
+
+                        {leg.mode === 'AIR' && (
+                          <div className="grid grid-cols-1 gap-4 sm:grid-cols-4">
+                            <div>
+                              <Label>Weight (kg)</Label>
+                              <Input
+                                type="number"
+                                min={0}
+                                value={leg.weightKg ?? ''}
+                                onChange={(e) =>
+                                  updateLeg(index, {
+                                    weightKg: Number(e.target.value) || undefined,
+                                  })
+                                }
+                              />
+                            </div>
+                            <div>
+                              <Label>Length (cm)</Label>
+                              <Input
+                                type="number"
+                                min={0}
+                                value={leg.lengthCm ?? ''}
+                                onChange={(e) =>
+                                  updateLeg(index, {
+                                    lengthCm: Number(e.target.value) || undefined,
+                                  })
+                                }
+                              />
+                            </div>
+                            <div>
+                              <Label>Width (cm)</Label>
+                              <Input
+                                type="number"
+                                min={0}
+                                value={leg.widthCm ?? ''}
+                                onChange={(e) =>
+                                  updateLeg(index, { widthCm: Number(e.target.value) || undefined })
+                                }
+                              />
+                            </div>
+                            <div>
+                              <Label>Height (cm)</Label>
+                              <Input
+                                type="number"
+                                min={0}
+                                value={leg.heightCm ?? ''}
+                                onChange={(e) =>
+                                  updateLeg(index, {
+                                    heightCm: Number(e.target.value) || undefined,
+                                  })
+                                }
+                              />
+                            </div>
+                          </div>
+                        )}
+
+                        {leg.mode === 'OCEAN' && (
+                          <div className="grid grid-cols-1 gap-4 sm:grid-cols-4">
+                            <div>
+                              <Label>Container Type</Label>
+                              <Select
+                                value={leg.containerType ?? 'LCL'}
+                                onValueChange={(value) =>
+                                  updateLeg(index, { containerType: value as OceanContainerType })
+                                }
+                              >
+                                <SelectTrigger>
+                                  <SelectValue />
+                                </SelectTrigger>
+                                <SelectContent>
+                                  <SelectItem value="LCL">LCL (shared container)</SelectItem>
+                                  <SelectItem value="FCL_20FT">FCL 20ft</SelectItem>
+                                  <SelectItem value="FCL_40FT">FCL 40ft</SelectItem>
+                                  <SelectItem value="FCL_40FT_HC">FCL 40ft High-Cube</SelectItem>
+                                </SelectContent>
+                              </Select>
+                            </div>
+                            {(leg.containerType ?? 'LCL') === 'LCL' ? (
+                              <>
+                                <div>
+                                  <Label>Weight (kg)</Label>
+                                  <Input
+                                    type="number"
+                                    min={0}
+                                    value={leg.weightKg ?? ''}
+                                    onChange={(e) =>
+                                      updateLeg(index, {
+                                        weightKg: Number(e.target.value) || undefined,
+                                      })
+                                    }
+                                  />
+                                </div>
+                                <div>
+                                  <Label>Volume (CBM)</Label>
+                                  <Input
+                                    type="number"
+                                    min={0}
+                                    value={leg.volumeCbm ?? ''}
+                                    onChange={(e) =>
+                                      updateLeg(index, {
+                                        volumeCbm: Number(e.target.value) || undefined,
+                                      })
+                                    }
+                                  />
+                                </div>
+                              </>
+                            ) : (
+                              <div>
+                                <Label>Container Count</Label>
+                                <Input
+                                  type="number"
+                                  min={1}
+                                  value={leg.containerCount ?? 1}
+                                  onChange={(e) =>
+                                    updateLeg(index, {
+                                      containerCount: Number(e.target.value) || 1,
+                                    })
+                                  }
+                                />
+                              </div>
+                            )}
+                          </div>
+                        )}
+
+                        <div className="flex items-center gap-3">
+                          <Button
+                            type="button"
+                            variant="secondary"
+                            size="sm"
+                            onClick={() => void previewLeg(index)}
+                          >
+                            <Calculator size={14} className="mr-1.5" /> Calculate Rate
+                          </Button>
+                          {quote && (
+                            <span className="text-sm font-medium text-text-primary">
+                              {formatMoney(quote.calculatedCost, quote.currency)}
+                              {quote.chargeableWeightKg != null && (
+                                <span className="ml-2 text-xs text-text-secondary">
+                                  ({quote.chargeableWeightKg.toFixed(1)}kg chargeable)
+                                </span>
+                              )}
+                            </span>
+                          )}
+                          {quoteError && (
+                            <span className="text-sm text-status-error-text">{quoteError}</span>
+                          )}
+                        </div>
+
+                        {quote && quote.breakdown.length > 0 && (
+                          <ul className="space-y-1 rounded-md bg-surface-subtle px-3 py-2 text-xs text-text-secondary">
+                            {quote.breakdown.map((line) => (
+                              <li key={line.label} className="flex justify-between">
+                                <span>{line.label}</span>
+                                <span>{formatMoney(line.amount, quote.currency)}</span>
+                              </li>
+                            ))}
+                          </ul>
+                        )}
+                      </CardContent>
+                    </Card>
+                  );
+                })}
+              </div>
+
+              <div className="flex items-center justify-between">
+                <Button type="button" variant="outline" size="sm" onClick={addLeg}>
+                  <Plus size={14} className="mr-1.5" /> Add Leg
+                </Button>
+                <div className="flex items-center gap-3">
+                  {modesUsed.size > 1 && <Badge variant="secondary">Multi-modal</Badge>}
+                  <span className="text-sm text-text-secondary">
+                    Estimated total:{' '}
+                    <strong>{formatMoney(estimatedTotal, quotes[0]?.currency ?? 'USD')}</strong>
+                  </span>
+                </div>
+              </div>
+
+              <Button type="submit" disabled={isSubmitting}>
+                {isSubmitting ? 'Planning shipment...' : 'Plan Shipment'}
+              </Button>
+            </form>
+          </CardContent>
+        </Card>
+      </PageSection>
+
+      <PageSection title="Planned Multi-Modal Shipments">
+        {isLoading ? (
+          <LoadingState message="Loading multi-modal shipments..." />
+        ) : error ? (
+          <FormError message={error.message} />
+        ) : shipments.length === 0 ? (
+          <EmptyState
+            icon={<Ship size={32} />}
+            title="No multi-modal shipments yet"
+            description="Plan a shipment above to see it here once it spans more than one transport mode."
+          />
+        ) : (
+          <div className="space-y-4">
+            {shipments.map((shipment) => (
+              <Card key={shipment.id}>
+                <CardHeader className="flex flex-row items-center justify-between">
+                  <CardTitle className="text-base">{shipment.shipmentNumber}</CardTitle>
+                  <div className="flex items-center gap-2">
+                    <Badge variant="outline">{shipment.status}</Badge>
+                    <span className="text-sm font-medium">
+                      {formatMoney(shipment.totalFreightCost, shipment.freightCurrency)}
+                    </span>
+                  </div>
+                </CardHeader>
+                <CardContent>
+                  <div className="flex flex-wrap gap-2">
+                    {shipment.legs.map((leg) => {
+                      const Icon = MODE_ICON[leg.mode];
+                      return (
+                        <Badge key={leg.id} variant="secondary" className="flex items-center gap-1">
+                          <Icon size={12} /> {MODE_LABEL[leg.mode]}:{' '}
+                          {formatMoney(leg.calculatedCost, leg.currency)}
+                        </Badge>
+                      );
+                    })}
+                  </div>
+                </CardContent>
+              </Card>
+            ))}
+          </div>
+        )}
+      </PageSection>
+    </PageLayout>
+  );
+}

package/src/movethewheels/pages/OrderDetailsPage.tsx

@@ -53,6 +53,7 @@ import { useFleet } from '../hooks/useFleet';
 import { FormError } from '../components/FormError';
 import { Notice, useNotice } from '../components/Notice';
 import { DocumentsCard } from '../components/DocumentsCard';
+import { ProofOfDeliveryCard } from '../components/ProofOfDeliveryCard';
 import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
 import { formatCurrency, formatDate, formatAddress } from '../utils/formatters';
 import { joinPath } from '../utils/navigation';
@@ -593,6 +594,9 @@ export default function OrderDetailsPage() {
           {/* Documents — real files via wspace-files-svc */}
           <DocumentsCard entityType="order" entityId={order.id} />
 
+          {/* Proof of delivery — captured by the driver on completion (BOFF-4399) */}
+          <ProofOfDeliveryCard deliveryJobId={order.id} />
+
           {/* Special Instructions */}
           {order.specialInstructions && (
             <Card>

package/src/movethewheels/pages/TrackingPage.tsx

@@ -12,6 +12,7 @@ import { StatusBadge } from '../components/StatusBadge';
 import { Card, CardContent, CardHeader, CardTitle, Button, Input } from '../components/ui';
 import { EmphasisPanel, PagePurpose } from '@burdenoff/fe-libs/ui';
 import { TrackingMap, type TrackEndpoint, type TrackPoint } from '../components/maps';
+import { ProofOfDeliveryCard } from '../components/ProofOfDeliveryCard';
 import { firstRealLatLng } from '../utils/mapMarkers';
 import { useOrderTracking } from '../hooks/useTracking';
 import { formatDate, formatAddress } from '../utils/formatters';
@@ -455,6 +456,9 @@ export default function TrackingPage() {
               </CardContent>
             </Card>
 
+            {/* Proof of delivery — captured by the driver on completion (BOFF-4399) */}
+            <ProofOfDeliveryCard deliveryJobId={order.id} />
+
             {/* Actions */}
             <Card>
               <CardContent className="p-4 space-y-2">

package/src/movethewheels/types/index.ts

@@ -288,6 +288,27 @@ export interface Order {
   updatedAt: Date;
 }
 
+// Electronic proof of delivery (ePOD) — BOFF-4399
+export type SignatureType = 'drawn' | 'typed';
+
+export interface ProofOfDelivery {
+  id: string;
+  deliveryJobId: string;
+  shipmentId?: string;
+  recipientName: string;
+  signatureType: SignatureType;
+  /** Drawn: a `data:image/png;base64,...` capture. Typed: the typed full name. */
+  signatureData: string;
+  /** wspace-files-svc File ids for any attached delivery photos. */
+  photoFileIds: string[];
+  latitude?: number;
+  longitude?: number;
+  locationAccuracy?: number;
+  deliveredAt: Date;
+  capturedByDriverId: string;
+  notes?: string;
+}
+
 // Vehicle type
 export type VehicleType = 'van' | 'truck' | 'motorcycle' | 'bicycle' | 'car';
 export type VehicleStatus = 'available' | 'assigned' | 'maintenance' | 'out_of_service';