@burdenoff/microfe-movethewheels 2026.1101.1 → 2026.1101.2

package/src/movethewheels/components/EpodCaptureForm.tsx

@@ -0,0 +1,343 @@
+/**
+ * ePOD capture form (BOFF-4399), extracted from the driver deliveries page so
+ * the BOFF-3991 driver day view can open it from a stop's detail screen.
+ *
+ * Captures recipient name, signature (drawn or typed), an optional delivery
+ * photo (uploaded via the platform files primitive), device GPS if available,
+ * and notes, after the driver reviews the linked shipment status and attests
+ * completion. `captureEpod` owner-verifies the calling driver server-side.
+ */
+import { useEffect, useRef, useState } from 'react';
+import {
+  CheckCircle2,
+  Loader2,
+  MapPin,
+  PenLine,
+  Truck,
+  Type as TypeIcon,
+  Upload,
+} from 'lucide-react';
+import { Button, Card, CardContent, CardHeader, CardTitle, Input, Label, Textarea } from './ui';
+import { SignaturePad, type SignaturePadHandle } from './SignaturePad';
+import { FormError } from './FormError';
+import { useCaptureEpod, useEpodPhotoUpload, type PendingEpodDeliveryJob } from '../hooks/useEpod';
+import { formatAddress } from '../utils/formatters';
+import type { SignatureType } from '../types';
+import { useShipmentStatusQuery } from '../hooks/useShipmentStatusAuthority';
+import { StatusAuthorityOwnedDeliveryDocument } from '../../generated/shipment-status-authority-operations';
+import type { StatusAuthorityOwnedDeliveryQuery } from '../../generated/shipment-status-authority-operations';
+
+/** Resolves the device's current position, if the browser grants it. Never blocks submission. */
+function getCurrentPosition(): Promise<GeolocationPosition | null> {
+  return new Promise((resolve) => {
+    if (!navigator.geolocation) {
+      resolve(null);
+      return;
+    }
+    navigator.geolocation.getCurrentPosition(
+      (position) => resolve(position),
+      () => resolve(null),
+      { enableHighAccuracy: true, timeout: 8000, maximumAge: 30000 }
+    );
+  });
+}
+
+export function EpodCaptureForm({
+  job,
+  onCaptured,
+  onCancel,
+  offline = false,
+}: {
+  job: PendingEpodDeliveryJob;
+  onCaptured: (deliveryJobId: string) => void;
+  onCancel: () => void;
+  /**
+   * True while the device has no network. Capture needs the live linked
+   * shipment status and an acknowledged server write, so it is blocked
+   * rather than queued while offline.
+   */
+  offline?: boolean;
+}) {
+  const { captureEpod, isSubmitting, error: captureError, captureFeedback } = useCaptureEpod();
+  const [statusRefresh, setStatusRefresh] = useState(0);
+  const ownedStatus = useShipmentStatusQuery<StatusAuthorityOwnedDeliveryQuery>(
+    StatusAuthorityOwnedDeliveryDocument,
+    { deliveryJobId: job.id },
+    statusRefresh
+  );
+  const [completionAttestation, setCompletionAttestation] = useState(false);
+  const uploadedPhoto = useRef<{ file: File; id: string } | null>(null);
+  const submissionLock = useRef(false);
+  const active = useRef(true);
+  useEffect(() => {
+    active.current = true;
+    return () => {
+      active.current = false;
+    };
+  }, []);
+  const [preparing, setPreparing] = useState(false);
+  const [requiredStatusRefresh, setRequiredStatusRefresh] = useState(0);
+  const { upload: uploadPhoto, isUploading, error: uploadError } = useEpodPhotoUpload();
+  const signaturePadRef = useRef<SignaturePadHandle>(null);
+
+  const [recipientName, setRecipientName] = useState('');
+  const [signatureType, setSignatureType] = useState<SignatureType>('drawn');
+  const [typedSignature, setTypedSignature] = useState('');
+  const [photoFile, setPhotoFile] = useState<File | null>(null);
+  const [notes, setNotes] = useState('');
+  const [validationError, setValidationError] = useState<string | null>(null);
+
+  const handleSubmit = async () => {
+    if (submissionLock.current) return;
+    setValidationError(null);
+    if (offline) {
+      setValidationError('You are offline. Reconnect to confirm this delivery.');
+      return;
+    }
+    if (
+      ownedStatus.loading ||
+      ownedStatus.error ||
+      !ownedStatus.data ||
+      statusRefresh < requiredStatusRefresh ||
+      !completionAttestation ||
+      captureFeedback?.kind === 'UNKNOWN'
+    ) {
+      setValidationError(
+        'Review the current linked shipment status and confirm completion before capture. Do not resend an uncertain capture.'
+      );
+      return;
+    }
+
+    const trimmedRecipient = recipientName.trim();
+    if (!trimmedRecipient) {
+      setValidationError('Recipient name is required.');
+      return;
+    }
+
+    const signatureData =
+      signatureType === 'typed'
+        ? typedSignature.trim()
+        : (signaturePadRef.current?.toDataUrl() ?? null);
+    if (!signatureData) {
+      setValidationError(
+        signatureType === 'typed'
+          ? 'Type the recipient full name as their signature.'
+          : 'A signature is required.'
+      );
+      return;
+    }
+
+    submissionLock.current = true;
+    setPreparing(true);
+    try {
+      let photoFileIds: string[] | undefined;
+      if (photoFile) {
+        if (uploadedPhoto.current?.file === photoFile) photoFileIds = [uploadedPhoto.current.id];
+        else {
+          const uploaded = await uploadPhoto(photoFile);
+          uploadedPhoto.current = { file: photoFile, id: uploaded.fileId };
+          photoFileIds = [uploaded.fileId];
+        }
+      }
+
+      if (!active.current) return;
+      const position = await getCurrentPosition();
+      if (!active.current) return;
+
+      const proof = await captureEpod({
+        expectedShipmentId: ownedStatus.data.myEpodShipmentStatus?.id ?? null,
+        expectedShipmentStatusRevision: ownedStatus.data.myEpodShipmentStatus?.statusRevision,
+        completionAttestation,
+        deliveryJobId: job.id,
+        recipientName: trimmedRecipient,
+        signatureType,
+        signatureData,
+        photoFileIds,
+        latitude: position?.coords.latitude,
+        longitude: position?.coords.longitude,
+        locationAccuracy: position?.coords.accuracy,
+        notes: notes.trim() || undefined,
+      });
+
+      if (!active.current) return;
+      onCaptured(proof.deliveryJobId);
+    } catch {
+      setCompletionAttestation(false);
+      setRequiredStatusRefresh(statusRefresh + 1);
+      // captureError / uploadError already carry the message for display below.
+    } finally {
+      submissionLock.current = false;
+      setPreparing(false);
+    }
+  };
+
+  const submitting = isSubmitting || isUploading || preparing;
+
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle className="flex items-center gap-2">
+          <Truck size={18} /> Capture delivery for {job.deliveryJobNumber}
+        </CardTitle>
+      </CardHeader>
+      <CardContent className="space-y-4">
+        <div className="text-sm text-text-secondary space-y-1">
+          {job.customerName && <p>Recipient on file: {job.customerName}</p>}
+          {job.deliveryAddress && <p>{formatAddress(job.deliveryAddress)}</p>}
+        </div>
+        <section aria-label="Linked shipment status" className="space-y-2">
+          <p>
+            Recorded shipment:{' '}
+            {ownedStatus.data?.myEpodShipmentStatus
+              ? `${ownedStatus.data.myEpodShipmentStatus.status.toLowerCase().replaceAll('_', ' ')} · revision ${ownedStatus.data.myEpodShipmentStatus.statusRevision}`
+              : ownedStatus.data
+                ? 'No linked shipment'
+                : 'Loading current record'}
+          </p>
+          {ownedStatus.error && <p role="alert">{ownedStatus.error}</p>}
+          <Button
+            variant="outline"
+            disabled={ownedStatus.loading || submitting}
+            onClick={() => {
+              setCompletionAttestation(false);
+              setStatusRefresh((value) => value + 1);
+            }}
+          >
+            Refresh linked status
+          </Button>
+          <label className="flex items-start gap-2">
+            <input
+              type="checkbox"
+              checked={completionAttestation}
+              disabled={
+                ownedStatus.loading ||
+                !!ownedStatus.error ||
+                submitting ||
+                statusRefresh < requiredStatusRefresh ||
+                captureFeedback?.kind === 'UNKNOWN'
+              }
+              onChange={(event) => setCompletionAttestation(event.target.checked)}
+            />
+            I reviewed the recorded linked status and attest to this delivery completion.
+          </label>
+          <p>
+            This records an assigned driver's attestation; it does not independently verify physical
+            freight movement.
+          </p>
+          {captureFeedback && <p role="status">{captureFeedback.message}</p>}
+        </section>
+
+        <div className="space-y-1.5">
+          <Label htmlFor="epod-recipient-name">Recipient name</Label>
+          <Input
+            id="epod-recipient-name"
+            value={recipientName}
+            onChange={(event) => setRecipientName(event.target.value)}
+            placeholder="Who received the delivery?"
+          />
+        </div>
+
+        <div className="space-y-1.5">
+          <Label>Signature</Label>
+          <div className="flex gap-2">
+            <Button
+              type="button"
+              variant={signatureType === 'drawn' ? 'default' : 'outline'}
+              size="sm"
+              onClick={() => setSignatureType('drawn')}
+            >
+              <PenLine size={14} /> Draw
+            </Button>
+            <Button
+              type="button"
+              variant={signatureType === 'typed' ? 'default' : 'outline'}
+              size="sm"
+              onClick={() => setSignatureType('typed')}
+            >
+              <TypeIcon size={14} /> Type name instead
+            </Button>
+          </div>
+          {signatureType === 'drawn' ? (
+            <SignaturePad ref={signaturePadRef} />
+          ) : (
+            <Input
+              value={typedSignature}
+              onChange={(event) => setTypedSignature(event.target.value)}
+              placeholder="Type full name as signature"
+            />
+          )}
+        </div>
+
+        <div className="space-y-1.5">
+          <Label htmlFor="epod-photo">Delivery photo (optional)</Label>
+          <div className="flex items-center gap-2">
+            <input
+              id="epod-photo"
+              type="file"
+              accept="image/*"
+              capture="environment"
+              onChange={(event) => setPhotoFile(event.target.files?.[0] ?? null)}
+              className="text-sm"
+            />
+            {photoFile && <Upload size={14} className="text-text-secondary" />}
+          </div>
+          {photoFile && <p className="text-xs text-text-secondary">{photoFile.name}</p>}
+        </div>
+
+        <div className="space-y-1.5">
+          <Label htmlFor="epod-notes">Notes (optional)</Label>
+          <Textarea
+            id="epod-notes"
+            value={notes}
+            onChange={(event) => setNotes(event.target.value)}
+            placeholder="e.g. Left with front desk, gate code used, etc."
+            rows={2}
+          />
+        </div>
+
+        <p className="flex items-center gap-1.5 text-xs text-text-secondary">
+          <MapPin size={12} /> Device GPS is captured automatically when permitted by the browser.
+        </p>
+
+        {offline && (
+          <p role="alert" className="text-sm text-text-secondary">
+            You are offline. Your entries stay on this screen; reconnect to confirm the delivery.
+          </p>
+        )}
+        {validationError && <FormError message={validationError} />}
+        {captureError && <FormError message={captureError.message} />}
+        {uploadError && <FormError message={uploadError.message} />}
+
+        <div className="flex gap-2 justify-end">
+          <Button type="button" variant="outline" onClick={onCancel} disabled={submitting}>
+            Cancel
+          </Button>
+          <Button
+            type="button"
+            onClick={() => void handleSubmit()}
+            disabled={
+              submitting ||
+              offline ||
+              ownedStatus.loading ||
+              !!ownedStatus.error ||
+              !ownedStatus.data ||
+              statusRefresh < requiredStatusRefresh ||
+              !completionAttestation ||
+              captureFeedback?.kind === 'UNKNOWN'
+            }
+          >
+            {submitting ? (
+              <>
+                <Loader2 size={14} className="animate-spin" /> Submitting…
+              </>
+            ) : (
+              <>
+                <CheckCircle2 size={14} /> Confirm delivery
+              </>
+            )}
+          </Button>
+        </div>
+      </CardContent>
+    </Card>
+  );
+}

