@burdenoff/microfe-movethewheels 2026.703.3 → 2026.703.5

package/src/movethewheels/components/maps/MapCanvas.tsx

@@ -0,0 +1,118 @@
+import { useEffect, useState, type ReactNode } from 'react';
+import L from 'leaflet';
+import { MapContainer, TileLayer, useMap } from 'react-leaflet';
+import { cn } from '../../utils/cn';
+import { OSM_ATTRIBUTION, OSM_TILE_URL } from './leaflet-setup';
+
+/** SSR/lazy safety: only mount Leaflet (which touches the DOM) after mount. */
+export function useIsMounted(): boolean {
+  const [mounted, setMounted] = useState(false);
+  useEffect(() => setMounted(true), []);
+  return mounted;
+}
+
+/**
+ * Imperatively fit the map to a set of [lat,lng] points whenever they change.
+ * Invalidates size on mount so tiles render correctly inside flex/grid parents.
+ */
+export function FitBounds({
+  points,
+  padding = 48,
+  maxZoom = 13,
+}: {
+  points: Array<[number, number]>;
+  padding?: number;
+  maxZoom?: number;
+}) {
+  const map = useMap();
+
+  useEffect(() => {
+    const t = setTimeout(() => map.invalidateSize(), 0);
+    return () => clearTimeout(t);
+  }, [map]);
+
+  useEffect(() => {
+    if (points.length === 0) return;
+    if (points.length === 1) {
+      map.setView(points[0], Math.min(maxZoom, 12));
+      return;
+    }
+    const bounds = L.latLngBounds(points);
+    map.fitBounds(bounds, { padding: [padding, padding], maxZoom });
+  }, [map, points, padding, maxZoom]);
+
+  return null;
+}
+
+interface MapCanvasProps {
+  points: Array<[number, number]>;
+  height?: number | string;
+  className?: string;
+  fitToMarkers?: boolean;
+  /** Fallback center when there are no points but we still render the canvas. */
+  center?: [number, number];
+  zoom?: number;
+  children?: ReactNode;
+  /** Rendered instead of the map when there are no points. */
+  emptyState?: ReactNode;
+}
+
+/**
+ * MapCanvas — the shared OSM MapContainer used by every map component. Handles
+ * mount-safety, container sizing, rounded/overflow styling, tile layer, and
+ * auto-fit. Renders `emptyState` when there is nothing to plot.
+ */
+export function MapCanvas({
+  points,
+  height = 420,
+  className,
+  fitToMarkers = true,
+  center,
+  zoom = 5,
+  children,
+  emptyState,
+}: MapCanvasProps) {
+  const mounted = useIsMounted();
+
+  const wrapperClass = cn(
+    'relative overflow-hidden rounded-2xl border border-border-seam bg-bg-sunken',
+    className
+  );
+  const style = { height, width: '100%' };
+
+  if (points.length === 0 && emptyState) {
+    return (
+      <div className={wrapperClass} style={style}>
+        <div className="flex h-full w-full items-center justify-center p-6 text-center">
+          {emptyState}
+        </div>
+      </div>
+    );
+  }
+
+  if (!mounted) {
+    return (
+      <div className={wrapperClass} style={style} aria-busy="true">
+        <div className="h-full w-full motion-safe:animate-vc-shimmer bg-bg-sunken" />
+      </div>
+    );
+  }
+
+  const initialCenter: [number, number] = center ?? points[0] ?? [20, 0];
+
+  return (
+    <div className={wrapperClass} style={style}>
+      <MapContainer
+        center={initialCenter}
+        zoom={points.length > 0 ? zoom : 2}
+        scrollWheelZoom={false}
+        style={{ height: '100%', width: '100%' }}
+        className="z-0"
+      >
+        <TileLayer url={OSM_TILE_URL} attribution={OSM_ATTRIBUTION} />
+        {fitToMarkers && <FitBounds points={points} />}
+        {children}
+      </MapContainer>
+    </div>
+  );
+}

