@burdenoff/microfe-movethewheels 2026.921.1 → 2026.924.1

package/src/movethewheels/components/CustomerPicker.tsx

@@ -16,6 +16,7 @@ import {
   SelectTrigger,
   SelectValue,
 } from './ui';
+import { EntityCombobox } from './EntityCombobox';
 import type { Customer } from '../types';
 import { FormError } from './FormError';
 
@@ -30,7 +31,8 @@ interface CustomerPickerProps {
   onRetry: () => void;
   onOpenCustomers?: () => void;
   selectedCustomer?: Customer | null;
-  searchQuery?: string;
+  /** Called with the (already debounced) query text as the user types in the
+   *  combobox's search box, so the caller can re-fetch `customers` server-side. */
   onSearchQueryChange?: (query: string) => void;
   disabled?: boolean;
 }
@@ -51,13 +53,6 @@ const EMPTY_FORM: CustomerFormState = {
   company: '',
 };
 
-function mergeCustomers(customers: Customer[], selectedCustomer?: Customer | null): Customer[] {
-  if (!selectedCustomer || customers.some((customer) => customer.id === selectedCustomer.id)) {
-    return customers;
-  }
-  return [selectedCustomer, ...customers];
-}
-
 export function CustomerPicker({
   customers,
   value,
@@ -69,7 +64,6 @@ export function CustomerPicker({
   onRetry,
   onOpenCustomers,
   selectedCustomer,
-  searchQuery = '',
   onSearchQueryChange,
   disabled = false,
 }: CustomerPickerProps) {
@@ -77,7 +71,6 @@ export function CustomerPicker({
   const [form, setForm] = useState<CustomerFormState>(EMPTY_FORM);
   const [isCreating, setIsCreating] = useState(false);
   const [createError, setCreateError] = useState<string | null>(null);
-  const options = mergeCustomers(customers, selectedCustomer);
 
   const openCreateDialog = () => {
     setCreateError(null);
@@ -139,32 +132,29 @@ export function CustomerPicker({
         </Button>
       </div>
       <div className="flex flex-col gap-2 sm:flex-row sm:items-start">
-        {onSearchQueryChange && (
-          <Input
-            value={searchQuery}
-            onChange={(event) => onSearchQueryChange(event.target.value)}
-            placeholder="Search customers"
-            aria-label="Search customers"
-            disabled={disabled}
-            className="sm:max-w-56"
-          />
-        )}
-        <Select
+        <EntityCombobox
+          id="customer"
           value={value}
-          onValueChange={onValueChange}
-          disabled={disabled || isLoading || Boolean(error)}
-        >
-          <SelectTrigger id="customer" className="flex-1">
-            <SelectValue placeholder={isLoading ? 'Loading customers...' : 'Select customer'} />
-          </SelectTrigger>
-          <SelectContent>
-            {options.map((customer) => (
-              <SelectItem key={customer.id} value={customer.id}>
-                {customer.name} {customer.email ? `(${customer.email})` : ''}
-              </SelectItem>
-            ))}
-          </SelectContent>
-        </Select>
+          onChange={onValueChange}
+          options={customers}
+          loading={isLoading}
+          getId={(customer) => customer.id}
+          getLabel={(customer) => `${customer.name}${customer.email ? ` (${customer.email})` : ''}`}
+          renderOption={(customer) => (
+            <>
+              {customer.name} {customer.email ? `(${customer.email})` : ''}
+            </>
+          )}
+          selectedOption={selectedCustomer}
+          required
+          placeholder={isLoading ? 'Loading customers...' : 'Select customer'}
+          searchPlaceholder="Search customers"
+          emptyText="No customers found."
+          disabled={disabled || Boolean(error)}
+          error={error ? 'Customers could not be loaded' : undefined}
+          onSearchChange={onSearchQueryChange}
+          className="flex-1"
+        />
         {error && (
           <Button type="button" variant="outline" size="sm" onClick={onRetry}>
             <RefreshCw size={14} className="mr-1" />
@@ -183,7 +173,7 @@ export function CustomerPicker({
             </Button>
           )}
         </div>
-      ) : !isLoading && options.length === 0 ? (
+      ) : !isLoading && customers.length === 0 ? (
         <div className="rounded-lg border border-border-seam bg-bg-sunken/40 p-3">
           <div className="flex items-start gap-2">
             <UserPlus size={16} className="mt-0.5 shrink-0 text-text-secondary" />

package/src/movethewheels/components/EntityCombobox.tsx

@@ -0,0 +1,237 @@
+/**
+ * EntityCombobox — searchable single-select for backend-record lists (routes,
+ * customers, vehicles, drivers, …).
+ *
+ * A button trigger shows the current selection's label (or a placeholder) and
+ * opens a Popover with a cmdk Command. Built entirely on existing fe-libs `ui`
+ * primitives (Command + Popover) — no new dependency, following the pattern
+ * already proven by `microfe-product`'s `ProductCombobox`.
+ *
+ * Every list this feeds (`useRoutes`, `useCustomers`, `useVehicles`,
+ * `useDrivers`) is capped to a small server page (`limit`, default 20) so the
+ * option list is never "fetch everything" — a workspace with thousands of
+ * records would otherwise either hang the request or silently truncate. Two
+ * search modes cover both call shapes in this app:
+ *
+ * - **Internal search** (pass `onSearchChange`): the combobox renders its own
+ *   debounced `CommandInput` and calls back with the debounced query so the
+ *   caller's hook re-fetches server-side. Used where each field owns its own
+ *   search (saved route, customer).
+ * - **External search** (omit `onSearchChange`): no input is rendered inside
+ *   the popover; the caller is expected to already be filtering `options` via
+ *   a search control elsewhere on the page. Used where one shared search box
+ *   drives two comboboxes at once (vehicle + driver assignment), so a second,
+ *   redundant input isn't stacked on top of it.
+ *
+ * In both modes, the current selection's label is resolved independently via
+ * `selectedOption`/`selectedLoading` (typically a single-record lookup hook
+ * like `useRoute(value)`), so it keeps rendering correctly even once it falls
+ * outside the current search results or page.
+ */
+import { useEffect, useState } from 'react';
+import { Check, ChevronsUpDown } from 'lucide-react';
+import {
+  Command,
+  CommandEmpty,
+  CommandInput,
+  CommandItem,
+  CommandList,
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from './ui';
+import { cn } from '../utils/cn';
+import { useDebouncedValue } from '../hooks/useDebouncedValue';
+
+interface EntityComboboxProps<T> {
+  /** Selected record id (controlled). Empty string = nothing selected. */
+  value: string;
+  /** Called with the selected record id ('' when cleared). */
+  onChange: (id: string) => void;
+  /** The current (already fetched/filtered) page of selectable records. */
+  options: T[];
+  /** True while `options` is (re)loading. */
+  loading?: boolean;
+  getId: (option: T) => string;
+  /** Rich content for a list row. */
+  renderOption: (option: T) => React.ReactNode;
+  /** Plain-text label for the trigger button (must be a string, not JSX). */
+  getLabel: (option: T) => string;
+  /** Independently-loaded current selection, so its label still renders even
+   *  when it isn't present in `options` (filtered out or paginated away). */
+  selectedOption?: T | null;
+  selectedLoading?: boolean;
+  /** Renders a clearable "None" row when true (hidden when `required`). */
+  required?: boolean;
+  placeholder?: string;
+  searchPlaceholder?: string;
+  emptyText?: string;
+  noneLabel?: string;
+  disabled?: boolean;
+  id?: string;
+  /** Toggles the invalid border + aria-invalid. */
+  error?: string;
+  /** Extra classes merged onto the trigger button. */
+  className?: string;
+  /** Server-side search callback (debounced). Omit to hide the built-in search
+   *  input when a caller already provides one elsewhere for the same list. */
+  onSearchChange?: (value: string) => void;
+  /** True when the source hook's page doesn't hold every matching record —
+   *  paired with `totalCount` to render a "keep typing to narrow" hint. */
+  hasMore?: boolean;
+  totalCount?: number;
+}
+
+export function EntityCombobox<T>({
+  value,
+  onChange,
+  options,
+  loading = false,
+  getId,
+  renderOption,
+  getLabel,
+  selectedOption = null,
+  selectedLoading = false,
+  required = false,
+  placeholder = 'Select…',
+  searchPlaceholder = 'Search…',
+  emptyText = 'No results found.',
+  noneLabel = 'None',
+  disabled = false,
+  id,
+  error,
+  className,
+  onSearchChange,
+  hasMore = false,
+  totalCount,
+}: EntityComboboxProps<T>) {
+  const [open, setOpen] = useState(false);
+  const [search, setSearch] = useState('');
+  const debouncedSearch = useDebouncedValue(search.trim(), 200);
+
+  useEffect(() => {
+    if (onSearchChange) {
+      onSearchChange(debouncedSearch);
+    }
+    // Only internal-search mode reacts to keystrokes; external-search callers
+    // manage their own query state and don't pass `onSearchChange`.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [debouncedSearch]);
+
+  const triggerLabel = selectedOption
+    ? getLabel(selectedOption)
+    : value
+      ? selectedLoading
+        ? 'Loading…'
+        : value
+      : placeholder;
+
+  const triggerClassName = cn(
+    'w-full flex items-center justify-between gap-2 px-3 py-2',
+    'bg-surface',
+    'border border-default',
+    'rounded-lg',
+    'text-left text-sm text-text-primary',
+    'focus:outline-none focus:ring-2 focus:ring-[var(--color-border-focus)]',
+    'disabled:bg-bg-sunken disabled:cursor-not-allowed',
+    'transition-all duration-200',
+    error && 'border-[var(--color-status-error)]',
+    !selectedOption && 'text-text-tertiary',
+    className
+  );
+
+  const showMoreHint = hasMore && typeof totalCount === 'number' && totalCount > options.length;
+
+  return (
+    <Popover
+      open={open}
+      onOpenChange={(next: boolean) => {
+        setOpen(next);
+        // Reset the query on close so reopening starts fresh, not pre-filtered.
+        if (!next) setSearch('');
+      }}
+    >
+      <PopoverTrigger asChild>
+        <button
+          type="button"
+          id={id}
+          role="combobox"
+          aria-expanded={open}
+          aria-required={required}
+          aria-invalid={error ? true : undefined}
+          disabled={disabled}
+          className={triggerClassName}
+        >
+          <span className="truncate">{triggerLabel}</span>
+          <ChevronsUpDown size={16} className="shrink-0 text-text-tertiary" aria-hidden="true" />
+        </button>
+      </PopoverTrigger>
+      <PopoverContent
+        align="start"
+        className="w-[var(--radix-popover-trigger-width)] p-0 border border-default bg-surface"
+      >
+        {/* Search is server-side (or driven externally) → disable cmdk's
+            client filter so we render exactly what was fetched. */}
+        <Command shouldFilter={false} className="bg-surface text-text-primary">
+          {onSearchChange && (
+            <CommandInput
+              value={search}
+              onValueChange={setSearch}
+              placeholder={searchPlaceholder}
+              className="text-text-primary placeholder:text-text-tertiary"
+            />
+          )}
+          <CommandList>
+            <CommandEmpty className="text-text-tertiary">
+              {loading ? 'Searching…' : emptyText}
+            </CommandEmpty>
+            {!required && (
+              <CommandItem
+                value="__none__"
+                onSelect={() => {
+                  onChange('');
+                  setOpen(false);
+                }}
+                className="text-text-tertiary"
+              >
+                <Check
+                  size={16}
+                  className={cn('shrink-0', value === '' ? 'opacity-100' : 'opacity-0')}
+                  aria-hidden="true"
+                />
+                <span className="truncate italic">{noneLabel}</span>
+              </CommandItem>
+            )}
+            {options.map((option) => {
+              const optionId = getId(option);
+              return (
+                <CommandItem
+                  key={optionId}
+                  value={optionId}
+                  onSelect={() => {
+                    onChange(optionId);
+                    setOpen(false);
+                  }}
+                  className="text-text-primary"
+                >
+                  <Check
+                    size={16}
+                    className={cn('shrink-0', optionId === value ? 'opacity-100' : 'opacity-0')}
+                    aria-hidden="true"
+                  />
+                  <span className="truncate">{renderOption(option)}</span>
+                </CommandItem>
+              );
+            })}
+            {showMoreHint && (
+              <div className="px-2 py-1.5 text-xs text-text-tertiary border-t border-border-seam">
+                Showing {options.length} of {totalCount}
+                {onSearchChange ? ' — keep typing to narrow results.' : '.'}
+              </div>
+            )}
+          </CommandList>
+        </Command>
+      </PopoverContent>
+    </Popover>
+  );
+}

package/src/movethewheels/components/ui.tsx

@@ -21,6 +21,15 @@ export {
   SelectItem,
   SelectTrigger,
   SelectValue,
+  Command,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
   Tabs,
   TabsList,
   TabsTrigger,

package/src/movethewheels/hooks/useFleet.ts

@@ -533,7 +533,13 @@ export function useFleet(options: UseFleetOptions = {}): UseFleetResult {
   // refetched) every render when the caller passes an inline filters object.
   const filters = useMemo(
     () => rawFilters,
-    [rawFilters?.driverId, rawFilters?.search, rawFilters?.status, rawFilters?.vehicleType]
+    [
+      rawFilters?.driverId,
+      rawFilters?.search,
+      rawFilters?.status,
+      rawFilters?.vehicleId,
+      rawFilters?.vehicleType,
+    ]
   );
   const graphQLOptions = useGraphqlOptions();
   const [vehicles, setVehicles] = useState<Vehicle[]>([]);
@@ -551,13 +557,14 @@ export function useFleet(options: UseFleetOptions = {}): UseFleetResult {
             search: filters?.search,
             type: filters?.vehicleType?.toUpperCase(),
             status: filters?.status ? toApiVehicleStatus(filters.status) : undefined,
+            driverId: filters?.driverId,
           },
           pagination: { limit, offset: 0 },
         }),
         executeGraphQL<{ drivers: ApiDriver[] }>(graphQLOptions, LIST_DRIVERS_QUERY, {
           filter: {
             search: filters?.search,
-            vehicleId: filters?.driverId,
+            vehicleId: filters?.vehicleId,
           },
           pagination: { limit, offset: 0 },
         }),
@@ -695,6 +702,8 @@ interface UseVehiclesOptions extends UseListOptions {
   search?: string;
   status?: VehicleStatus;
   vehicleType?: Vehicle['type'];
+  /** Narrows to vehicles linked to this driver server-side (VehicleFilterInput.driverId). */
+  driverId?: string;
 }
 
 interface UseVehiclesResult {
@@ -710,7 +719,7 @@ interface UseVehiclesResult {
 }
 
 export function useVehicles(options: UseVehiclesOptions = {}): UseVehiclesResult {
-  const { limit = 20, offset = 0, search, status, vehicleType } = options;
+  const { limit = 20, offset = 0, search, status, vehicleType, driverId } = options;
   const graphQLOptions = useGraphqlOptions();
   const [vehicles, setVehicles] = useState<Vehicle[]>([]);
   const [totalVehicles, setTotalVehicles] = useState(0);
@@ -730,6 +739,7 @@ export function useVehicles(options: UseVehiclesOptions = {}): UseVehiclesResult
           search: search || undefined,
           status: status ? toApiVehicleStatus(status) : undefined,
           type: vehicleType?.toUpperCase(),
+          driverId: driverId || undefined,
         },
         pagination: { limit, offset },
       });
@@ -741,7 +751,7 @@ export function useVehicles(options: UseVehiclesOptions = {}): UseVehiclesResult
     } finally {
       setIsLoading(false);
     }
-  }, [graphQLOptions, limit, offset, search, status, vehicleType]);
+  }, [graphQLOptions, limit, offset, search, status, vehicleType, driverId]);
 
   useEffect(() => {
     void load();
@@ -859,10 +869,12 @@ interface UseDriversOptions extends UseListOptions {
   status?: DriverStatus;
   search?: string;
   licenseClass?: string;
+  /** Narrows to drivers linked to this vehicle server-side (DriverFilterInput.vehicleId). */
+  vehicleId?: string;
 }
 
 export function useDrivers(options: UseDriversOptions = {}): UseDriversResult {
-  const { limit = 20, offset = 0, status, search, licenseClass } = options;
+  const { limit = 20, offset = 0, status, search, licenseClass, vehicleId } = options;
   const graphQLOptions = useGraphqlOptions();
   const [drivers, setDrivers] = useState<Driver[]>([]);
   const [totalDrivers, setTotalDrivers] = useState(0);
@@ -882,6 +894,7 @@ export function useDrivers(options: UseDriversOptions = {}): UseDriversResult {
           status: status ? toApiDriverStatus(status) : undefined,
           search: search || undefined,
           licenseClass: licenseClass || undefined,
+          vehicleId: vehicleId || undefined,
         },
         pagination: { limit, offset },
       });
@@ -893,7 +906,7 @@ export function useDrivers(options: UseDriversOptions = {}): UseDriversResult {
     } finally {
       setIsLoading(false);
     }
-  }, [graphQLOptions, limit, offset, status, search, licenseClass]);
+  }, [graphQLOptions, limit, offset, status, search, licenseClass, vehicleId]);
 
   useEffect(() => {
     void load();

package/src/movethewheels/hooks/useOrders.ts

@@ -1,6 +1,7 @@
 import { useCallback, useEffect, useMemo, useState } from 'react';
 import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
 import type { Order, OrderFilter, OrderStatus } from '../types';
+import { mapRoute } from './useRoutes';
 import { executeGraphQL } from '../utils/graphqlClient';
 
 interface UseOrdersOptions {
@@ -53,6 +54,21 @@ export interface ApiOrder {
   scheduledDelivery?: string | null;
   vehicleId?: string | null;
   driverId?: string | null;
+  routeId?: string | null;
+  route?: {
+    id: string;
+    name: string;
+    status: string;
+    vehicleId?: string | null;
+    driverId?: string | null;
+    waypoints?: unknown;
+    estimatedDistance?: number | null;
+    estimatedDuration?: number | null;
+    fuelCost?: number | null;
+    actualDistance?: number | null;
+    actualDuration?: number | null;
+    createdAt: string;
+  } | null;
   createdAt: string;
   updatedAt: string;
   customer?: {
@@ -85,6 +101,21 @@ const DELIVERY_JOB_FIELDS = `
   scheduledDelivery
   vehicleId
   driverId
+  routeId
+  route {
+    id
+    name
+    status
+    vehicleId
+    driverId
+    waypoints
+    estimatedDistance
+    estimatedDuration
+    fuelCost
+    actualDistance
+    actualDuration
+    createdAt
+  }
   createdAt
   updatedAt
   customer {
@@ -302,6 +333,8 @@ export function mapOrder(order: ApiOrder): Order {
     scheduledDelivery: order.scheduledDelivery ? new Date(order.scheduledDelivery) : undefined,
     vehicleId: order.vehicleId ?? undefined,
     driverId: order.driverId ?? undefined,
+    routeId: order.routeId ?? undefined,
+    route: order.route ? mapRoute(order.route) : undefined,
     createdAt: new Date(order.createdAt),
     updatedAt: new Date(order.updatedAt),
   };
@@ -409,6 +442,7 @@ export function useOrders(options: UseOrdersOptions = {}): UseOrdersResult {
           scheduledDelivery: orderData.scheduledDelivery?.toISOString(),
           vehicleId: orderData.vehicleId,
           driverId: orderData.driverId,
+          routeId: orderData.routeId,
         },
       });
 
@@ -440,6 +474,7 @@ export function useOrders(options: UseOrdersOptions = {}): UseOrdersResult {
             updates.scheduledDelivery === null ? null : updates.scheduledDelivery?.toISOString(),
           vehicleId: updates.vehicleId,
           driverId: updates.driverId,
+          routeId: updates.routeId,
         },
       });
 

package/src/movethewheels/hooks/useRoutes.ts

@@ -218,7 +218,7 @@ function mapWaypoints(waypoints: unknown): RouteStop[] {
   });
 }
 
-function mapRoute(route: ApiRoute): Route {
+export function mapRoute(route: ApiRoute): Route {
   return {
     id: route.id,
     name: route.name,