@burdenoff/microfe-movethewheels 2026.924.1 → 2026.925.1

package/src/movethewheels/pages/CreateOrderPage.tsx

@@ -4,18 +4,17 @@
  * Form for creating or editing orders.
  */
 
-import { useEffect, useState } from 'react';
+import { useEffect, useState, type ChangeEvent } from 'react';
 import { useParams, useSearchParams } from 'react-router';
 import {
   Package,
   ArrowLeft,
   Save,
   Plus,
-  Trash2,
   Users,
   MapPin,
   CalendarClock,
-  Route as RouteIcon,
+  ArrowRight,
 } from 'lucide-react';
 import { PageLayout, EmptyState } from '../components/PageLayout';
 import { FormError } from '../components/FormError';
@@ -24,6 +23,9 @@ import {
   CardContent,
   CardHeader,
   CardTitle,
+  CardDescription,
+  Badge,
+  Separator,
   Button,
   Input,
   Label,
@@ -33,16 +35,18 @@ import {
   SelectItem,
   SelectTrigger,
   SelectValue,
-  Separator,
 } from '../components/ui';
-import { EmphasisPanel, NextSteps, PagePurpose } from '@burdenoff/fe-libs/ui';
+import { FormSection } from '@burdenoff/fe-libs/form';
+import { EmphasisPanel, PagePurpose, Stepper } from '@burdenoff/fe-libs/ui';
 import { useOrder, useOrders } from '../hooks/useOrders';
 import { useCustomer, useCustomers } from '../hooks/useCustomers';
 import { useRoute, useRoutes } from '../hooks/useRoutes';
+import { useProducts } from '../hooks/useInventory';
 import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
 import { joinPath, buildCustomerCreatePath } from '../utils/navigation';
 import { CustomerPicker } from '../components/CustomerPicker';
 import { EntityCombobox } from '../components/EntityCombobox';
+import { OrderItemRow } from '../components/OrderItemRow';
 import type { Customer } from '../types';
 
 /**
@@ -92,6 +96,11 @@ export default function CreateOrderPage() {
     search: routeSearch || undefined,
     limit: 20,
   });
+  const [productSearch, setProductSearch] = useState('');
+  const { products, isLoading: productsLoading } = useProducts({
+    search: productSearch || undefined,
+    limit: 20,
+  });
 
   const isEditing = !!orderId && !!order;
 
@@ -253,8 +262,12 @@ export default function CreateOrderPage() {
           navigate(joinPath(basePath, `orders/${orderId}`));
         }
       } else {
-        await createOrder(input);
-        goBack();
+        const createdOrder = await createOrder(input);
+        if (navigate) {
+          navigate(joinPath(basePath, `orders/${createdOrder.id}`));
+        } else {
+          goBack();
+        }
       }
     } catch (error) {
       setFormError(
@@ -354,18 +367,37 @@ export default function CreateOrderPage() {
     navigate(joinPath(basePath, buildCustomerCreatePath(orderPath)));
   };
 
+  const activeStep = !formData.customerId
+    ? 0
+    : !formData.pickupAddress.street || !formData.deliveryAddress.street
+      ? 1
+      : formData.items.length === 0
+        ? 2
+        : 3;
+
+  const focusStep = (step: number) => {
+    const targetIds = ['customer', 'pickupStreet', 'items-section', 'scheduledDelivery'];
+    const target = document.getElementById(targetIds[step]);
+    if (target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement) {
+      target.focus();
+      return;
+    }
+    target?.scrollIntoView({ behavior: 'smooth', block: 'start' });
+  };
+
   return (
     <PageLayout
       title={isEditing ? 'Edit Order' : 'Create Order'}
       subtitle={isEditing ? `Editing ${order?.orderNumber}` : 'Create a new delivery order'}
       icon={<Package size={24} />}
+      maxWidth="2xl"
       headerActions={
-        <div className="flex gap-2">
-          <Button variant="outline" onClick={goBack}>
+        <div className="flex w-full flex-col-reverse gap-2 sm:w-auto sm:flex-row">
+          <Button type="button" variant="outline" onClick={goBack} disabled={isSubmitting}>
             <ArrowLeft size={16} />
             Cancel
           </Button>
-          <Button onClick={handleSubmit} disabled={isSubmitting || customersLoading}>
+          <Button type="submit" form="order-form" disabled={isSubmitting || customersLoading}>
             <Save size={16} />
             {isSubmitting ? 'Saving...' : isEditing ? 'Save Changes' : 'Create Order'}
           </Button>
@@ -374,48 +406,63 @@ export default function CreateOrderPage() {
     >
       <PagePurpose icon={<Package size={18} />}>
         {isEditing
-          ? 'Update this delivery before it goes out — change the customer, addresses, items or handling notes, then save.'
-          : 'Book a new delivery in a few steps: choose who it’s for, set pickup and drop-off addresses, list what’s being shipped, and add any handling notes. Once created it joins the orders pipeline ready to assign and track.'}
+          ? 'Update the customer, delivery plan, shipment contents, or handling details before saving.'
+          : 'Set the customer and delivery plan, add what is being shipped, then choose any timing or handling preferences.'}
       </PagePurpose>
 
-      <NextSteps
-        storageKey="movethewheels-create-order"
+      <Stepper
         steps={[
           {
-            id: 'customer',
-            label: 'Pick the customer first',
-            description: 'Their saved contact details auto-fill the order.',
-            icon: <Users size={16} />,
-            done: !!formData.customerId,
-            onClick: () => document.getElementById('customer')?.focus(),
+            key: 'customer',
+            label: 'Customer & priority',
+            description: 'Who is receiving this delivery?',
+          },
+          {
+            key: 'locations',
+            label: 'Route & addresses',
+            description: 'Where should it be collected and delivered?',
           },
           {
-            id: 'addresses',
-            label: 'Set pickup & delivery addresses',
-            description: 'Where the shipment is collected and dropped off.',
-            icon: <MapPin size={16} />,
-            done: !!formData.pickupAddress.street && !!formData.deliveryAddress.street,
-            onClick: () => document.getElementById('pickupStreet')?.focus(),
+            key: 'items',
+            label: 'Shipment contents',
+            description: 'What is being shipped?',
           },
           {
-            id: 'items',
-            label: 'Add the items to ship',
-            description: 'List each product with its quantity and value.',
-            icon: <Package size={16} />,
-            done: formData.items.length > 0,
-            onClick: addItem,
+            key: 'preferences',
+            label: 'Timing & handling',
+            description: 'Add optional delivery instructions.',
           },
         ]}
+        active={activeStep}
+        onStepClick={focusStep}
+        allowSkipAhead
       />
 
-      <form onSubmit={handleSubmit} className="space-y-6">
+      <form id="order-form" onSubmit={handleSubmit} className="space-y-6">
         <FormError message={formError} />
 
-        {/* Order Details — the page's single emphasis zone (the form's starting point) */}
-        <EmphasisPanel>
-          <h2 className="text-base font-semibold text-text-primary mb-4">Order Details</h2>
-          <div className="space-y-4">
-            <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
+        <section aria-labelledby="order-details-title">
+          <EmphasisPanel className="space-y-5">
+            <div className="flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between">
+              <div className="flex items-start gap-3">
+                <div className="rounded-xl bg-action-primary-bg/10 p-2 text-action-primary-bg">
+                  <Users size={18} aria-hidden="true" />
+                </div>
+                <div>
+                  <h2
+                    id="order-details-title"
+                    className="text-base font-semibold text-text-primary"
+                  >
+                    Customer &amp; priority
+                  </h2>
+                  <p className="mt-1 text-sm text-text-secondary">
+                    Choose who this delivery is for and how urgently it should be handled.
+                  </p>
+                </div>
+              </div>
+              <Badge variant="outline">Required</Badge>
+            </div>
+            <div className="grid grid-cols-1 gap-4 md:grid-cols-2">
               <CustomerPicker
                 customers={customers}
                 value={formData.customerId}