package/src/movethewheels/components/maps/RouteMap.tsx

@@ -0,0 +1,71 @@
+import { useMemo } from 'react';
+import { Marker, Polyline, Popup } from 'react-leaflet';
+import { MapCanvas } from './MapCanvas';
+import { createStopIcon, isRealCoord } from './leaflet-setup';
+
+export interface RouteStop {
+  lat: number;
+  lng: number;
+  label: string;
+  sequence: number;
+}
+
+interface RouteMapProps {
+  stops: RouteStop[];
+  height?: number | string;
+  className?: string;
+  /** Polyline color (design-token string). Defaults to brand blue. */
+  routeColor?: string;
+  emptyMessage?: string;
+}
+
+/**
+ * RouteMap — numbered stop markers in sequence connected by a polyline. Filters
+ * out stops without a real coordinate and orders the line by `sequence`.
+ */
+export function RouteMap({
+  stops,
+  height = 420,
+  className,
+  routeColor = 'var(--color-chart-1)',
+  emptyMessage = 'No stops with coordinates yet',
+}: RouteMapProps) {
+  const ordered = useMemo(
+    () => [...stops].filter((s) => isRealCoord(s.lat, s.lng)).sort((a, b) => a.sequence - b.sequence),
+    [stops]
+  );
+
+  const line = useMemo<Array<[number, number]>>(
+    () => ordered.map((s) => [s.lat, s.lng]),
+    [ordered]
+  );
+
+  return (
+    <MapCanvas
+      points={line}
+      height={height}
+      className={className}
+      emptyState={<p className="text-sm text-text-secondary">{emptyMessage}</p>}
+    >
+      {line.length >= 2 && (
+        <Polyline
+          positions={line}
+          pathOptions={{ color: routeColor, weight: 4, opacity: 0.85 }}
+        />
+      )}
+      {ordered.map((s) => (
+        <Marker
+          key={`${s.sequence}-${s.lat}-${s.lng}`}
+          position={[s.lat, s.lng]}
+          icon={createStopIcon(s.sequence)}
+        >
+          <Popup>
+            <span className="font-semibold">
+              {s.sequence}. {s.label}
+            </span>
+          </Popup>
+        </Marker>
+      ))}
+    </MapCanvas>
+  );
+}

package/src/movethewheels/components/maps/TrackingMap.tsx

