@burdenoff/microfe-movethewheels 2026.804.1 → 2026.805.1

package/src/movethewheels/components/UpcomingDemandPanel.tsx

@@ -0,0 +1,228 @@
+/**
+ * UpcomingDemandPanel
+ *
+ * Surfaces next-week demand forecasts by lane / customer alongside the
+ * most recent closed-period variance (BOFF-4393). Pure read-side view
+ * over `wspace-movethewheels-svc`'s DemandForecast surface.
+ */
+
+import { Calendar, TrendingUp, TrendingDown, AlertCircle } from 'lucide-react';
+
+import { Card, CardContent, CardHeader, CardTitle, Skeleton } from './ui';
+
+import type {
+  ForecastPoint,
+  ForecastVariance,
+} from '../hooks/useDemandForecast';
+
+interface UpcomingDemandPanelProps {
+  laneForecast: ForecastPoint[];
+  customerForecast: ForecastPoint[];
+  laneVariance: ForecastVariance[];
+  customerVariance: ForecastVariance[];
+  isLoading: boolean;
+  error: Error | null;
+  onRetry: () => void;
+}
+
+const formatWeek = (iso: string): string => {
+  const date = new Date(iso);
+  if (Number.isNaN(date.getTime())) return iso;
+  return date.toLocaleDateString(undefined, { month: 'short', day: 'numeric' });
+};
+
+const topByVolume = (rows: ForecastPoint[], weekStart: string): ForecastPoint[] => {
+  const filtered = rows.filter((row) => row.periodStart === weekStart);
+  return [...filtered].sort((a, b) => b.predictedVolume - a.predictedVolume).slice(0, 3);
+};
+
+const topByRevenue = (rows: ForecastPoint[], weekStart: string): ForecastPoint[] => {
+  const filtered = rows.filter((row) => row.periodStart === weekStart);
+  return [...filtered].sort((a, b) => b.predictedRevenue - a.predictedRevenue).slice(0, 3);
+};
+
+const totalVolume = (rows: ForecastPoint[], weekStart: string): number =>
+  rows.filter((row) => row.periodStart === weekStart).reduce((sum, row) => sum + row.predictedVolume, 0);
+
+const formatConfidence = (confidence: number): string => {
+  if (confidence <= 0) return 'Not enough history';
+  return `${Math.round(confidence * 100)}% confidence`;
+};
+
+export function UpcomingDemandPanel({
+  laneForecast,
+  customerForecast,
+  laneVariance,
+  customerVariance,
+  isLoading,
+  error,
+  onRetry,
+}: UpcomingDemandPanelProps) {
+  if (error && !isLoading) {
+    return (
+      <Card className="border-status-error-border">
+        <CardContent className="p-6 text-center space-y-3">
+          <p className="text-status-error-text font-medium">Couldn&apos;t load demand forecast</p>
+          <p className="text-sm text-text-secondary">{error.message}</p>
+          <button
+            type="button"
+            onClick={onRetry}
+            className="text-sm font-medium text-primary hover:underline"
+          >
+            Retry
+          </button>
+        </CardContent>
+      </Card>
+    );
+  }
+
+  if (isLoading) {
+    return (
+      <Card>
+        <CardHeader>
+          <CardTitle>Upcoming demand</CardTitle>
+        </CardHeader>
+        <CardContent className="space-y-4">
+          <Skeleton className="h-16 w-full" />
+          <Skeleton className="h-16 w-full" />
+          <Skeleton className="h-16 w-full" />
+        </CardContent>
+      </Card>
+    );
+  }
+
+  const nextWeekStart = laneForecast[0]?.periodStart ?? customerForecast[0]?.periodStart ?? null;
+
+  if (!nextWeekStart || laneForecast.length === 0) {
+    return (
+      <Card>
+        <CardHeader>
+          <CardTitle className="flex items-center gap-2">
+            <Calendar size={18} aria-hidden="true" />
+            Upcoming demand
+          </CardTitle>
+        </CardHeader>
+        <CardContent>
+          <div className="flex items-start gap-2 rounded-lg border border-border/60 bg-muted/40 p-4 text-sm text-text-secondary">
+            <AlertCircle size={16} aria-hidden="true" className="mt-0.5 shrink-0" />
+            <p>
+              Not enough history to forecast next week yet. Once you have at least 4 weeks of
+              completed orders, this panel will surface demand by lane and customer.
+            </p>
+          </div>
+        </CardContent>
+      </Card>
+    );
+  }
+
+  const topLanes = topByVolume(laneForecast, nextWeekStart);
+  const topLanesByRevenue = topByRevenue(laneForecast, nextWeekStart);
+  const topCustomers = topByVolume(customerForecast, nextWeekStart);
+  const total = totalVolume(laneForecast, nextWeekStart);
+
+  // Most-recent variance row per scope key — show the lane that overshot /
+  // undershot the most in absolute volume terms.
+  const mostRecentVariance = [...laneVariance, ...customerVariance]
+    .sort((a, b) => Math.abs(b.volumeVariance) - Math.abs(a.volumeVariance))
+    .slice(0, 3);
+
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle className="flex items-center gap-2">
+          <Calendar size={18} aria-hidden="true" />
+          Upcoming demand — week of {formatWeek(nextWeekStart)}
+        </CardTitle>
+      </CardHeader>
+      <CardContent className="space-y-4">
+        <div className="flex items-baseline justify-between rounded-lg border border-border/60 bg-muted/40 px-4 py-3">
+          <div>
+            <p className="text-xs uppercase tracking-wide text-text-secondary">
+              Predicted jobs (all lanes)
+            </p>
+            <p className="text-2xl font-bold">{total}</p>
+          </div>
+          <p className="text-xs text-text-secondary">
+            {topLanes[0] ? formatConfidence(topLanes[0].confidence) : ''}
+          </p>
+        </div>
+
+        <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
+          <ForecastList title="Top lanes (volume)" rows={topLanes} />
+          <ForecastList title="Top lanes (revenue)" rows={topLanesByRevenue} />
+          <ForecastList title="Top customers (volume)" rows={topCustomers} />
+          <VarianceList rows={mostRecentVariance} />
+        </div>
+      </CardContent>
+    </Card>
+  );
+}
+
+interface ForecastListProps {
+  title: string;
+  rows: ForecastPoint[];
+}
+
+function ForecastList({ title, rows }: ForecastListProps) {
+  if (rows.length === 0) {
+    return (
+      <div className="rounded-lg border border-border/60 p-4">
+        <p className="text-sm font-medium mb-2">{title}</p>
+        <p className="text-xs text-text-secondary">No forecasts yet for this week.</p>
+      </div>
+    );
+  }
+  return (
+    <div className="rounded-lg border border-border/60 p-4">
+      <p className="text-sm font-medium mb-3">{title}</p>
+      <ul className="space-y-2">
+        {rows.map((row) => (
+          <li key={`${row.scopeType}-${row.scopeKey}`} className="flex items-center justify-between text-sm">
+            <span className="truncate font-medium">{row.scopeKey}</span>
+            <span className="ml-2 shrink-0 text-text-secondary">
+              {row.predictedVolume} jobs ·{' '}
+              {new Intl.NumberFormat(undefined, { style: 'currency', currency: 'USD', maximumFractionDigits: 0 }).format(
+                row.predictedRevenue
+              )}
+            </span>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+
+interface VarianceListProps {
+  rows: ForecastVariance[];
+}
+
+function VarianceList({ rows }: VarianceListProps) {
+  return (
+    <div className="rounded-lg border border-border/60 p-4">
+      <p className="text-sm font-medium mb-3">Recent forecast variance</p>
+      {rows.length === 0 ? (
+        <p className="text-xs text-text-secondary">No closed periods to compare yet.</p>
+      ) : (
+        <ul className="space-y-2">
+          {rows.map((row) => {
+            const isOvershoot = row.volumeVariance > 0;
+            const Icon = isOvershoot ? TrendingUp : TrendingDown;
+            const tone = isOvershoot ? 'text-emerald-600 dark:text-emerald-400' : 'text-rose-600 dark:text-rose-400';
+            return (
+              <li key={`${row.scopeType}-${row.scopeKey}-${row.periodStart}`} className="flex items-center justify-between text-sm">
+                <span className="flex items-center gap-2 truncate">
+                  <Icon size={14} className={tone} aria-hidden="true" />
+                  <span className="truncate font-medium">{row.scopeKey}</span>
+                </span>
+                <span className={`ml-2 shrink-0 ${tone}`}>
+                  {isOvershoot ? '+' : ''}
+                  {row.volumeVariance} jobs
+                </span>
+              </li>
+            );
+          })}
+        </ul>
+      )}
+    </div>
+  );
+}

package/src/movethewheels/hooks/useDemandForecast.ts

@@ -0,0 +1,155 @@
+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,14 @@ 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 { EmphasisPanel, PagePurpose } from '@burdenoff/fe-libs/ui';
-import { useAnalytics, useOrderAnalytics, useFleetAnalytics } from '../hooks/useAnalytics';
+import {
+  useAnalytics,
+  useOrderAnalytics,
+  useFleetAnalytics,
+} from '../hooks/useAnalytics';
+import { useDemandForecast } from '../hooks/useDemandForecast';
 import { formatCurrency } from '../utils/formatters';
 
 const statusLabel = (status: string) =>
@@ -23,6 +29,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 +144,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>

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