@burdenoff/microfe-movethewheels 2026.804.1 → 2026.822.1

package/src/movethewheels/components/index.ts

@@ -74,3 +74,6 @@ export { Notice, useNotice } from './Notice';
 
 // Documents (reuse of wspace-files-svc)
 export { DocumentsCard } from './DocumentsCard';
+
+// Sustainability / carbon tracking (BOFF-4391)
+export { CarbonFootprintPanel } from './CarbonFootprintPanel';

package/src/movethewheels/hooks/index.ts

@@ -43,6 +43,8 @@ export {
   usePerformanceAnalytics,
   useFinanceMetrics,
   type FinanceMetrics,
+  useEmissionsSummary,
+  type EmissionsSummary,
 } from './useAnalytics';
 
 // Tracking

package/src/movethewheels/hooks/useAnalytics.ts

@@ -493,6 +493,22 @@ const FINANCE_METRICS_QUERY = `
   }
 `;
 
+const EMISSIONS_SUMMARY_QUERY = `
+  query GetMovethewheelsEmissionsSummary {
+    emissionsSummary {
+      totalCo2eKg
+      totalDistanceKm
+      averageCo2eKgPerKm
+      byVehicle {
+        vehicleId
+        vehicleNumber
+        totalDistanceKm
+        co2eKg
+      }
+    }
+  }
+`;
+
 export interface FinanceMetrics {
   totalRevenue: number;
   deliveredRevenue: number;
@@ -593,3 +609,73 @@ export function usePerformanceAnalytics() {
 
   return { performanceData, isLoading, error };
 }
+
+export interface EmissionsSummary {
+  totalCo2eKg: number;
+  totalDistanceKm: number;
+  averageCo2eKgPerKm: number;
+  byVehicle: Array<{
+    vehicleId: string | null;
+    vehicleNumber: string | null;
+    totalDistanceKm: number;
+    co2eKg: number;
+  }>;
+}
+
+/**
+ * Real emissions figures straight from Query.emissionsSummary (BOFF-4391).
+ * Returns totals, per-km intensity, and a per-vehicle breakdown sourced from
+ * cached route CO2e values and actual/estimated distances.
+ */
+export function useEmissionsSummary() {
+  const { apiGatewayUrl, authToken, workspaceToken, workspaceId, tenantId, currentUser } =
+    useMoveTheWheels();
+  const [summary, setSummary] = useState<EmissionsSummary>({
+    totalCo2eKg: 0,
+    totalDistanceKm: 0,
+    averageCo2eKgPerKm: 0,
+    byVehicle: [],
+  });
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const graphQLOptions = useMemo(
+    () => ({
+      apiGatewayUrl,
+      authToken,
+      workspaceToken,
+      workspaceId,
+      tenantId,
+      actorId: currentUser?.id,
+    }),
+    [apiGatewayUrl, authToken, workspaceToken, workspaceId, tenantId, currentUser?.id]
+  );
+
+  const load = useCallback(async () => {
+    setIsLoading(true);
+    setError(null);
+    try {
+      const data = await executeGraphQL<{
+        emissionsSummary: EmissionsSummary;
+      }>(graphQLOptions, EMISSIONS_SUMMARY_QUERY);
+
+      setSummary(data.emissionsSummary);
+    } catch (fetchError) {
+      setError(
+        fetchError instanceof Error ? fetchError : new Error('Failed to load emissions summary')
+      );
+    } finally {
+      setIsLoading(false);
+    }
+  }, [graphQLOptions]);
+
+  useEffect(() => {
+    void load();
+  }, [load]);
+
+  const refetch = useCallback(() => {
+    void load();
+  }, [load]);
+
+  return { summary, isLoading, error, refetch };
+}

package/src/movethewheels/hooks/useDemandForecast.ts

@@ -0,0 +1,161 @@
+import { useCallback, useEffect, useMemo, useState } from 'react';
+
+import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
+import { executeGraphQL } from '../utils/graphqlClient';
+
+/**
+ * Demand forecasting hook (BOFF-4393). Pulls next-N-week forecasts by lane
+ * and customer plus the recent closed-period variance. Read-side only — the
+ * admin console exposes `recalculateDemandForecasts` separately.
+ */
+
+export interface ForecastPoint {
+  scopeType: 'LANE' | 'CUSTOMER';
+  scopeKey: string;
+  periodStart: string;
+  periodEnd: string;
+  predictedVolume: number;
+  predictedRevenue: number;
+  actualVolume: number | null;
+  actualRevenue: number | null;
+  confidence: number;
+}
+
+export interface ForecastVariance {
+  scopeType: 'LANE' | 'CUSTOMER';
+  scopeKey: string;
+  periodStart: string;
+  periodEnd: string;
+  predictedVolume: number;
+  actualVolume: number;
+  volumeVariance: number;
+  predictedRevenue: number;
+  actualRevenue: number;
+  revenueVariance: number;
+}
+
+interface UseDemandForecastResult {
+  laneForecast: ForecastPoint[];
+  customerForecast: ForecastPoint[];
+  laneVariance: ForecastVariance[];
+  customerVariance: ForecastVariance[];
+  isLoading: boolean;
+  error: Error | null;
+  refetch: () => void;
+}
+
+const FORECAST_QUERY = `
+  query GetMovethewheelsDemandForecast($weeks: Int!, $varianceLimit: Int!) {
+    demandForecastByLane(weeks: $weeks) {
+      scopeType
+      scopeKey
+      periodStart
+      periodEnd
+      predictedVolume
+      predictedRevenue
+      actualVolume
+      actualRevenue
+      confidence
+    }
+    demandForecastByCustomer(weeks: $weeks) {
+      scopeType
+      scopeKey
+      periodStart
+      periodEnd
+      predictedVolume
+      predictedRevenue
+      actualVolume
+      actualRevenue
+      confidence
+    }
+    laneVariance: demandForecastVariance(scopeType: LANE, limit: $varianceLimit) {
+      scopeType
+      scopeKey
+      periodStart
+      periodEnd
+      predictedVolume
+      actualVolume
+      volumeVariance
+      predictedRevenue
+      actualRevenue
+      revenueVariance
+    }
+    customerVariance: demandForecastVariance(scopeType: CUSTOMER, limit: $varianceLimit) {
+      scopeType
+      scopeKey
+      periodStart
+      periodEnd
+      predictedVolume
+      actualVolume
+      volumeVariance
+      predictedRevenue
+      actualRevenue
+      revenueVariance
+    }
+  }
+`;
+
+export function useDemandForecast(weeks = 4, varianceLimit = 8): UseDemandForecastResult {
+  const { apiGatewayUrl, authToken, workspaceToken, workspaceId, tenantId, currentUser } =
+    useMoveTheWheels();
+  const [laneForecast, setLaneForecast] = useState<ForecastPoint[]>([]);
+  const [customerForecast, setCustomerForecast] = useState<ForecastPoint[]>([]);
+  const [laneVariance, setLaneVariance] = useState<ForecastVariance[]>([]);
+  const [customerVariance, setCustomerVariance] = useState<ForecastVariance[]>([]);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const graphQLOptions = useMemo(
+    () => ({
+      apiGatewayUrl,
+      authToken,
+      workspaceToken,
+      workspaceId,
+      tenantId,
+      actorId: currentUser?.id,
+    }),
+    [apiGatewayUrl, authToken, workspaceToken, workspaceId, tenantId, currentUser?.id]
+  );
+
+  const load = useCallback(async () => {
+    setIsLoading(true);
+    setError(null);
+    try {
+      const data = await executeGraphQL<{
+        demandForecastByLane: ForecastPoint[];
+        demandForecastByCustomer: ForecastPoint[];
+        laneVariance: ForecastVariance[];
+        customerVariance: ForecastVariance[];
+      }>(graphQLOptions, FORECAST_QUERY, { weeks, varianceLimit });
+
+      setLaneForecast(data.demandForecastByLane ?? []);
+      setCustomerForecast(data.demandForecastByCustomer ?? []);
+      setLaneVariance(data.laneVariance ?? []);
+      setCustomerVariance(data.customerVariance ?? []);
+    } catch (fetchError) {
+      setError(
+        fetchError instanceof Error ? fetchError : new Error('Failed to load demand forecast')
+      );
+    } finally {
+      setIsLoading(false);
+    }
+  }, [graphQLOptions, weeks, varianceLimit]);
+
+  useEffect(() => {
+    void load();
+  }, [load]);
+
+  const refetch = useCallback(() => {
+    void load();
+  }, [load]);
+
+  return {
+    laneForecast,
+    customerForecast,
+    laneVariance,
+    customerVariance,
+    isLoading,
+    error,
+    refetch,
+  };
+}

package/src/movethewheels/pages/AnalyticsPage.tsx

@@ -12,8 +12,11 @@ import { PageLayout } from '../components/PageLayout';
 import { MetricCard, MetricGrid, MetricCardSkeleton } from '../components/MetricCard';
 import { Card, CardContent, CardHeader, CardTitle, Progress, Button } from '../components/ui';
 import { TrendChart, VolumeBar, StatusDonut, type DonutSlice } from '../components/charts';
+import { UpcomingDemandPanel } from '../components/UpcomingDemandPanel';
+import { CarbonFootprintPanel } from '../components/CarbonFootprintPanel';
 import { EmphasisPanel, PagePurpose } from '@burdenoff/fe-libs/ui';
 import { useAnalytics, useOrderAnalytics, useFleetAnalytics } from '../hooks/useAnalytics';
+import { useDemandForecast } from '../hooks/useDemandForecast';
 import { formatCurrency } from '../utils/formatters';
 
 const statusLabel = (status: string) =>
@@ -23,6 +26,15 @@ export default function AnalyticsPage() {
   const { analytics, isLoading, error, refetch } = useAnalytics();
   const { orderData } = useOrderAnalytics();
   const { fleetData } = useFleetAnalytics();
+  const {
+    laneForecast,
+    customerForecast,
+    laneVariance,
+    customerVariance,
+    isLoading: forecastLoading,
+    error: forecastError,
+    refetch: refetchForecast,
+  } = useDemandForecast(4, 8);
 
   const orderSpark = useMemo(
     () => analytics.trends.dailyOrders.map((d) => d.orders),
@@ -129,6 +141,18 @@ export default function AnalyticsPage() {
         </CardContent>
       </Card>
 
+      {/* Upcoming demand (BOFF-4393) — heuristic forecast, surfaces only
+          when the workspace has enough history (>=4 weeks). */}
+      <UpcomingDemandPanel
+        laneForecast={laneForecast}
+        customerForecast={customerForecast}
+        laneVariance={laneVariance}
+        customerVariance={customerVariance}
+        isLoading={forecastLoading}
+        error={forecastError}
+        onRetry={refetchForecast}
+      />
+
       <div className="grid grid-cols-1 lg:grid-cols-2 gap-6">
         <Card>
           <CardHeader>
@@ -214,6 +238,9 @@ export default function AnalyticsPage() {
           </div>
         </EmphasisPanel>
       </div>
+
+      {/* Carbon footprint (BOFF-4391) */}
+      <CarbonFootprintPanel />
     </PageLayout>
   );
 }

package/src/operations/wspace/movethewheels/queries/forecast.graphql

@@ -0,0 +1,47 @@
+# Demand forecasting (BOFF-4393) — query operations against the
+# wspace-movethewheels-svc DemandForecast surface. Read-side only on the
+# UI; recalculation is triggered from the admin console via a separate
+# mutation that is not wired into the MFE yet.
+
+query GetMovethewheelsDemandForecastByLane($weeks: Int!) {
+  demandForecastByLane(weeks: $weeks) {
+    scopeType
+    scopeKey
+    periodStart
+    periodEnd
+    predictedVolume
+    predictedRevenue
+    actualVolume
+    actualRevenue
+    confidence
+  }
+}
+
+query GetMovethewheelsDemandForecastByCustomer($weeks: Int!) {
+  demandForecastByCustomer(weeks: $weeks) {
+    scopeType
+    scopeKey
+    periodStart
+    periodEnd
+    predictedVolume
+    predictedRevenue
+    actualVolume
+    actualRevenue
+    confidence
+  }
+}
+
+query GetMovethewheelsDemandForecastVariance($scopeType: DemandForecastScope!, $limit: Int!) {
+  demandForecastVariance(scopeType: $scopeType, limit: $limit) {
+    scopeType
+    scopeKey
+    periodStart
+    periodEnd
+    predictedVolume
+    actualVolume
+    volumeVariance
+    predictedRevenue
+    actualRevenue
+    revenueVariance
+  }
+}