@@ -0,0 +1,102 @@
+import { useMemo } from 'react';
+import { Marker, Polyline, Popup } from 'react-leaflet';
+import { MapCanvas } from './MapCanvas';
+import { createCurrentIcon, createPinIcon, isRealCoord } from './leaflet-setup';
+
+export interface TrackPoint {
+  lat: number;
+  lng: number;
+  timestamp?: string;
+}
+
+export interface TrackEndpoint {
+  lat: number;
+  lng: number;
+  label?: string;
+}
+
+interface TrackingMapProps {
+  origin?: TrackEndpoint | null;
+  destination?: TrackEndpoint | null;
+  /** Ordered breadcrumb of positions the shipment has passed through. */
+  trail: TrackPoint[];
+  current?: TrackEndpoint | null;
+  height?: number | string;
+  className?: string;
+  /** Trail polyline color (design-token string). Defaults to brand blue. */
+  trailColor?: string;
+  emptyMessage?: string;
+}
+
+/**
+ * TrackingMap — renders a shipment's breadcrumb trail with origin/destination
+ * pins and a live "current position" dot. Everything is filtered for real
+ * coordinates so a missing GPS fix never plots at null-island.
+ */
+export function TrackingMap({
+  origin,
+  destination,
+  trail,
+  current,
+  height = 360,
+  className,
+  trailColor = 'var(--color-chart-1)',
+  emptyMessage = 'No tracking positions yet',
+}: TrackingMapProps) {
+  const trailLine = useMemo<Array<[number, number]>>(
+    () => trail.filter((p) => isRealCoord(p.lat, p.lng)).map((p) => [p.lat, p.lng]),
+    [trail]
+  );
+
+  const originOk = origin && isRealCoord(origin.lat, origin.lng) ? origin : null;
+  const destOk = destination && isRealCoord(destination.lat, destination.lng) ? destination : null;
+  const currentOk = current && isRealCoord(current.lat, current.lng) ? current : null;
+
+  const fitPoints = useMemo<Array<[number, number]>>(() => {
+    const pts: Array<[number, number]> = [...trailLine];
+    if (originOk) pts.push([originOk.lat, originOk.lng]);
+    if (destOk) pts.push([destOk.lat, destOk.lng]);
+    if (currentOk) pts.push([currentOk.lat, currentOk.lng]);
+    return pts;
+  }, [trailLine, originOk, destOk, currentOk]);
+
+  return (
+    <MapCanvas
+      points={fitPoints}
+      height={height}
+      className={className}
+      emptyState={<p className="text-sm text-text-secondary">{emptyMessage}</p>}
+    >
+      {trailLine.length >= 2 && (
+        <Polyline
+          positions={trailLine}
+          pathOptions={{ color: trailColor, weight: 4, opacity: 0.85, dashArray: '1 8', lineCap: 'round' }}
+        />
+      )}
+      {originOk && (
+        <Marker position={[originOk.lat, originOk.lng]} icon={createPinIcon('origin', { glyph: false })}>
+          <Popup>
+            <span className="font-semibold">{originOk.label ?? 'Origin'}</span>
+          </Popup>
+        </Marker>
+      )}
+      {destOk && (
+        <Marker
+          position={[destOk.lat, destOk.lng]}
+          icon={createPinIcon('destination', { glyph: false })}
+        >
+          <Popup>
+            <span className="font-semibold">{destOk.label ?? 'Destination'}</span>
+          </Popup>
+        </Marker>
+      )}
+      {currentOk && (
+        <Marker position={[currentOk.lat, currentOk.lng]} icon={createCurrentIcon()}>
+          <Popup>
+            <span className="font-semibold">{currentOk.label ?? 'Current position'}</span>
+          </Popup>
+        </Marker>
+      )}
+    </MapCanvas>
+  );
+}

package/src/movethewheels/components/maps/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Map primitives (react-leaflet + OpenStreetMap tiles) — brand-styled markers,
+ * mount-safe, responsive, honest empty states. Coordinates at null-island (0,0)
+ * or non-finite values are always filtered out.
+ */
+export { LogisticsMap, type LogisticsMarker, type LogisticsRoute } from './LogisticsMap';
+export { RouteMap, type RouteStop } from './RouteMap';
+export { TrackingMap, type TrackPoint, type TrackEndpoint } from './TrackingMap';
+export { MapCanvas } from './MapCanvas';
+export {
+  createPinIcon,
+  createStopIcon,
+  createCurrentIcon,
+  isRealCoord,
+  type MapMarkerStatus,
+} from './leaflet-setup';

package/src/movethewheels/components/maps/leaflet-setup.ts