@@ -447,7 +494,7 @@ export default function CreateOrderPage() {
                 <Label htmlFor="priority">Priority</Label>
                 <Select
                   value={formData.priority}
-                  onValueChange={(value) => updateField('priority', value)}
+                  onValueChange={(value: string) => updateField('priority', value)}
                 >
                   <SelectTrigger id="priority">
                     <SelectValue />
@@ -459,307 +506,331 @@ export default function CreateOrderPage() {
                     <SelectItem value="urgent">Urgent</SelectItem>
                   </SelectContent>
                 </Select>
+                <p className="text-xs text-text-secondary">Normal is selected by default.</p>
               </div>
             </div>
-          </div>
-        </EmphasisPanel>
-
-        {/* Saved route — optional shortcut; manual addresses remain authoritative. */}
-        <Card>
-          <CardHeader>
-            <CardTitle className="flex items-center gap-2">
-              <RouteIcon size={18} />
-              Saved Route (Optional)
-            </CardTitle>
-          </CardHeader>
-          <CardContent className="space-y-2">
-            <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…'
-                : routesError
-                  ? 'Saved routes are unavailable; enter pickup and delivery addresses manually.'
-                  : 'A saved route fills any blank address fields. You can always edit both addresses below.'}
-            </p>
-          </CardContent>
-        </Card>
-
-        {/* Addresses */}
-        <div className="grid grid-cols-1 md:grid-cols-2 gap-6">
-          {/* Pickup Address */}
-          <Card>
-            <CardHeader>
-              <CardTitle>Pickup Address</CardTitle>
-            </CardHeader>
-            <CardContent className="space-y-4">
-              <div className="space-y-2">
-                <Label htmlFor="pickupStreet">Street Address</Label>
-                <Input
-                  id="pickupStreet"
-                  value={formData.pickupAddress.street}
-                  onChange={(e) => updateAddress('pickupAddress', 'street', e.target.value)}
-                  placeholder="123 Main St"
-                />
-              </div>
-              <div className="grid grid-cols-1 sm:grid-cols-2 gap-4">
-                <div className="space-y-2">
-                  <Label htmlFor="pickupCity">City</Label>
-                  <Input
-                    id="pickupCity"
-                    value={formData.pickupAddress.city}
-                    onChange={(e) => updateAddress('pickupAddress', 'city', e.target.value)}
-                    placeholder="San Francisco"
-                  />
-                </div>
-                <div className="space-y-2">
-                  <Label htmlFor="pickupState">State</Label>
-                  <Input
-                    id="pickupState"
-                    value={formData.pickupAddress.state}
-                    onChange={(e) => updateAddress('pickupAddress', 'state', e.target.value)}
-                    placeholder="CA"
-                  />
-                </div>
-              </div>
-              <div className="grid grid-cols-1 sm:grid-cols-2 gap-4">
-                <div className="space-y-2">
-                  <Label htmlFor="pickupPostal">Postal Code</Label>
-                  <Input
-                    id="pickupPostal"
-                    value={formData.pickupAddress.postalCode}
-                    onChange={(e) => updateAddress('pickupAddress', 'postalCode', e.target.value)}
-                    placeholder="94103"
-                  />
-                </div>
-                <div className="space-y-2">
-                  <Label htmlFor="pickupCountry">Country</Label>
-                  <Input
-                    id="pickupCountry"
-                    value={formData.pickupAddress.country}
-                    onChange={(e) => updateAddress('pickupAddress', 'country', e.target.value)}
-                    placeholder="USA"
-                  />
+          </EmphasisPanel>
+        </section>
+
+        <div id="locations-section">
+          <FormSection
+            title={
+              <span className="flex items-center gap-2">
+                <MapPin size={18} aria-hidden="true" />
+                Route &amp; addresses
+              </span>
+            }
+            description="Choose an optional saved route, then review or enter the collection and destination details."
+          >
+            <div className="rounded-card border border-border-subtle bg-bg-sunken/40 p-4">
+              <div className="mb-3 flex flex-col gap-2 sm:flex-row sm:items-start sm:justify-between">
+                <div>
+                  <h3 className="text-sm font-semibold text-text-primary">Use a saved route</h3>
+                  <p className="mt-1 text-xs text-text-secondary">
+                    Optional — fills only blank address fields; you can always edit them below.
+                  </p>
                 </div>
+                <Badge variant="secondary">Optional</Badge>
               </div>
-            </CardContent>
-          </Card>
-
-          {/* Delivery Address */}
-          <Card>
-            <CardHeader>
-              <CardTitle>Delivery Address</CardTitle>
-            </CardHeader>
-            <CardContent className="space-y-4">
-              <div className="space-y-2">
-                <Label htmlFor="deliveryStreet">Street Address</Label>
-                <Input
-                  id="deliveryStreet"
-                  value={formData.deliveryAddress.street}
-                  onChange={(e) => updateAddress('deliveryAddress', 'street', e.target.value)}
-                  placeholder="456 Oak Ave"
-                />
-              </div>
-              <div className="grid grid-cols-1 sm:grid-cols-2 gap-4">
-                <div className="space-y-2">
-                  <Label htmlFor="deliveryCity">City</Label>
-                  <Input
-                    id="deliveryCity"
-                    value={formData.deliveryAddress.city}
-                    onChange={(e) => updateAddress('deliveryAddress', 'city', e.target.value)}
-                    placeholder="Los Angeles"
-                  />
-                </div>
-                <div className="space-y-2">
-                  <Label htmlFor="deliveryState">State</Label>
-                  <Input
-                    id="deliveryState"
-                    value={formData.deliveryAddress.state}
-                    onChange={(e) => updateAddress('deliveryAddress', 'state', e.target.value)}
-                    placeholder="CA"
-                  />
-                </div>
-              </div>
-              <div className="grid grid-cols-1 sm:grid-cols-2 gap-4">
-                <div className="space-y-2">
-                  <Label htmlFor="deliveryPostal">Postal Code</Label>
-                  <Input
-                    id="deliveryPostal"
-                    value={formData.deliveryAddress.postalCode}
-                    onChange={(e) => updateAddress('deliveryAddress', 'postalCode', e.target.value)}
-                    placeholder="90210"
-                  />
-                </div>
-                <div className="space-y-2">
-                  <Label htmlFor="deliveryCountry">Country</Label>
-                  <Input
-                    id="deliveryCountry"
-                    value={formData.deliveryAddress.country}
-                    onChange={(e) => updateAddress('deliveryAddress', 'country', e.target.value)}
-                    placeholder="USA"
-                  />
-                </div>
-              </div>
-            </CardContent>
-          </Card>
-        </div>
-
-        {/* Order Items */}
-        <Card>
-          <CardHeader className="flex flex-row items-center justify-between">
-            <CardTitle>Order Items</CardTitle>
-            <Button type="button" variant="outline" size="sm" onClick={addItem}>
-              <Plus size={16} />
-              Add Item
-            </Button>
-          </CardHeader>
-          <CardContent>
-            {formData.items.length === 0 ? (
-              <EmptyState
-                illustration="empty-files"
-                title="No items added yet"
-                description="Add the products this order will ship — each with a name, SKU, quantity and value."
-                action={
-                  <Button type="button" variant="outline" onClick={addItem}>
-                    <Plus size={16} className="mr-1.5" />
-                    Add your first item
-                  </Button>
-                }
+              <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}
               />
-            ) : (
-              <div className="space-y-4">
-                {formData.items.map((item, index) => (
-                  <div key={item.id}>
-                    {index > 0 && <Separator className="my-4" />}
-                    <div className="grid grid-cols-1 md:grid-cols-7 gap-4">
-                      <div className="md:col-span-2 space-y-2">
-                        <Label>Item Name</Label>
+              <p className="mt-2 text-xs text-text-secondary" role="status">
+                {routesLoading
+                  ? 'Loading planned routes…'
+                  : routesError
+                    ? 'Saved routes are unavailable; enter pickup and delivery addresses manually.'
+                    : 'Manual values always remain authoritative when a route is selected.'}
+              </p>
+            </div>
+
+            <Separator />
+            <div className="grid grid-cols-1 gap-4 lg:grid-cols-[minmax(0,1fr)_auto_minmax(0,1fr)] lg:items-stretch">
+              <Card className="border-border-seam shadow-none">
+                <CardHeader>
+                  <CardTitle className="flex items-center gap-2 text-base">
+                    <MapPin size={17} className="text-text-secondary" aria-hidden="true" />
+                    Pickup address <span className="text-status-error-text">*</span>
+                  </CardTitle>
+                  <CardDescription>Where the shipment is collected.</CardDescription>
+                </CardHeader>
+                <CardContent className="space-y-4">
+                  <fieldset className="space-y-4">
+                    <legend className="sr-only">Pickup address details</legend>
+                    <div className="space-y-2">
+                      <Label htmlFor="pickupStreet">
+                        Street address <span className="text-status-error-text">*</span>
+                      </Label>
+                      <Input
+                        id="pickupStreet"
+                        value={formData.pickupAddress.street}
+                        onChange={(e: ChangeEvent<HTMLInputElement>) =>
+                          updateAddress('pickupAddress', 'street', e.target.value)
+                        }
+                        placeholder="123 Main St"
+                        aria-required="true"
+                      />
+                    </div>
+                    <div className="grid grid-cols-1 sm:grid-cols-2 gap-4">
+                      <div className="space-y-2">
+                        <Label htmlFor="pickupCity">City</Label>
+                        <Input
+                          id="pickupCity"
+                          value={formData.pickupAddress.city}
+                          onChange={(e: ChangeEvent<HTMLInputElement>) =>
+                            updateAddress('pickupAddress', 'city', e.target.value)
+                          }
+                          placeholder="San Francisco"
+                        />
+                      </div>
+                      <div className="space-y-2">
+                        <Label htmlFor="pickupState">State</Label>
+                        <Input
+                          id="pickupState"
+                          value={formData.pickupAddress.state}
+                          onChange={(e: ChangeEvent<HTMLInputElement>) =>
+                            updateAddress('pickupAddress', 'state', e.target.value)
+                          }
+                          placeholder="CA"
+                        />
+                      </div>
+                    </div>
+                    <div className="grid grid-cols-1 sm:grid-cols-2 gap-4">
+                      <div className="space-y-2">
+                        <Label htmlFor="pickupPostal">Postal Code</Label>
                         <Input
-                          value={item.name}
-                          onChange={(e) => updateItem(index, 'name', e.target.value)}
-                          placeholder="Product name"
+                          id="pickupPostal"
+                          value={formData.pickupAddress.postalCode}
+                          onChange={(e: ChangeEvent<HTMLInputElement>) =>
+                            updateAddress('pickupAddress', 'postalCode', e.target.value)
+                          }
+                          placeholder="94103"
                         />
                       </div>
                       <div className="space-y-2">
-                        <Label>SKU</Label>
+                        <Label htmlFor="pickupCountry">Country</Label>
                         <Input
-                          value={item.sku}
-                          onChange={(e) => updateItem(index, 'sku', e.target.value)}
-                          placeholder="SKU-001"
+                          id="pickupCountry"
+                          value={formData.pickupAddress.country}
+                          onChange={(e: ChangeEvent<HTMLInputElement>) =>
+                            updateAddress('pickupAddress', 'country', e.target.value)
+                          }
+                          placeholder="USA"
                         />
                       </div>
+                    </div>
+                  </fieldset>
+                </CardContent>
+              </Card>
+
+              <div className="hidden items-center justify-center lg:flex" aria-hidden="true">
+                <ArrowRight size={18} className="text-text-muted" />
+              </div>
+
+              <Card className="border-border-seam shadow-none">
+                <CardHeader>
+                  <CardTitle className="flex items-center gap-2 text-base">
+                    <MapPin size={17} className="text-text-secondary" aria-hidden="true" />
+                    Delivery address <span className="text-status-error-text">*</span>
+                  </CardTitle>
+                  <CardDescription>Where the shipment is delivered.</CardDescription>
+                </CardHeader>
+                <CardContent className="space-y-4">
+                  <fieldset className="space-y-4">
+                    <legend className="sr-only">Delivery address details</legend>
+                    <div className="space-y-2">
+                      <Label htmlFor="deliveryStreet">
+                        Street address <span className="text-status-error-text">*</span>
+                      </Label>
+                      <Input
+                        id="deliveryStreet"
+                        value={formData.deliveryAddress.street}
+                        onChange={(e: ChangeEvent<HTMLInputElement>) =>
+                          updateAddress('deliveryAddress', 'street', e.target.value)
+                        }
+                        placeholder="456 Oak Ave"
+                        aria-required="true"
+                      />
+                    </div>
+                    <div className="grid grid-cols-1 gap-4 sm:grid-cols-2">
                       <div className="space-y-2">
-                        <Label>Quantity</Label>
+                        <Label htmlFor="deliveryCity">City</Label>
                         <Input
-                          type="number"
-                          min="1"
-                          value={item.quantity}
-                          onChange={(e) =>
-                            updateItem(index, 'quantity', parseInt(e.target.value) || 1)
+                          id="deliveryCity"
+                          value={formData.deliveryAddress.city}
+                          onChange={(e: ChangeEvent<HTMLInputElement>) =>
+                            updateAddress('deliveryAddress', 'city', e.target.value)
                           }
+                          placeholder="Los Angeles"
                         />
                       </div>
                       <div className="space-y-2">
-                        <Label>Weight (kg)</Label>
+                        <Label htmlFor="deliveryState">State</Label>
                         <Input
-                          type="number"
-                          min="0"
-                          step="0.1"
-                          value={item.weight}
-                          onChange={(e) =>
-                            updateItem(index, 'weight', parseFloat(e.target.value) || 0)
+                          id="deliveryState"
+                          value={formData.deliveryAddress.state}
+                          onChange={(e: ChangeEvent<HTMLInputElement>) =>
+                            updateAddress('deliveryAddress', 'state', e.target.value)
                           }
+                          placeholder="CA"
                         />
                       </div>
+                    </div>
+                    <div className="grid grid-cols-1 gap-4 sm:grid-cols-2">
                       <div className="space-y-2">
-                        <Label>Value ($)</Label>
+                        <Label htmlFor="deliveryPostal">Postal code</Label>
                         <Input
-                          type="number"
-                          min="0"
-                          step="0.01"
-                          value={item.value}
-                          onChange={(e) =>
-                            updateItem(index, 'value', parseFloat(e.target.value) || 0)
+                          id="deliveryPostal"
+                          value={formData.deliveryAddress.postalCode}
+                          onChange={(e: ChangeEvent<HTMLInputElement>) =>
+                            updateAddress('deliveryAddress', 'postalCode', e.target.value)
                           }
+                          placeholder="90210"
                         />
                       </div>
-                      <div className="flex items-end">
-                        <Button
-                          type="button"
-                          variant="ghost"
-                          size="icon"
-                          className="text-status-error-text"
-                          onClick={() => removeItem(index)}
-                        >
-                          <Trash2 size={16} />
-                        </Button>
+                      <div className="space-y-2">
+                        <Label htmlFor="deliveryCountry">Country</Label>
+                        <Input
+                          id="deliveryCountry"
+                          value={formData.deliveryAddress.country}
+                          onChange={(e: ChangeEvent<HTMLInputElement>) =>
+                            updateAddress('deliveryAddress', 'country', e.target.value)
+                          }
+                          placeholder="USA"
+                        />
                       </div>
                     </div>
-                  </div>
-                ))}
+                  </fieldset>
+                </CardContent>
+              </Card>
+            </div>
+          </FormSection>
+        </div>
+
+        <div id="items-section">
+          <FormSection
+            title={
+              <span className="flex items-center gap-2">
+                <Package size={18} aria-hidden="true" />
+                Shipment contents <Badge variant="secondary">{formData.items.length}</Badge>
+              </span>
+            }
+            description="Add each item being shipped. Use the catalog to prefill details or enter a one-off item manually."
+            actions={
+              <Button type="button" variant="outline" size="sm" onClick={addItem}>
+                <Plus size={16} />
+                Add item
+              </Button>
+            }
+          >
+            {formData.items.length === 0 ? (
+              <EmptyState
+                illustration="empty-files"
+                title="No items added yet"
+                description="Add the products this order will ship — each with a name, SKU, quantity and value."
+                action={
+                  <Button type="button" variant="outline" onClick={addItem}>
+                    <Plus size={16} className="mr-1.5" />
+                    Add your first item
+                  </Button>
+                }
+              />
+            ) : (
+              <div className="space-y-4">
+                <div className="rounded-card border border-border-subtle bg-bg-sunken/40 p-4">
+                  <Label htmlFor="item-product-search">Search product catalog</Label>
+                  <Input
+                    id="item-product-search"
+                    value={productSearch}
+                    onChange={(e: ChangeEvent<HTMLInputElement>) =>
+                      setProductSearch(e.target.value)
+                    }
+                    placeholder="Search by name or SKU"
+                    className="mt-2"
+                  />
+                  <p className="mt-2 text-xs text-text-secondary">
+                    This filters the catalog picker for every item below. You can still edit any
+                    autofilled value or enter item details manually.
+                  </p>
+                </div>
+                <ol className="space-y-4" aria-label="Shipment items">
+                  {formData.items.map((item, index) => (
+                    <li key={item.id}>
+                      <OrderItemRow
+                        item={item}
+                        index={index}
+                        products={products}
+                        productsLoading={productsLoading}
+                        onUpdate={updateItem}
+                        onRemove={removeItem}
+                      />
+                    </li>
+                  ))}
+                </ol>
               </div>
             )}
-          </CardContent>
-        </Card>
-
-        {/* Scheduling & handling notes */}
-        <Card>
-          <CardHeader>
-            <CardTitle>Scheduling &amp; Handling</CardTitle>
-          </CardHeader>
-          <CardContent>
-            <div className="grid grid-cols-1 md:grid-cols-3 gap-6">
-              <div className="space-y-2">
-                <Label htmlFor="scheduledDelivery" className="flex items-center gap-1.5">
-                  <CalendarClock size={14} className="text-text-secondary" />
-                  Scheduled Delivery
-                </Label>
-                <Input
-                  id="scheduledDelivery"
-                  type="datetime-local"
-                  value={formData.scheduledDelivery}
-                  onChange={(e) => updateField('scheduledDelivery', e.target.value)}
-                />
-                <p className="text-xs text-text-secondary">
-                  The delivery window promised to the customer. Leave blank to dispatch as soon as a
-                  driver is free.
-                </p>
-              </div>
-              <div className="md:col-span-2 space-y-2">
-                <Label htmlFor="specialInstructions">Special Instructions</Label>
-                <Textarea
-                  id="specialInstructions"
-                  value={formData.specialInstructions}
-                  onChange={(e) => updateField('specialInstructions', e.target.value)}
-                  placeholder="Any special handling or delivery instructions..."
-                  rows={4}
-                />
-              </div>
+          </FormSection>
+        </div>
+
+        <FormSection
+          title={
+            <span className="flex items-center gap-2">
+              <CalendarClock size={18} aria-hidden="true" />
+              Timing &amp; handling
+            </span>
+          }
+          description="Optional delivery timing and instructions for the carrier."
+        >
+          <div className="grid grid-cols-1 gap-6 lg:grid-cols-3">
+            <div className="space-y-2">
+              <Label htmlFor="scheduledDelivery">Scheduled delivery</Label>
+              <Input
+                id="scheduledDelivery"
+                type="datetime-local"
+                value={formData.scheduledDelivery}
+                onChange={(e: ChangeEvent<HTMLInputElement>) =>
+                  updateField('scheduledDelivery', e.target.value)
+                }
+              />
+              <p className="text-xs text-text-secondary">
+                Leave blank to dispatch as soon as a driver is available.
+              </p>
             </div>
-          </CardContent>
-        </Card>
+            <div className="space-y-2 lg:col-span-2">
+              <Label htmlFor="specialInstructions">Special instructions</Label>
+              <Textarea
+                id="specialInstructions"
+                value={formData.specialInstructions}
+                onChange={(e: ChangeEvent<HTMLTextAreaElement>) =>
+                  updateField('specialInstructions', e.target.value)
+                }
+                placeholder="Any special handling or delivery instructions..."
+                rows={4}
+              />
+            </div>
+          </div>
+        </FormSection>
       </form>
     </PageLayout>
   );