@burdenoff/microfe-movethewheels 2026.703.2 → 2026.703.4

package/src/movethewheels/hooks/useAnalytics.ts

@@ -469,6 +469,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();
 

package/src/movethewheels/hooks/useCustomers.ts

@@ -12,6 +12,8 @@ interface UseCustomersOptions {
 interface UseCustomersResult {
   customers: Customer[];
   totalCustomers: number;
+  /** True when the last fetch returned a full page (rawCount === limit). */
+  hasMore: boolean;
   isLoading: boolean;
   error: Error | null;
   refetch: () => void;
@@ -151,9 +153,10 @@ function mapCustomer(customer: ApiCustomer): Customer {
 
 export function useCustomers(options: UseCustomersOptions = {}): UseCustomersResult {
   const { filters: rawFilters, limit = 20, offset = 0 } = options;
-  // Stabilize filters by its structural fields so the load callback's inferred
-  // `filters` dependency (React Compiler) matches a stable reference and the
-  // effect does not re-run on every parent render.
+  // Stabilize the filters reference by its primitive fields so React Compiler's
+  // inferred `filters` dependency stays stable and loadCustomers is not
+  // recreated (and refetched) on every render when the caller passes an inline
+  // filters object.
   const filters = useMemo(
     () => rawFilters,
     [rawFilters?.isActive, rawFilters?.search, rawFilters?.type]
@@ -162,6 +165,7 @@ export function useCustomers(options: UseCustomersOptions = {}): UseCustomersRes
     useMoveTheWheels();
 
   const [customers, setCustomers] = useState<Customer[]>([]);
+  const [hasMore, setHasMore] = useState(false);
   const [isLoading, setIsLoading] = useState(false);
   const [error, setError] = useState<Error | null>(null);
 
@@ -191,7 +195,9 @@ export function useCustomers(options: UseCustomersOptions = {}): UseCustomersRes
         pagination: { limit, offset },
       });
 
-      let mapped = data.customers.map(mapCustomer);
+      const raw = data.customers;
+      setHasMore(raw.length === limit);
+      let mapped = raw.map(mapCustomer);
       if (filters?.isActive !== undefined) {
         mapped = mapped.filter((item) => item.isActive === filters.isActive);
       }
@@ -275,6 +281,7 @@ export function useCustomers(options: UseCustomersOptions = {}): UseCustomersRes
   return {
     customers,
     totalCustomers: customers.length,
+    hasMore,
     isLoading,
     error,
     refetch,

package/src/movethewheels/hooks/useEntityDocuments.ts

@@ -0,0 +1,132 @@
+/**
+ * useEntityDocuments — real document listing via wspace-files-svc.
+ *
+ * MoveTheWheels does NOT own a Document model. Documents attached to a vehicle,
+ * driver or order live in the platform Files module (wspace-files-svc), which
+ * federates into the same workspace gateway. We tag each uploaded file with two
+ * marqueue entity tags — `mtwEntityType` and `mtwEntityId` — and list them back
+ * here through the federated `files(filter:{ tags:[...] })` query.
+ *
+ * There is no upload UI here (out of scope): uploading/managing happens in the
+ * Files module, deep-linked from DocumentsCard. This hook is read-only.
+ */
+
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
+import { executeGraphQL } from '../utils/graphqlClient';
+
+export type EntityDocumentType = 'vehicle' | 'driver' | 'order';
+
+export interface EntityDocument {
+  id: string;
+  name: string;
+  /** Byte size (File.size is BigInt → string over JSON). */
+  size: number;
+  mimeType: string;
+  createdAt: Date;
+  /** Presigned download/open link, when the files service exposes one. */
+  downloadUrl?: string;
+}
+
+interface ApiFile {
+  id: string;
+  name: string;
+  size: string | number | null;
+  mimeType: string;
+  createdAt: string;
+  downloadUrl?: string | null;
+}
+
+interface UseEntityDocumentsResult {
+  documents: EntityDocument[];
+  isLoading: boolean;
+  error: Error | null;
+  refetch: () => void;
+}
+
+const LIST_ENTITY_FILES_QUERY = `
+  query ListEntityDocuments($filter: FileFilterInput, $pagination: PaginationInput) {
+    files(filter: $filter, pagination: $pagination) {
+      id
+      name
+      size
+      mimeType
+      createdAt
+      downloadUrl
+    }
+  }
+`;
+
+function mapFile(file: ApiFile): EntityDocument {
+  return {
+    id: file.id,
+    name: file.name,
+    size: file.size != null ? Number(file.size) : 0,
+    mimeType: file.mimeType,
+    createdAt: new Date(file.createdAt),
+    downloadUrl: file.downloadUrl ?? undefined,
+  };
+}
+
+export function useEntityDocuments(
+  entityType: EntityDocumentType,
+  entityId: string | undefined
+): UseEntityDocumentsResult {
+  const { apiGatewayUrl, authToken, workspaceToken, workspaceId, tenantId, currentUser } =
+    useMoveTheWheels();
+  const [documents, setDocuments] = useState<EntityDocument[]>([]);
+  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 () => {
+    if (!entityId) {
+      setDocuments([]);
+      return;
+    }
+    setIsLoading(true);
+    setError(null);
+    try {
+      const data = await executeGraphQL<{ files: ApiFile[] }>(
+        graphQLOptions,
+        LIST_ENTITY_FILES_QUERY,
+        {
+          filter: {
+            tags: [
+              { key: 'mtwEntityType', value: entityType },
+              { key: 'mtwEntityId', value: entityId },
+            ],
+          },
+          pagination: { limit: 50, offset: 0 },
+        }
+      );
+      setDocuments((data.files ?? []).map(mapFile));
+    } catch (fetchError) {
+      setError(fetchError instanceof Error ? fetchError : new Error('Failed to load documents'));
+      setDocuments([]);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [entityId, entityType, graphQLOptions]);
+
+  useEffect(() => {
+    void load();
+  }, [load]);
+
+  const refetch = useCallback(() => {
+    void load();
+  }, [load]);
+
+  return { documents, isLoading, error, refetch };
+}

package/src/movethewheels/hooks/useFleet.ts

@@ -428,7 +428,9 @@ function useGraphqlOptions() {
 
 export function useFleet(options: UseFleetOptions = {}): UseFleetResult {
   const { filters: rawFilters } = options;
-  // Stabilize filters reference for React Compiler memoization.
+  // Stabilize the filters reference by its primitive fields so React Compiler's
+  // inferred `filters` dependency stays stable and `load` is not recreated (and
+  // refetched) every render when the caller passes an inline filters object.
   const filters = useMemo(
     () => rawFilters,
     [rawFilters?.driverId, rawFilters?.status, rawFilters?.vehicleType]
@@ -534,9 +536,16 @@ export function useFleet(options: UseFleetOptions = {}): UseFleetResult {
   };
 }
 
+interface UseListOptions {
+  limit?: number;
+  offset?: number;
+}
+
 interface UseVehiclesResult {
   vehicles: Vehicle[];
   totalVehicles: number;
+  /** True when the last fetch returned a full page (rawCount === limit). */
+  hasMore: boolean;
   isLoading: boolean;
   error: Error | null;
   refetch: () => void;
@@ -544,9 +553,11 @@ interface UseVehiclesResult {
   assignDriver: (vehicleId: string, driverId: string) => Promise<Vehicle>;
 }
 
-export function useVehicles(): UseVehiclesResult {
+export function useVehicles(options: UseListOptions = {}): UseVehiclesResult {
+  const { limit = 200, offset = 0 } = options;
   const graphQLOptions = useGraphqlOptions();
   const [vehicles, setVehicles] = useState<Vehicle[]>([]);
+  const [hasMore, setHasMore] = useState(false);
   const [isLoading, setIsLoading] = useState(false);
   const [error, setError] = useState<Error | null>(null);
 
@@ -558,16 +569,17 @@ export function useVehicles(): UseVehiclesResult {
         graphQLOptions,
         LIST_VEHICLES_QUERY,
         {
-          pagination: { limit: 200, offset: 0 },
+          pagination: { limit, offset },
         }
       );
+      setHasMore(data.vehicles.length === limit);
       setVehicles(data.vehicles.map(mapVehicle));
     } catch (fetchError) {
       setError(fetchError instanceof Error ? fetchError : new Error('Failed to load vehicles'));
     } finally {
       setIsLoading(false);
     }
-  }, [graphQLOptions]);
+  }, [graphQLOptions, limit, offset]);
 
   useEffect(() => {
     void load();
@@ -618,6 +630,7 @@ export function useVehicles(): UseVehiclesResult {
   return {
     vehicles,
     totalVehicles: vehicles.length,
+    hasMore,
     isLoading,
     error,
     refetch,
@@ -670,6 +683,8 @@ export function useVehicle(vehicleId: string | undefined) {
 interface UseDriversResult {
   drivers: Driver[];
   totalDrivers: number;
+  /** True when the last fetch returned a full page (rawCount === limit). */
+  hasMore: boolean;
   isLoading: boolean;
   error: Error | null;
   refetch: () => void;
@@ -677,9 +692,11 @@ interface UseDriversResult {
   assignVehicle: (driverId: string, vehicleId: string) => Promise<Driver>;
 }
 
-export function useDrivers(): UseDriversResult {
+export function useDrivers(options: UseListOptions = {}): UseDriversResult {
+  const { limit = 200, offset = 0 } = options;
   const graphQLOptions = useGraphqlOptions();
   const [drivers, setDrivers] = useState<Driver[]>([]);
+  const [hasMore, setHasMore] = useState(false);
   const [isLoading, setIsLoading] = useState(false);
   const [error, setError] = useState<Error | null>(null);
 
@@ -691,16 +708,17 @@ export function useDrivers(): UseDriversResult {
         graphQLOptions,
         LIST_DRIVERS_QUERY,
         {
-          pagination: { limit: 200, offset: 0 },
+          pagination: { limit, offset },
         }
       );
+      setHasMore(data.drivers.length === limit);
       setDrivers(data.drivers.map(mapDriver));
     } catch (fetchError) {
       setError(fetchError instanceof Error ? fetchError : new Error('Failed to load drivers'));
     } finally {
       setIsLoading(false);
     }
-  }, [graphQLOptions]);
+  }, [graphQLOptions, limit, offset]);
 
   useEffect(() => {
     void load();
@@ -747,6 +765,7 @@ export function useDrivers(): UseDriversResult {
   return {
     drivers,
     totalDrivers: drivers.length,
+    hasMore,
     isLoading,
     error,
     refetch,

package/src/movethewheels/hooks/useInventory.ts

@@ -356,7 +356,9 @@ function useGraphqlOptions() {
 
 export function useInventory(options: UseInventoryOptions = {}): UseInventoryResult {
   const { filters: rawFilters } = options;
-  // Stabilize filters reference for React Compiler memoization.
+  // Stabilize the filters reference by its primitive fields so React Compiler's
+  // inferred `filters` dependency stays stable and `load` is not recreated (and
+  // refetched) every render when the caller passes an inline filters object.
   const filters = useMemo(
     () => rawFilters,
     [rawFilters?.lowStock, rawFilters?.productId, rawFilters?.warehouseId]
@@ -532,9 +534,16 @@ export function useInventory(options: UseInventoryOptions = {}): UseInventoryRes
   };
 }
 
-export function useProducts() {
+interface UseListOptions {
+  limit?: number;
+  offset?: number;
+}
+
+export function useProducts(options: UseListOptions = {}) {
+  const { limit = 500, offset = 0 } = options;
   const graphQLOptions = useGraphqlOptions();
   const [products, setProducts] = useState<Product[]>([]);
+  const [hasMore, setHasMore] = useState(false);
   const [isLoading, setIsLoading] = useState(false);
   const [error, setError] = useState<Error | null>(null);
 
@@ -546,16 +555,17 @@ export function useProducts() {
         graphQLOptions,
         LIST_PRODUCTS_QUERY,
         {
-          pagination: { limit: 500, offset: 0 },
+          pagination: { limit, offset },
         }
       );
+      setHasMore(data.products.length === limit);
       setProducts(data.products.map(mapProduct));
     } catch (fetchError) {
       setError(fetchError instanceof Error ? fetchError : new Error('Failed to load products'));
     } finally {
       setIsLoading(false);
     }
-  }, [graphQLOptions]);
+  }, [graphQLOptions, limit, offset]);
 
   useEffect(() => {
     void load();
@@ -564,12 +574,33 @@ export function useProducts() {
   return {
     products,
     totalProducts: products.length,
+    hasMore,
     isLoading,
     error,
     refetch: () => void load(),
   };
 }
 
+/**
+ * Bounded aggregate for the Products page "at a glance" tiles. Fetches up to
+ * `sampleSize` products (independent of the paginated list) and computes the
+ * special-handling / temperature-controlled counts so the tiles never reflect
+ * a single truncated page. There is no product *Count field on the frozen
+ * supergraph, so this bounded sample is the aggregate source.
+ */
+export function useProductStats(sampleSize = 500) {
+  const { products, isLoading, error } = useProducts({ limit: sampleSize, offset: 0 });
+
+  const stats = useMemo(() => {
+    const total = products.length;
+    const specialHandling = products.filter((item) => item.fragile || item.hazardous).length;
+    const temperatureControlled = products.filter((item) => item.temperatureControlled).length;
+    return { total, specialHandling, temperatureControlled };
+  }, [products]);
+
+  return { stats, isLoading, error };
+}
+
 export function useProduct(productId: string | undefined) {
   const graphQLOptions = useGraphqlOptions();
   const [product, setProduct] = useState<Product | null>(null);
@@ -606,9 +637,11 @@ export function useProduct(productId: string | undefined) {
   return { product, isLoading, error, refetch: () => void load() };
 }
 
-export function useWarehouses() {
+export function useWarehouses(options: UseListOptions = {}) {
+  const { limit = 500, offset = 0 } = options;
   const graphQLOptions = useGraphqlOptions();
   const [warehouses, setWarehouses] = useState<Warehouse[]>([]);
+  const [hasMore, setHasMore] = useState(false);
   const [isLoading, setIsLoading] = useState(false);
   const [error, setError] = useState<Error | null>(null);
 
@@ -620,16 +653,17 @@ export function useWarehouses() {
         graphQLOptions,
         LIST_WAREHOUSES_QUERY,
         {
-          pagination: { limit: 500, offset: 0 },
+          pagination: { limit, offset },
         }
       );
+      setHasMore(data.warehouses.length === limit);
       setWarehouses(data.warehouses.map(mapWarehouse));
     } catch (fetchError) {
       setError(fetchError instanceof Error ? fetchError : new Error('Failed to load warehouses'));
     } finally {
       setIsLoading(false);
     }
-  }, [graphQLOptions]);
+  }, [graphQLOptions, limit, offset]);
 
   useEffect(() => {
     void load();
@@ -638,12 +672,41 @@ export function useWarehouses() {
   return {
     warehouses,
     totalWarehouses: warehouses.length,
+    hasMore,
     isLoading,
     error,
     refetch: () => void load(),
   };
 }
 
+/**
+ * Bounded aggregate for the Warehouses page "at a glance" tiles — fetches up to
+ * `sampleSize` warehouses (independent of the paginated list) so the active /
+ * avg-utilization tiles never reflect a single truncated page.
+ */
+export function useWarehouseStats(sampleSize = 500) {
+  const { warehouses, isLoading, error } = useWarehouses({ limit: sampleSize, offset: 0 });
+
+  const stats = useMemo(() => {
+    const total = warehouses.length;
+    const active = warehouses.filter((item) => item.isActive).length;
+    const avgUtilization =
+      total > 0
+        ? warehouses.reduce(
+            (sum, item) =>
+              sum +
+              (item.capacity.totalSpace > 0
+                ? item.capacity.usedSpace / item.capacity.totalSpace
+                : 0),
+            0
+          ) / total
+        : 0;
+    return { total, active, avgUtilization };
+  }, [warehouses]);
+
+  return { stats, isLoading, error };
+}
+
 export function useWarehouse(warehouseId: string | undefined) {
   const graphQLOptions = useGraphqlOptions();
   const [warehouse, setWarehouse] = useState<Warehouse | null>(null);

package/src/movethewheels/hooks/useOrders.ts

@@ -12,6 +12,12 @@ interface UseOrdersOptions {
 interface UseOrdersResult {
   orders: Order[];
   totalOrders: number;
+  /**
+   * True when the most recent fetch returned a full page (rawCount === limit),
+   * i.e. there may be another page. Used for offset pagers where no grand
+   * total is available.
+   */
+  hasMore: boolean;
   isLoading: boolean;
   error: Error | null;
   refetch: () => void;
@@ -402,11 +408,28 @@ function mapOrder(order: ApiOrder): Order {
 }
 
 export function useOrders(options: UseOrdersOptions = {}): UseOrdersResult {
-  const { filters, limit = 20, offset = 0 } = options;
+  const { filters: rawFilters, limit = 20, offset = 0 } = options;
+  // React Compiler memoizes loadOrders on the inferred `filters` dependency, so
+  // an inline filters object from the caller would recreate the loader every
+  // render and refetch forever. Stabilize the reference by its primitive fields:
+  // the memoized `filters` only changes identity when a filter value actually
+  // changes, so stable-value renders no longer recreate loadOrders.
+  const filters = useMemo(
+    () => rawFilters,
+    [
+      rawFilters?.status,
+      rawFilters?.priority,
+      rawFilters?.orderType,
+      rawFilters?.customerId,
+      rawFilters?.driverId,
+      rawFilters?.unassigned,
+    ]
+  );
   const { apiGatewayUrl, authToken, workspaceToken, workspaceId, tenantId, currentUser } =
     useMoveTheWheels();
 
   const [orders, setOrders] = useState<Order[]>([]);
+  const [hasMore, setHasMore] = useState(false);
   const [isLoading, setIsLoading] = useState(false);
   const [error, setError] = useState<Error | null>(null);
 
@@ -441,7 +464,13 @@ export function useOrders(options: UseOrdersOptions = {}): UseOrdersResult {
         pagination: { limit, offset },
       });
 
-      setOrders(data.movethewheelsOrders.map(mapOrder));
+      const raw = data.movethewheelsOrders;
+      setHasMore(raw.length === limit);
+      let mapped = raw.map(mapOrder);
+      if (filters?.unassigned) {
+        mapped = mapped.filter((item) => !item.driverId);
+      }
+      setOrders(mapped);
     } catch (fetchError) {
       setError(fetchError instanceof Error ? fetchError : new Error('Failed to load orders'));
     } finally {
@@ -554,6 +583,7 @@ export function useOrders(options: UseOrdersOptions = {}): UseOrdersResult {
   return {
     orders,
     totalOrders: orders.length,
+    hasMore,
     isLoading,
     error,
     refetch,

package/src/movethewheels/hooks/useReports.ts

@@ -68,8 +68,15 @@ export interface CreateReportInput {
   status?: string;
 }
 
+interface UseReportsOptions {
+  limit?: number;
+  offset?: number;
+}
+
 interface UseReportsResult {
   reports: MovethewheelsReport[];
+  /** True when the last fetch returned a full page (rawCount === limit). */
+  hasMore: boolean;
   isLoading: boolean;
   error: Error | null;
   refetch: () => void;
@@ -80,10 +87,12 @@ interface UseReportsResult {
   ) => Promise<GeneratedReport>;
 }
 
-export function useReports(): UseReportsResult {
+export function useReports(options: UseReportsOptions = {}): UseReportsResult {
+  const { limit = 100, offset = 0 } = options;
   const { apiGatewayUrl, authToken, workspaceToken, workspaceId, tenantId, currentUser } =
     useMoveTheWheels();
   const [reports, setReports] = useState<MovethewheelsReport[]>([]);
+  const [hasMore, setHasMore] = useState(false);
   const [isLoading, setIsLoading] = useState(false);
   const [error, setError] = useState<Error | null>(null);
 
@@ -106,15 +115,16 @@ export function useReports(): UseReportsResult {
       const data = await executeGraphQL<{ movethewheelsReports: MovethewheelsReport[] }>(
         graphQLOptions,
         LIST_REPORTS_QUERY,
-        { pagination: { limit: 100, offset: 0 } }
+        { pagination: { limit, offset } }
       );
+      setHasMore(data.movethewheelsReports.length === limit);
       setReports(data.movethewheelsReports);
     } catch (fetchError) {
       setError(fetchError instanceof Error ? fetchError : new Error('Failed to load reports'));
     } finally {
       setIsLoading(false);
     }
-  }, [graphQLOptions]);
+  }, [graphQLOptions, limit, offset]);
 
   useEffect(() => {
     void load();
@@ -154,5 +164,5 @@ export function useReports(): UseReportsResult {
     [graphQLOptions]
   );
 
-  return { reports, isLoading, error, refetch, createReport, generateReport };
+  return { reports, hasMore, isLoading, error, refetch, createReport, generateReport };
 }