Merge pull request #214 from Sea-Haven-Industries/feat/ab/sh-325-add-team-member

SH-325: add team member form

e2e/work-orders/work-orders.visual.spec.ts

@@ -204,6 +204,12 @@ async function openWorkOrderPage(page: Page, mode: "default" | "empty" | "error"
   });
 }
 
+async function expectWorkOrderPageReady(page: Page) {
+  await expect(page.getByRole("heading", { name: "Work Orders" })).toBeVisible({
+    timeout: 90_000,
+  });
+}
+
 async function expectStableScreenshot(page: Page, name: string) {
   await page.waitForTimeout(250);
   await page.evaluate(
@@ -217,15 +223,18 @@ async function expectStableScreenshot(page: Page, name: string) {
 }
 
 test.describe("Work Orders deterministic pixel regression", () => {
+  test.setTimeout(120_000);
+
   test("list", async ({ page }) => {
     await openWorkOrderPage(page);
-    await expect(page.getByRole("heading", { name: "Work Orders" })).toBeVisible();
+    await expectWorkOrderPageReady(page);
     await expect(page.getByText("WO-501").first()).toBeVisible();
     await expectStableScreenshot(page, "wo-list.png");
   });
 
   test("filters", async ({ page }) => {
     await openWorkOrderPage(page);
+    await expectWorkOrderPageReady(page);
     await page.getByRole("button", { name: "Advanced Filters" }).click();
     await expect(page.getByRole("dialog", { name: "Advanced Filters" })).toBeVisible();
     await expectStableScreenshot(page, "wo-filters.png");
@@ -233,6 +242,7 @@ test.describe("Work Orders deterministic pixel regression", () => {
 
   test("new", async ({ page }) => {
     await openWorkOrderPage(page);
+    await expectWorkOrderPageReady(page);
     await page.getByRole("button", { name: "New WO" }).click();
     await expect(page.getByRole("heading", { name: "Type & schedule" })).toBeVisible();
     await expectStableScreenshot(page, "wo-new.png");
@@ -240,6 +250,7 @@ test.describe("Work Orders deterministic pixel regression", () => {
 
   test("detail", async ({ page }) => {
     await openWorkOrderPage(page);
+    await expectWorkOrderPageReady(page);
     const row = page.locator("#wo-row-1");
     await row.hover();
     await row.getByRole("button", { name: "View details" }).click();
@@ -249,7 +260,7 @@ test.describe("Work Orders deterministic pixel regression", () => {
 
   test("empty", async ({ page }) => {
     await openWorkOrderPage(page, "empty");
-    await expect(page.getByRole("heading", { name: "Work Orders" })).toBeVisible();
+    await expectWorkOrderPageReady(page);
     await page.getByLabel("Search work orders").fill("zz");
     await expect(page.getByText("No work orders match your search")).toBeVisible();
     await expectStableScreenshot(page, "wo-empty.png");
@@ -257,7 +268,7 @@ test.describe("Work Orders deterministic pixel regression", () => {
 
   test("error", async ({ page }) => {
     await openWorkOrderPage(page, "error");
-    await expect(page.getByRole("heading", { name: "Work Orders" })).toBeVisible();
+    await expectWorkOrderPageReady(page);
     const alert = page.getByRole("main").getByRole("alert");
     await expect(alert).toBeVisible();
     await expect(alert).toContainText(/server error/i);
@@ -267,6 +278,7 @@ test.describe("Work Orders deterministic pixel regression", () => {
   test("mobile", async ({ page }) => {
     await page.setViewportSize({ width: 390, height: 844 });
     await openWorkOrderPage(page);
+    await expectWorkOrderPageReady(page);
     await expect(page.getByText("WO-501").first()).toBeVisible();
     await expectStableScreenshot(page, "wo-mobile.png");
 

src/api/api-paths.ts

@@ -77,6 +77,10 @@ export const API_PATHS = {
     deleteEmployees: "Employee/DeleteEmployees",
     dropdown: "Employee/Dropdown",
   },
+  teamMember: {
+    getList: "User",
+    create: "team-members",
+  },
   contact: {
     getList: "Contact/GetContactList",
     getContacts: "Contact/GetContacts",

src/app/(protected)/team-members/_components/add-team-member-dialog.tsx

@@ -0,0 +1,473 @@
+import { useEffect, useMemo, useRef, useState, type Dispatch, type SetStateAction } from "react";
+import {
+  Accordion,
+  AccordionDetails,
+  AccordionSummary,
+  Alert,
+  Box,
+  Button,
+  Checkbox,
+  CircularProgress,
+  Dialog,
+  DialogActions,
+  DialogContent,
+  DialogTitle,
+  FormControl,
+  FormControlLabel,
+  FormHelperText,
+  InputLabel,
+  MenuItem,
+  Select,
+  Stack,
+  TextField,
+  Typography,
+} from "@mui/material";
+import ExpandMoreIcon from "@mui/icons-material/ExpandMore";
+import { AREA_ZONES } from "@/data/areas";
+import { useCreateTeamMember } from "@/domain/team-members/use-cases/use-create-team-member";
+import type {
+  CreateTeamMemberInput,
+  TeamMemberRole,
+} from "@/domain/team-members/types/team-member";
+
+const ROLES: TeamMemberRole[] = ["Dispatcher", "Scheduler", "Admin"];
+const COLORS = [
+  "#F59E0B",
+  "#0D9488",
+  "#6366F1",
+  "#F43F5E",
+  "#7C3AED",
+  "#0EA5E9",
+  "#16A34A",
+  "#EA580C",
+  "#0891B2",
+  "#C026D3",
+] as const;
+
+const PERMISSION_GROUPS = [
+  {
+    label: "Team Members",
+    keys: ["manageTeamMembers", "changeTeamMemberRole"],
+  },
+  {
+    label: "Vendors",
+    keys: ["createVendors", "editVendors", "deactivateVendors"],
+  },
+  {
+    label: "Sites",
+    keys: ["createSites", "editSites", "deleteSites"],
+  },
+  {
+    label: "Services",
+    keys: ["createServices", "editServices", "deactivateServices"],
+  },
+  {
+    label: "Completion Document Templates",
+    keys: [
+      "createCompletionDocTemplates",
+      "editCompletionDocTemplates",
+      "deleteCompletionDocTemplates",
+    ],
+  },
+  {
+    label: "Work Orders",
+    keys: ["createWorkOrders", "editOthersWorkOrders", "cancelWorkOrders", "deleteWorkOrders"],
+  },
+  {
+    label: "Uplifts",
+    keys: ["requestUplifts", "autoApproveUplifts", "reviewUplifts"],
+  },
+  {
+    label: "Dashboard",
+    keys: ["viewAllDispatchersOnDashboard"],
+  },
+] as const;
+
+const PERMISSION_LABELS: Record<string, string> = {
+  manageTeamMembers: "Manage team members",
+  changeTeamMemberRole: "Change team member role",
+  createVendors: "Create vendors",
+  editVendors: "Edit vendors",
+  deactivateVendors: "Deactivate vendors",
+  createSites: "Create sites",
+  editSites: "Edit sites",
+  deleteSites: "Delete sites",
+  createServices: "Create services",
+  editServices: "Edit services",
+  deactivateServices: "Deactivate services",
+  createCompletionDocTemplates: "Create completion document templates",
+  editCompletionDocTemplates: "Edit completion document templates",
+  deleteCompletionDocTemplates: "Delete completion document templates",
+  createWorkOrders: "Create work orders",
+  editOthersWorkOrders: "Edit other users' work orders",
+  cancelWorkOrders: "Cancel work orders",
+  deleteWorkOrders: "Delete work orders",
+  requestUplifts: "Request uplifts",
+  autoApproveUplifts: "Automatically approve uplifts",
+  reviewUplifts: "Review uplifts",
+  viewAllDispatchersOnDashboard: "View all Dispatchers on dashboard",
+};
+
+const ALL_PERMISSION_KEYS = PERMISSION_GROUPS.flatMap((group) => group.keys);
+const DISPATCHER_DEFAULTS = new Set([
+  "createVendors",
+  "editVendors",
+  "deactivateVendors",
+  "createSites",
+  "editSites",
+  "createWorkOrders",
+  "editOthersWorkOrders",
+  "cancelWorkOrders",
+  "requestUplifts",
+  "autoApproveUplifts",
+]);
+const SCHEDULER_DEFAULTS = new Set([
+  ...Array.from(DISPATCHER_DEFAULTS).filter(
+    (key) => key !== "requestUplifts" && key !== "autoApproveUplifts",
+  ),
+  "deleteSites",
+  "createServices",
+  "editServices",
+  "createCompletionDocTemplates",
+  "editCompletionDocTemplates",
+  "viewAllDispatchersOnDashboard",
+]);
+
+function defaultsForRole(role: TeamMemberRole): Set<string> {
+  if (role === "Admin") return new Set(ALL_PERMISSION_KEYS);
+  return role === "Scheduler" ? new Set(SCHEDULER_DEFAULTS) : new Set(DISPATCHER_DEFAULTS);
+}
+
+function emptyForm() {
+  return {
+    name: "",
+    role: "Dispatcher" as TeamMemberRole,
+    color: "",
+    email: "",
+    phone: "",
+    serviceAreas: [] as string[],
+    permissions: defaultsForRole("Dispatcher"),
+  };
+}
+
+function permissionOverrides(role: TeamMemberRole, selected: Set<string>) {
+  const defaults = defaultsForRole(role);
+  return Object.fromEntries(
+    ALL_PERMISSION_KEYS.filter((key) => defaults.has(key) !== selected.has(key)).map((key) => [
+      key,
+      selected.has(key) ? 1 : 2,
+    ]),
+  ) as Record<string, 1 | 2>;
+}
+
+type TeamMemberForm = ReturnType<typeof emptyForm>;
+type FormErrors = ReturnType<typeof getFormErrors>;
+
+function getFormErrors(form: TeamMemberForm, submitted: boolean, emailIsValid: boolean) {
+  return {
+    name: submitted && !form.name.trim() ? "Name is required." : "",
+    role: submitted && !form.role ? "Role is required." : "",
+    color: submitted && !form.color ? "Color is required." : "",
+    email:
+      submitted && !form.email.trim()
+        ? "Email is required."
+        : submitted && !emailIsValid
+          ? "Enter a valid email address."
+          : "",
+    serviceAreas:
+      submitted && form.role === "Dispatcher" && form.serviceAreas.length === 0
+        ? "Select at least one service area."
+        : "",
+  };
+}
+
+function PermissionsSection({
+  form,
+  togglePermission,
+}: {
+  form: TeamMemberForm;
+  togglePermission: (key: string) => void;
+}) {
+  return (
+    <Box>
+      <Typography variant="h6" sx={{ mb: 1 }}>
+        Permissions
+      </Typography>
+      <Typography variant="body2" color="text.secondary" sx={{ mb: 1 }}>
+        Permissions start with the selected role's defaults. Customize them before saving.
+      </Typography>
+      {PERMISSION_GROUPS.map((group) => (
+        <Accordion key={group.label} disableGutters>
+          <AccordionSummary expandIcon={<ExpandMoreIcon />}>
+            <Typography>{group.label}</Typography>
+          </AccordionSummary>
+          <AccordionDetails>
+            <Stack>
+              {group.keys.map((key) => (
+                <FormControlLabel
+                  key={key}
+                  control={
+                    <Checkbox
+                      checked={form.permissions.has(key)}
+                      onChange={() => togglePermission(key)}
+                    />
+                  }
+                  label={PERMISSION_LABELS[key]}
+                />
+              ))}
+            </Stack>
+          </AccordionDetails>
+        </Accordion>
+      ))}
+    </Box>
+  );
+}
+
+function TeamMemberFormFields({
+  form,
+  setForm,
+  errors,
+  updateRole,
+  toggleArea,
+  togglePermission,
+}: {
+  form: TeamMemberForm;
+  setForm: Dispatch<SetStateAction<TeamMemberForm>>;
+  errors: FormErrors;
+  updateRole: (role: TeamMemberRole) => void;
+  toggleArea: (area: string) => void;
+  togglePermission: (key: string) => void;
+}) {
+  return (
+    <Stack spacing={2.5}>
+      <TextField
+        label="Name"
+        placeholder="Team member name"
+        value={form.name}
+        onChange={(event) => setForm((current) => ({ ...current, name: event.target.value }))}
+        error={Boolean(errors.name)}
+        helperText={errors.name}
+        required
+        fullWidth
+      />
+      <FormControl fullWidth required error={Boolean(errors.role)}>
+        <InputLabel id="team-member-role-label">Role</InputLabel>
+        <Select
+          labelId="team-member-role-label"
+          label="Role"
+          value={form.role}
+          onChange={(event) => updateRole(event.target.value as TeamMemberRole)}
+        >
+          {ROLES.map((role) => (
+            <MenuItem key={role} value={role}>
+              {role}
+            </MenuItem>
+          ))}
+        </Select>
+        {Boolean(errors.role) && <FormHelperText>{errors.role}</FormHelperText>}
+      </FormControl>
+
+      <Box>
+        <Typography component="p" variant="body2" sx={{ mb: 1, fontWeight: 600 }}>
+          Color <span aria-hidden="true">*</span>
+        </Typography>
+        <Stack direction="row" spacing={1} useFlexGap sx={{ flexWrap: "wrap" }}>
+          {COLORS.map((color) => (
+            <Button
+              key={color}
+              type="button"
+              aria-label={`Select color ${color}`}
+              aria-pressed={form.color === color}
+              onClick={() => setForm((current) => ({ ...current, color }))}
+              sx={{
+                minWidth: 32,
+                width: 32,
+                height: 32,
+                borderRadius: "50%",
+                backgroundColor: color,
+                border: form.color === color ? "3px solid" : "2px solid transparent",
+                borderColor: form.color === color ? "text.primary" : "transparent",
+                boxShadow: form.color === color ? "0 0 0 2px white" : "none",
+                p: 0,
+                "&:hover": { backgroundColor: color, opacity: 0.85 },
+              }}
+            />
+          ))}
+        </Stack>
+        {Boolean(errors.color) && <FormHelperText error>{errors.color}</FormHelperText>}
+      </Box>
+
+      {form.role === "Dispatcher" && (
+        <Box>
+          <Typography component="p" variant="body2" sx={{ mb: 1, fontWeight: 600 }}>
+            Service Area <span aria-hidden="true">*</span>
+          </Typography>
+          <Typography variant="body2" color="text.secondary" sx={{ mb: 1 }}>
+            {form.serviceAreas.length ? form.serviceAreas.join(", ") : "Select service areas…"}
+          </Typography>
+          <Stack direction="row" useFlexGap sx={{ flexWrap: "wrap", columnGap: 1 }}>
+            {AREA_ZONES.map((area) => (
+              <FormControlLabel
+                key={area}
+                control={
+                  <Checkbox
+                    checked={form.serviceAreas.includes(area)}
+                    onChange={() => toggleArea(area)}
+                  />
+                }
+                label={area}
+              />
+            ))}
+          </Stack>
+          {Boolean(errors.serviceAreas) && (
+            <FormHelperText error>{errors.serviceAreas}</FormHelperText>
+          )}
+        </Box>
+      )}
+      {form.role !== "Dispatcher" && (
+        <Typography variant="body2" color="text.secondary">
+          Not applicable for this role
+        </Typography>
+      )}
+
+      <TextField
+        label="Phone"
+        placeholder="(555) 555-0100"
+        value={form.phone}
+        onChange={(event) => setForm((current) => ({ ...current, phone: event.target.value }))}
+        fullWidth
+      />
+      <TextField
+        label="Email"
+        placeholder="name@seahavenind.com"
+        value={form.email}
+        onChange={(event) => setForm((current) => ({ ...current, email: event.target.value }))}
+        error={Boolean(errors.email)}
+        helperText={errors.email || "A valid email is required to send the invite"}
+        required
+        type="email"
+        fullWidth
+      />
+
+      <PermissionsSection form={form} togglePermission={togglePermission} />
+    </Stack>
+  );
+}
+
+export function AddTeamMemberDialog({ open, onClose }: { open: boolean; onClose: () => void }) {
+  const [form, setForm] = useState(emptyForm);
+  const [submitted, setSubmitted] = useState(false);
+  const submissionId = useRef(0);
+  const { error: mutationError, isPending, mutate, reset } = useCreateTeamMember();
+
+  useEffect(() => {
+    submissionId.current += 1;
+    reset();
+    if (open) {
+      setForm(emptyForm());
+      setSubmitted(false);
+    }
+  }, [open, reset]);
+
+  const handleClose = () => {
+    if (isPending) return;
+
+    submissionId.current += 1;
+    reset();
+    onClose();
+  };
+
+  const emailIsValid = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(form.email.trim());
+  const errors = useMemo(
+    () => getFormErrors(form, submitted, emailIsValid),
+    [emailIsValid, form, submitted],
+  );
+  const isValid =
+    Boolean(form.name.trim()) &&
+    Boolean(form.role) &&
+    Boolean(form.color) &&
+    emailIsValid &&
+    (form.role !== "Dispatcher" || form.serviceAreas.length > 0);
+
+  const updateRole = (role: TeamMemberRole) => {
+    setForm((current) => ({
+      ...current,
+      role,
+      serviceAreas: [],
+      permissions: defaultsForRole(role),
+    }));
+  };
+
+  const togglePermission = (key: string) => {
+    setForm((current) => {
+      const permissions = new Set(current.permissions);
+      if (permissions.has(key)) permissions.delete(key);
+      else permissions.add(key);
+      return { ...current, permissions };
+    });
+  };
+
+  const toggleArea = (area: string) => {
+    setForm((current) => ({
+      ...current,
+      serviceAreas: current.serviceAreas.includes(area)
+        ? current.serviceAreas.filter((value) => value !== area)
+        : [...current.serviceAreas, area],
+    }));
+  };
+
+  const submit = () => {
+    setSubmitted(true);
+    if (!isValid) return;
+
+    const input: CreateTeamMemberInput = {
+      name: form.name.trim(),
+      role: form.role,
+      color: form.color,
+      email: form.email.trim(),
+      phone: form.phone.trim() || undefined,
+      serviceAreas: form.serviceAreas,
+      permissionOverrides: permissionOverrides(form.role, form.permissions),
+    };
+    const currentSubmissionId = submissionId.current;
+    mutate(input, {
+      onSuccess: () => {
+        if (submissionId.current !== currentSubmissionId) return;
+        reset();
+        onClose();
+      },
+    });
+  };
+
+  return (
+    <Dialog open={open} onClose={handleClose} fullWidth maxWidth="md" scroll="paper">
+      <DialogTitle>Add Member</DialogTitle>
+      <DialogContent dividers>
+        <Typography color="text.secondary" sx={{ mb: 3 }}>
+          Register a new team member.
+        </Typography>
+        {Boolean(mutationError) && (
+          <Alert severity="error" sx={{ mb: 2 }}>
+            {mutationError?.message}
+          </Alert>
+        )}
+        <TeamMemberFormFields
+          form={form}
+          setForm={setForm}
+          errors={errors}
+          updateRole={updateRole}
+          toggleArea={toggleArea}
+          togglePermission={togglePermission}
+        />
+      </DialogContent>
+      <DialogActions>
+        <Button onClick={handleClose} disabled={isPending}>
+          Cancel
+        </Button>
+        <Button variant="contained" onClick={submit} disabled={isPending}>
+          {isPending ? <CircularProgress size={20} color="inherit" /> : "Add Member"}
+        </Button>
+      </DialogActions>
+    </Dialog>
+  );
+}

src/app/(protected)/team-members/_components/team-members-table.tsx

@@ -0,0 +1,110 @@
+import {
+  Avatar,
+  Button,
+  CircularProgress,
+  Paper,
+  Table,
+  TableBody,
+  TableCell,
+  TableContainer,
+  TableHead,
+  TableRow,
+  Typography,
+} from "@mui/material";
+import type { TeamMemberListItem } from "@/domain/team-members/types/team-member";
+
+const HEADINGS = ["Team Member", "Role", "Service Area", "Phone", "Email", "Color", "Status"];
+
+function memberStatusLabel(member: TeamMemberListItem) {
+  return member.pendingRegistration ? "Pending registration" : member.status;
+}
+
+export function TeamMembersTable({
+  rows,
+  isLoading,
+  hasError,
+  tab,
+  onOpen,
+}: {
+  rows: TeamMemberListItem[];
+  isLoading: boolean;
+  hasError: boolean;
+  tab: "active" | "inactive";
+  onOpen: (member: TeamMemberListItem) => void;
+}) {
+  return (
+    <TableContainer component={Paper} variant="outlined">
+      <Table stickyHeader size="small" sx={{ minWidth: 900 }}>
+        <TableHead>
+          <TableRow>
+            {HEADINGS.map((heading) => (
+              <TableCell key={heading} className="font-semibold">
+                {heading}
+              </TableCell>
+            ))}
+            <TableCell align="right" className="font-semibold">
+              Actions
+            </TableCell>
+          </TableRow>
+        </TableHead>
+        <TableBody>
+          {isLoading ? (
+            <TableRow>
+              <TableCell colSpan={8} align="center" sx={{ py: 8 }}>
+                <CircularProgress size={28} />
+              </TableCell>
+            </TableRow>
+          ) : hasError ? (
+            <TableRow>
+              <TableCell colSpan={8} align="center" sx={{ py: 8 }}>
+                <Typography sx={{ fontWeight: 600 }}>Unable to load team members</Typography>
+                <Typography variant="body2" color="text.secondary">
+                  Check your connection and try again.
+                </Typography>
+              </TableCell>
+            </TableRow>
+          ) : rows.length === 0 ? (
+            <TableRow>
+              <TableCell colSpan={8} align="center" sx={{ py: 8 }}>
+                <Typography sx={{ fontWeight: 600 }}>No {tab} team members found</Typography>
+                <Typography variant="body2" color="text.secondary">
+                  Try a different search, or add a new team member.
+                </Typography>
+              </TableCell>
+            </TableRow>
+          ) : (
+            rows.map((member) => (
+              <TableRow
+                key={String(member.id)}
+                hover
+                onClick={() => onOpen(member)}
+                sx={{ cursor: "pointer" }}
+              >
+                <TableCell>{member.name || "—"}</TableCell>
+                <TableCell>{member.role || "—"}</TableCell>
+                <TableCell>{member.serviceArea || "—"}</TableCell>
+                <TableCell>{member.phone || "—"}</TableCell>
+                <TableCell>{member.email || "—"}</TableCell>
+                <TableCell>
+                  <Avatar sx={{ width: 22, height: 22, bgcolor: member.color || "primary.main" }} />
+                </TableCell>
+                <TableCell>{memberStatusLabel(member)}</TableCell>
+                <TableCell align="right">
+                  <Button
+                    size="small"
+                    onClick={(event) => {
+                      event.stopPropagation();
+                      onOpen(member);
+                    }}
+                  >
+                    View
+                  </Button>
+                </TableCell>
+              </TableRow>
+            ))
+          )}
+        </TableBody>
+      </Table>
+    </TableContainer>
+  );
+}

src/app/(protected)/team-members/index.tsx

@@ -0,0 +1,184 @@
+import { useState } from "react";
+import { useDebounce } from "@/hooks/use-debounce";
+import { useTeamMembersList } from "@/domain/team-members/use-cases/use-team-members-list";
+import type { TeamMemberListItem } from "@/domain/team-members/types/team-member";
+import {
+  Alert,
+  Avatar,
+  Box,
+  Button,
+  Chip,
+  Drawer,
+  IconButton,
+  Stack,
+  Tab,
+  Tabs,
+  TextField,
+  Typography,
+} from "@mui/material";
+import CloseIcon from "@mui/icons-material/Close";
+import { TeamMembersTable } from "./_components/team-members-table";
+import { AddTeamMemberDialog } from "./_components/add-team-member-dialog";
+
+type StatusTab = "active" | "inactive";
+
+const STATUS_LABELS: Record<StatusTab, "Active" | "Inactive"> = {
+  active: "Active",
+  inactive: "Inactive",
+};
+
+function MemberStatus({ status }: { status: TeamMemberListItem["status"] }) {
+  return <Chip size="small" label={status} color={status === "Active" ? "success" : "default"} />;
+}
+
+function TeamMemberDrawer({
+  member,
+  onClose,
+}: {
+  member: TeamMemberListItem | null;
+  onClose: () => void;
+}) {
+  return (
+    <Drawer anchor="right" open={Boolean(member)} onClose={onClose}>
+      <Box sx={{ width: { xs: "100vw", sm: 380 }, p: 3 }}>
+        <Stack
+          direction="row"
+          sx={{ alignItems: "center", justifyContent: "space-between", mb: 3 }}
+        >
+          <Typography variant="h6">Team Member</Typography>
+          <IconButton aria-label="Close team member details" onClick={onClose}>
+            <CloseIcon />
+          </IconButton>
+        </Stack>
+        {member !== null && (
+          <Stack spacing={2}>
+            <Stack direction="row" spacing={2} sx={{ alignItems: "center" }}>
+              <Avatar sx={{ bgcolor: member.color || "primary.main" }}>
+                {member.name.slice(0, 1).toUpperCase() || "?"}
+              </Avatar>
+              <Box>
+                <Typography variant="h6">{member.name || "—"}</Typography>
+                <Typography color="text.secondary">{member.role || "—"}</Typography>
+              </Box>
+            </Stack>
+            <MemberStatus status={member.status} />
+            <Typography>
+              <strong>Service Area:</strong> {member.serviceArea || "—"}
+            </Typography>
+            <Typography>
+              <strong>Phone:</strong> {member.phone || "—"}
+            </Typography>
+            <Typography>
+              <strong>Email:</strong> {member.email || "—"}
+            </Typography>
+          </Stack>
+        )}
+      </Box>
+    </Drawer>
+  );
+}
+
+export default function TeamMembersListPage() {
+  const [search, setSearch] = useState("");
+  const [tab, setTab] = useState<StatusTab>("active");
+  const [selectedMember, setSelectedMember] = useState<TeamMemberListItem | null>(null);
+  const [addMemberOpen, setAddMemberOpen] = useState(false);
+  const debouncedSearch = useDebounce(search, 300).trim().toLowerCase();
+  const { data, isLoading, error } = useTeamMembersList();
+  const allMembers = data?.items ?? [];
+
+  const activeCount = allMembers.filter((member) => member.status === "Active").length;
+  const inactiveCount = allMembers.length - activeCount;
+  const rows = allMembers
+    .filter((member) => member.status === STATUS_LABELS[tab])
+    .filter((member) => !debouncedSearch || member.name.toLowerCase().includes(debouncedSearch));
+
+  return (
+    <Box
+      className="flex h-full flex-col overflow-hidden"
+      sx={{ backgroundColor: "var(--color-bg-page)" }}
+    >
+      <Stack
+        direction={{ xs: "column", sm: "row" }}
+        spacing={2}
+        sx={{
+          alignItems: { xs: "stretch", sm: "center" },
+          justifyContent: "space-between",
+          p: 2.5,
+          backgroundColor: "var(--color-bg-surface)",
+          borderBottom: "1px solid var(--color-border)",
+        }}
+      >
+        <Box>
+          <Typography variant="h4" component="h1">
+            Team Members
+          </Typography>
+          <Typography variant="body2" color="text.secondary" sx={{ mt: 0.75 }}>
+            {allMembers.length} team member{allMembers.length === 1 ? "" : "s"} · {activeCount}{" "}
+            active
+          </Typography>
+        </Box>
+        <Stack direction="row" spacing={1} sx={{ alignItems: "center" }}>
+          <TextField
+            size="small"
+            value={search}
+            onChange={(event) => setSearch(event.target.value)}
+            placeholder="Search team member…"
+            aria-label="Search team member"
+            sx={{ width: 224 }}
+          />
+          <Button variant="contained" size="small" onClick={() => setAddMemberOpen(true)}>
+            Add Member
+          </Button>
+        </Stack>
+      </Stack>
+
+      <Tabs
+        value={tab}
+        onChange={(_event, value: StatusTab) => setTab(value)}
+        aria-label="Team member status"
+      >
+        <Tab value="active" label={`Active ${activeCount}`} />
+        <Tab value="inactive" label={`Inactive ${inactiveCount}`} />
+      </Tabs>
+
+      {Boolean(error) && (
+        <Alert severity="error">
+          {error instanceof Error ? error.message : "Failed to load team members"}
+        </Alert>
+      )}
+
+      <Box sx={{ flex: 1, overflow: "auto", p: 2 }}>
+        <TeamMembersTable
+          rows={rows}
+          isLoading={isLoading}
+          hasError={Boolean(error)}
+          tab={tab}
+          onOpen={setSelectedMember}
+        />
+      </Box>
+
+      <Stack
+        direction="row"
+        sx={{
+          justifyContent: "space-between",
+          px: 2,
+          py: 1,
+          borderTop: "1px solid var(--color-border)",
+          backgroundColor: "var(--color-bg-surface)",
+        }}
+      >
+        <Typography variant="caption" color="text.secondary">
+          {rows.length} {tab} team member{rows.length === 1 ? "" : "s"}
+          {debouncedSearch ? " · filtered" : ""}
+        </Typography>
+        <Typography variant="caption" color="text.secondary">
+          {activeCount} active · {inactiveCount} inactive
+        </Typography>
+      </Stack>
+
+      <TeamMemberDrawer member={selectedMember} onClose={() => setSelectedMember(null)} />
+      <AddTeamMemberDialog open={addMemberOpen} onClose={() => setAddMemberOpen(false)} />
+    </Box>
+  );
+}

src/config/menu.ts

@@ -10,6 +10,7 @@ import {
   Bell,
   BarChart3,
   Star,
+  Users,
 } from "lucide-react";
 
 export type NavItemDef = {
@@ -58,6 +59,10 @@ export const navGroups: NavGroup[] = [
       { label: "Sites", icon: MapPin, path: "/locations" },
     ],
   },
+  {
+    title: "TEAM",
+    items: [{ label: "Team Members", icon: Users, path: "/team-members" }],
+  },
   // {
   //   title: "INTERNAL",
   //   items: [{ label: "Documents", icon: FileText, path: "/documents" }],

src/domain/team-members/api/team-members-api.ts

@@ -0,0 +1,22 @@
+import { apiGet, apiPost } from "@/api/api";
+import { API_PATHS } from "@/api/api-paths";
+import { handleApiResponse } from "@/api/handle-api-response";
+import { mapTeamMemberListItems } from "@/domain/team-members/mappers/team-member-mapper";
+import type {
+  CreateTeamMemberInput,
+  TeamMemberCreated,
+  TeamMemberListResult,
+} from "@/domain/team-members/types/team-member";
+
+export const teamMembersApi = {
+  getList: async (): Promise<TeamMemberListResult> => {
+    const data = await apiGet<unknown>(API_PATHS.teamMember.getList);
+    const items = handleApiResponse<unknown[]>(data);
+    return { items: mapTeamMemberListItems(Array.isArray(items) ? items : []) };
+  },
+
+  create: async (input: CreateTeamMemberInput): Promise<TeamMemberCreated> => {
+    const data = await apiPost<unknown>(API_PATHS.teamMember.create, input);
+    return handleApiResponse<TeamMemberCreated>(data);
+  },
+};

src/domain/team-members/mappers/team-member-mapper.ts

@@ -0,0 +1,46 @@
+import type { TeamMemberListItem } from "@/domain/team-members/types/team-member";
+
+function readString(record: Record<string, unknown>, ...keys: string[]): string {
+  for (const key of keys) {
+    const value = record[key];
+    if (typeof value === "string") return value;
+    if (typeof value === "number") return String(value);
+  }
+  return "";
+}
+
+function readBoolean(record: Record<string, unknown>, ...keys: string[]): boolean {
+  for (const key of keys) {
+    const value = record[key];
+    if (typeof value === "boolean") return value;
+    if (typeof value === "string") return value.toLowerCase() === "true";
+  }
+  return false;
+}
+
+export function mapTeamMemberListItem(raw: unknown): TeamMemberListItem {
+  const record = (typeof raw === "object" && raw !== null ? raw : {}) as Record<string, unknown>;
+  const id = record.id ?? record.Id;
+  const status =
+    readString(record, "status", "Status").toLowerCase() === "inactive" ||
+    readBoolean(record, "isDeleted", "IsDeleted")
+      ? "Inactive"
+      : "Active";
+
+  return {
+    id: typeof id === "string" || typeof id === "number" ? id : "",
+    name: readString(record, "name", "Name"),
+    role: readString(record, "role", "Role", "roleName", "RoleName"),
+    serviceArea: readString(record, "serviceArea", "ServiceArea", "locations", "Locations"),
+    phone: readString(record, "phone", "Phone"),
+    email: readString(record, "email", "Email"),
+    color: readString(record, "color", "Color"),
+    status,
+    isAccountOwner: readBoolean(record, "isAccountOwner", "IsAccountOwner"),
+    pendingRegistration: readBoolean(record, "pendingRegistration", "PendingRegistration"),
+  };
+}
+
+export function mapTeamMemberListItems(rawItems: unknown[]): TeamMemberListItem[] {
+  return rawItems.map(mapTeamMemberListItem);
+}

src/domain/team-members/types/team-member.ts

@@ -0,0 +1,39 @@
+export interface TeamMemberListItem {
+  id: string | number;
+  name: string;
+  role: string;
+  serviceArea: string;
+  phone: string;
+  email: string;
+  color: string;
+  status: "Active" | "Inactive";
+  isAccountOwner: boolean;
+  pendingRegistration: boolean;
+}
+
+export type TeamMemberRole = "Dispatcher" | "Scheduler" | "Admin";
+
+export interface CreateTeamMemberInput {
+  name: string;
+  role: TeamMemberRole;
+  color: string;
+  email: string;
+  phone?: string;
+  serviceAreas: string[];
+  permissionOverrides: Record<string, 1 | 2>;
+}
+
+export interface TeamMemberCreated {
+  id: string;
+  name: string;
+  role: TeamMemberRole;
+  color: string;
+  email: string;
+  phone: string;
+  serviceAreas: string[];
+  pendingRegistration: boolean;
+}
+
+export interface TeamMemberListResult {
+  items: TeamMemberListItem[];
+}

src/domain/team-members/use-cases/use-create-team-member.ts

@@ -0,0 +1,27 @@
+import { useMutation, useQueryClient, type UseMutationResult } from "@tanstack/react-query";
+import { toast } from "react-toastify";
+import { teamMembersApi } from "@/domain/team-members/api/team-members-api";
+import type {
+  CreateTeamMemberInput,
+  TeamMemberCreated,
+} from "@/domain/team-members/types/team-member";
+import { queryKeys } from "@/infra/query-key/query-key";
+
+export function useCreateTeamMember(): UseMutationResult<
+  TeamMemberCreated,
+  Error,
+  CreateTeamMemberInput
+> {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: teamMembersApi.create,
+    onSuccess: () => {
+      void queryClient.invalidateQueries({ queryKey: queryKeys.teamMembers.all });
+      toast.success("Team member created with pending registration.");
+    },
+    onError: (error: Error) => {
+      toast.error(error.message || "Failed to create team member");
+    },
+  });
+}

src/domain/team-members/use-cases/use-team-members-list.ts

@@ -0,0 +1,11 @@
+import { useQuery, type UseQueryResult } from "@tanstack/react-query";
+import { teamMembersApi } from "@/domain/team-members/api/team-members-api";
+import type { TeamMemberListResult } from "@/domain/team-members/types/team-member";
+import { queryKeys } from "@/infra/query-key/query-key";
+
+export function useTeamMembersList(): UseQueryResult<TeamMemberListResult, Error> {
+  return useQuery({
+    queryKey: queryKeys.teamMembers.list(),
+    queryFn: teamMembersApi.getList,
+  });
+}

src/domain/work-orders/errors/board-create-errors.ts

@@ -1,12 +1,12 @@
 import { isHTTPError, isNetworkError, isTimeoutError } from "ky";
 import { mapHttpStatusToMessage } from "@/api/api-error";
-import { DISPATCH_REQUIRED_MESSAGE } from "@/domain/work-orders/errors/board-patch-errors";
+import {
+  DISPATCH_REQUIRED_MESSAGE,
+  DUPLICATE_WO_NUMBER_MESSAGE,
+} from "@/domain/work-orders/errors/board-patch-errors";
 
 export const BOARD_CREATE_FAILED_MESSAGE = "Unable to create the work order. Please try again.";
 
-const DUPLICATE_WO_NUMBER_MESSAGE =
-  "This work order number is already assigned to another work order.";
-
 /** Statuses whose mapped copy is fixed product text, never the response body. */
 const FIXED_COPY_STATUSES = new Set([401, 403, 404, 500]);
 

src/domain/work-orders/errors/board-patch-errors.ts

@@ -1,3 +1,5 @@
+import { isNetworkError, isTimeoutError } from "ky";
+import { ApiError, mapHttpStatusToMessage } from "@/api/api-error";
 import type { WorkOrderTableRow } from "@/domain/work-orders/types/work-order-table-row";
 
 export class BoardPatchConflictError extends Error {
@@ -24,10 +26,64 @@ export class BoardPatchValidationError extends Error {
 
 export const DISPATCH_REQUIRED_MESSAGE = "Select a vendor company before saving.";
 
-/** why: backend field names must never be exposed through user-facing board toasts. */
+export const BOARD_PATCH_FAILED_MESSAGE = "Unable to save the work order. Please try again.";
+
+export const NO_PERSISTABLE_FIELDS_MESSAGE =
+  "These changes cannot be saved on the board. Refresh and edit a supported field.";
+
+export const DUPLICATE_WO_NUMBER_MESSAGE =
+  "This work order number is already assigned to another work order.";
+
+const KNOWN_VALIDATION_COPY: ReadonlyMap<string, string> = new Map([
+  ["DispatchRequired", DISPATCH_REQUIRED_MESSAGE],
+  ["NoPersistableFields", NO_PERSISTABLE_FIELDS_MESSAGE],
+  // why: editing a WO number to one that already exists returns 422 DuplicateWoNumber;
+  // show the same product copy as create, not the generic save-failed fallback.
+  ["DuplicateWoNumber", DUPLICATE_WO_NUMBER_MESSAGE],
+]);
+
+/**
+ * why: board PATCH validation text ("vendorId is required…", object ids, backend codes)
+ * must never reach the screen. Unknown codes fall back to generic copy, not `error.message`.
+ */
 export function boardPatchValidationMessage(error: BoardPatchValidationError): string {
-  if (error.code === "DispatchRequired") {
-    return DISPATCH_REQUIRED_MESSAGE;
-  }
-  return error.message;
+  return KNOWN_VALIDATION_COPY.get(error.code) ?? BOARD_PATCH_FAILED_MESSAGE;
+}
+
+export const BOARD_PATCH_CONFLICT_MESSAGE =
+  "This work order was changed by someone else. Refresh to see the latest before saving again.";
+
+export const PARTIAL_SAVE_PREFIX = "Some changes were saved, but the rest were not.";
+
+/** Statuses whose mapped copy is fixed product text, never the response body. */
+const FIXED_COPY_STATUSES = new Set([401, 403, 404, 500]);
+
+/** why: any board edit failure toast must use product copy, never backend text or field keys. */
+export function boardPatchErrorMessage(error: unknown): string {
+  if (error instanceof BoardPatchConflictError) {
+    return BOARD_PATCH_CONFLICT_MESSAGE;
+  }
+  if (error instanceof BoardPatchValidationError) {
+    return boardPatchValidationMessage(error);
+  }
+  if (error instanceof ApiError && FIXED_COPY_STATUSES.has(error.status)) {
+    return mapHttpStatusToMessage(error.status);
+  }
+  if (isNetworkError(error) || isTimeoutError(error)) {
+    return error.message;
+  }
+  return BOARD_PATCH_FAILED_MESSAGE;
+}
+
+/** Thrown when a multi-field board edit fails after some fields already persisted. */
+export class BoardPatchPartialSaveError extends Error {
+  readonly partialRow: WorkOrderTableRow;
+  readonly failure: unknown;
+
+  constructor(partialRow: WorkOrderTableRow, failure: unknown) {
+    super(`${PARTIAL_SAVE_PREFIX} ${boardPatchErrorMessage(failure)}`);
+    this.name = "BoardPatchPartialSaveError";
+    this.partialRow = partialRow;
+    this.failure = failure;
+  }
 }

src/domain/work-orders/use-cases/use-work-order-table-mutations.ts

@@ -3,9 +3,11 @@ import { useMutation, useQueryClient } from "@tanstack/react-query";
 import { toast } from "react-toastify";
 import { workOrdersApi } from "@/domain/work-orders/api/work-orders-api";
 import {
-  boardPatchValidationMessage,
+  boardPatchErrorMessage,
   BoardPatchConflictError,
+  BoardPatchPartialSaveError,
   BoardPatchValidationError,
+  NO_PERSISTABLE_FIELDS_MESSAGE,
 } from "@/domain/work-orders/errors/board-patch-errors";
 import { mapApiStatusToWizard } from "@/domain/work-orders/mappers/wizard-draft-mapper";
 import {
@@ -58,10 +60,7 @@ async function applyBoardFieldOps(
 ): Promise<WorkOrderTableRow> {
   const ops = expandTablePatchToBoardFieldOps(patch);
   if (ops.length === 0) {
-    throw new BoardPatchValidationError(
-      "NoPersistableFields",
-      "These changes cannot be saved on the board. Refresh and edit a supported field.",
-    );
+    throw new BoardPatchValidationError("NoPersistableFields", NO_PERSISTABLE_FIELDS_MESSAGE);
   }
 
   const current = getRow?.(id);
@@ -77,14 +76,7 @@ async function applyBoardFieldOps(
       completedOps += 1;
     } catch (error) {
       if (completedOps > 0) {
-        const field = op.field;
-        const partial = new Error(
-          `Schedule update partially saved (${completedOps}/${ops.length} fields). Failed on "${field}": ${
-            error instanceof Error ? error.message : "Unknown error"
-          }`,
-        );
-        (partial as Error & { partialRow?: WorkOrderTableRow }).partialRow = latest;
-        throw partial;
+        throw new BoardPatchPartialSaveError(latest, error);
       }
       throw error;
     }
@@ -155,9 +147,8 @@ export function useWorkOrderTableMutations(
       invalidate();
     },
     onError: (error: Error, { id }) => {
-      const partialRow = (error as Error & { partialRow?: WorkOrderTableRow }).partialRow;
-      if (partialRow) {
-        onPatch(id, partialRow);
+      if (error instanceof BoardPatchPartialSaveError) {
+        onPatch(id, error.partialRow);
         toast.error(error.message);
         invalidate();
         return;
@@ -165,13 +156,10 @@ export function useWorkOrderTableMutations(
 
       if (error instanceof BoardPatchConflictError && error.currentState) {
         onPatch(id, error.currentState);
-        toast.error(error.message || "Conflict — refreshed with latest data");
-      } else if (error instanceof BoardPatchValidationError) {
-        clearPatch(id);
-        toast.error(boardPatchValidationMessage(error));
+        toast.error(boardPatchErrorMessage(error));
       } else {
         clearPatch(id);
-        toast.error(error.message || "Failed to update work order");
+        toast.error(boardPatchErrorMessage(error));
       }
       invalidate();
     },

src/infra/query-key/query-key.ts

@@ -47,6 +47,10 @@ export const queryKeys = {
       [...queryKeys.employees.all, "list", params ?? {}] as const,
     detail: (id: string | number) => [...queryKeys.employees.all, "detail", id] as const,
   },
+  teamMembers: {
+    all: ["teamMembers"] as const,
+    list: () => [...queryKeys.teamMembers.all, "list"] as const,
+  },
   dashboard: {
     all: ["dashboard"] as const,
     stats: () => [...queryKeys.dashboard.all, "stats"] as const,

src/test/app/(protected)/team-members/add-team-member-dialog.test.tsx

@@ -0,0 +1,104 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { renderWithProviders } from "@/test/test-utils";
+import { AddTeamMemberDialog } from "@/app/(protected)/team-members/_components/add-team-member-dialog";
+import { useCreateTeamMember } from "@/domain/team-members/use-cases/use-create-team-member";
+
+vi.mock("@/domain/team-members/use-cases/use-create-team-member", () => ({
+  useCreateTeamMember: vi.fn(),
+}));
+
+describe("AddTeamMemberDialog", () => {
+  const mutate = vi.fn();
+  const reset = vi.fn();
+
+  beforeEach(() => {
+    mutate.mockReset();
+    reset.mockReset();
+    vi.mocked(useCreateTeamMember).mockReturnValue({
+      mutate,
+      reset,
+      isPending: false,
+      error: null,
+    } as unknown as ReturnType<typeof useCreateTeamMember>);
+  });
+
+  it("requires the required fields and a Dispatcher service area", async () => {
+    const user = userEvent.setup();
+    renderWithProviders(<AddTeamMemberDialog open onClose={vi.fn()} />, { withAuth: false });
+
+    await user.click(screen.getByRole("button", { name: "Add Member" }));
+
+    expect(screen.getByText("Name is required.")).toBeInTheDocument();
+    expect(screen.getByText("Color is required.")).toBeInTheDocument();
+    expect(screen.getByText("Email is required.")).toBeInTheDocument();
+    expect(screen.getByText("Select at least one service area.")).toBeInTheDocument();
+    expect(mutate).not.toHaveBeenCalled();
+  });
+
+  it("resets role defaults and submits customized permissions", async () => {
+    const user = userEvent.setup();
+    renderWithProviders(<AddTeamMemberDialog open onClose={vi.fn()} />, { withAuth: false });
+
+    await user.type(screen.getByRole("textbox", { name: "Name" }), "Taylor Dispatcher");
+    await user.type(screen.getByRole("textbox", { name: "Email" }), "taylor@example.com");
+    await user.click(screen.getByRole("button", { name: "Select color #F59E0B" }));
+    await user.click(screen.getByRole("combobox", { name: "Role" }));
+    await user.click(screen.getByRole("option", { name: "Scheduler" }));
+
+    expect(screen.queryByLabelText("East")).not.toBeInTheDocument();
+    const createSites = screen.getByLabelText("Create sites");
+    expect(createSites).toBeChecked();
+    await user.click(createSites);
+    await user.click(screen.getByRole("button", { name: "Add Member" }));
+
+    expect(mutate).toHaveBeenCalledWith(
+      expect.objectContaining({
+        name: "Taylor Dispatcher",
+        role: "Scheduler",
+        color: "#F59E0B",
+        email: "taylor@example.com",
+        serviceAreas: [],
+        permissionOverrides: { createSites: 2 },
+      }),
+      expect.any(Object),
+    );
+  }, 15000);
+
+  it("does not close while a member is being created", async () => {
+    const user = userEvent.setup();
+    const onClose = vi.fn();
+    vi.mocked(useCreateTeamMember).mockReturnValue({
+      mutate,
+      reset,
+      isPending: true,
+      error: null,
+    } as unknown as ReturnType<typeof useCreateTeamMember>);
+    renderWithProviders(<AddTeamMemberDialog open onClose={onClose} />, { withAuth: false });
+
+    await user.keyboard("{Escape}");
+
+    expect(onClose).not.toHaveBeenCalled();
+  });
+
+  it("clears a previous mutation error when reopened", () => {
+    const mutation = {
+      mutate,
+      reset,
+      isPending: false,
+      error: new Error("Email is already in use."),
+    } as unknown as ReturnType<typeof useCreateTeamMember>;
+    vi.mocked(useCreateTeamMember).mockReturnValue(mutation);
+    const { rerender } = renderWithProviders(<AddTeamMemberDialog open onClose={vi.fn()} />, {
+      withAuth: false,
+    });
+
+    expect(screen.getByText("Email is already in use.")).toBeInTheDocument();
+    mutation.error = null;
+    rerender(<AddTeamMemberDialog open={false} onClose={vi.fn()} />);
+    rerender(<AddTeamMemberDialog open onClose={vi.fn()} />);
+
+    expect(screen.queryByText("Email is already in use.")).not.toBeInTheDocument();
+  });
+});

src/test/domain/team-members/api/team-members-api.test.ts

@@ -0,0 +1,48 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { API_PATHS } from "@/api/api-paths";
+
+const apiGet = vi.fn();
+const apiPost = vi.fn();
+
+vi.mock("@/api/api", () => ({
+  apiGet: (...args: unknown[]) => apiGet(...args),
+  apiPost: (...args: unknown[]) => apiPost(...args),
+}));
+
+import { teamMembersApi } from "@/domain/team-members/api/team-members-api";
+
+describe("teamMembersApi", () => {
+  beforeEach(() => {
+    apiGet.mockReset();
+    apiPost.mockReset();
+  });
+
+  it("posts the pending team member contract without invitation fields", async () => {
+    apiPost.mockResolvedValueOnce({
+      data: {
+        id: "u-1",
+        name: "Taylor Dispatcher",
+        role: "Dispatcher",
+        pendingRegistration: true,
+      },
+    });
+
+    const input = {
+      name: "Taylor Dispatcher",
+      role: "Dispatcher" as const,
+      color: "#F59E0B",
+      email: "taylor@example.com",
+      phone: "555-0100",
+      serviceAreas: ["East"],
+      permissionOverrides: { deleteSites: 1 as const },
+    };
+
+    await expect(teamMembersApi.create(input)).resolves.toMatchObject({
+      id: "u-1",
+      pendingRegistration: true,
+    });
+    expect(apiPost).toHaveBeenCalledWith(API_PATHS.teamMember.create, input);
+    expect(apiPost.mock.calls[0]?.[1]).not.toHaveProperty("invite");
+    expect(apiPost.mock.calls[0]?.[1]).not.toHaveProperty("password");
+  });
+});

src/test/domain/team-members/team-member-mapper.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+import { mapTeamMemberListItem } from "@/domain/team-members/mappers/team-member-mapper";
+
+describe("mapTeamMemberListItem", () => {
+  it("maps the existing User list response and derives inactive state", () => {
+    expect(
+      mapTeamMemberListItem({
+        Id: "u1",
+        Name: "Alex Smith",
+        RoleName: "Dispatcher",
+        Locations: "Central",
+        Email: "alex@example.com",
+        Status: "Inactive",
+        IsAccountOwner: true,
+      }),
+    ).toEqual({
+      id: "u1",
+      name: "Alex Smith",
+      role: "Dispatcher",
+      serviceArea: "Central",
+      phone: "",
+      email: "alex@example.com",
+      color: "",
+      status: "Inactive",
+      isAccountOwner: true,
+      pendingRegistration: false,
+    });
+  });
+});

src/test/domain/work-orders/api/work-orders-api.test.ts

@@ -634,6 +634,28 @@ describe("workOrdersApi.patchBoardField", () => {
       }),
     ).rejects.toBeInstanceOf(BoardPatchConflictError);
   });
+
+  it("throws BoardPatchValidationError with DuplicateWoNumber code on 422", async () => {
+    apiPatchFn.mockResolvedValue({
+      ok: false,
+      status: 422,
+      json: async () => ({
+        code: "DuplicateWoNumber",
+        message: "WO number already exists.",
+      }),
+    });
+
+    await expect(
+      workOrdersApi.patchBoardField(10, {
+        field: "woNumber",
+        value: "12345678901",
+        workOrderVersion: "AAAAAAA=",
+      }),
+    ).rejects.toMatchObject({
+      name: "BoardPatchValidationError",
+      code: "DuplicateWoNumber",
+    });
+  });
 });
 
 describe("workOrdersApi.createComment", () => {

src/test/domain/work-orders/errors/board-patch-errors.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+import {
+  BOARD_PATCH_CONFLICT_MESSAGE,
+  BOARD_PATCH_FAILED_MESSAGE,
+  BoardPatchConflictError,
+  BoardPatchValidationError,
+  DUPLICATE_WO_NUMBER_MESSAGE,
+  boardPatchErrorMessage,
+} from "@/domain/work-orders/errors/board-patch-errors";
+
+describe("boardPatchErrorMessage", () => {
+  it("maps a DuplicateWoNumber validation error to the duplicate-WO product copy", () => {
+    const error = new BoardPatchValidationError("DuplicateWoNumber", "WO number already exists.");
+
+    expect(boardPatchErrorMessage(error)).toBe(DUPLICATE_WO_NUMBER_MESSAGE);
+  });
+
+  it("never leaks backend validation text for unknown codes", () => {
+    const error = new BoardPatchValidationError("SomethingElse", "vendorId is required.");
+
+    expect(boardPatchErrorMessage(error)).toBe(BOARD_PATCH_FAILED_MESSAGE);
+  });
+
+  it("maps a conflict error to the concurrent-edit copy", () => {
+    const error = new BoardPatchConflictError("stale", null);
+
+    expect(boardPatchErrorMessage(error)).toBe(BOARD_PATCH_CONFLICT_MESSAGE);
+  });
+});

src/test/domain/work-orders/use-cases/use-work-order-table-mutations-errors.test.tsx

@@ -0,0 +1,171 @@
+import { QueryClientProvider } from "@tanstack/react-query";
+import { act, renderHook, waitFor } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { toast } from "react-toastify";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  BOARD_PATCH_CONFLICT_MESSAGE,
+  BOARD_PATCH_FAILED_MESSAGE,
+  DISPATCH_REQUIRED_MESSAGE,
+  PARTIAL_SAVE_PREFIX,
+} from "@/domain/work-orders/errors/board-patch-errors";
+import type {
+  WorkOrderTablePatch,
+  WorkOrderTableRow,
+} from "@/domain/work-orders/types/work-order-table-row";
+import { useWorkOrderTableMutations } from "@/domain/work-orders/use-cases/use-work-order-table-mutations";
+import { createTestQueryClient } from "@/test/test-utils";
+
+vi.mock("react-toastify", () => ({
+  toast: { error: vi.fn(), success: vi.fn(), warning: vi.fn() },
+}));
+
+const ROW = { id: 7, rowVersion: "v1" } as WorkOrderTableRow;
+
+function wrapper({ children }: { children: ReactNode }) {
+  return <QueryClientProvider client={createTestQueryClient()}>{children}</QueryClientProvider>;
+}
+
+type FakeResponse = { status: number; body: Record<string, unknown> };
+
+/** Board PATCH goes through the real ky client; only the network responses are faked. */
+function respondWith(...responses: FakeResponse[]) {
+  const queue = [...responses];
+  globalThis.fetch = vi.fn(async () => {
+    const next = queue.shift() ?? responses[responses.length - 1];
+    return new Response(JSON.stringify(next.body), {
+      status: next.status,
+      headers: { "Content-Type": "application/json" },
+    });
+  }) as typeof fetch;
+}
+
+async function patchAndGetToast(
+  patch: WorkOrderTablePatch = { woNumber: "WO-100" },
+  expectedCalls = 1,
+  onPatch: (id: string | number, patch: WorkOrderTablePatch) => void = () => undefined,
+): Promise<unknown> {
+  const { result } = renderHook(
+    () =>
+      useWorkOrderTableMutations({
+        onPatch,
+        clearPatch: () => undefined,
+        getRow: () => ROW,
+      }),
+    { wrapper },
+  );
+  act(() => {
+    result.current.patchField(7, patch);
+  });
+  await waitFor(() => expect(toast.error).toHaveBeenCalledTimes(1));
+  expect(globalThis.fetch).toHaveBeenCalledTimes(expectedCalls);
+  return vi.mocked(toast.error).mock.calls[0]?.[0];
+}
+
+describe("useWorkOrderTableMutations edit error copy", () => {
+  const originalFetch = globalThis.fetch;
+
+  beforeEach(() => {
+    vi.mocked(toast.error).mockClear();
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  it("shows generic copy instead of backend text for an unknown 422 code", async () => {
+    respondWith({
+      status: 422,
+      body: {
+        code: "InvalidLifecycleStatus",
+        message: "lifecycleStatus cannot move from Completed for workOrderId 7.",
+      },
+    });
+
+    const message = await patchAndGetToast();
+
+    expect(message).toBe(BOARD_PATCH_FAILED_MESSAGE);
+    expect(message).not.toMatch(/lifecycleStatus|workOrderId|InvalidLifecycleStatus/);
+  });
+
+  it("keeps specific copy for DispatchRequired", async () => {
+    respondWith({
+      status: 422,
+      body: {
+        code: "DispatchRequired",
+        message: "vendorId is required when setting appointment fields.",
+      },
+    });
+
+    const message = await patchAndGetToast();
+
+    expect(message).toBe(DISPATCH_REQUIRED_MESSAGE);
+  });
+
+  it("shows generic copy instead of backend text for a non-422 failure", async () => {
+    respondWith({ status: 400, body: { message: "siteCode is required for accountId 42." } });
+
+    const message = await patchAndGetToast();
+
+    expect(message).toBe(BOARD_PATCH_FAILED_MESSAGE);
+  });
+
+  it("reports a partial save in plain language without backend field keys", async () => {
+    const onPatch = vi.fn();
+    respondWith(
+      { status: 200, body: { id: 7, workOrderNumber: "WO-100", rowVersion: "v2" } },
+      {
+        status: 422,
+        body: {
+          code: "SeverityInvalid",
+          message: "severity 3 is not allowed for workOrderType Emergency.",
+        },
+      },
+    );
+
+    const message = await patchAndGetToast({ woNumber: "WO-100", severity: 3 }, 2, onPatch);
+
+    expect(message).toBe(`${PARTIAL_SAVE_PREFIX} ${BOARD_PATCH_FAILED_MESSAGE}`);
+    expect(message).not.toMatch(/severity|woNumber|workOrderType|SeverityInvalid|\d\/\d/);
+    expect(onPatch).toHaveBeenCalledWith(7, expect.objectContaining({ rowVersion: "v2" }));
+  });
+
+  it("keeps DispatchRequired copy inside a partial save", async () => {
+    respondWith(
+      { status: 200, body: { id: 7, workOrderNumber: "WO-100", rowVersion: "v2" } },
+      {
+        status: 422,
+        body: { code: "DispatchRequired", message: "vendorId is required." },
+      },
+    );
+
+    const message = await patchAndGetToast({ woNumber: "WO-100", severity: 2 }, 2);
+
+    expect(message).toBe(`${PARTIAL_SAVE_PREFIX} ${DISPATCH_REQUIRED_MESSAGE}`);
+  });
+
+  it("shows fixed conflict copy and still applies the latest row on a 409", async () => {
+    const onPatch = vi.fn();
+    respondWith({
+      status: 409,
+      body: {
+        message: "RowVersion mismatch for workOrderId 7 (expected v1, found v3).",
+        currentState: { id: 7, workOrderNumber: "WO-099", rowVersion: "v3" },
+      },
+    });
+
+    const message = await patchAndGetToast({ woNumber: "WO-100" }, 1, onPatch);
+
+    expect(message).toBe(BOARD_PATCH_CONFLICT_MESSAGE);
+    expect(message).not.toMatch(/RowVersion|workOrderId|v3/);
+    expect(onPatch).toHaveBeenLastCalledWith(7, expect.objectContaining({ rowVersion: "v3" }));
+  });
+
+  it("shows fixed conflict copy when a 409 carries no latest row", async () => {
+    respondWith({ status: 409, body: { message: "RowVersion mismatch for workOrderId 7." } });
+
+    const message = await patchAndGetToast();
+
+    expect(message).toBe(BOARD_PATCH_CONFLICT_MESSAGE);
+  });
+});