@burdenoff/microfe-movethewheels 2026.1031.6 → 2026.1101.2

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;
+}