@burdenoff/microfe-movethewheels 2026.923.1 → 2026.924.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@burdenoff/microfe-movethewheels",
-  "version": "2026.923.1",
+  "version": "2026.924.1",
   "description": "Burdenoff MoveTheWheels Microfrontend - Logistics & Supply Chain Management Platform",
   "type": "module",
   "files": [

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

@@ -702,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 {
@@ -717,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);
@@ -737,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 },
       });
@@ -748,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();
@@ -866,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);
@@ -889,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 },
       });
@@ -900,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/pages/CreateOrderPage.tsx

@@ -38,11 +38,11 @@ import {
 import { EmphasisPanel, NextSteps, PagePurpose } from '@burdenoff/fe-libs/ui';
 import { useOrder, useOrders } from '../hooks/useOrders';
 import { useCustomer, useCustomers } from '../hooks/useCustomers';
-import { useRoutes } from '../hooks/useRoutes';
-import { useDebouncedValue } from '../hooks/useDebouncedValue';
+import { useRoute, useRoutes } from '../hooks/useRoutes';
 import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
 import { joinPath, buildCustomerCreatePath } from '../utils/navigation';
 import { CustomerPicker } from '../components/CustomerPicker';
+import { EntityCombobox } from '../components/EntityCombobox';
 import type { Customer } from '../types';
 
 /**
@@ -69,7 +69,6 @@ export default function CreateOrderPage() {
   const { order } = useOrder(orderId);
   const { createOrder, updateOrder } = useOrders();
   const [customerSearch, setCustomerSearch] = useState('');
-  const debouncedCustomerSearch = useDebouncedValue(customerSearch);
   const {
     customers,
     createCustomer,
@@ -78,15 +77,19 @@ export default function CreateOrderPage() {
     refetch: refetchCustomers,
   } = useCustomers({
     limit: 20,
-    filters: { search: debouncedCustomerSearch || undefined },
+    filters: { search: customerSearch || undefined },
   });
   const { customer: linkedCustomer } = useCustomer(prefilledCustomerId ?? order?.customerId);
+  const [routeSearch, setRouteSearch] = useState('');
   const {
     routes,
     isLoading: routesLoading,
     error: routesError,
+    hasMore: routesHaveMore,
+    totalRoutes,
   } = useRoutes({
     status: 'planned',
+    search: routeSearch || undefined,
     limit: 20,
   });
 
@@ -116,6 +119,13 @@ export default function CreateOrderPage() {
     specialInstructions: order?.specialInstructions || '',
   });
 
+  // Resolved independently of the (searchable, 20-row) `routes` page so the
+  // saved-route combobox's trigger still shows the right name even when the
+  // selection has scrolled out of the current search/page.
+  const { route: selectedRoute, isLoading: selectedRouteLoading } = useRoute(
+    formData.routeId || undefined
+  );
+
   const [isSubmitting, setIsSubmitting] = useState(false);
   const [formError, setFormError] = useState<string | null>(null);
 
@@ -275,7 +285,7 @@ export default function CreateOrderPage() {
   };
 
   const selectSavedRoute = (value: string) => {
-    if (value === 'none') {
+    if (!value) {
       updateField('routeId', '');
       return;
     }
@@ -431,7 +441,6 @@ export default function CreateOrderPage() {
                 onRetry={refetchCustomers}
                 onOpenCustomers={goToCustomerCreate}
                 selectedCustomer={selectedCustomer}
-                searchQuery={customerSearch}
                 onSearchQueryChange={setCustomerSearch}
               />
               <div className="space-y-2">
@@ -464,19 +473,30 @@ export default function CreateOrderPage() {
             </CardTitle>
           </CardHeader>
           <CardContent className="space-y-2">
-            <Select value={formData.routeId || 'none'} onValueChange={selectSavedRoute}>
-              <SelectTrigger id="saved-route">
-                <SelectValue placeholder="Choose a saved route" />
-              </SelectTrigger>
-              <SelectContent>
-                <SelectItem value="none">No saved route</SelectItem>
-                {routes.map((route) => (
-                  <SelectItem key={route.id} value={route.id}>
-                    {route.name} · {route.stops.length} stops
-                  </SelectItem>
-                ))}
-              </SelectContent>
-            </Select>
+            <EntityCombobox
+              id="saved-route"
+              value={formData.routeId}
+              onChange={selectSavedRoute}
+              options={routes}
+              loading={routesLoading}
+              getId={(route) => route.id}
+              getLabel={(route) => `${route.name} · ${route.stops.length} stops`}
+              renderOption={(route) => (
+                <>
+                  {route.name} · {route.stops.length} stops
+                </>
+              )}
+              selectedOption={selectedRoute}
+              selectedLoading={selectedRouteLoading}
+              placeholder="Choose a saved route"
+              searchPlaceholder="Search saved routes"
+              emptyText="No saved routes found."
+              noneLabel="No saved route"
+              error={routesError ? 'Saved routes are unavailable' : undefined}
+              onSearchChange={setRouteSearch}
+              hasMore={routesHaveMore}
+              totalCount={totalRoutes}
+            />
             <p className="text-xs text-text-secondary">
               {routesLoading
                 ? 'Loading planned routes…'