package/src/movethewheels/hooks/index.ts

@@ -80,6 +80,15 @@ export {
   type EntityDocumentType,
 } from './useEntityDocuments';
 
+// Driver day view (mobile driver task list) — BOFF-3991
+export {
+  useMyDeliveryDay,
+  useOnlineStatus,
+  type DriverDay,
+  type DriverStop,
+  type DriverStopState,
+} from './useDriverDay';
+
 // Electronic proof of delivery (ePOD) capture — BOFF-4399
 export {
   useEpod,

package/src/movethewheels/hooks/useDriverDay.ts

@@ -0,0 +1,289 @@
+/**
+ * Driver day view data (BOFF-3991): the calling driver's stops for one local
+ * calendar day, in driving sequence, from the `myDeliveryDay` Type C
+ * self-list in `wspace-movethewheels-svc` (src/modules/epod/schema/epod.gql).
+ * The driver is resolved from the authenticated actor server-side; this hook
+ * never sends a driver or user id.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
+import type { Order } from '../types';
+import { executeGraphQL } from '../utils/graphqlClient';
+import { deviceTimeZone, timezoneOffsetFor } from '../utils/driverNavigation';
+
+const STOP_FIELDS = `
+  sequence
+  state
+  awaitingCapture
+  overdue
+  deliveredAt
+  routeId
+  routeName
+  deliveryJob {
+    id
+    deliveryJobNumber
+    status
+    priority
+    deliveryAddress
+    scheduledDelivery
+    specialInstructions
+    customer {
+      name
+      phone
+    }
+  }
+`;
+
+const MY_DELIVERY_DAY_QUERY = `
+  query MyDeliveryDay($date: String!, $timezoneOffsetMinutes: Int, $timeZone: String) {
+    myDeliveryDay(date: $date, timezoneOffsetMinutes: $timezoneOffsetMinutes, timeZone: $timeZone) {
+      date
+      driverId
+      driverName
+      totalStops
+      completedStops
+      remainingStops
+      stops {
+        ${STOP_FIELDS}
+      }
+    }
+  }
+`;
+
+export type DriverStopState = 'COMPLETED' | 'EN_ROUTE' | 'UPCOMING' | 'FAILED';
+
+export interface DriverStop {
+  sequence: number;
+  state: DriverStopState;
+  awaitingCapture: boolean;
+  overdue: boolean;
+  deliveredAt?: Date;
+  routeId?: string;
+  routeName?: string;
+  jobId: string;
+  deliveryJobNumber: string;
+  status: string;
+  priority: string;
+  deliveryAddress: Order['deliveryAddress'] | null;
+  scheduledDelivery?: Date;
+  specialInstructions?: string;
+  customerName?: string;
+  customerPhone?: string;
+}
+
+export interface DriverDay {
+  date: string;
+  driverId: string | null;
+  driverName: string | null;
+  stops: DriverStop[];
+  totalStops: number;
+  completedStops: number;
+  remainingStops: number;
+  nextStop: DriverStop | null;
+}
+
+interface ApiStop {
+  sequence: number;
+  state: DriverStopState;
+  awaitingCapture: boolean;
+  overdue: boolean;
+  deliveredAt?: string | null;
+  routeId?: string | null;
+  routeName?: string | null;
+  deliveryJob: {
+    id: string;
+    deliveryJobNumber: string;
+    status: string;
+    priority: string;
+    deliveryAddress: Order['deliveryAddress'] | null;
+    scheduledDelivery?: string | null;
+    specialInstructions?: string | null;
+    customer?: { name?: string | null; phone?: string | null } | null;
+  };
+}
+
+interface ApiDriverDay {
+  date: string;
+  driverId: string | null;
+  driverName: string | null;
+  totalStops: number;
+  completedStops: number;
+  remainingStops: number;
+  stops: ApiStop[];
+}
+
+function mapStop(stop: ApiStop): DriverStop {
+  const job = stop.deliveryJob;
+  return {
+    sequence: stop.sequence,
+    state: stop.state,
+    awaitingCapture: stop.awaitingCapture,
+    overdue: stop.overdue,
+    deliveredAt: stop.deliveredAt ? new Date(stop.deliveredAt) : undefined,
+    routeId: stop.routeId ?? undefined,
+    routeName: stop.routeName ?? undefined,
+    jobId: job.id,
+    deliveryJobNumber: job.deliveryJobNumber,
+    status: job.status,
+    priority: job.priority,
+    deliveryAddress: job.deliveryAddress,
+    scheduledDelivery: job.scheduledDelivery ? new Date(job.scheduledDelivery) : undefined,
+    specialInstructions: job.specialInstructions ?? undefined,
+    customerName: job.customer?.name ?? undefined,
+    customerPhone: job.customer?.phone ?? undefined,
+  };
+}
+
+/**
+ * Applies acknowledged captures on top of a server snapshot: a stop whose
+ * capture the server already acknowledged is shown completed even if a
+ * delayed read still reports it en route. This is an in-memory UI fact for
+ * the current actor/scope, never a fabricated server update.
+ */
+export function applyAcknowledgedCaptures(
+  stops: DriverStop[],
+  acknowledged: ReadonlySet<string>
+): DriverDay['stops'] {
+  return stops.map((stop) =>
+    acknowledged.has(stop.jobId) && stop.state !== 'COMPLETED'
+      ? { ...stop, state: 'COMPLETED', awaitingCapture: false, status: 'DELIVERED' }
+      : stop
+  );
+}
+
+/** Derived counters and the next stop, recomputed after acknowledgement overrides. */
+export function summariseStops(stops: DriverStop[]) {
+  const completedStops = stops.filter(
+    (stop) => stop.state === 'COMPLETED' || stop.state === 'FAILED'
+  ).length;
+  return {
+    totalStops: stops.length,
+    completedStops,
+    remainingStops: stops.length - completedStops,
+    nextStop:
+      stops.find((stop) => stop.awaitingCapture) ??
+      stops.find((stop) => stop.state === 'UPCOMING') ??
+      null,
+  };
+}
+
+export function useMyDeliveryDay(date: string) {
+  const { apiGatewayUrl, authToken, workspaceToken, workspaceId, tenantId, currentUser } =
+    useMoveTheWheels();
+  const graphQLOptions = useMemo(
+    () => ({
+      apiGatewayUrl,
+      authToken,
+      workspaceToken,
+      workspaceId,
+      tenantId,
+      actorId: currentUser?.id,
+    }),
+    [apiGatewayUrl, authToken, workspaceToken, workspaceId, tenantId, currentUser?.id]
+  );
+  const scopeKey = JSON.stringify([apiGatewayUrl, workspaceId, tenantId, currentUser?.id]);
+  const readKey = JSON.stringify([scopeKey, date]);
+  const [acknowledgedJobs, setAcknowledgedJobs] = useState<{
+    scopeKey: string;
+    ids: ReadonlySet<string>;
+  }>({ scopeKey, ids: new Set<string>() });
+  const requestId = useRef(0);
+  const [snapshot, setSnapshot] = useState<{
+    readKey: string;
+    day: ApiDriverDay | null;
+    isLoading: boolean;
+    error: Error | null;
+  }>({ readKey, day: null, isLoading: true, error: null });
+
+  const load = useCallback(async () => {
+    const request = ++requestId.current;
+    setSnapshot((previous) => ({
+      readKey,
+      day: previous.readKey === readKey ? previous.day : null,
+      isLoading: true,
+      error: null,
+    }));
+    try {
+      const data = await executeGraphQL<{ myDeliveryDay: ApiDriverDay }>(
+        graphQLOptions,
+        MY_DELIVERY_DAY_QUERY,
+        { date, timezoneOffsetMinutes: timezoneOffsetFor(date), timeZone: deviceTimeZone() }
+      );
+      if (request !== requestId.current) return;
+      setSnapshot({ readKey, day: data.myDeliveryDay, isLoading: false, error: null });
+    } catch (fetchError) {
+      if (request !== requestId.current) return;
+      setSnapshot((previous) => ({
+        readKey,
+        // Keep the last good list on screen (e.g. a dropped connection on the road).
+        day: previous.readKey === readKey ? previous.day : null,
+        isLoading: false,
+        error:
+          fetchError instanceof Error ? fetchError : new Error('Failed to load your deliveries'),
+      }));
+    }
+  }, [graphQLOptions, date, readKey]);
+
+  const cancelPendingRead = useCallback(() => {
+    requestId.current++;
+  }, []);
+
+  useEffect(() => {
+    void load();
+    return cancelPendingRead;
+  }, [load, cancelPendingRead]);
+
+  const markCaptured = useCallback(
+    (deliveryJobId: string) => {
+      setAcknowledgedJobs((previous) => {
+        // An actor/workspace switch starts a fresh acknowledgement set.
+        const ids = new Set(previous.scopeKey === scopeKey ? previous.ids : []);
+        ids.add(deliveryJobId);
+        return { scopeKey, ids };
+      });
+    },
+    [scopeKey]
+  );
+
+  const current = snapshot.readKey === readKey ? snapshot : null;
+  const currentDay = current?.day ?? null;
+  const day = useMemo<DriverDay | null>(() => {
+    if (!currentDay) return null;
+    const acknowledged =
+      acknowledgedJobs.scopeKey === scopeKey ? acknowledgedJobs.ids : new Set<string>();
+    const stops = applyAcknowledgedCaptures(currentDay.stops.map(mapStop), acknowledged);
+    return {
+      date: currentDay.date,
+      driverId: currentDay.driverId,
+      driverName: currentDay.driverName,
+      stops,
+      ...summariseStops(stops),
+    };
+  }, [currentDay, scopeKey, acknowledgedJobs]);
+
+  return {
+    day,
+    isLoading: !current || current.isLoading,
+    error: current?.error ?? null,
+    refetch: load,
+    markCaptured,
+  };
+}
+
+/** Tracks `navigator.onLine` so the driver sees when capture is unavailable. */
+export function useOnlineStatus(): boolean {
+  const [online, setOnline] = useState(() =>
+    typeof navigator === 'undefined' ? true : navigator.onLine !== false
+  );
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+    const update = () => setOnline(navigator.onLine !== false);
+    window.addEventListener('online', update);
+    window.addEventListener('offline', update);
+    return () => {
+      window.removeEventListener('online', update);
+      window.removeEventListener('offline', update);
+    };
+  }, []);
+  return online;
+}