shipping

client/src/components/AppShell.tsx

@@ -12,6 +12,7 @@ const links = [
   { to: "/inventory/warehouses", label: "Warehouses" },
   { to: "/sales/quotes", label: "Quotes" },
   { to: "/sales/orders", label: "Sales Orders" },
+  { to: "/shipping/shipments", label: "Shipments" },
   { to: "/planning/gantt", label: "Gantt" },
 ];
 

client/src/lib/api.ts

@@ -40,6 +40,13 @@ import type {
   SalesDocumentStatus,
   SalesDocumentSummaryDto,
 } from "@mrp/shared/dist/sales/types.js";
+import type {
+  ShipmentDetailDto,
+  ShipmentInput,
+  ShipmentOrderOptionDto,
+  ShipmentStatus,
+  ShipmentSummaryDto,
+} from "@mrp/shared/dist/shipping/types.js";
 
 export class ApiError extends Error {
   constructor(message: string, public readonly code: string) {
@@ -427,6 +434,36 @@ export const api = {
       token
     );
   },
+  getShipmentOrderOptions(token: string) {
+    return request<ShipmentOrderOptionDto[]>("/api/v1/shipping/orders/options", undefined, token);
+  },
+  getShipments(token: string, filters?: { q?: string; status?: ShipmentStatus; salesOrderId?: string }) {
+    return request<ShipmentSummaryDto[]>(
+      `/api/v1/shipping/shipments${buildQueryString({
+        q: filters?.q,
+        status: filters?.status,
+        salesOrderId: filters?.salesOrderId,
+      })}`,
+      undefined,
+      token
+    );
+  },
+  getShipment(token: string, shipmentId: string) {
+    return request<ShipmentDetailDto>(`/api/v1/shipping/shipments/${shipmentId}`, undefined, token);
+  },
+  createShipment(token: string, payload: ShipmentInput) {
+    return request<ShipmentDetailDto>("/api/v1/shipping/shipments", { method: "POST", body: JSON.stringify(payload) }, token);
+  },
+  updateShipment(token: string, shipmentId: string, payload: ShipmentInput) {
+    return request<ShipmentDetailDto>(`/api/v1/shipping/shipments/${shipmentId}`, { method: "PUT", body: JSON.stringify(payload) }, token);
+  },
+  updateShipmentStatus(token: string, shipmentId: string, status: ShipmentStatus) {
+    return request<ShipmentDetailDto>(
+      `/api/v1/shipping/shipments/${shipmentId}/status`,
+      { method: "PATCH", body: JSON.stringify({ status }) },
+      token
+    );
+  },
   async getCompanyProfilePreviewPdf(token: string) {
     const response = await fetch("/api/v1/documents/company-profile-preview.pdf", {
       headers: {

client/src/main.tsx

@@ -24,6 +24,9 @@ import { WarehousesPage } from "./modules/inventory/WarehousesPage";
 import { SalesDetailPage } from "./modules/sales/SalesDetailPage";
 import { SalesFormPage } from "./modules/sales/SalesFormPage";
 import { SalesListPage } from "./modules/sales/SalesListPage";
+import { ShipmentDetailPage } from "./modules/shipping/ShipmentDetailPage";
+import { ShipmentFormPage } from "./modules/shipping/ShipmentFormPage";
+import { ShipmentListPage } from "./modules/shipping/ShipmentListPage";
 import { ThemeProvider } from "./theme/ThemeProvider";
 import "./index.css";
 
@@ -69,6 +72,13 @@ const router = createBrowserRouter([
               { path: "/sales/orders/:orderId", element: <SalesDetailPage entity="order" /> },
             ],
           },
+          {
+            element: <ProtectedRoute requiredPermissions={[permissions.shippingRead]} />,
+            children: [
+              { path: "/shipping/shipments", element: <ShipmentListPage /> },
+              { path: "/shipping/shipments/:shipmentId", element: <ShipmentDetailPage /> },
+            ],
+          },
           {
             element: <ProtectedRoute requiredPermissions={[permissions.crmWrite]} />,
             children: [
@@ -87,6 +97,13 @@ const router = createBrowserRouter([
               { path: "/sales/orders/:orderId/edit", element: <SalesFormPage entity="order" mode="edit" /> },
             ],
           },
+          {
+            element: <ProtectedRoute requiredPermissions={[permissions.shippingWrite]} />,
+            children: [
+              { path: "/shipping/shipments/new", element: <ShipmentFormPage mode="create" /> },
+              { path: "/shipping/shipments/:shipmentId/edit", element: <ShipmentFormPage mode="edit" /> },
+            ],
+          },
           {
             element: <ProtectedRoute requiredPermissions={[permissions.inventoryWrite]} />,
             children: [

client/src/modules/sales/SalesDetailPage.tsx

@@ -1,5 +1,6 @@
 import { permissions } from "@mrp/shared";
 import type { SalesDocumentDetailDto, SalesDocumentStatus } from "@mrp/shared/dist/sales/types.js";
+import type { ShipmentSummaryDto } from "@mrp/shared/dist/shipping/types.js";
 import { useEffect, useState } from "react";
 import { Link, useNavigate, useParams } from "react-router-dom";
 
@@ -7,6 +8,7 @@ import { useAuth } from "../../auth/AuthProvider";
 import { api, ApiError } from "../../lib/api";
 import { salesConfigs, salesStatusOptions, type SalesDocumentEntity } from "./config";
 import { SalesStatusBadge } from "./SalesStatusBadge";
+import { ShipmentStatusBadge } from "../shipping/ShipmentStatusBadge";
 
 export function SalesDetailPage({ entity }: { entity: SalesDocumentEntity }) {
   const { token, user } = useAuth();
@@ -18,8 +20,11 @@ export function SalesDetailPage({ entity }: { entity: SalesDocumentEntity }) {
   const [status, setStatus] = useState(`Loading ${config.singularLabel.toLowerCase()}...`);
   const [isUpdatingStatus, setIsUpdatingStatus] = useState(false);
   const [isConverting, setIsConverting] = useState(false);
+  const [shipments, setShipments] = useState<ShipmentSummaryDto[]>([]);
 
   const canManage = user?.permissions.includes(permissions.salesWrite) ?? false;
+  const canManageShipping = user?.permissions.includes(permissions.shippingWrite) ?? false;
+  const canReadShipping = user?.permissions.includes(permissions.shippingRead) ?? false;
 
   useEffect(() => {
     if (!token || !documentId) {
@@ -31,12 +36,15 @@ export function SalesDetailPage({ entity }: { entity: SalesDocumentEntity }) {
       .then((nextDocument) => {
         setDocument(nextDocument);
         setStatus(`${config.singularLabel} loaded.`);
+        if (entity === "order" && canReadShipping) {
+          api.getShipments(token, { salesOrderId: nextDocument.id }).then(setShipments).catch(() => setShipments([]));
+        }
       })
       .catch((error: unknown) => {
         const message = error instanceof ApiError ? error.message : `Unable to load ${config.singularLabel.toLowerCase()}.`;
         setStatus(message);
       });
-  }, [config.singularLabel, documentId, entity, token]);
+  }, [canReadShipping, config.singularLabel, documentId, entity, token]);
 
   if (!document) {
     return <div className="rounded-[28px] border border-line/70 bg-surface/90 p-4 text-sm text-muted shadow-panel">{status}</div>;
@@ -116,6 +124,11 @@ export function SalesDetailPage({ entity }: { entity: SalesDocumentEntity }) {
                     {isConverting ? "Converting..." : "Convert to sales order"}
                   </button>
                 ) : null}
+                {entity === "order" && canManageShipping ? (
+                  <Link to={`/shipping/shipments/new?orderId=${activeDocument.id}`} className="inline-flex items-center justify-center rounded-2xl border border-line/70 px-2 py-2 text-sm font-semibold text-text">
+                    New shipment
+                  </Link>
+                ) : null}
               </>
             ) : null}
           </div>
@@ -239,6 +252,40 @@ export function SalesDetailPage({ entity }: { entity: SalesDocumentEntity }) {
           </div>
         )}
       </section>
+      {entity === "order" && canReadShipping ? (
+        <section className="rounded-[28px] border border-line/70 bg-surface/90 p-4 shadow-panel 2xl:p-5">
+          <div className="flex items-center justify-between gap-3">
+            <div>
+              <p className="text-xs font-semibold uppercase tracking-[0.24em] text-muted">Shipping</p>
+              <p className="mt-2 text-sm text-muted">Shipment records currently tied to this sales order.</p>
+            </div>
+            {canManageShipping ? (
+              <Link to={`/shipping/shipments/new?orderId=${activeDocument.id}`} className="inline-flex items-center justify-center rounded-2xl border border-line/70 px-2 py-2 text-sm font-semibold text-text">
+                Create shipment
+              </Link>
+            ) : null}
+          </div>
+          {shipments.length === 0 ? (
+            <div className="mt-6 rounded-3xl border border-dashed border-line/70 bg-page/60 px-4 py-8 text-center text-sm text-muted">
+              No shipments have been created for this sales order yet.
+            </div>
+          ) : (
+            <div className="mt-6 space-y-3">
+              {shipments.map((shipment) => (
+                <Link key={shipment.id} to={`/shipping/shipments/${shipment.id}`} className="block rounded-3xl border border-line/70 bg-page/60 p-3 transition hover:bg-page/80">
+                  <div className="flex flex-wrap items-center justify-between gap-3">
+                    <div>
+                      <div className="font-semibold text-text">{shipment.shipmentNumber}</div>
+                      <div className="mt-1 text-xs text-muted">{shipment.carrier || "Carrier not set"} · {shipment.trackingNumber || "No tracking"}</div>
+                    </div>
+                    <ShipmentStatusBadge status={shipment.status} />
+                  </div>
+                </Link>
+              ))}
+            </div>
+          )}
+        </section>
+      ) : null}
     </section>
   );
 }

client/src/modules/shipping/ShipmentDetailPage.tsx

@@ -0,0 +1,148 @@
+import { permissions } from "@mrp/shared";
+import type { ShipmentDetailDto, ShipmentStatus, ShipmentSummaryDto } from "@mrp/shared/dist/shipping/types.js";
+import { useEffect, useState } from "react";
+import { Link, useParams } from "react-router-dom";
+
+import { useAuth } from "../../auth/AuthProvider";
+import { api, ApiError } from "../../lib/api";
+import { shipmentStatusOptions } from "./config";
+import { ShipmentStatusBadge } from "./ShipmentStatusBadge";
+
+export function ShipmentDetailPage() {
+  const { token, user } = useAuth();
+  const { shipmentId } = useParams();
+  const [shipment, setShipment] = useState<ShipmentDetailDto | null>(null);
+  const [relatedShipments, setRelatedShipments] = useState<ShipmentSummaryDto[]>([]);
+  const [status, setStatus] = useState("Loading shipment...");
+  const [isUpdatingStatus, setIsUpdatingStatus] = useState(false);
+
+  const canManage = user?.permissions.includes(permissions.shippingWrite) ?? false;
+
+  useEffect(() => {
+    if (!token || !shipmentId) {
+      return;
+    }
+
+    api.getShipment(token, shipmentId)
+      .then((nextShipment) => {
+        setShipment(nextShipment);
+        setStatus("Shipment loaded.");
+        return api.getShipments(token, { salesOrderId: nextShipment.salesOrderId });
+      })
+      .then((shipments) => setRelatedShipments(shipments.filter((candidate) => candidate.id !== shipmentId)))
+      .catch((error: unknown) => {
+        const message = error instanceof ApiError ? error.message : "Unable to load shipment.";
+        setStatus(message);
+      });
+  }, [shipmentId, token]);
+
+  async function handleStatusChange(nextStatus: ShipmentStatus) {
+    if (!token || !shipment) {
+      return;
+    }
+
+    setIsUpdatingStatus(true);
+    setStatus("Updating shipment status...");
+    try {
+      const nextShipment = await api.updateShipmentStatus(token, shipment.id, nextStatus);
+      setShipment(nextShipment);
+      setStatus("Shipment status updated.");
+    } catch (error: unknown) {
+      const message = error instanceof ApiError ? error.message : "Unable to update shipment status.";
+      setStatus(message);
+    } finally {
+      setIsUpdatingStatus(false);
+    }
+  }
+
+  if (!shipment) {
+    return <div className="rounded-[28px] border border-line/70 bg-surface/90 p-4 text-sm text-muted shadow-panel">{status}</div>;
+  }
+
+  return (
+    <section className="space-y-4">
+      <div className="rounded-[28px] border border-line/70 bg-surface/90 p-4 shadow-panel 2xl:p-5">
+        <div className="flex flex-col gap-3 lg:flex-row lg:items-start lg:justify-between">
+          <div>
+            <p className="text-xs font-semibold uppercase tracking-[0.24em] text-muted">Shipment</p>
+            <h3 className="mt-2 text-xl font-bold text-text">{shipment.shipmentNumber}</h3>
+            <p className="mt-1 text-sm text-text">{shipment.salesOrderNumber} · {shipment.customerName}</p>
+            <div className="mt-3"><ShipmentStatusBadge status={shipment.status} /></div>
+          </div>
+          <div className="flex flex-wrap gap-3">
+            <Link to="/shipping/shipments" className="inline-flex items-center justify-center rounded-2xl border border-line/70 px-2 py-2 text-sm font-semibold text-text">Back to shipments</Link>
+            <Link to={`/sales/orders/${shipment.salesOrderId}`} className="inline-flex items-center justify-center rounded-2xl border border-line/70 px-2 py-2 text-sm font-semibold text-text">Open sales order</Link>
+            {canManage ? (
+              <Link to={`/shipping/shipments/${shipment.id}/edit`} className="inline-flex items-center justify-center rounded-2xl bg-brand px-2 py-2 text-sm font-semibold text-white">Edit shipment</Link>
+            ) : null}
+          </div>
+        </div>
+      </div>
+      {canManage ? (
+        <section className="rounded-[28px] border border-line/70 bg-surface/90 p-4 shadow-panel 2xl:p-5">
+          <div className="flex flex-col gap-3 lg:flex-row lg:items-center lg:justify-between">
+            <div>
+              <p className="text-xs font-semibold uppercase tracking-[0.24em] text-muted">Quick Actions</p>
+              <p className="mt-2 text-sm text-muted">Update shipment status without opening the editor.</p>
+            </div>
+            <div className="flex flex-wrap gap-2">
+              {shipmentStatusOptions.map((option) => (
+                <button key={option.value} type="button" onClick={() => handleStatusChange(option.value)} disabled={isUpdatingStatus || shipment.status === option.value} className="rounded-2xl border border-line/70 px-2 py-2 text-sm font-semibold text-text disabled:cursor-not-allowed disabled:opacity-60">
+                  {option.label}
+                </button>
+              ))}
+            </div>
+          </div>
+        </section>
+      ) : null}
+      <section className="grid gap-3 xl:grid-cols-4">
+        <article className="rounded-[24px] border border-line/70 bg-surface/90 px-3 py-3 shadow-panel"><p className="text-xs font-semibold uppercase tracking-[0.18em] text-muted">Carrier</p><div className="mt-2 text-base font-bold text-text">{shipment.carrier || "Not set"}</div></article>
+        <article className="rounded-[24px] border border-line/70 bg-surface/90 px-3 py-3 shadow-panel"><p className="text-xs font-semibold uppercase tracking-[0.18em] text-muted">Service</p><div className="mt-2 text-base font-bold text-text">{shipment.serviceLevel || "Not set"}</div></article>
+        <article className="rounded-[24px] border border-line/70 bg-surface/90 px-3 py-3 shadow-panel"><p className="text-xs font-semibold uppercase tracking-[0.18em] text-muted">Tracking</p><div className="mt-2 text-base font-bold text-text">{shipment.trackingNumber || "Not set"}</div></article>
+        <article className="rounded-[24px] border border-line/70 bg-surface/90 px-3 py-3 shadow-panel"><p className="text-xs font-semibold uppercase tracking-[0.18em] text-muted">Packages</p><div className="mt-2 text-base font-bold text-text">{shipment.packageCount}</div></article>
+      </section>
+      <div className="grid gap-3 xl:grid-cols-[minmax(0,1fr)_minmax(320px,0.9fr)]">
+        <article className="rounded-[28px] border border-line/70 bg-surface/90 p-4 shadow-panel 2xl:p-5">
+          <p className="text-xs font-semibold uppercase tracking-[0.24em] text-muted">Shipment Notes</p>
+          <p className="mt-3 whitespace-pre-line text-sm leading-6 text-text">{shipment.notes || "No notes recorded for this shipment."}</p>
+        </article>
+        <article className="rounded-[28px] border border-line/70 bg-surface/90 p-4 shadow-panel 2xl:p-5">
+          <p className="text-xs font-semibold uppercase tracking-[0.24em] text-muted">Timing</p>
+          <dl className="mt-5 grid gap-3">
+            <div><dt className="text-xs font-semibold uppercase tracking-[0.18em] text-muted">Ship Date</dt><dd className="mt-1 text-sm text-text">{shipment.shipDate ? new Date(shipment.shipDate).toLocaleDateString() : "Not set"}</dd></div>
+            <div><dt className="text-xs font-semibold uppercase tracking-[0.18em] text-muted">Created</dt><dd className="mt-1 text-sm text-text">{new Date(shipment.createdAt).toLocaleString()}</dd></div>
+            <div><dt className="text-xs font-semibold uppercase tracking-[0.18em] text-muted">Updated</dt><dd className="mt-1 text-sm text-text">{new Date(shipment.updatedAt).toLocaleString()}</dd></div>
+          </dl>
+        </article>
+      </div>
+      <section className="rounded-[28px] border border-line/70 bg-surface/90 p-4 shadow-panel 2xl:p-5">
+        <div className="flex items-center justify-between gap-3">
+          <div>
+            <p className="text-xs font-semibold uppercase tracking-[0.24em] text-muted">Related Shipments</p>
+            <p className="mt-2 text-sm text-muted">Other shipments already tied to this sales order.</p>
+          </div>
+          {canManage ? (
+            <Link to={`/shipping/shipments/new?orderId=${shipment.salesOrderId}`} className="inline-flex items-center justify-center rounded-2xl border border-line/70 px-2 py-2 text-sm font-semibold text-text">Add another shipment</Link>
+          ) : null}
+        </div>
+        {relatedShipments.length === 0 ? (
+          <div className="mt-6 rounded-3xl border border-dashed border-line/70 bg-page/60 px-4 py-8 text-center text-sm text-muted">No additional shipments exist for this sales order.</div>
+        ) : (
+          <div className="mt-6 space-y-3">
+            {relatedShipments.map((related) => (
+              <Link key={related.id} to={`/shipping/shipments/${related.id}`} className="block rounded-3xl border border-line/70 bg-page/60 p-3 transition hover:bg-page/80">
+                <div className="flex flex-wrap items-center justify-between gap-3">
+                  <div>
+                    <div className="font-semibold text-text">{related.shipmentNumber}</div>
+                    <div className="mt-1 text-xs text-muted">{related.carrier || "Carrier not set"} · {related.trackingNumber || "No tracking"}</div>
+                  </div>
+                  <ShipmentStatusBadge status={related.status} />
+                </div>
+              </Link>
+            ))}
+          </div>
+        )}
+      </section>
+    </section>
+  );
+}

client/src/modules/shipping/ShipmentFormPage.tsx

@@ -0,0 +1,201 @@
+import type { ShipmentInput, ShipmentOrderOptionDto } from "@mrp/shared/dist/shipping/types.js";
+import { useEffect, useState } from "react";
+import { Link, useNavigate, useParams, useSearchParams } from "react-router-dom";
+
+import { useAuth } from "../../auth/AuthProvider";
+import { api, ApiError } from "../../lib/api";
+import { emptyShipmentInput, shipmentStatusOptions } from "./config";
+
+export function ShipmentFormPage({ mode }: { mode: "create" | "edit" }) {
+  const { token } = useAuth();
+  const navigate = useNavigate();
+  const { shipmentId } = useParams();
+  const [searchParams] = useSearchParams();
+  const seededOrderId = searchParams.get("orderId") ?? "";
+  const [form, setForm] = useState<ShipmentInput>({ ...emptyShipmentInput, salesOrderId: seededOrderId });
+  const [orderOptions, setOrderOptions] = useState<ShipmentOrderOptionDto[]>([]);
+  const [orderSearchTerm, setOrderSearchTerm] = useState("");
+  const [orderPickerOpen, setOrderPickerOpen] = useState(false);
+  const [status, setStatus] = useState(mode === "create" ? "Create a new shipment." : "Loading shipment...");
+  const [isSaving, setIsSaving] = useState(false);
+
+  useEffect(() => {
+    if (!token) {
+      return;
+    }
+
+    api.getShipmentOrderOptions(token).then((options) => {
+      setOrderOptions(options);
+      const seeded = options.find((option) => option.id === seededOrderId);
+      if (seeded && mode === "create") {
+        setOrderSearchTerm(`${seeded.documentNumber} - ${seeded.customerName}`);
+      }
+    }).catch(() => setOrderOptions([]));
+  }, [mode, seededOrderId, token]);
+
+  useEffect(() => {
+    if (!token || mode !== "edit" || !shipmentId) {
+      return;
+    }
+
+    api.getShipment(token, shipmentId)
+      .then((shipment) => {
+        setForm({
+          salesOrderId: shipment.salesOrderId,
+          status: shipment.status,
+          shipDate: shipment.shipDate,
+          carrier: shipment.carrier,
+          serviceLevel: shipment.serviceLevel,
+          trackingNumber: shipment.trackingNumber,
+          packageCount: shipment.packageCount,
+          notes: shipment.notes,
+        });
+        setOrderSearchTerm(`${shipment.salesOrderNumber} - ${shipment.customerName}`);
+        setStatus("Shipment loaded.");
+      })
+      .catch((error: unknown) => {
+        const message = error instanceof ApiError ? error.message : "Unable to load shipment.";
+        setStatus(message);
+      });
+  }, [mode, shipmentId, token]);
+
+  function updateField<Key extends keyof ShipmentInput>(key: Key, value: ShipmentInput[Key]) {
+    setForm((current) => ({ ...current, [key]: value }));
+  }
+
+  function getSelectedOrder(orderId: string) {
+    return orderOptions.find((option) => option.id === orderId) ?? null;
+  }
+
+  async function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    if (!token) {
+      return;
+    }
+
+    setIsSaving(true);
+    setStatus("Saving shipment...");
+    try {
+      const saved = mode === "create" ? await api.createShipment(token, form) : await api.updateShipment(token, shipmentId ?? "", form);
+      navigate(`/shipping/shipments/${saved.id}`);
+    } catch (error: unknown) {
+      const message = error instanceof ApiError ? error.message : "Unable to save shipment.";
+      setStatus(message);
+      setIsSaving(false);
+    }
+  }
+
+  return (
+    <form className="space-y-6" onSubmit={handleSubmit}>
+      <section className="rounded-[28px] border border-line/70 bg-surface/90 p-4 shadow-panel 2xl:p-5">
+        <div className="flex flex-col gap-3 lg:flex-row lg:items-start lg:justify-between">
+          <div>
+            <p className="text-xs font-semibold uppercase tracking-[0.24em] text-muted">Shipping Editor</p>
+            <h3 className="mt-2 text-xl font-bold text-text">{mode === "create" ? "New Shipment" : "Edit Shipment"}</h3>
+          </div>
+          <Link to={mode === "create" ? "/shipping/shipments" : `/shipping/shipments/${shipmentId}`} className="inline-flex items-center justify-center rounded-2xl border border-line/70 px-2 py-2 text-sm font-semibold text-text">
+            Cancel
+          </Link>
+        </div>
+      </section>
+      <section className="space-y-4 rounded-[28px] border border-line/70 bg-surface/90 p-4 shadow-panel 2xl:p-5">
+        <label className="block">
+          <span className="mb-2 block text-sm font-semibold text-text">Sales Order</span>
+          <div className="relative">
+            <input
+              value={orderSearchTerm}
+              onChange={(event) => {
+                setOrderSearchTerm(event.target.value);
+                updateField("salesOrderId", "");
+                setOrderPickerOpen(true);
+              }}
+              onFocus={() => setOrderPickerOpen(true)}
+              onBlur={() => {
+                window.setTimeout(() => {
+                  setOrderPickerOpen(false);
+                  const selected = getSelectedOrder(form.salesOrderId);
+                  if (selected) {
+                    setOrderSearchTerm(`${selected.documentNumber} - ${selected.customerName}`);
+                  }
+                }, 120);
+              }}
+              placeholder="Search sales order"
+              className="w-full rounded-2xl border border-line/70 bg-page px-2 py-2 text-text outline-none transition focus:border-brand"
+            />
+            {orderPickerOpen ? (
+              <div className="absolute z-20 mt-2 max-h-64 w-full overflow-y-auto rounded-2xl border border-line/70 bg-surface shadow-panel">
+                {orderOptions
+                  .filter((option) => {
+                    const query = orderSearchTerm.trim().toLowerCase();
+                    if (!query) {
+                      return true;
+                    }
+                    return option.documentNumber.toLowerCase().includes(query) || option.customerName.toLowerCase().includes(query);
+                  })
+                  .slice(0, 12)
+                  .map((option) => (
+                    <button
+                      key={option.id}
+                      type="button"
+                      onMouseDown={(event) => {
+                        event.preventDefault();
+                        updateField("salesOrderId", option.id);
+                        setOrderSearchTerm(`${option.documentNumber} - ${option.customerName}`);
+                        setOrderPickerOpen(false);
+                      }}
+                      className="block w-full border-b border-line/50 px-2 py-2 text-left text-sm transition last:border-b-0 hover:bg-page/70"
+                    >
+                      <div className="font-semibold text-text">{option.documentNumber}</div>
+                      <div className="mt-1 text-xs text-muted">{option.customerName}</div>
+                    </button>
+                  ))}
+              </div>
+            ) : null}
+          </div>
+        </label>
+        <div className="grid gap-3 xl:grid-cols-3">
+          <label className="block">
+            <span className="mb-2 block text-sm font-semibold text-text">Status</span>
+            <select value={form.status} onChange={(event) => updateField("status", event.target.value as ShipmentInput["status"])} className="w-full rounded-2xl border border-line/70 bg-page px-2 py-2 text-text outline-none transition focus:border-brand">
+              {shipmentStatusOptions.map((option) => (
+                <option key={option.value} value={option.value}>{option.label}</option>
+              ))}
+            </select>
+          </label>
+          <label className="block">
+            <span className="mb-2 block text-sm font-semibold text-text">Ship Date</span>
+            <input type="date" value={form.shipDate ? form.shipDate.slice(0, 10) : ""} onChange={(event) => updateField("shipDate", event.target.value ? new Date(event.target.value).toISOString() : null)} className="w-full rounded-2xl border border-line/70 bg-page px-2 py-2 text-text outline-none transition focus:border-brand" />
+          </label>
+          <label className="block">
+            <span className="mb-2 block text-sm font-semibold text-text">Packages</span>
+            <input type="number" min={1} step={1} value={form.packageCount} onChange={(event) => updateField("packageCount", Number.parseInt(event.target.value, 10) || 1)} className="w-full rounded-2xl border border-line/70 bg-page px-2 py-2 text-text outline-none transition focus:border-brand" />
+          </label>
+        </div>
+        <div className="grid gap-3 xl:grid-cols-3">
+          <label className="block">
+            <span className="mb-2 block text-sm font-semibold text-text">Carrier</span>
+            <input value={form.carrier} onChange={(event) => updateField("carrier", event.target.value)} className="w-full rounded-2xl border border-line/70 bg-page px-2 py-2 text-text outline-none transition focus:border-brand" />
+          </label>
+          <label className="block">
+            <span className="mb-2 block text-sm font-semibold text-text">Service Level</span>
+            <input value={form.serviceLevel} onChange={(event) => updateField("serviceLevel", event.target.value)} className="w-full rounded-2xl border border-line/70 bg-page px-2 py-2 text-text outline-none transition focus:border-brand" />
+          </label>
+          <label className="block">
+            <span className="mb-2 block text-sm font-semibold text-text">Tracking Number</span>
+            <input value={form.trackingNumber} onChange={(event) => updateField("trackingNumber", event.target.value)} className="w-full rounded-2xl border border-line/70 bg-page px-2 py-2 text-text outline-none transition focus:border-brand" />
+          </label>
+        </div>
+        <label className="block">
+          <span className="mb-2 block text-sm font-semibold text-text">Notes</span>
+          <textarea value={form.notes} onChange={(event) => updateField("notes", event.target.value)} rows={4} className="w-full rounded-3xl border border-line/70 bg-page px-2 py-2 text-text outline-none transition focus:border-brand" />
+        </label>
+        <div className="flex flex-col gap-3 rounded-2xl border border-line/70 bg-page/70 px-2 py-2 sm:flex-row sm:items-center sm:justify-between">
+          <span className="min-w-0 text-sm text-muted">{status}</span>
+          <button type="submit" disabled={isSaving} className="rounded-2xl bg-brand px-2 py-2 text-sm font-semibold text-white disabled:cursor-not-allowed disabled:opacity-60">
+            {isSaving ? "Saving..." : mode === "create" ? "Create shipment" : "Save changes"}
+          </button>
+        </div>
+      </section>
+    </form>
+  );
+}

client/src/modules/shipping/ShipmentListPage.tsx

@@ -0,0 +1,116 @@
+import { permissions } from "@mrp/shared";
+import type { ShipmentStatus, ShipmentSummaryDto } from "@mrp/shared/dist/shipping/types.js";
+import { useEffect, useState } from "react";
+import { Link } from "react-router-dom";
+
+import { useAuth } from "../../auth/AuthProvider";
+import { api, ApiError } from "../../lib/api";
+import { shipmentStatusFilters } from "./config";
+import { ShipmentStatusBadge } from "./ShipmentStatusBadge";
+
+export function ShipmentListPage() {
+  const { token, user } = useAuth();
+  const [shipments, setShipments] = useState<ShipmentSummaryDto[]>([]);
+  const [searchTerm, setSearchTerm] = useState("");
+  const [statusFilter, setStatusFilter] = useState<"ALL" | ShipmentStatus>("ALL");
+  const [status, setStatus] = useState("Loading shipments...");
+
+  const canManage = user?.permissions.includes(permissions.shippingWrite) ?? false;
+
+  useEffect(() => {
+    if (!token) {
+      return;
+    }
+
+    api
+      .getShipments(token, {
+        q: searchTerm.trim() || undefined,
+        status: statusFilter === "ALL" ? undefined : statusFilter,
+      })
+      .then((nextShipments) => {
+        setShipments(nextShipments);
+        setStatus(`${nextShipments.length} shipments matched the current filters.`);
+      })
+      .catch((error: unknown) => {
+        const message = error instanceof ApiError ? error.message : "Unable to load shipments.";
+        setStatus(message);
+      });
+  }, [searchTerm, statusFilter, token]);
+
+  return (
+    <section className="rounded-[28px] border border-line/70 bg-surface/90 p-4 shadow-panel">
+      <div className="flex flex-col gap-3 lg:flex-row lg:items-start lg:justify-between">
+        <div>
+          <p className="text-xs font-semibold uppercase tracking-[0.24em] text-muted">Shipping</p>
+          <h3 className="mt-2 text-lg font-bold text-text">Shipments</h3>
+          <p className="mt-2 max-w-2xl text-sm text-muted">Outbound shipment records tied to sales orders, carriers, and tracking details.</p>
+        </div>
+        {canManage ? (
+          <Link to="/shipping/shipments/new" className="inline-flex items-center justify-center rounded-2xl bg-brand px-3 py-2 text-sm font-semibold text-white">
+            New shipment
+          </Link>
+        ) : null}
+      </div>
+      <div className="mt-6 grid gap-3 rounded-3xl border border-line/70 bg-page/60 p-3 xl:grid-cols-[1.35fr_0.8fr]">
+        <label className="block">
+          <span className="mb-2 block text-xs font-semibold uppercase tracking-[0.16em] text-muted">Search</span>
+          <input
+            value={searchTerm}
+            onChange={(event) => setSearchTerm(event.target.value)}
+            placeholder="Search by shipment, order, customer, carrier, or tracking"
+            className="w-full rounded-2xl border border-line/70 bg-surface px-2 py-2 text-text outline-none transition focus:border-brand"
+          />
+        </label>
+        <label className="block">
+          <span className="mb-2 block text-xs font-semibold uppercase tracking-[0.16em] text-muted">Status</span>
+          <select
+            value={statusFilter}
+            onChange={(event) => setStatusFilter(event.target.value as "ALL" | ShipmentStatus)}
+            className="w-full rounded-2xl border border-line/70 bg-surface px-2 py-2 text-text outline-none transition focus:border-brand"
+          >
+            {shipmentStatusFilters.map((option) => (
+              <option key={option.value} value={option.value}>
+                {option.label}
+              </option>
+            ))}
+          </select>
+        </label>
+      </div>
+      <div className="mt-6 rounded-2xl border border-line/70 bg-page/60 px-2 py-2 text-sm text-muted">{status}</div>
+      {shipments.length === 0 ? (
+        <div className="mt-6 rounded-3xl border border-dashed border-line/70 bg-page/60 px-4 py-8 text-center text-sm text-muted">No shipments have been added yet.</div>
+      ) : (
+        <div className="mt-6 overflow-hidden rounded-2xl border border-line/70">
+          <table className="min-w-full divide-y divide-line/70 text-sm">
+            <thead className="bg-page/80 text-left text-muted">
+              <tr>
+                <th className="px-2 py-2">Shipment</th>
+                <th className="px-2 py-2">Sales Order</th>
+                <th className="px-2 py-2">Customer</th>
+                <th className="px-2 py-2">Status</th>
+                <th className="px-2 py-2">Carrier</th>
+                <th className="px-2 py-2">Ship Date</th>
+              </tr>
+            </thead>
+            <tbody className="divide-y divide-line/70 bg-surface">
+              {shipments.map((shipment) => (
+                <tr key={shipment.id} className="transition hover:bg-page/70">
+                  <td className="px-2 py-2">
+                    <Link to={`/shipping/shipments/${shipment.id}`} className="font-semibold text-text hover:text-brand">
+                      {shipment.shipmentNumber}
+                    </Link>
+                  </td>
+                  <td className="px-2 py-2 text-muted">{shipment.salesOrderNumber}</td>
+                  <td className="px-2 py-2 text-muted">{shipment.customerName}</td>
+                  <td className="px-2 py-2"><ShipmentStatusBadge status={shipment.status} /></td>
+                  <td className="px-2 py-2 text-muted">{shipment.carrier || "Not set"}</td>
+                  <td className="px-2 py-2 text-muted">{shipment.shipDate ? new Date(shipment.shipDate).toLocaleDateString() : "Not set"}</td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      )}
+    </section>
+  );
+}

client/src/modules/shipping/ShipmentStatusBadge.tsx

@@ -0,0 +1,8 @@
+import type { ShipmentStatus } from "@mrp/shared/dist/shipping/types.js";
+
+import { shipmentStatusOptions, shipmentStatusPalette } from "./config";
+
+export function ShipmentStatusBadge({ status }: { status: ShipmentStatus }) {
+  const label = shipmentStatusOptions.find((option) => option.value === status)?.label ?? status;
+  return <span className={`inline-flex rounded-full px-2 py-1 text-xs font-semibold ${shipmentStatusPalette[status]}`}>{label}</span>;
+}

client/src/modules/shipping/ShipmentsPage.tsx

@@ -0,0 +1,5 @@
+import { Outlet } from "react-router-dom";
+
+export function ShipmentsPage() {
+  return <Outlet />;
+}

client/src/modules/shipping/config.ts

@@ -0,0 +1,33 @@
+import type { ShipmentInput, ShipmentStatus } from "@mrp/shared/dist/shipping/types.js";
+
+export const shipmentStatusOptions: Array<{ value: ShipmentStatus; label: string }> = [
+  { value: "DRAFT", label: "Draft" },
+  { value: "PICKING", label: "Picking" },
+  { value: "PACKED", label: "Packed" },
+  { value: "SHIPPED", label: "Shipped" },
+  { value: "DELIVERED", label: "Delivered" },
+];
+
+export const shipmentStatusFilters: Array<{ value: "ALL" | ShipmentStatus; label: string }> = [
+  { value: "ALL", label: "All statuses" },
+  ...shipmentStatusOptions,
+];
+
+export const shipmentStatusPalette: Record<ShipmentStatus, string> = {
+  DRAFT: "border border-sky-400/30 bg-sky-500/12 text-sky-700 dark:text-sky-300",
+  PICKING: "border border-amber-400/30 bg-amber-500/12 text-amber-700 dark:text-amber-300",
+  PACKED: "border border-violet-400/30 bg-violet-500/12 text-violet-700 dark:text-violet-300",
+  SHIPPED: "border border-brand/30 bg-brand/10 text-brand",
+  DELIVERED: "border border-emerald-400/30 bg-emerald-500/12 text-emerald-700 dark:text-emerald-300",
+};
+
+export const emptyShipmentInput: ShipmentInput = {
+  salesOrderId: "",
+  status: "DRAFT",
+  shipDate: null,
+  carrier: "",
+  serviceLevel: "",
+  trackingNumber: "",
+  packageCount: 1,
+  notes: "",
+};