@@ -0,0 +1,124 @@
+import L from 'leaflet';
+// Leaflet's stylesheet — imported once here so every map component inherits it.
+import 'leaflet/dist/leaflet.css';
+// Brand-styled marker CSS (pins, numbered stops, live dot).
+import './map-markers.css';
+
+/**
+ * OpenStreetMap raster tiles. There is no CSP blocking external tiles in the
+ * app-shell, so we use the standard OSM tile server.
+ */
+export const OSM_TILE_URL = 'https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png';
+export const OSM_ATTRIBUTION =
+  '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors';
+
+export type MapMarkerStatus =
+  | 'active'
+  | 'in_transit'
+  | 'idle'
+  | 'delayed'
+  | 'delivered'
+  | 'origin'
+  | 'destination'
+  | 'default';
+
+/**
+ * A coordinate is "real" only when it is finite and not the null-island (0,0)
+ * sentinel that backends emit for "unknown location". We never plot those.
+ */
+export function isRealCoord(lat: unknown, lng: unknown): lat is number {
+  return (
+    typeof lat === 'number' &&
+    typeof lng === 'number' &&
+    Number.isFinite(lat) &&
+    Number.isFinite(lng) &&
+    !(lat === 0 && lng === 0) &&
+    Math.abs(lat) <= 90 &&
+    Math.abs(lng) <= 180
+  );
+}
+
+/**
+ * Map a domain status to a fe-libs design token color (resolved via CSS var, so
+ * it stays theme-aware). No raw palette colors.
+ */
+function statusColorToken(status: MapMarkerStatus): string {
+  switch (status) {
+    case 'delayed':
+      return 'var(--color-status-error-text)';
+    case 'idle':
+      return 'var(--color-status-warning-text)';
+    case 'delivered':
+    case 'destination':
+      return 'var(--color-status-success-text)';
+    case 'in_transit':
+    case 'active':
+    case 'origin':
+    default:
+      return 'var(--color-brand-primary)';
+  }
+}
+
+const TRUCK_GLYPH = `
+<svg viewBox="0 0 24 24" width="13" height="13" fill="none" stroke="white"
+  stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+  <path d="M10 17h4V5H2v12h3"/><path d="M20 17h2v-3.34a4 4 0 0 0-1.17-2.83L19 9h-5v8h1"/>
+  <circle cx="7.5" cy="17.5" r="1.5"/><circle cx="17.5" cy="17.5" r="1.5"/>
+</svg>`;
+
+/**
+ * A brand-styled teardrop pin (orange by default) with a white truck glyph.
+ * Built as an HTML `divIcon` because Leaflet's default marker PNGs break under
+ * bundlers.
+ */
+export function createPinIcon(
+  status: MapMarkerStatus = 'default',
+  options?: { pulse?: boolean; glyph?: boolean }
+): L.DivIcon {
+  const color = statusColorToken(status);
+  const pulse = options?.pulse ?? (status === 'in_transit' || status === 'active');
+  const glyph = options?.glyph ?? true;
+
+  const html = `
+    <div class="mtw-pin${pulse ? ' mtw-pin--pulse' : ''}" style="--mtw-pin-color:${color}">
+      <span class="mtw-pin__body">${glyph ? TRUCK_GLYPH : ''}</span>
+    </div>`;
+
+  return L.divIcon({
+    html,
+    className: 'mtw-pin-wrapper',
+    iconSize: [30, 38],
+    iconAnchor: [15, 36],
+    popupAnchor: [0, -32],
+  });
+}
+
+/**
+ * A small numbered circle marker for ordered route stops.
+ */
+export function createStopIcon(sequence: number, color = 'var(--color-brand-primary)'): L.DivIcon {
+  const html = `
+    <div class="mtw-stop" style="--mtw-pin-color:${color}">
+      <span class="mtw-stop__num">${sequence}</span>
+    </div>`;
+  return L.divIcon({
+    html,
+    className: 'mtw-pin-wrapper',
+    iconSize: [28, 28],
+    iconAnchor: [14, 14],
+    popupAnchor: [0, -14],
+  });
+}
+
+/**
+ * A pulsing dot for the shipment's current/live position.
+ */
+export function createCurrentIcon(color = 'var(--color-brand-primary)'): L.DivIcon {
+  const html = `<div class="mtw-current" style="--mtw-pin-color:${color}"><span></span></div>`;
+  return L.divIcon({
+    html,
+    className: 'mtw-pin-wrapper',
+    iconSize: [20, 20],
+    iconAnchor: [10, 10],
+  });
+}

package/src/movethewheels/components/maps/map-markers.css

