POs

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: "/purchasing/orders", label: "Purchase 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 {
+  PurchaseOrderDetailDto,
+  PurchaseOrderInput,
+  PurchaseOrderStatus,
+  PurchaseOrderSummaryDto,
+  PurchaseVendorOptionDto,
+} from "@mrp/shared";
 import type {
   ShipmentDetailDto,
   ShipmentInput,
@@ -379,6 +386,9 @@ export const api = {
   getSalesCustomers(token: string) {
     return request<SalesCustomerOptionDto[]>("/api/v1/sales/customers/options", undefined, token);
   },
+  getPurchaseVendors(token: string) {
+    return request<PurchaseVendorOptionDto[]>("/api/v1/purchasing/vendors/options", undefined, token);
+  },
   getQuotes(token: string, filters?: { q?: string; status?: SalesDocumentStatus }) {
     return request<SalesDocumentSummaryDto[]>(
       `/api/v1/sales/quotes${buildQueryString({
@@ -434,6 +444,32 @@ export const api = {
       token
     );
   },
+  getPurchaseOrders(token: string, filters?: { q?: string; status?: PurchaseOrderStatus }) {
+    return request<PurchaseOrderSummaryDto[]>(
+      `/api/v1/purchasing/orders${buildQueryString({
+        q: filters?.q,
+        status: filters?.status,
+      })}`,
+      undefined,
+      token
+    );
+  },
+  getPurchaseOrder(token: string, orderId: string) {
+    return request<PurchaseOrderDetailDto>(`/api/v1/purchasing/orders/${orderId}`, undefined, token);
+  },
+  createPurchaseOrder(token: string, payload: PurchaseOrderInput) {
+    return request<PurchaseOrderDetailDto>("/api/v1/purchasing/orders", { method: "POST", body: JSON.stringify(payload) }, token);
+  },
+  updatePurchaseOrder(token: string, orderId: string, payload: PurchaseOrderInput) {
+    return request<PurchaseOrderDetailDto>(`/api/v1/purchasing/orders/${orderId}`, { method: "PUT", body: JSON.stringify(payload) }, token);
+  },
+  updatePurchaseOrderStatus(token: string, orderId: string, status: PurchaseOrderStatus) {
+    return request<PurchaseOrderDetailDto>(
+      `/api/v1/purchasing/orders/${orderId}/status`,
+      { method: "PATCH", body: JSON.stringify({ status }) },
+      token
+    );
+  },
   getShipmentOrderOptions(token: string) {
     return request<ShipmentOrderOptionDto[]>("/api/v1/shipping/orders/options", undefined, token);
   },

client/src/main.tsx

@@ -18,6 +18,10 @@ import { GanttPage } from "./modules/gantt/GanttPage";
 import { InventoryDetailPage } from "./modules/inventory/InventoryDetailPage";
 import { InventoryFormPage } from "./modules/inventory/InventoryFormPage";
 import { InventoryItemsPage } from "./modules/inventory/InventoryItemsPage";
+import { PurchaseDetailPage } from "./modules/purchasing/PurchaseDetailPage";
+import { PurchaseFormPage } from "./modules/purchasing/PurchaseFormPage";
+import { PurchaseListPage } from "./modules/purchasing/PurchaseListPage";
+import { PurchaseOrdersPage } from "./modules/purchasing/PurchaseOrdersPage";
 import { WarehouseDetailPage } from "./modules/inventory/WarehouseDetailPage";
 import { WarehouseFormPage } from "./modules/inventory/WarehouseFormPage";
 import { WarehousesPage } from "./modules/inventory/WarehousesPage";
@@ -63,6 +67,13 @@ const router = createBrowserRouter([
               { path: "/inventory/warehouses/:warehouseId", element: <WarehouseDetailPage /> },
             ],
           },
+          {
+            element: <ProtectedRoute requiredPermissions={["purchasing.read"]} />,
+            children: [
+              { path: "/purchasing/orders", element: <PurchaseOrdersPage /> },
+              { path: "/purchasing/orders/:orderId", element: <PurchaseDetailPage /> },
+            ],
+          },
           {
             element: <ProtectedRoute requiredPermissions={[permissions.salesRead]} />,
             children: [
@@ -88,6 +99,13 @@ const router = createBrowserRouter([
               { path: "/crm/vendors/:vendorId/edit", element: <CrmFormPage entity="vendor" mode="edit" /> },
             ],
           },
+          {
+            element: <ProtectedRoute requiredPermissions={["purchasing.write"]} />,
+            children: [
+              { path: "/purchasing/orders/new", element: <PurchaseFormPage mode="create" /> },
+              { path: "/purchasing/orders/:orderId/edit", element: <PurchaseFormPage mode="edit" /> },
+            ],
+          },
           {
             element: <ProtectedRoute requiredPermissions={[permissions.salesWrite]} />,
             children: [

client/src/modules/purchasing/PurchaseDetailPage.tsx

@@ -0,0 +1,157 @@
+import { permissions } from "@mrp/shared";
+import type { PurchaseOrderDetailDto, PurchaseOrderStatus } from "@mrp/shared";
+import { useEffect, useState } from "react";
+import { Link, useParams } from "react-router-dom";
+
+import { useAuth } from "../../auth/AuthProvider";
+import { api, ApiError } from "../../lib/api";
+import { purchaseStatusOptions } from "./config";
+import { PurchaseStatusBadge } from "./PurchaseStatusBadge";
+
+export function PurchaseDetailPage() {
+  const { token, user } = useAuth();
+  const { orderId } = useParams();
+  const [document, setDocument] = useState<PurchaseOrderDetailDto | null>(null);
+  const [status, setStatus] = useState("Loading purchase order...");
+  const [isUpdatingStatus, setIsUpdatingStatus] = useState(false);
+
+  const canManage = user?.permissions.includes("purchasing.write") ?? false;
+
+  useEffect(() => {
+    if (!token || !orderId) {
+      return;
+    }
+
+    api.getPurchaseOrder(token, orderId)
+      .then((nextDocument) => {
+        setDocument(nextDocument);
+        setStatus("Purchase order loaded.");
+      })
+      .catch((error: unknown) => {
+        const message = error instanceof ApiError ? error.message : "Unable to load purchase order.";
+        setStatus(message);
+      });
+  }, [orderId, 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>;
+  }
+
+  const activeDocument = document;
+
+  async function handleStatusChange(nextStatus: PurchaseOrderStatus) {
+    if (!token) {
+      return;
+    }
+
+    setIsUpdatingStatus(true);
+    setStatus("Updating purchase order status...");
+
+    try {
+      const nextDocument = await api.updatePurchaseOrderStatus(token, activeDocument.id, nextStatus);
+      setDocument(nextDocument);
+      setStatus("Purchase order status updated.");
+    } catch (error: unknown) {
+      const message = error instanceof ApiError ? error.message : "Unable to update purchase order status.";
+      setStatus(message);
+    } finally {
+      setIsUpdatingStatus(false);
+    }
+  }
+
+  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">Purchase Order</p>
+            <h3 className="mt-2 text-xl font-bold text-text">{activeDocument.documentNumber}</h3>
+            <p className="mt-1 text-sm text-text">{activeDocument.vendorName}</p>
+            <div className="mt-3 flex flex-wrap gap-2">
+              <PurchaseStatusBadge status={activeDocument.status} />
+            </div>
+          </div>
+          <div className="flex flex-wrap gap-3">
+            <Link to="/purchasing/orders" 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 purchase orders
+            </Link>
+            {canManage ? (
+              <Link to={`/purchasing/orders/${activeDocument.id}/edit`} className="inline-flex items-center justify-center rounded-2xl bg-brand px-2 py-2 text-sm font-semibold text-white">
+                Edit purchase order
+              </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 purchase-order status without opening the full editor.</p>
+            </div>
+            <div className="flex flex-wrap gap-2">
+              {purchaseStatusOptions.map((option) => (
+                <button key={option.value} type="button" onClick={() => handleStatusChange(option.value)} disabled={isUpdatingStatus || activeDocument.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">Issue Date</p><div className="mt-2 text-base font-bold text-text">{new Date(activeDocument.issueDate).toLocaleDateString()}</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">Lines</p><div className="mt-2 text-base font-bold text-text">{activeDocument.lineCount}</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">Subtotal</p><div className="mt-2 text-base font-bold text-text">${activeDocument.subtotal.toFixed(2)}</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">Total</p><div className="mt-2 text-base font-bold text-text">${activeDocument.total.toFixed(2)}</div></article>
+      </section>
+      <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">Tax</p><div className="mt-2 text-base font-bold text-text">${activeDocument.taxAmount.toFixed(2)}</div><div className="mt-1 text-xs text-muted">{activeDocument.taxPercent.toFixed(2)}%</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">Freight</p><div className="mt-2 text-base font-bold text-text">${activeDocument.freightAmount.toFixed(2)}</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">Payment Terms</p><div className="mt-2 text-base font-bold text-text">{activeDocument.paymentTerms || "N/A"}</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">Currency</p><div className="mt-2 text-base font-bold text-text">{activeDocument.currencyCode || "USD"}</div></article>
+      </section>
+      <div className="grid gap-3 xl:grid-cols-[minmax(0,1.05fr)_minmax(320px,0.95fr)]">
+        <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">Vendor</p>
+          <dl className="mt-5 grid gap-3">
+            <div><dt className="text-xs font-semibold uppercase tracking-[0.18em] text-muted">Account</dt><dd className="mt-1 text-sm text-text">{activeDocument.vendorName}</dd></div>
+            <div><dt className="text-xs font-semibold uppercase tracking-[0.18em] text-muted">Email</dt><dd className="mt-1 text-sm text-text">{activeDocument.vendorEmail}</dd></div>
+          </dl>
+        </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">Notes</p>
+          <p className="mt-3 whitespace-pre-line text-sm leading-6 text-text">{activeDocument.notes || "No notes recorded for this document."}</p>
+        </article>
+      </div>
+      <section 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">Line Items</p>
+        {activeDocument.lines.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 line items 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">Item</th><th className="px-2 py-2">Description</th><th className="px-2 py-2">Qty</th><th className="px-2 py-2">UOM</th><th className="px-2 py-2">Unit Cost</th><th className="px-2 py-2">Total</th></tr>
+              </thead>
+              <tbody className="divide-y divide-line/70 bg-surface">
+                {activeDocument.lines.map((line: PurchaseOrderDetailDto["lines"][number]) => (
+                  <tr key={line.id}>
+                    <td className="px-2 py-2"><div className="font-semibold text-text">{line.itemSku}</div><div className="mt-1 text-xs text-muted">{line.itemName}</div></td>
+                    <td className="px-2 py-2 text-muted">{line.description}</td>
+                    <td className="px-2 py-2 text-muted">{line.quantity}</td>
+                    <td className="px-2 py-2 text-muted">{line.unitOfMeasure}</td>
+                    <td className="px-2 py-2 text-muted">${line.unitCost.toFixed(2)}</td>
+                    <td className="px-2 py-2 text-muted">${line.lineTotal.toFixed(2)}</td>
+                  </tr>
+                ))}
+              </tbody>
+            </table>
+          </div>
+        )}
+      </section>
+      <div className="rounded-2xl border border-line/70 bg-page/60 px-2 py-2 text-sm text-muted">{status}</div>
+    </section>
+  );
+}

client/src/modules/purchasing/PurchaseFormPage.tsx

@@ -0,0 +1,356 @@
+import type { InventoryItemOptionDto } from "@mrp/shared/dist/inventory/types.js";
+import type { PurchaseLineInput, PurchaseOrderInput, PurchaseVendorOptionDto } from "@mrp/shared";
+import { useEffect, useState } from "react";
+import { Link, useNavigate, useParams } from "react-router-dom";
+
+import { useAuth } from "../../auth/AuthProvider";
+import { api, ApiError } from "../../lib/api";
+import { inventoryUnitOptions } from "../inventory/config";
+import { emptyPurchaseOrderInput, purchaseStatusOptions } from "./config";
+
+export function PurchaseFormPage({ mode }: { mode: "create" | "edit" }) {
+  const { token } = useAuth();
+  const navigate = useNavigate();
+  const { orderId } = useParams();
+  const [form, setForm] = useState<PurchaseOrderInput>(emptyPurchaseOrderInput);
+  const [status, setStatus] = useState(mode === "create" ? "Create a new purchase order." : "Loading purchase order...");
+  const [vendors, setVendors] = useState<PurchaseVendorOptionDto[]>([]);
+  const [vendorSearchTerm, setVendorSearchTerm] = useState("");
+  const [vendorPickerOpen, setVendorPickerOpen] = useState(false);
+  const [itemOptions, setItemOptions] = useState<InventoryItemOptionDto[]>([]);
+  const [lineSearchTerms, setLineSearchTerms] = useState<string[]>([]);
+  const [activeLinePicker, setActiveLinePicker] = useState<number | null>(null);
+  const [isSaving, setIsSaving] = useState(false);
+
+  const subtotal = form.lines.reduce((sum: number, line: PurchaseLineInput) => sum + line.quantity * line.unitCost, 0);
+  const taxAmount = subtotal * (form.taxPercent / 100);
+  const total = subtotal + taxAmount + form.freightAmount;
+
+  useEffect(() => {
+    if (!token) {
+      return;
+    }
+
+    api.getPurchaseVendors(token).then(setVendors).catch(() => setVendors([]));
+    api.getInventoryItemOptions(token).then(setItemOptions).catch(() => setItemOptions([]));
+  }, [token]);
+
+  useEffect(() => {
+    if (!token || mode !== "edit" || !orderId) {
+      return;
+    }
+
+    api.getPurchaseOrder(token, orderId)
+      .then((document) => {
+        setForm({
+          vendorId: document.vendorId,
+          status: document.status,
+          issueDate: document.issueDate,
+          taxPercent: document.taxPercent,
+          freightAmount: document.freightAmount,
+          notes: document.notes,
+          lines: document.lines.map((line: { itemId: string; description: string; quantity: number; unitOfMeasure: PurchaseLineInput["unitOfMeasure"]; unitCost: number; position: number }) => ({
+            itemId: line.itemId,
+            description: line.description,
+            quantity: line.quantity,
+            unitOfMeasure: line.unitOfMeasure,
+            unitCost: line.unitCost,
+            position: line.position,
+          })),
+        });
+        setVendorSearchTerm(document.vendorName);
+        setLineSearchTerms(document.lines.map((line: { itemSku: string }) => line.itemSku));
+        setStatus("Purchase order loaded.");
+      })
+      .catch((error: unknown) => {
+        const message = error instanceof ApiError ? error.message : "Unable to load purchase order.";
+        setStatus(message);
+      });
+  }, [mode, orderId, token]);
+
+  function updateField<Key extends keyof PurchaseOrderInput>(key: Key, value: PurchaseOrderInput[Key]) {
+    setForm((current: PurchaseOrderInput) => ({ ...current, [key]: value }));
+  }
+
+  function getSelectedVendorName(vendorId: string) {
+    return vendors.find((vendor) => vendor.id === vendorId)?.name ?? "";
+  }
+
+  function getSelectedVendor(vendorId: string) {
+    return vendors.find((vendor) => vendor.id === vendorId) ?? null;
+  }
+
+  function updateLine(index: number, nextLine: PurchaseLineInput) {
+    setForm((current: PurchaseOrderInput) => ({
+      ...current,
+      lines: current.lines.map((line: PurchaseLineInput, lineIndex: number) => (lineIndex === index ? nextLine : line)),
+    }));
+  }
+
+  function updateLineSearchTerm(index: number, value: string) {
+    setLineSearchTerms((current) => {
+      const next = [...current];
+      next[index] = value;
+      return next;
+    });
+  }
+
+  function addLine() {
+    setForm((current: PurchaseOrderInput) => ({
+      ...current,
+      lines: [
+        ...current.lines,
+        {
+          itemId: "",
+          description: "",
+          quantity: 1,
+          unitOfMeasure: "EA",
+          unitCost: 0,
+          position: current.lines.length === 0 ? 10 : Math.max(...current.lines.map((line: PurchaseLineInput) => line.position)) + 10,
+        },
+      ],
+    }));
+    setLineSearchTerms((current) => [...current, ""]);
+  }
+
+  function removeLine(index: number) {
+    setForm((current: PurchaseOrderInput) => ({
+      ...current,
+      lines: current.lines.filter((_line: PurchaseLineInput, lineIndex: number) => lineIndex !== index),
+    }));
+    setLineSearchTerms((current) => current.filter((_term, termIndex) => termIndex !== index));
+  }
+
+  async function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    if (!token) {
+      return;
+    }
+
+    setIsSaving(true);
+    setStatus("Saving purchase order...");
+
+    try {
+      const saved = mode === "create" ? await api.createPurchaseOrder(token, form) : await api.updatePurchaseOrder(token, orderId ?? "", form);
+      navigate(`/purchasing/orders/${saved.id}`);
+    } catch (error: unknown) {
+      const message = error instanceof ApiError ? error.message : "Unable to save purchase order.";
+      setStatus(message);
+      setIsSaving(false);
+    }
+  }
+
+  const filteredVendorCount = vendors.filter((vendor) => {
+    const query = vendorSearchTerm.trim().toLowerCase();
+    if (!query) {
+      return true;
+    }
+
+    return vendor.name.toLowerCase().includes(query) || vendor.email.toLowerCase().includes(query);
+  }).length;
+
+  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">Purchasing Editor</p>
+            <h3 className="mt-2 text-xl font-bold text-text">{mode === "create" ? "New Purchase Order" : "Edit Purchase Order"}</h3>
+          </div>
+          <Link to={mode === "create" ? "/purchasing/orders" : `/purchasing/orders/${orderId}`} 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">
+        <div className="grid gap-3 xl:grid-cols-4">
+          <label className="block xl:col-span-2">
+            <span className="mb-2 block text-sm font-semibold text-text">Vendor</span>
+            <div className="relative">
+              <input
+                value={vendorSearchTerm}
+                onChange={(event) => {
+                  setVendorSearchTerm(event.target.value);
+                  updateField("vendorId", "");
+                  setVendorPickerOpen(true);
+                }}
+                onFocus={() => setVendorPickerOpen(true)}
+                onBlur={() => {
+                  window.setTimeout(() => {
+                    setVendorPickerOpen(false);
+                    if (form.vendorId) {
+                      setVendorSearchTerm(getSelectedVendorName(form.vendorId));
+                    }
+                  }, 120);
+                }}
+                placeholder="Search vendor"
+                className="w-full rounded-2xl border border-line/70 bg-page px-2 py-2 text-text outline-none transition focus:border-brand"
+              />
+              {vendorPickerOpen ? (
+                <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">
+                  {vendors
+                    .filter((vendor) => {
+                      const query = vendorSearchTerm.trim().toLowerCase();
+                      if (!query) {
+                        return true;
+                      }
+
+                      return vendor.name.toLowerCase().includes(query) || vendor.email.toLowerCase().includes(query);
+                    })
+                    .slice(0, 12)
+                    .map((vendor) => (
+                      <button
+                        key={vendor.id}
+                        type="button"
+                        onMouseDown={(event) => {
+                          event.preventDefault();
+                          updateField("vendorId", vendor.id);
+                          setVendorSearchTerm(vendor.name);
+                          setVendorPickerOpen(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">{vendor.name}</div>
+                        <div className="mt-1 text-xs text-muted">{vendor.email}</div>
+                      </button>
+                    ))}
+                  {filteredVendorCount === 0 ? <div className="px-2 py-2 text-sm text-muted">No matching vendors found.</div> : null}
+                </div>
+              ) : null}
+            </div>
+            <div className="mt-2 min-h-5 text-xs text-muted">{form.vendorId ? getSelectedVendorName(form.vendorId) : "No vendor selected"}</div>
+            {form.vendorId ? (
+              <div className="mt-1 text-xs text-muted">
+                Terms: {getSelectedVendor(form.vendorId)?.paymentTerms || "N/A"} | Currency: {getSelectedVendor(form.vendorId)?.currencyCode || "USD"}
+              </div>
+            ) : null}
+          </label>
+          <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 PurchaseOrderInput["status"])} className="w-full rounded-2xl border border-line/70 bg-page px-2 py-2 text-text outline-none transition focus:border-brand">
+              {purchaseStatusOptions.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">Issue date</span>
+            <input type="date" value={form.issueDate.slice(0, 10)} onChange={(event) => updateField("issueDate", new Date(event.target.value).toISOString())} 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={3} 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="grid gap-3 xl:grid-cols-2">
+          <label className="block">
+            <span className="mb-2 block text-sm font-semibold text-text">Tax %</span>
+            <input type="number" min={0} max={100} step={0.01} value={form.taxPercent} onChange={(event) => updateField("taxPercent", Number(event.target.value) || 0)} 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">Freight</span>
+            <input type="number" min={0} step={0.01} value={form.freightAmount} onChange={(event) => updateField("freightAmount", Number(event.target.value) || 0)} 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>
+      </section>
+      <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">Line Items</p>
+            <h4 className="mt-2 text-lg font-bold text-text">Procurement lines</h4>
+          </div>
+          <button type="button" onClick={addLine} className="inline-flex items-center justify-center rounded-2xl border border-line/70 px-2 py-2 text-sm font-semibold text-text">Add line</button>
+        </div>
+        {form.lines.length === 0 ? (
+          <div className="mt-5 rounded-3xl border border-dashed border-line/70 bg-page/60 px-4 py-8 text-center text-sm text-muted">No line items added yet.</div>
+        ) : (
+          <div className="mt-5 space-y-4">
+            {form.lines.map((line: PurchaseLineInput, index: number) => (
+              <div key={index} className="rounded-3xl border border-line/70 bg-page/60 p-3">
+                <div className="grid gap-3 xl:grid-cols-[1.15fr_1.25fr_0.5fr_0.55fr_0.7fr_0.75fr_auto]">
+                  <label className="block">
+                    <span className="mb-2 block text-xs font-semibold uppercase tracking-[0.16em] text-muted">SKU</span>
+                    <div className="relative">
+                      <input
+                        value={lineSearchTerms[index] ?? ""}
+                        onChange={(event) => {
+                          updateLineSearchTerm(index, event.target.value);
+                          updateLine(index, { ...line, itemId: "" });
+                          setActiveLinePicker(index);
+                        }}
+                        onFocus={() => setActiveLinePicker(index)}
+                        onBlur={() => window.setTimeout(() => setActiveLinePicker((current) => (current === index ? null : current)), 120)}
+                        placeholder="Search by SKU"
+                        className="w-full rounded-2xl border border-line/70 bg-surface px-2 py-2 text-text outline-none transition focus:border-brand"
+                      />
+                      {activeLinePicker === index ? (
+                        <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">
+                          {itemOptions
+                            .filter((option) => option.sku.toLowerCase().includes((lineSearchTerms[index] ?? "").trim().toLowerCase()))
+                            .slice(0, 12)
+                            .map((option) => (
+                              <button
+                                key={option.id}
+                                type="button"
+                                onMouseDown={(event) => {
+                                  event.preventDefault();
+                                  updateLine(index, {
+                                    ...line,
+                                    itemId: option.id,
+                                    description: line.description || option.name,
+                                  });
+                                  updateLineSearchTerm(index, option.sku);
+                                  setActiveLinePicker(null);
+                                }}
+                                className="block w-full border-b border-line/50 px-2 py-2 text-left text-sm font-semibold text-text transition last:border-b-0 hover:bg-page/70"
+                              >
+                                {option.sku}
+                              </button>
+                            ))}
+                        </div>
+                      ) : null}
+                    </div>
+                  </label>
+                  <label className="block">
+                    <span className="mb-2 block text-xs font-semibold uppercase tracking-[0.16em] text-muted">Description</span>
+                    <input value={line.description} onChange={(event) => updateLine(index, { ...line, description: event.target.value })} 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">Qty</span>
+                    <input type="number" min={1} step={1} value={line.quantity} onChange={(event) => updateLine(index, { ...line, quantity: Number.parseInt(event.target.value, 10) || 0 })} 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">UOM</span>
+                    <select value={line.unitOfMeasure} onChange={(event) => updateLine(index, { ...line, unitOfMeasure: event.target.value as PurchaseLineInput["unitOfMeasure"] })} className="w-full rounded-2xl border border-line/70 bg-surface px-2 py-2 text-text outline-none transition focus:border-brand">
+                      {inventoryUnitOptions.map((option) => (
+                        <option key={option.value} value={option.value}>{option.label}</option>
+                      ))}
+                    </select>
+                  </label>
+                  <label className="block">
+                    <span className="mb-2 block text-xs font-semibold uppercase tracking-[0.16em] text-muted">Unit Cost</span>
+                    <input type="number" min={0} step={0.01} value={line.unitCost} onChange={(event) => updateLine(index, { ...line, unitCost: Number(event.target.value) })} className="w-full rounded-2xl border border-line/70 bg-surface px-2 py-2 text-text outline-none transition focus:border-brand" />
+                  </label>
+                  <div className="flex items-end"><div className="w-full rounded-2xl border border-line/70 bg-surface px-2 py-2 text-sm text-text">${(line.quantity * line.unitCost).toFixed(2)}</div></div>
+                  <div className="flex items-end"><button type="button" onClick={() => removeLine(index)} className="rounded-2xl border border-rose-400/40 px-2 py-2 text-sm font-semibold text-rose-700 dark:text-rose-300">Remove</button></div>
+                </div>
+              </div>
+            ))}
+          </div>
+        )}
+        <div className="mt-5 grid gap-3 md:grid-cols-3 xl:grid-cols-4">
+          <div className="rounded-2xl border border-line/70 bg-page/60 px-2 py-2 text-sm"><div className="text-xs font-semibold uppercase tracking-[0.16em] text-muted">Subtotal</div><div className="mt-1 font-semibold text-text">${subtotal.toFixed(2)}</div></div>
+          <div className="rounded-2xl border border-line/70 bg-page/60 px-2 py-2 text-sm"><div className="text-xs font-semibold uppercase tracking-[0.16em] text-muted">Tax</div><div className="mt-1 font-semibold text-text">${taxAmount.toFixed(2)}</div></div>
+          <div className="rounded-2xl border border-line/70 bg-page/60 px-2 py-2 text-sm"><div className="text-xs font-semibold uppercase tracking-[0.16em] text-muted">Freight</div><div className="mt-1 font-semibold text-text">${form.freightAmount.toFixed(2)}</div></div>
+          <div className="rounded-2xl border border-line/70 bg-page/60 px-2 py-2 text-sm"><div className="text-xs font-semibold uppercase tracking-[0.16em] text-muted">Total</div><div className="mt-1 font-semibold text-text">${total.toFixed(2)}</div></div>
+        </div>
+        <div className="mt-6 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 purchase order" : "Save changes"}
+          </button>
+        </div>
+      </section>
+    </form>
+  );
+}

client/src/modules/purchasing/PurchaseListPage.tsx

@@ -0,0 +1,99 @@
+import { permissions } from "@mrp/shared";
+import type { PurchaseOrderStatus, PurchaseOrderSummaryDto } from "@mrp/shared";
+import { useEffect, useState } from "react";
+import { Link } from "react-router-dom";
+
+import { useAuth } from "../../auth/AuthProvider";
+import { api, ApiError } from "../../lib/api";
+import { purchaseStatusFilters } from "./config";
+import { PurchaseStatusBadge } from "./PurchaseStatusBadge";
+
+export function PurchaseListPage() {
+  const { token, user } = useAuth();
+  const [documents, setDocuments] = useState<PurchaseOrderSummaryDto[]>([]);
+  const [searchTerm, setSearchTerm] = useState("");
+  const [statusFilter, setStatusFilter] = useState<"ALL" | PurchaseOrderStatus>("ALL");
+  const [status, setStatus] = useState("Loading purchase orders...");
+
+  const canManage = user?.permissions.includes("purchasing.write") ?? false;
+
+  useEffect(() => {
+    if (!token) {
+      return;
+    }
+
+    api.getPurchaseOrders(token, { q: searchTerm.trim() || undefined, status: statusFilter === "ALL" ? undefined : statusFilter })
+      .then((nextDocuments) => {
+        setDocuments(nextDocuments);
+        setStatus(`${nextDocuments.length} purchase orders matched the current filters.`);
+      })
+      .catch((error: unknown) => {
+        const message = error instanceof ApiError ? error.message : "Unable to load purchase orders.";
+        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">Purchasing</p>
+          <h3 className="mt-2 text-lg font-bold text-text">Purchase Orders</h3>
+          <p className="mt-2 max-w-2xl text-sm text-muted">Vendor-facing procurement documents for material replenishment and bought-in components.</p>
+        </div>
+        {canManage ? (
+          <Link to="/purchasing/orders/new" className="inline-flex items-center justify-center rounded-2xl bg-brand px-3 py-2 text-sm font-semibold text-white">
+            New purchase order
+          </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 purchase orders by document number or vendor" 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" | PurchaseOrderStatus)} className="w-full rounded-2xl border border-line/70 bg-surface px-2 py-2 text-text outline-none transition focus:border-brand">
+            {purchaseStatusFilters.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>
+      {documents.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 purchase orders 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">Document</th>
+                <th className="px-2 py-2">Vendor</th>
+                <th className="px-2 py-2">Status</th>
+                <th className="px-2 py-2">Issue Date</th>
+                <th className="px-2 py-2">Value</th>
+                <th className="px-2 py-2">Lines</th>
+              </tr>
+            </thead>
+            <tbody className="divide-y divide-line/70 bg-surface">
+              {documents.map((document) => (
+                <tr key={document.id} className="transition hover:bg-page/70">
+                  <td className="px-2 py-2"><Link to={`/purchasing/orders/${document.id}`} className="font-semibold text-text hover:text-brand">{document.documentNumber}</Link></td>
+                  <td className="px-2 py-2 text-muted">{document.vendorName}</td>
+                  <td className="px-2 py-2"><PurchaseStatusBadge status={document.status} /></td>
+                  <td className="px-2 py-2 text-muted">{new Date(document.issueDate).toLocaleDateString()}</td>
+                  <td className="px-2 py-2 text-muted">${document.total.toFixed(2)}</td>
+                  <td className="px-2 py-2 text-muted">{document.lineCount}</td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      )}
+    </section>
+  );
+}

client/src/modules/purchasing/PurchaseOrdersPage.tsx

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

client/src/modules/purchasing/PurchaseStatusBadge.tsx

@@ -0,0 +1,7 @@
+import type { PurchaseOrderStatus } from "@mrp/shared";
+
+import { purchaseStatusPalette } from "./config";
+
+export function PurchaseStatusBadge({ status }: { status: PurchaseOrderStatus }) {
+  return <span className={`inline-flex rounded-full px-2 py-1 text-xs font-semibold ${purchaseStatusPalette[status]}`}>{status.replace("_", " ")}</span>;
+}

client/src/modules/purchasing/config.ts

@@ -0,0 +1,30 @@
+import type { PurchaseOrderInput, PurchaseOrderStatus } from "@mrp/shared";
+
+export const purchaseStatusOptions: Array<{ value: PurchaseOrderStatus; label: string }> = [
+  { value: "DRAFT", label: "Draft" },
+  { value: "ISSUED", label: "Issued" },
+  { value: "APPROVED", label: "Approved" },
+  { value: "CLOSED", label: "Closed" },
+];
+
+export const purchaseStatusFilters: Array<{ value: "ALL" | PurchaseOrderStatus; label: string }> = [
+  { value: "ALL", label: "All statuses" },
+  ...purchaseStatusOptions,
+];
+
+export const purchaseStatusPalette: Record<PurchaseOrderStatus, string> = {
+  DRAFT: "border border-sky-400/30 bg-sky-500/12 text-sky-700 dark:text-sky-300",
+  ISSUED: "border border-amber-400/30 bg-amber-500/12 text-amber-700 dark:text-amber-300",
+  APPROVED: "border border-emerald-400/30 bg-emerald-500/12 text-emerald-700 dark:text-emerald-300",
+  CLOSED: "border border-slate-400/30 bg-slate-500/12 text-slate-700 dark:text-slate-300",
+};
+
+export const emptyPurchaseOrderInput: PurchaseOrderInput = {
+  vendorId: "",
+  status: "DRAFT",
+  issueDate: new Date().toISOString(),
+  taxPercent: 0,
+  freightAmount: 0,
+  notes: "",
+  lines: [],
+};