@@ -0,0 +1,121 @@
+/* Brand-styled Leaflet markers for MoveTheWheels.
+ * Colors come from --mtw-pin-color, which each divIcon sets from a design token
+ * (var(--color-*)), so markers stay theme-aware with no raw palette values. */
+
+.mtw-pin-wrapper {
+  background: transparent;
+  border: 0;
+}
+
+.mtw-pin {
+  position: relative;
+  width: 30px;
+  height: 38px;
+  filter: drop-shadow(0 4px 6px rgb(0 0 0 / 0.28));
+}
+
+.mtw-pin__body {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding-bottom: 8px;
+  background: var(--mtw-pin-color, #f97316);
+  border: 2px solid rgb(255 255 255 / 0.9);
+  border-radius: 50% 50% 50% 0;
+  transform: rotate(-45deg);
+  box-sizing: border-box;
+}
+
+.mtw-pin__body > svg {
+  transform: rotate(45deg);
+}
+
+.mtw-pin--pulse::before {
+  content: '';
+  position: absolute;
+  left: 50%;
+  top: 13px;
+  width: 30px;
+  height: 30px;
+  transform: translate(-50%, -50%);
+  border-radius: 50%;
+  background: var(--mtw-pin-color, #f97316);
+  opacity: 0.45;
+  animation: mtw-pin-pulse 1.8s ease-out infinite;
+}
+
+@keyframes mtw-pin-pulse {
+  0% {
+    transform: translate(-50%, -50%) scale(0.6);
+    opacity: 0.5;
+  }
+  100% {
+    transform: translate(-50%, -50%) scale(2.4);
+    opacity: 0;
+  }
+}
+
+.mtw-stop {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 28px;
+  height: 28px;
+  border-radius: 9999px;
+  background: var(--mtw-pin-color, #f97316);
+  border: 2px solid rgb(255 255 255 / 0.95);
+  box-shadow: 0 2px 6px rgb(0 0 0 / 0.28);
+}
+
+.mtw-stop__num {
+  color: #fff;
+  font-size: 12px;
+  font-weight: 700;
+  line-height: 1;
+}
+
+.mtw-current {
+  position: relative;
+  width: 20px;
+  height: 20px;
+}
+
+.mtw-current > span {
+  position: absolute;
+  inset: 4px;
+  border-radius: 9999px;
+  background: var(--mtw-pin-color, #f97316);
+  border: 2px solid rgb(255 255 255 / 0.95);
+  box-shadow: 0 2px 6px rgb(0 0 0 / 0.3);
+}
+
+.mtw-current::after {
+  content: '';
+  position: absolute;
+  inset: 0;
+  border-radius: 9999px;
+  background: var(--mtw-pin-color, #f97316);
+  opacity: 0.4;
+  animation: mtw-pin-pulse 1.8s ease-out infinite;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .mtw-pin--pulse::before,
+  .mtw-current::after {
+    animation: none;
+  }
+}
+
+/* Keep Leaflet controls/attribution visually consistent with the app surface. */
+.leaflet-container {
+  font-family: inherit;
+  background: var(--color-bg-sunken, #eef1f5);
+}
+
+.leaflet-container .leaflet-control-attribution {
+  background: rgb(255 255 255 / 0.75);
+  color: #4b5563;
+  font-size: 10px;
+}

package/src/movethewheels/hooks/index.ts

@@ -41,6 +41,8 @@ export {
   useOrderAnalytics,
   useFleetAnalytics,
   usePerformanceAnalytics,
+  useFinanceMetrics,
+  type FinanceMetrics,
 } from './useAnalytics';
 
 // Tracking
@@ -65,3 +67,10 @@ export { useImportExport } from './useImportExport';
 
 // Module settings
 export { useModuleSettings } from './useSettings';
+
+// Entity documents (reuse of wspace-files-svc)
+export {
+  useEntityDocuments,
+  type EntityDocument,
+  type EntityDocumentType,
+} from './useEntityDocuments';

package/src/movethewheels/hooks/useAnalytics.ts

@@ -165,6 +165,7 @@ export function useAnalytics(_options: UseAnalyticsOptions = {}): UseAnalyticsRe
       const data = await executeGraphQL<{
         analytics: {
           orderTrend: Array<{ label: string; value: number }>;
+          deliveryTrend: Array<{ label: string; value: number }>;
           revenueTrend: Array<{ label: string; value: number }>;
         };
         dashboardMetrics: {
@@ -191,10 +192,19 @@ export function useAnalytics(_options: UseAnalyticsOptions = {}): UseAnalyticsRe
           customerSatisfaction: data.dashboardMetrics.customerSatisfaction,
         },
         trends: {
-          dailyOrders: data.analytics.orderTrend.map((item) => ({
-            date: item.label,
-            orders: Math.round(item.value),
-          })),
+          dailyOrders: (() => {
+            const deliveriesByLabel = new Map(
+              (data.analytics.deliveryTrend ?? []).map((item) => [
+                item.label,
+                Math.round(item.value),
+              ])
+            );
+            return data.analytics.orderTrend.map((item) => ({
+              date: item.label,
+              orders: Math.round(item.value),
+              deliveries: deliveriesByLabel.get(item.label) ?? 0,
+            }));
+          })(),
           revenue: data.analytics.revenueTrend.map((item) => ({
             month: item.label,
             revenue: item.value,
@@ -469,6 +479,101 @@ export function useFleetAnalytics() {
   return { fleetData, isLoading, error };
 }
 
+const FINANCE_METRICS_QUERY = `
+  query GetMovethewheelsFinanceMetrics {
+    financeMetrics {
+      revenue {
+        totalRevenue
+        deliveredRevenue
+        averageOrderValue
+      }
+      fuelCost
+      openInvoices
+    }
+  }
+`;
+
+export interface FinanceMetrics {
+  totalRevenue: number;
+  deliveredRevenue: number;
+  averageOrderValue: number;
+  fuelCost: number;
+  openInvoices: number;
+}
+
+/**
+ * Real finance figures straight from Query.financeMetrics — no simulated splits.
+ * `deliveredRevenue` is money already collected on delivered orders; `openInvoices`
+ * is the count of orders still owing. Both come from the service, never inferred.
+ */
+export function useFinanceMetrics() {
+  const { apiGatewayUrl, authToken, workspaceToken, workspaceId, tenantId, currentUser } =
+    useMoveTheWheels();
+  const [metrics, setMetrics] = useState<FinanceMetrics>({
+    totalRevenue: 0,
+    deliveredRevenue: 0,
+    averageOrderValue: 0,
+    fuelCost: 0,
+    openInvoices: 0,
+  });
+  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<{
+        financeMetrics: {
+          revenue: {
+            totalRevenue: number;
+            deliveredRevenue: number;
+            averageOrderValue: number;
+          };
+          fuelCost: number;
+          openInvoices: number;
+        };
+      }>(graphQLOptions, FINANCE_METRICS_QUERY);
+
+      setMetrics({
+        totalRevenue: data.financeMetrics.revenue.totalRevenue,
+        deliveredRevenue: data.financeMetrics.revenue.deliveredRevenue,
+        averageOrderValue: data.financeMetrics.revenue.averageOrderValue,
+        fuelCost: data.financeMetrics.fuelCost,
+        openInvoices: data.financeMetrics.openInvoices,
+      });
+    } catch (fetchError) {
+      setError(
+        fetchError instanceof Error ? fetchError : new Error('Failed to load finance metrics')
+      );
+    } finally {
+      setIsLoading(false);
+    }
+  }, [graphQLOptions]);
+
+  useEffect(() => {
+    void load();
+  }, [load]);
+
+  const refetch = useCallback(() => {
+    void load();
+  }, [load]);
+
+  return { metrics, isLoading, error, refetch };
+}
+
 export function usePerformanceAnalytics() {
   const { analytics, isLoading, error } = useAnalytics();