adam/shoc-frontend-new
1
0
Fork 0
mirror of https://github.com/Sea-Haven-Industries/shoc-frontend-new.git synced 2026-09-30 08:03:13 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Merge branch 'dev' into feat/ab/sh-326-team-member

Browse source
This commit is contained in:
Alexandre Brandizzi 2026-09-17 15:30:16 -03:00 • committed by GitHub
commit d53507731e
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
58 changed files with 3360 additions and 493 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

BIN
e2e/__screenshots__/dashboard/dashboard.visual.spec.ts/dashboard-admin.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 140 KiB

BIN
e2e/__screenshots__/dashboard/dashboard.visual.spec.ts/dashboard-dispatcher.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 120 KiB

256
e2e/dashboard/dashboard.visual.spec.ts Normal file
View file

@ -0,0 +1,256 @@
import { expect, test, type Page, type Route } from "@playwright/test";
const FROZEN_NOW = "2026-08-19T15:00:00.000Z";
function testUser(userRoles: string) {
return {
token: "dashboard-visual-token",
expiration: "2030-01-01T00:00:00.000Z",
email: "admin@seahavenind.com",
userRoles,
phoneNumber: "5551234567",
fullname: "Dashboard Visual User",
id: "1",
};
}
const DISPATCHERS = [
{ id: "1", name: "Pat Dispatcher" },
{ id: "2", name: "Riley Chen" },
{ id: "3", name: "Sam Okafor" },
];
const STATS = {
total: 128,
open: 52,
notDispatched: 8,
completed: 64,
dueCount: 40,
completedDueCount: 30,
completionRate: 82,
averageResolutionDays: 3.4,
scheduledTomorrow: 6,
pendingUplifts: 4,
avetaPending: 3,
breakdown: [
{ status: "PM", count: 24 },
{ status: "Emergency", count: 6 },
{ status: "Reactive", count: 12 },
{ status: "Overdue", count: 9 },
],
statusDistribution: [
{ status: "Scheduled", count: 30 },
{ status: "In Progress", count: 18 },
{ status: "Completed", count: 64 },
{ status: "Pending", count: 16 },
],
};
const WORKLOAD = {
items: [
{
dispatcherId: "1",
dispatcherName: "Pat Dispatcher",
openWorkOrders: 12,
totalWorkOrders: 20,
},
{ dispatcherId: "2", dispatcherName: "Riley Chen", openWorkOrders: 7, totalWorkOrders: 15 },
],
page: 1,
pageSize: 10,
totalDispatchers: 2,
};
const PERFORMANCE = {
items: [
{
dispatcherId: "1",
dispatcherName: "Pat Dispatcher",
completionRate: 94,
averageResolutionDays: 2.5,
assignedCount: 20,
completedCount: 18,
},
{
dispatcherId: "2",
dispatcherName: "Riley Chen",
completionRate: 78,
averageResolutionDays: 3.1,
assignedCount: 15,
completedCount: 11,
},
{
dispatcherId: "3",
dispatcherName: "Sam Okafor",
completionRate: 61,
averageResolutionDays: 4.4,
assignedCount: 9,
completedCount: 5,
},
],
page: 1,
pageSize: 10,
totalDispatchers: 3,
};
const REGIONS = {
items: [
{ region: "East", workOrderCount: 44 },
{ region: "Central", workOrderCount: 31 },
{ region: "West", workOrderCount: 22 },
{ region: "California", workOrderCount: 18 },
{ region: "Unmapped/Other", workOrderCount: 5 },
],
};
const VENDOR_INSIGHTS = {
items: [
{
vendorId: "101",
vendorName: "Gateway Plumbing",
completionRate: 88,
rescheduleRate: 12,
averageResolutionDays: 2.9,
totalJobs: 40,
},
{
vendorId: "102",
vendorName: "Summit HVAC",
completionRate: 76,
rescheduleRate: 20,
averageResolutionDays: 3.6,
totalJobs: 28,
},
],
};
const TREND = {
granularity: "week",
buckets: [
{
date: "2026-07-27",
label: "Jul 27",
total: 18,
open: 4,
completed: 12,
canceled: 1,
overdue: 1,
isCurrent: false,
},
{
date: "2026-08-03",
label: "Aug 3",
total: 22,
open: 6,
completed: 13,
canceled: 1,
overdue: 2,
isCurrent: false,
},
{
date: "2026-08-10",
label: "Aug 10",
total: 26,
open: 8,
completed: 15,
canceled: 0,
overdue: 3,
isCurrent: false,
},
{
date: "2026-08-17",
label: "Aug 17",
total: 20,
open: 9,
completed: 9,
canceled: 1,
overdue: 1,
isCurrent: true,
},
],
};
async function fulfillJson(route: Route, body: unknown, status = 200) {
await route.fulfill({ status, contentType: "application/json", body: JSON.stringify(body) });
}
async function mockDashboardApi(page: Page, userRoles: string) {
await page.clock.setFixedTime(new Date(FROZEN_NOW));
await page.addInitScript(
(user) => localStorage.setItem("auth", JSON.stringify(user)),
testUser(userRoles),
);
await page.route("**/api/**", async (route) => {
const pathname = new URL(route.request().url()).pathname;
// Only stub real backend calls; let Vite dev module requests (e.g.
// /src/domain/auth/api/*.ts) through untouched.
if (!pathname.startsWith("/api/")) {
await route.continue();
return;
}
if (pathname.includes("/Dashboard/Stats")) return fulfillJson(route, { data: STATS });
if (pathname.includes("/Dashboard/Workload")) return fulfillJson(route, { data: WORKLOAD });
if (pathname.includes("/Dashboard/Performance"))
return fulfillJson(route, { data: PERFORMANCE });
if (pathname.includes("/Dashboard/Regions")) return fulfillJson(route, { data: REGIONS });
if (pathname.includes("/Dashboard/VendorInsights")) {
return fulfillJson(route, { data: VENDOR_INSIGHTS });
}
if (pathname.includes("/Dashboard/Trend")) return fulfillJson(route, { data: TREND });
if (pathname.includes("/workorders/lookups/dispatchers")) {
return fulfillJson(route, { data: DISPATCHERS });
}
return fulfillJson(route, { data: [] });
});
}
async function openDashboard(page: Page, userRoles: string) {
await mockDashboardApi(page, userRoles);
await page.goto("/");
await page.evaluate(() => document.fonts.ready);
await page.addStyleTag({
content: `
*, *::before, *::after { transition: none !important; animation: none !important; }
.MuiDrawer-paper { transform: none !important; }
.Toastify__toast-container { display: none !important; }
.tsqd-parent-container { display: none !important; }
`,
});
}
async function expectStableScreenshot(page: Page, name: string) {
await page.waitForTimeout(250);
await page.evaluate(
() =>
new Promise<void>((resolve) =>
requestAnimationFrame(() => requestAnimationFrame(() => resolve())),
),
);
await expect(page).toHaveScreenshot(name, { fullPage: true });
}
test.describe("Dashboard deterministic pixel regression", () => {
test("admin dashboard", async ({ page }) => {
await openDashboard(page, "Admin");
await expect(page.getByRole("heading", { name: "Dashboard" })).toBeVisible();
await expect(page.getByText("Status Distribution")).toBeVisible();
await expect(page.getByText("Dispatcher Performance")).toBeVisible();
// The scope picker is available to Admin/Scheduler (SH-336).
await expect(page.getByRole("button", { name: /All dispatchers/ })).toBeVisible();
await expectStableScreenshot(page, "dashboard-admin.png");
});
test("dispatcher scoped dashboard", async ({ page }) => {
await openDashboard(page, "Dispatcher");
await expect(page.getByRole("heading", { name: "Dashboard" })).toBeVisible();
// A Dispatcher gets the static "My WOs" label and no dispatcher tables (SH-336).
await expect(page.getByText("My WOs")).toBeVisible();
await expect(page.getByText("Dispatcher Performance")).toHaveCount(0);
await expect(page.getByText("Status Distribution")).toBeVisible();
await expectStableScreenshot(page, "dashboard-dispatcher.png");
});
});

5
src/api/api-paths.ts
View file

@ -153,6 +153,11 @@ export const API_PATHS = {
},
dashboard: {
stats: "Dashboard/Stats",
workload: "Dashboard/Workload",
performance: "Dashboard/Performance",
regions: "Dashboard/Regions",
vendorInsights: "Dashboard/VendorInsights",
trend: "Dashboard/Trend",
},
dropdownOptions: {
byCategory: "DropdownOptions/ByCategory",

240
src/app/(protected)/dashboard.tsx
View file

@ -1,240 +0,0 @@
import type { ReactNode } from "react";
import { useNavigate } from "react-router";
import AddIcon from "@mui/icons-material/Add";
import CheckCircleOutlineIcon from "@mui/icons-material/CheckCircleOutlined";
import FolderOpenOutlinedIcon from "@mui/icons-material/FolderOpenOutlined";
import ScheduleOutlinedIcon from "@mui/icons-material/ScheduleOutlined";
import {
Alert,
Box,
CircularProgress,
Paper,
Stack,
Table,
TableBody,
TableCell,
TableContainer,
TableHead,
TableRow,
Typography,
} from "@mui/material";
import { useDashboardStats } from "@/domain/dashboard/use-cases/use-dashboard-stats";
const INVOICE_STATUSES = ["Draft", "Challenged", "Pending Approval", "Approved", "Paid"] as const;
const PRIORITY_LEVELS = [5, 4, 3, 2, 1] as const;
interface KpiCardProps {
title: string;
description?: string;
value?: string | number;
icon: ReactNode;
color: "success" | "primary" | "info" | "warning";
onClick: () => void;
loading?: boolean;
}
function KpiCard({ title, description, value, icon, color, onClick, loading }: KpiCardProps) {
const colorMap = {
success: "success.main",
primary: "primary.main",
info: "info.main",
warning: "warning.main",
} as const;
return (
<Paper
variant="outlined"
onClick={onClick}
className="flex min-h-[140px] flex-1 cursor-pointer transition-shadow hover:shadow-md"
sx={{
borderLeftWidth: 4,
borderLeftStyle: "solid",
borderLeftColor: colorMap[color],
}}
>
<Box className="flex w-full gap-4 p-4">
<Box
className="flex h-12 w-12 shrink-0 items-center justify-center rounded-full"
sx={{ bgcolor: `${colorMap[color]}22`, color: colorMap[color] }}
>
{icon}
</Box>
<Box className="flex min-w-0 flex-col justify-center gap-1">
<Typography variant="subtitle1" className="font-semibold">
{title}
</Typography>
{value !== undefined && (
<Typography variant="h4" component="p" className="font-bold leading-tight">
{loading ? "..." : typeof value === "number" ? value.toLocaleString() : value}
</Typography>
)}
{Boolean(description) && (
<Typography
variant="body2"
sx={{
color: "text.secondary",
}}
>
{description}
</Typography>
)}
</Box>
</Box>
</Paper>
);
}
export default function DashboardPage() {
const navigate = useNavigate();
const { data: stats, isLoading, isFetching, error } = useDashboardStats();
const formatStat = (value: number | undefined) => (isLoading ? undefined : (value ?? 0));
return (
<Box className="flex flex-col gap-4 p-4">
<Stack
direction="row"
spacing={2}
sx={{
alignItems: "baseline",
}}
>
<Typography variant="h5" component="h1">
Dashboard
</Typography>
{isFetching && !isLoading && <CircularProgress size={16} />}
</Stack>
{Boolean(error) && (
<Alert severity="error">
{error instanceof Error ? error.message : "Failed to load dashboard stats"}
</Alert>
)}
<Stack
direction={{ xs: "column", lg: "row" }}
spacing={2}
useFlexGap
sx={{
flexWrap: "wrap",
}}
>
<KpiCard
title="Create a Work Order"
description="Report a problem you need fixed"
icon={<AddIcon />}
color="success"
onClick={() => navigate("/workorders/new")}
/>
<KpiCard
title="Open Work Orders"
value={formatStat(stats?.open)}
icon={<FolderOpenOutlinedIcon />}
color="primary"
loading={isLoading}
onClick={() => navigate("/workorders")}
/>
<KpiCard
title="Not Dispatched"
value={formatStat(stats?.notDispatched)}
icon={<ScheduleOutlinedIcon />}
color="info"
loading={isLoading}
onClick={() => navigate("/workorders")}
/>
<KpiCard
title="Completed Orders"
value={formatStat(stats?.completed)}
icon={<CheckCircleOutlineIcon />}
color="warning"
loading={isLoading}
onClick={() => navigate("/workorders")}
/>
</Stack>
<Paper variant="outlined" className="overflow-hidden">
<Box className="border-b border-border px-4 py-3">
<Typography variant="h6" component="h2">
Priority Analysis
</Typography>
<Typography
variant="body2"
sx={{
color: "text.secondary",
}}
>
Age of open Work Orders by Priority
</Typography>
</Box>
<TableContainer>
<Table size="small">
<TableHead>
<TableRow>
<TableCell className="font-semibold">Priority</TableCell>
<TableCell align="right" className="font-semibold">
Total
</TableCell>
<TableCell align="right" className="font-semibold">
0-14 Days
</TableCell>
<TableCell align="right" className="font-semibold">
15-29 Days
</TableCell>
<TableCell align="right" className="font-semibold">
30-59 Days
</TableCell>
<TableCell align="right" className="font-semibold">
60+ Days
</TableCell>
</TableRow>
</TableHead>
<TableBody>
{PRIORITY_LEVELS.map((priority) => (
<TableRow key={priority}>
<TableCell>{priority}</TableCell>
<TableCell align="right">—</TableCell>
<TableCell align="right">—</TableCell>
<TableCell align="right">—</TableCell>
<TableCell align="right">—</TableCell>
<TableCell align="right">—</TableCell>
</TableRow>
))}
</TableBody>
</Table>
</TableContainer>
</Paper>
<Paper variant="outlined" className="overflow-hidden">
<Box className="border-b border-border px-4 py-3">
<Typography variant="h6" component="h2">
Invoice Analysis
</Typography>
</Box>
<TableContainer>
<Table size="small">
<TableHead>
<TableRow>
<TableCell className="font-semibold">Status</TableCell>
<TableCell align="right" className="font-semibold">
Count
</TableCell>
<TableCell align="right" className="font-semibold">
Amount
</TableCell>
</TableRow>
</TableHead>
<TableBody>
{INVOICE_STATUSES.map((status) => (
<TableRow key={status}>
<TableCell>{status}</TableCell>
<TableCell align="right">0</TableCell>
<TableCell align="right">$0.00</TableCell>
</TableRow>
))}
</TableBody>
</Table>
</TableContainer>
</Paper>
</Box>
);
}

86
src/app/(protected)/dashboard/_components/dashboard-bar-list.tsx Normal file
View file

@ -0,0 +1,86 @@
import { Box, ButtonBase } from "@mui/material";
import { Text } from "@/components/ui/text";
export interface DashboardBarListRow {
id: string;
label: string;
count: number;
}
interface DashboardBarListProps {
rows: DashboardBarListRow[];
onSelectRow?: (row: DashboardBarListRow) => void;
isSelectable?: (row: DashboardBarListRow) => boolean;
ariaLabel: string;
}
function percentOf(count: number, max: number): number {
if (max <= 0 || count <= 0) {
return 0;
}
return Math.round((count / max) * 100);
}
function BarListRow({ row, width }: { row: DashboardBarListRow; width: number }) {
return (
<Box className="flex w-full flex-col gap-1 py-1.5">
<Box className="flex items-baseline justify-between gap-2">
<Text variant="description" className="truncate">
{row.label}
</Text>
<Text variant="description" tone="muted">
{row.count.toLocaleString()}
</Text>
</Box>
<Box className="h-2 w-full overflow-hidden rounded-full" sx={{ bgcolor: "action.hover" }}>
{width > 0 && (
<Box
data-testid="dashboard-bar-mark"
className="h-full rounded-full"
sx={{ width: `${width}%`, bgcolor: "primary.main" }}
/>
)}
</Box>
</Box>
);
}
export function DashboardBarList({
rows,
onSelectRow,
isSelectable,
ariaLabel,
}: DashboardBarListProps) {
const max = Math.max(...rows.map((row) => row.count), 0);
return (
<Box aria-label={ariaLabel} className="flex flex-col">
{rows.map((row) => {
const width = percentOf(row.count, max);
const selectable = Boolean(onSelectRow) && row.count > 0 && (isSelectable?.(row) ?? true);
return selectable ? (
<ButtonBase
key={row.id}
onClick={() => onSelectRow?.(row)}
sx={{
width: "100%",
textAlign: "left",
borderRadius: 1,
px: 1,
mx: -1,
cursor: "pointer",
}}
>
<BarListRow row={row} width={width} />
</ButtonBase>
) : (
<Box key={row.id} sx={{ px: 1, mx: -1 }}>
<BarListRow row={row} width={width} />
</Box>
);
})}
</Box>
);
}

52
src/app/(protected)/dashboard/_components/dashboard-card.tsx Normal file
View file

@ -0,0 +1,52 @@
import type { ReactNode } from "react";
import { Box, CircularProgress, Paper } from "@mui/material";
import { QueryErrorPanel } from "@/components/ui/query-error-panel";
import { Text } from "@/components/ui/text";
interface DashboardCardProps {
title: string;
/** Optional scope caption shown beside the title (e.g. SH-349's all-time note). */
caption?: string;
isLoading?: boolean;
error?: unknown;
isEmpty: boolean;
emptyMessage: string;
children: ReactNode;
}
export function DashboardCard({
title,
caption,
isLoading = false,
error,
isEmpty,
emptyMessage,
children,
}: DashboardCardProps) {
return (
<Paper variant="outlined" className="flex flex-col overflow-hidden">
<Box className="flex items-baseline justify-between gap-2 border-b border-border px-4 py-3">
<Text variant="heading">{title}</Text>
{!!caption && (
<Text variant="description" tone="muted">
{caption}
</Text>
)}
</Box>
{isLoading && (
<Box className="flex items-center justify-center p-8">
<CircularProgress size={24} />
</Box>
)}
{!isLoading && Boolean(error) && <QueryErrorPanel compact className="m-4" />}
{!isLoading && !error && isEmpty && (
<Box className="p-6">
<Text variant="description" tone="muted">
{emptyMessage}
</Text>
</Box>
)}
{!isLoading && !error && !isEmpty && <Box className="p-4">{children}</Box>}
</Paper>
);
}

67
src/app/(protected)/dashboard/_components/dashboard-header-actions.tsx Normal file
View file

@ -0,0 +1,67 @@
import { Box, Button, CircularProgress } from "@mui/material";
import { Users } from "lucide-react";
import { Text } from "@/components/ui/text";
import type { WorkOrderUser } from "@/domain/work-orders/types/work-order";
import type { DashboardRangeKey } from "@/domain/dashboard/types/dashboard-range";
import { DashboardRangeToggle } from "./dashboard-range-toggle";
import { DashboardScopePicker } from "./dashboard-scope-picker";
import type { DashboardScope } from "./dashboard-scope";
interface DashboardHeaderActionsProps {
isRefreshing: boolean;
showReset: boolean;
onResetFilters: () => void;
canViewAll: boolean;
scope: DashboardScope;
onScopeChange: (scope: DashboardScope) => void;
dispatcherUsers: WorkOrderUser[];
dispatcherUsersLoading: boolean;
currentUserId: string | number | undefined;
range: DashboardRangeKey;
onRangeChange: (range: DashboardRangeKey) => void;
}
export function DashboardHeaderActions({
isRefreshing,
showReset,
onResetFilters,
canViewAll,
scope,
onScopeChange,
dispatcherUsers,
dispatcherUsersLoading,
currentUserId,
range,
onRangeChange,
}: DashboardHeaderActionsProps) {
return (
<Box className="flex items-center gap-2">
{isRefreshing && <CircularProgress size={16} />}
{showReset && (
<Button size="small" onClick={onResetFilters}>
Reset filters
</Button>
)}
{canViewAll ? (
<DashboardScopePicker
scope={scope}
onChange={onScopeChange}
users={dispatcherUsers}
usersLoading={dispatcherUsersLoading}
currentUserId={currentUserId}
/>
) : (
<Box
className="flex shrink-0 items-center gap-1.5 whitespace-nowrap"
style={{ fontSize: 13, fontWeight: 500, color: "var(--muted-foreground)" }}
>
<Users size={13} aria-hidden style={{ color: "var(--muted-foreground)" }} />
<Text variant="description" tone="muted">
My WOs
</Text>
</Box>
)}
<DashboardRangeToggle value={range} onChange={onRangeChange} />
</Box>
);
}

68
src/app/(protected)/dashboard/_components/dashboard-kpi-card.tsx Normal file
View file

@ -0,0 +1,68 @@
import type { ReactNode } from "react";
import { Box, ButtonBase, Paper } from "@mui/material";
import { Text } from "@/components/ui/text";
type KpiTone = "success" | "primary" | "info" | "warning";
const toneColor: Record<KpiTone, string> = {
success: "success.main",
primary: "primary.main",
info: "info.main",
warning: "warning.main",
};
interface DashboardKpiCardProps {
title: string;
value?: number;
icon: ReactNode;
tone: KpiTone;
loading?: boolean;
active?: boolean;
onSelect?: () => void;
}
export function DashboardKpiCard({
title,
value,
icon,
tone,
loading = false,
active = false,
onSelect,
}: DashboardKpiCardProps) {
const color = toneColor[tone];
const content = (
<Box className="flex w-full items-center gap-4 p-4" sx={{ textAlign: "left" }}>
<Box
className="flex h-12 w-12 shrink-0 items-center justify-center rounded-full"
sx={{ bgcolor: `${color}22`, color }}
>
{icon}
</Box>
<Box className="flex min-w-0 flex-col gap-0.5">
<Text variant="label" tone="muted">
{title}
</Text>
<Text variant="label" sx={{ fontSize: 28, fontWeight: 700, lineHeight: 1.2 }}>
{loading ? "…" : (value ?? 0).toLocaleString()}
</Text>
</Box>
</Box>
);
return (
<Paper
variant="outlined"
className="min-h-[104px]"
sx={{ borderLeftWidth: 4, borderLeftStyle: "solid", borderLeftColor: color }}
>
{active && Boolean(onSelect) ? (
<ButtonBase sx={{ width: "100%", cursor: "pointer" }} onClick={onSelect}>
{content}
</ButtonBase>
) : (
content
)}
</Paper>
);
}

42
src/app/(protected)/dashboard/_components/dashboard-range-toggle.tsx Normal file
View file

@ -0,0 +1,42 @@
import { ToggleButton, ToggleButtonGroup } from "@mui/material";
import { DASHBOARD_RANGES, type DashboardRangeKey } from "@/domain/dashboard/types/dashboard-range";
const RANGE_LABELS: Record<DashboardRangeKey, string> = {
"this-week": "This week",
"last-3-months": "Last 3 months",
today: "Today",
"all-time": "All time",
};
interface DashboardRangeToggleProps {
value: DashboardRangeKey;
onChange: (value: DashboardRangeKey) => void;
disabled?: boolean;
}
export function DashboardRangeToggle({
value,
onChange,
disabled = false,
}: DashboardRangeToggleProps) {
return (
<ToggleButtonGroup
exclusive
size="small"
value={value}
disabled={disabled}
aria-label="Dashboard date range"
onChange={(_, next: DashboardRangeKey | null) => {
if (next) {
onChange(next);
}
}}
>
{DASHBOARD_RANGES.map((range) => (
<ToggleButton key={range} value={range}>
{RANGE_LABELS[range]}
</ToggleButton>
))}
</ToggleButtonGroup>
);
}

118
src/app/(protected)/dashboard/_components/dashboard-scope-picker.tsx Normal file
View file

@ -0,0 +1,118 @@
import { useMemo } from "react";
import { Popover, Skeleton } from "@mui/material";
import { ChevronDown, Users } from "lucide-react";
import type { WorkOrderUser } from "@/domain/work-orders/types/work-order";
import { CheckboxMenuItem } from "@/components/ui/checkbox-menu-item";
import { MenuAnchorButton } from "@/components/ui/menu-anchor-button";
import { useMenuAnchor } from "@/hooks/use-menu-anchor";
import type { DashboardScope } from "./dashboard-scope";
type DashboardScopePickerProps = {
scope: DashboardScope;
onChange: (scope: DashboardScope) => void;
users: WorkOrderUser[];
usersLoading?: boolean;
currentUserId?: string | number;
};
export function DashboardScopePicker({
scope,
onChange,
users,
usersLoading = false,
currentUserId,
}: DashboardScopePickerProps) {
const { anchorEl, open, setAnchor, close } = useMenuAnchor();
const meId = currentUserId != null && currentUserId !== "" ? String(currentUserId) : null;
const dispatchers = useMemo(
() => [...users].sort((a, b) => a.name.localeCompare(b.name)),
[users],
);
const label = useMemo(() => {
if (scope.mode === "all") return "All dispatchers";
if (scope.mode === "mine") return "My WOs";
return dispatchers.find((user) => String(user.id) === scope.id)?.name ?? "Dispatcher";
}, [scope, dispatchers]);
const select = (next: DashboardScope) => {
onChange(next);
close();
};
if (usersLoading && users.length === 0) {
return (
<Skeleton
variant="rounded"
width={140}
height={18}
animation="wave"
aria-label="Loading dispatchers"
/>
);
}
return (
<>
<MenuAnchorButton
onAnchor={setAnchor}
open={open}
className="flex w-auto shrink-0 items-center gap-1.5 whitespace-nowrap transition-colors"
style={{ fontSize: 13, fontWeight: 500, color: "var(--muted-foreground)" }}
aria-haspopup="listbox"
>
<Users size={13} aria-hidden style={{ color: "var(--muted-foreground)" }} />
{label}
<ChevronDown size={13} aria-hidden style={{ color: "var(--muted-foreground)" }} />
</MenuAnchorButton>
<Popover
open={open}
anchorEl={anchorEl}
onClose={close}
anchorOrigin={{ vertical: "bottom", horizontal: "left" }}
transformOrigin={{ vertical: "top", horizontal: "left" }}
slotProps={{
paper: {
className: "mt-1 w-[220px] rounded-lg border border-border p-1.5 shadow-md",
},
}}
>
<CheckboxMenuItem
checked={scope.mode === "all"}
label="All dispatchers"
onClick={() => select({ mode: "all" })}
/>
{meId != null && (
<CheckboxMenuItem
checked={scope.mode === "mine"}
label="My WOs only"
labelClassName="font-medium text-primary"
className="mb-1 pb-2"
style={{ borderBottom: "1px solid var(--color-border)" }}
onClick={() => select({ mode: "mine" })}
/>
)}
{dispatchers.map((user) => {
const id = String(user.id);
return (
<CheckboxMenuItem
key={id}
checked={scope.mode === "individual" && scope.id === id}
label={user.name}
right={
meId === id ? (
<span className="text-[10px] text-muted-foreground">me</span>
) : undefined
}
onClick={() => select({ mode: "individual", id })}
/>
);
})}
</Popover>
</>
);
}

21
src/app/(protected)/dashboard/_components/dashboard-scope.ts Normal file
View file

@ -0,0 +1,21 @@
/**
* SH-336 dispatcher-scope selection. Single-select — the Dashboard scopes to at
* most one dispatcher at a time (All company / My WOs / one individual), unlike
* the board's multi-select dispatcher filter.
*/
export type DashboardScope =
{ mode: "all" } | { mode: "mine" } | { mode: "individual"; id: string };
export const DASHBOARD_SCOPE_ALL: DashboardScope = { mode: "all" };
/** Resolves the scope to the `dispatcherId` query param, or null for company-wide. */
export function scopeDispatcherId(
scope: DashboardScope,
currentUserId: string | number | undefined,
): string | null {
if (scope.mode === "all") return null;
if (scope.mode === "mine") {
return currentUserId != null && currentUserId !== "" ? String(currentUserId) : null;
}
return scope.id || null;
}

119
src/app/(protected)/dashboard/_components/dashboard-trend-card.tsx Normal file
View file

@ -0,0 +1,119 @@
import { useMemo, useState } from "react";
import { Box, IconButton } from "@mui/material";
import ArrowBackOutlinedIcon from "@mui/icons-material/ArrowBackOutlined";
import ArrowForwardOutlinedIcon from "@mui/icons-material/ArrowForwardOutlined";
import { Text } from "@/components/ui/text";
import type { DashboardRangeKey } from "@/domain/dashboard/types/dashboard-range";
import type { DashboardTrendPoint } from "@/domain/dashboard/types/dashboard-trend";
import { useDashboardTrend } from "@/domain/dashboard/use-cases/use-dashboard-trend";
import {
businessTodayIso,
dashboardRangeParams,
} from "@/domain/dashboard/utils/dashboard-range-utils";
import { DashboardCard } from "./dashboard-card";
interface DashboardTrendCardProps {
range: DashboardRangeKey;
}
function trendParams(range: DashboardRangeKey, year: number) {
if (range === "all-time") return { year };
const params = dashboardRangeParams(range);
return {
...params,
...(range === "last-3-months" ? { range: "3m" as const } : {}),
};
}
function barHeight(point: DashboardTrendPoint, max: number): number {
if (point.total <= 0 || max <= 0) return 0;
return Math.max(6, Math.round((point.total / max) * 100));
}
function TrendBar({ point, max }: { point: DashboardTrendPoint; max: number }) {
const height = barHeight(point, max);
return (
<Box
className="flex min-w-[42px] flex-1 flex-col items-center gap-1"
data-testid="dashboard-trend-point"
sx={{ borderLeft: point.isCurrent ? "2px dashed" : undefined, borderColor: "warning.main" }}
>
<Text variant="description" tone="muted">
{point.total.toLocaleString()}
</Text>
<Box className="flex h-32 items-end">
{height > 0 && (
<Box
data-testid="dashboard-trend-bar"
className="w-6 rounded-t"
sx={{
height: `${height}%`,
bgcolor: point.isCurrent ? "warning.main" : "primary.main",
}}
/>
)}
</Box>
<Text variant="description" className="max-w-16 truncate text-center" title={point.label}>
{point.label}
</Text>
{point.isCurrent && <Text variant="description">Today</Text>}
</Box>
);
}
export function DashboardTrendCard({ range }: DashboardTrendCardProps) {
const currentYear = Number(businessTodayIso().slice(0, 4));
const [year, setYear] = useState(currentYear);
const params = useMemo(() => trendParams(range, year), [range, year]);
const trend = useDashboardTrend(params);
const points = trend.data?.points ?? [];
const max = Math.max(...points.map((point) => point.total), 0);
return (
<DashboardCard
title="Work Order Trend"
isLoading={trend.isLoading}
error={trend.error}
isEmpty={!trend.isLoading && !trend.error && points.length === 0}
emptyMessage="No work orders match the current filters."
>
<Box className="flex flex-col gap-3">
<Box className="flex items-center justify-between">
<Text variant="description" tone="muted">
{trend.data?.granularity ? `${trend.data.granularity} buckets` : "Trend"}
</Text>
{range === "all-time" && (
<Box className="flex items-center">
<IconButton
aria-label="Previous year"
size="small"
onClick={() => setYear((value) => value - 1)}
>
<ArrowBackOutlinedIcon fontSize="small" />
</IconButton>
<Text variant="description">{year}</Text>
<IconButton
aria-label="Next year"
size="small"
onClick={() => setYear((value) => value + 1)}
>
<ArrowForwardOutlinedIcon fontSize="small" />
</IconButton>
</Box>
)}
</Box>
<Box
className="flex min-h-48 items-end gap-1 overflow-x-auto pb-1"
aria-label="Work Order Trend chart"
>
{points.map((point) => (
<TrendBar key={`${point.date}-${point.label}`} point={point} max={max} />
))}
</Box>
<Text variant="description" tone="muted">
The dashed marker and “Today” label identify the current business date.
</Text>
</Box>
</DashboardCard>
);
}

139
src/app/(protected)/dashboard/_components/dispatcher-performance-card.tsx Normal file
View file

@ -0,0 +1,139 @@
import { useNavigate } from "react-router";
import { Table, TableBody, TableCell, TableContainer, TableHead, TableRow } from "@mui/material";
import { Text } from "@/components/ui/text";
import type { DashboardRangeKey } from "@/domain/dashboard/types/dashboard-range";
import type { DispatcherPerformanceRow } from "@/domain/dashboard/types/dashboard-performance";
import {
workOrderDispatcherDrilldownSearch,
workOrderDrilldownUrl,
} from "@/domain/dashboard/utils/work-order-drilldown-links";
import { DashboardCard } from "./dashboard-card";
import { DispatcherTablePager } from "./dispatcher-table-pager";
const EMPTY_MESSAGE = "No dispatchers are set up yet.";
interface DispatcherPerformanceCardProps {
rows: DispatcherPerformanceRow[];
range: DashboardRangeKey;
page: number;
pageSize: number;
totalDispatchers: number;
onPageChange: (page: number) => void;
isLoading?: boolean;
error?: unknown;
}
function formatDays(value: number): string {
return (Math.round(value * 10) / 10).toLocaleString();
}
// SH-347: colour the completion rate green at 90+, amber 70–89, red below 70.
function completionRateColor(rate: number): string {
if (rate >= 90) return "success.main";
if (rate >= 70) return "warning.main";
return "error.main";
}
function DispatcherNameCell({
row,
range,
}: {
row: DispatcherPerformanceRow;
range: DashboardRangeKey;
}) {
const navigate = useNavigate();
// A listed dispatcher is one with work in range; the drill-down filters Work
// Orders by dispatcher + range and never uses the completion rate, so gate on
// identity rather than the rate. (A dispatcher with assigned work but a 0%
// rate was previously inert here while drillable from Workload.) The gate stays
// on identity rather than `assignedCount > 0` so a legacy response without the
// SH-347 count field (assignedCount → 0) keeps its rows drillable.
const drillable = Boolean(row.dispatcherId);
if (!drillable) {
return <Text variant="description">{row.dispatcherName}</Text>;
}
return (
<Text
variant="description"
as="button"
className="cursor-pointer text-left font-medium underline-offset-2 hover:underline"
onClick={() =>
navigate(workOrderDrilldownUrl(workOrderDispatcherDrilldownSearch(row.dispatcherId, range)))
}
>
{row.dispatcherName}
</Text>
);
}
export function DispatcherPerformanceCard({
rows,
range,
page,
pageSize,
totalDispatchers,
onPageChange,
isLoading = false,
error,
}: DispatcherPerformanceCardProps) {
return (
<DashboardCard
title="Dispatcher Performance"
isLoading={isLoading}
error={error}
isEmpty={!isLoading && !error && rows.length === 0}
emptyMessage={EMPTY_MESSAGE}
>
<TableContainer>
<Table size="small" aria-label="Dispatcher Performance">
<TableHead>
<TableRow>
<TableCell className="font-semibold">Dispatcher</TableCell>
<TableCell align="right" className="font-semibold">
Assigned
</TableCell>
<TableCell align="right" className="font-semibold">
Completed
</TableCell>
<TableCell align="right" className="font-semibold">
Completion %
</TableCell>
<TableCell align="right" className="font-semibold">
Avg days
</TableCell>
</TableRow>
</TableHead>
<TableBody>
{rows.map((row) => (
<TableRow key={row.dispatcherId || row.dispatcherName}>
<TableCell>
<DispatcherNameCell row={row} range={range} />
</TableCell>
<TableCell align="right">{row.assignedCount.toLocaleString()}</TableCell>
<TableCell align="right">{row.completedCount.toLocaleString()}</TableCell>
<TableCell
align="right"
sx={{ color: completionRateColor(row.completionRate), fontWeight: 600 }}
>
{`${row.completionRate.toLocaleString()}%`}
</TableCell>
<TableCell align="right">
{row.averageResolutionDays == null ? "—" : formatDays(row.averageResolutionDays)}
</TableCell>
</TableRow>
))}
</TableBody>
</Table>
</TableContainer>
<DispatcherTablePager
page={page}
pageSize={pageSize}
totalDispatchers={totalDispatchers}
onPageChange={onPageChange}
label="Dispatcher Performance pagination"
/>
</DashboardCard>
);
}

40
src/app/(protected)/dashboard/_components/dispatcher-table-pager.tsx Normal file
View file

@ -0,0 +1,40 @@
import { Box, Pagination } from "@mui/material";
interface DispatcherTablePagerProps {
page: number;
pageSize: number;
totalDispatchers: number;
onPageChange: (page: number) => void;
label: string;
}
/**
* 10-row pager for the dispatcher tables (SH-346/SH-347). Renders nothing until
* there is more than one page, so single-page tables are unchanged.
*/
export function DispatcherTablePager({
page,
pageSize,
totalDispatchers,
onPageChange,
label,
}: DispatcherTablePagerProps) {
const pageCount = pageSize > 0 ? Math.ceil(totalDispatchers / pageSize) : 1;
if (pageCount <= 1) {
return null;
}
return (
<Box className="mt-3 flex justify-end">
<Pagination
size="small"
color="primary"
count={pageCount}
page={page}
onChange={(_event, value) => onPageChange(value)}
aria-label={label}
/>
</Box>
);
}

60
src/app/(protected)/dashboard/_components/dispatcher-tables-section.tsx Normal file
View file

@ -0,0 +1,60 @@
import type { UseQueryResult } from "@tanstack/react-query";
import {
DISPATCHER_PAGE_SIZE,
type DispatcherPage,
} from "@/domain/dashboard/types/dashboard-dispatcher-page";
import type { DashboardRangeKey } from "@/domain/dashboard/types/dashboard-range";
import type { DispatcherPerformanceRow } from "@/domain/dashboard/types/dashboard-performance";
import type { DispatcherWorkloadRow } from "@/domain/dashboard/types/dashboard-workload";
import { DispatcherPerformanceCard } from "./dispatcher-performance-card";
import { DispatcherWorkloadCard } from "./dispatcher-workload-card";
interface DispatcherTablesSectionProps {
range: DashboardRangeKey;
workload: UseQueryResult<DispatcherPage<DispatcherWorkloadRow>, Error>;
performance: UseQueryResult<DispatcherPage<DispatcherPerformanceRow>, Error>;
workloadPage: number;
performancePage: number;
onWorkloadPageChange: (page: number) => void;
onPerformancePageChange: (page: number) => void;
}
/**
* The two paged dispatcher tables. Kept as a fragment so both cards stay direct
* children of the dashboard grid, and so the paging view-model derivation lives
* here rather than inflating the page component.
*/
export function DispatcherTablesSection({
range,
workload,
performance,
workloadPage,
performancePage,
onWorkloadPageChange,
onPerformancePageChange,
}: DispatcherTablesSectionProps) {
return (
<>
<DispatcherWorkloadCard
rows={workload.data?.items ?? []}
range={range}
page={workloadPage}
pageSize={workload.data?.pageSize ?? DISPATCHER_PAGE_SIZE}
totalDispatchers={workload.data?.totalDispatchers ?? 0}
onPageChange={onWorkloadPageChange}
isLoading={workload.isLoading}
error={workload.error}
/>
<DispatcherPerformanceCard
rows={performance.data?.items ?? []}
range={range}
page={performancePage}
pageSize={performance.data?.pageSize ?? DISPATCHER_PAGE_SIZE}
totalDispatchers={performance.data?.totalDispatchers ?? 0}
onPageChange={onPerformancePageChange}
isLoading={performance.isLoading}
error={performance.error}
/>
</>
);
}

107
src/app/(protected)/dashboard/_components/dispatcher-workload-card.tsx Normal file
View file

@ -0,0 +1,107 @@
import { useNavigate } from "react-router";
import { Table, TableBody, TableCell, TableContainer, TableHead, TableRow } from "@mui/material";
import { Text } from "@/components/ui/text";
import type { DashboardRangeKey } from "@/domain/dashboard/types/dashboard-range";
import type { DispatcherWorkloadRow } from "@/domain/dashboard/types/dashboard-workload";
import {
workOrderDispatcherDrilldownSearch,
workOrderDrilldownUrl,
} from "@/domain/dashboard/utils/work-order-drilldown-links";
import { DashboardCard } from "./dashboard-card";
import { DispatcherTablePager } from "./dispatcher-table-pager";
const EMPTY_MESSAGE = "No dispatchers are set up yet.";
interface DispatcherWorkloadCardProps {
rows: DispatcherWorkloadRow[];
range: DashboardRangeKey;
page: number;
pageSize: number;
totalDispatchers: number;
onPageChange: (page: number) => void;
isLoading?: boolean;
error?: unknown;
}
function DispatcherNameCell({
row,
range,
}: {
row: DispatcherWorkloadRow;
range: DashboardRangeKey;
}) {
const navigate = useNavigate();
const drillable = Boolean(row.dispatcherId) && row.totalWorkOrders > 0;
if (!drillable) {
return <Text variant="description">{row.dispatcherName}</Text>;
}
return (
<Text
variant="description"
as="button"
className="cursor-pointer text-left font-medium underline-offset-2 hover:underline"
onClick={() =>
navigate(workOrderDrilldownUrl(workOrderDispatcherDrilldownSearch(row.dispatcherId, range)))
}
>
{row.dispatcherName}
</Text>
);
}
export function DispatcherWorkloadCard({
rows,
range,
page,
pageSize,
totalDispatchers,
onPageChange,
isLoading = false,
error,
}: DispatcherWorkloadCardProps) {
return (
<DashboardCard
title="Dispatcher Workload"
isLoading={isLoading}
error={error}
isEmpty={!isLoading && !error && rows.length === 0}
emptyMessage={EMPTY_MESSAGE}
>
<TableContainer>
<Table size="small" aria-label="Dispatcher Workload">
<TableHead>
<TableRow>
<TableCell className="font-semibold">Dispatcher</TableCell>
<TableCell align="right" className="font-semibold">
Open
</TableCell>
<TableCell align="right" className="font-semibold">
Total
</TableCell>
</TableRow>
</TableHead>
<TableBody>
{rows.map((row) => (
<TableRow key={row.dispatcherId || row.dispatcherName}>
<TableCell>
<DispatcherNameCell row={row} range={range} />
</TableCell>
<TableCell align="right">{row.openWorkOrders.toLocaleString()}</TableCell>
<TableCell align="right">{row.totalWorkOrders.toLocaleString()}</TableCell>
</TableRow>
))}
</TableBody>
</Table>
</TableContainer>
<DispatcherTablePager
page={page}
pageSize={pageSize}
totalDispatchers={totalDispatchers}
onPageChange={onPageChange}
label="Dispatcher Workload pagination"
/>
</DashboardCard>
);
}

55
src/app/(protected)/dashboard/_components/status-distribution-card.tsx Normal file
View file

@ -0,0 +1,55 @@
import { useNavigate } from "react-router";
import { ALL_WIZARD_STATUSES } from "@/domain/work-orders/types/work-order-wizard";
import type { DashboardRangeKey } from "@/domain/dashboard/types/dashboard-range";
import type { DashboardStatusBucketRow } from "@/domain/dashboard/types/dashboard-stats";
import {
workOrderDrilldownUrl,
workOrderStatusDrilldownSearch,
} from "@/domain/dashboard/utils/work-order-drilldown-links";
import { DashboardBarList } from "./dashboard-bar-list";
import { DashboardCard } from "./dashboard-card";
const EMPTY_MESSAGE = "No work orders match the current filters.";
const DRILLABLE_STATUSES = new Set<string>(ALL_WIZARD_STATUSES);
interface StatusDistributionCardProps {
rows: DashboardStatusBucketRow[];
range: DashboardRangeKey;
isLoading?: boolean;
error?: unknown;
}
export function StatusDistributionCard({
rows,
range,
isLoading = false,
error,
}: StatusDistributionCardProps) {
const navigate = useNavigate();
return (
<DashboardCard
title="Status Distribution"
isLoading={isLoading}
error={error}
isEmpty={!isLoading && !error && rows.length === 0}
emptyMessage={EMPTY_MESSAGE}
>
<DashboardBarList
ariaLabel="Status Distribution"
rows={rows.map((row) => ({
id: row.status,
label: row.status,
count: row.count,
}))}
// Lifecycle labels the board can filter on are drillable; the "Unknown"
// bucket (unparseable statuses) has no board filter, so leave it inert.
isSelectable={(row) => DRILLABLE_STATUSES.has(row.id)}
onSelectRow={(row) =>
navigate(workOrderDrilldownUrl(workOrderStatusDrilldownSearch(row.id, range)))
}
/>
</DashboardCard>
);
}

87
src/app/(protected)/dashboard/_components/use-dashboard-scope.ts Normal file
View file

@ -0,0 +1,87 @@
import { useState } from "react";
import { canViewAllDispatchersOnDashboard } from "@/lib/auth/user-utils";
import { useAuthContext } from "@/providers/auth-context";
import {
DEFAULT_DASHBOARD_RANGE,
type DashboardRangeKey,
} from "@/domain/dashboard/types/dashboard-range";
import { DASHBOARD_SCOPE_ALL, scopeDispatcherId, type DashboardScope } from "./dashboard-scope";
export interface DashboardScopeState {
canViewAll: boolean;
currentUserId: string | number | undefined;
range: DashboardRangeKey;
scope: DashboardScope;
/** The `dispatcherId` query param for the scoped endpoints (null = company-wide). */
dispatcherId: string | null;
workloadPage: number;
performancePage: number;
showReset: boolean;
setWorkloadPage: (page: number) => void;
setPerformancePage: (page: number) => void;
changeRange: (next: DashboardRangeKey) => void;
changeScope: (next: DashboardScope) => void;
resetFilters: () => void;
}
/**
* SH-336 dashboard scope/paging state. A Dispatcher (no
* `viewAllDispatchersOnDashboard`) is locked to their own work orders and sends
* no dispatcherId; Scheduler/Admin drive an explicit scope through the picker.
*/
export function useDashboardScope(): DashboardScopeState {
const { user } = useAuthContext();
const canViewAll = canViewAllDispatchersOnDashboard(user?.userRoles);
const [range, setRange] = useState<DashboardRangeKey>(DEFAULT_DASHBOARD_RANGE);
const [scope, setScope] = useState<DashboardScope>(DASHBOARD_SCOPE_ALL);
const [workloadPage, setWorkloadPage] = useState(1);
const [performancePage, setPerformancePage] = useState(1);
const dispatcherId = canViewAll ? scopeDispatcherId(scope, user?.id) : null;
// A range or scope change re-scopes both dispatcher tables, so their page must
// reset — otherwise a switch while on page 3 lands on an out-of-range empty
// page that reads as a false "no dispatchers" state.
const resetPages = () => {
setWorkloadPage(1);
setPerformancePage(1);
};
const changeRange = (next: DashboardRangeKey) => {
setRange(next);
resetPages();
};
const changeScope = (next: DashboardScope) => {
setScope(next);
resetPages();
};
const resetFilters = () => {
setRange(DEFAULT_DASHBOARD_RANGE);
setScope(DASHBOARD_SCOPE_ALL);
resetPages();
};
// A Dispatcher's forced own-WOs scope never triggers the reset affordance (only
// an active date range can, for that role); a Scheduler/Admin's non-All scope does.
const scopeIsFiltered = canViewAll && scope.mode !== "all";
const showReset = range !== DEFAULT_DASHBOARD_RANGE || scopeIsFiltered;
return {
canViewAll,
currentUserId: user?.id,
range,
scope,
dispatcherId,
workloadPage,
performancePage,
showReset,
setWorkloadPage,
setPerformancePage,
changeRange,
changeScope,
resetFilters,
};
}

64
src/app/(protected)/dashboard/_components/vendor-insights-card.tsx Normal file
View file

@ -0,0 +1,64 @@
import { Table, TableBody, TableCell, TableContainer, TableHead, TableRow } from "@mui/material";
import { Text } from "@/components/ui/text";
import type { VendorInsightRow } from "@/domain/dashboard/types/dashboard-vendor-insights";
import { DashboardCard } from "./dashboard-card";
const EMPTY_MESSAGE = "No active vendor has any work orders yet.";
interface VendorInsightsCardProps {
rows: VendorInsightRow[];
isLoading?: boolean;
error?: unknown;
}
export function VendorInsightsCard({ rows, isLoading = false, error }: VendorInsightsCardProps) {
return (
<DashboardCard
title="Vendor Insights"
caption="All-time, company-wide"
isLoading={isLoading}
error={error}
isEmpty={!isLoading && !error && rows.length === 0}
emptyMessage={EMPTY_MESSAGE}
>
<TableContainer>
<Table size="small" aria-label="Vendor Insights">
<TableHead>
<TableRow>
<TableCell className="font-semibold">Vendor</TableCell>
<TableCell align="right" className="font-semibold">
Completion %
</TableCell>
<TableCell align="right" className="font-semibold">
Reschedule %
</TableCell>
<TableCell align="right" className="font-semibold">
Avg days
</TableCell>
<TableCell align="right" className="font-semibold">
Jobs
</TableCell>
</TableRow>
</TableHead>
<TableBody>
{rows.map((row) => (
<TableRow key={row.vendorId || row.vendorName}>
<TableCell>
<Text variant="description">{row.vendorName}</Text>
</TableCell>
<TableCell align="right">{`${row.completionRate.toLocaleString()}%`}</TableCell>
<TableCell align="right">{`${row.rescheduleRate.toLocaleString()}%`}</TableCell>
<TableCell align="right">
{row.averageResolutionDays == null
? "—"
: row.averageResolutionDays.toLocaleString()}
</TableCell>
<TableCell align="right">{row.totalJobs.toLocaleString()}</TableCell>
</TableRow>
))}
</TableBody>
</Table>
</TableContainer>
</DashboardCard>
);
}

47
src/app/(protected)/dashboard/_components/work-order-breakdown-card.tsx Normal file
View file

@ -0,0 +1,47 @@
import { useNavigate } from "react-router";
import type { DashboardRangeKey } from "@/domain/dashboard/types/dashboard-range";
import type { DashboardBreakdownRow } from "@/domain/dashboard/types/dashboard-stats";
import {
workOrderDrilldownUrl,
workOrderTypeDrilldownSearch,
} from "@/domain/dashboard/utils/work-order-drilldown-links";
import { DashboardBarList } from "./dashboard-bar-list";
import { DashboardCard } from "./dashboard-card";
const EMPTY_MESSAGE = "No work orders match the current filters.";
interface WorkOrderBreakdownCardProps {
breakdown: DashboardBreakdownRow[];
range: DashboardRangeKey;
isLoading?: boolean;
error?: unknown;
}
export function WorkOrderBreakdownCard({
breakdown,
range,
isLoading = false,
error,
}: WorkOrderBreakdownCardProps) {
const navigate = useNavigate();
return (
<DashboardCard
title="Work Order Breakdown"
isLoading={isLoading}
error={error}
isEmpty={!isLoading && !error && breakdown.length === 0}
emptyMessage={EMPTY_MESSAGE}
>
<DashboardBarList
ariaLabel="Work Order Breakdown"
rows={breakdown.map((row) => ({ id: row.status, label: row.status, count: row.count }))}
isSelectable={(row) => workOrderTypeDrilldownSearch(row.id, range) !== null}
onSelectRow={(row) => {
const search = workOrderTypeDrilldownSearch(row.id, range);
if (search) navigate(workOrderDrilldownUrl(search));
}}
/>
</DashboardCard>
);
}

57
src/app/(protected)/dashboard/_components/work-orders-by-region-card.tsx Normal file
View file

@ -0,0 +1,57 @@
import { useNavigate } from "react-router";
import type { DashboardRangeKey } from "@/domain/dashboard/types/dashboard-range";
import {
UNMAPPED_REGION_LABEL,
type RegionWorkOrdersRow,
} from "@/domain/dashboard/types/dashboard-regions";
import {
workOrderDrilldownUrl,
workOrderRegionDrilldownSearch,
} from "@/domain/dashboard/utils/work-order-drilldown-links";
import { DashboardBarList } from "./dashboard-bar-list";
import { DashboardCard } from "./dashboard-card";
const EMPTY_MESSAGE = "No work orders match the current filters.";
interface WorkOrdersByRegionCardProps {
rows: RegionWorkOrdersRow[];
range: DashboardRangeKey;
isLoading?: boolean;
error?: unknown;
}
export function WorkOrdersByRegionCard({
rows,
range,
isLoading = false,
error,
}: WorkOrdersByRegionCardProps) {
const navigate = useNavigate();
// SH-348 open point: the "Unmapped/Other" bucket is proposed but not yet
// confirmed with the client ("do not implement until confirmed"), so only the
// four canonical zones are shown.
const zones = rows.filter((row) => row.region !== UNMAPPED_REGION_LABEL);
return (
<DashboardCard
title="Work Orders by Region"
isLoading={isLoading}
error={error}
isEmpty={!isLoading && !error && zones.length === 0}
emptyMessage={EMPTY_MESSAGE}
>
<DashboardBarList
ariaLabel="Work Orders by Region"
rows={zones.map((row) => ({
id: row.region,
label: row.region,
count: row.workOrderCount,
}))}
onSelectRow={(row) =>
navigate(workOrderDrilldownUrl(workOrderRegionDrilldownSearch(row.id, range)))
}
/>
</DashboardCard>
);
}

133
src/app/(protected)/dashboard/index.tsx Normal file
View file

@ -0,0 +1,133 @@
import { useNavigate } from "react-router";
import EventOutlinedIcon from "@mui/icons-material/EventOutlined";
import PendingActionsIcon from "@mui/icons-material/PendingActions";
import ShieldOutlinedIcon from "@mui/icons-material/ShieldOutlined";
import { Box } from "@mui/material";
import { PageHeader } from "@/components/ui/page-header";
import { DashboardHeaderActions } from "@/app/(protected)/dashboard/_components/dashboard-header-actions";
import { DashboardKpiCard } from "@/app/(protected)/dashboard/_components/dashboard-kpi-card";
import { DashboardTrendCard } from "@/app/(protected)/dashboard/_components/dashboard-trend-card";
import { DispatcherTablesSection } from "@/app/(protected)/dashboard/_components/dispatcher-tables-section";
import { StatusDistributionCard } from "@/app/(protected)/dashboard/_components/status-distribution-card";
import { useDashboardScope } from "@/app/(protected)/dashboard/_components/use-dashboard-scope";
import { VendorInsightsCard } from "@/app/(protected)/dashboard/_components/vendor-insights-card";
import { WorkOrderBreakdownCard } from "@/app/(protected)/dashboard/_components/work-order-breakdown-card";
import { WorkOrdersByRegionCard } from "@/app/(protected)/dashboard/_components/work-orders-by-region-card";
import { useDashboardPerformance } from "@/domain/dashboard/use-cases/use-dashboard-performance";
import { useDashboardRegions } from "@/domain/dashboard/use-cases/use-dashboard-regions";
import { useDashboardStats } from "@/domain/dashboard/use-cases/use-dashboard-stats";
import { useDashboardVendorInsights } from "@/domain/dashboard/use-cases/use-dashboard-vendor-insights";
import { useDashboardWorkload } from "@/domain/dashboard/use-cases/use-dashboard-workload";
import { useWorkOrderUsers } from "@/domain/work-orders/use-cases/use-work-orders-list";
import {
avetaPendingDrilldownSearch,
scheduledTomorrowDrilldownSearch,
UPLIFTS_ROUTE,
workOrderDrilldownUrl,
} from "@/domain/dashboard/utils/work-order-drilldown-links";
export default function DashboardPage() {
const navigate = useNavigate();
const scope = useDashboardScope();
const { canViewAll, range, dispatcherId, workloadPage, performancePage } = scope;
const dispatcherUsers = useWorkOrderUsers();
const stats = useDashboardStats(range, dispatcherId);
const workload = useDashboardWorkload(range, workloadPage, dispatcherId, canViewAll);
const performance = useDashboardPerformance(range, performancePage, dispatcherId, canViewAll);
const regions = useDashboardRegions(range, dispatcherId);
const vendors = useDashboardVendorInsights();
const isRefreshing =
[stats, workload, performance, regions, vendors].some((query) => query.isFetching) &&
!stats.isLoading;
return (
<Box className="flex flex-col gap-4 p-4">
<PageHeader
title="Dashboard"
actions={
<DashboardHeaderActions
isRefreshing={isRefreshing}
showReset={scope.showReset}
onResetFilters={scope.resetFilters}
canViewAll={canViewAll}
scope={scope.scope}
onScopeChange={scope.changeScope}
dispatcherUsers={dispatcherUsers.data ?? []}
dispatcherUsersLoading={dispatcherUsers.isLoading}
currentUserId={scope.currentUserId}
range={range}
onRangeChange={scope.changeRange}
/>
}
/>
<Box className="grid grid-cols-1 gap-4 md:grid-cols-2 lg:grid-cols-3">
<DashboardKpiCard
title="Scheduled Tomorrow"
icon={<EventOutlinedIcon />}
tone="primary"
value={stats.data?.scheduledTomorrow}
loading={stats.isLoading}
active={(stats.data?.scheduledTomorrow ?? 0) > 0}
onSelect={() => navigate(workOrderDrilldownUrl(scheduledTomorrowDrilldownSearch()))}
/>
<DashboardKpiCard
title="Pending Uplifts"
icon={<PendingActionsIcon />}
tone="info"
value={stats.data?.pendingUplifts}
loading={stats.isLoading}
active={(stats.data?.pendingUplifts ?? 0) > 0}
onSelect={() => navigate(UPLIFTS_ROUTE)}
/>
<DashboardKpiCard
title="Aveta Pending"
icon={<ShieldOutlinedIcon />}
tone="warning"
value={stats.data?.avetaPending}
loading={stats.isLoading}
active={(stats.data?.avetaPending ?? 0) > 0}
onSelect={() => navigate(workOrderDrilldownUrl(avetaPendingDrilldownSearch()))}
/>
</Box>
<Box className="grid grid-cols-1 gap-4 lg:grid-cols-2">
<WorkOrderBreakdownCard
breakdown={stats.data?.breakdown ?? []}
range={range}
isLoading={stats.isLoading}
error={stats.error}
/>
<StatusDistributionCard
rows={stats.data?.statusDistribution ?? []}
range={range}
isLoading={stats.isLoading}
error={stats.error}
/>
<WorkOrdersByRegionCard
rows={regions.data ?? []}
range={range}
isLoading={regions.isLoading}
error={regions.error}
/>
{canViewAll && (
<DispatcherTablesSection
range={range}
workload={workload}
performance={performance}
workloadPage={workloadPage}
performancePage={performancePage}
onWorkloadPageChange={scope.setWorkloadPage}
onPerformancePageChange={scope.setPerformancePage}
/>
)}
</Box>
<DashboardTrendCard range={range} />
<VendorInsightsCard
rows={vendors.data ?? []}
isLoading={vendors.isLoading}
error={vendors.error}
/>
</Box>
);
}

241
src/app/(protected)/index.tsx
View file

@ -1,240 +1,5 @@
import type { ReactNode } from "react";
import { useNavigate } from "react-router";
import AddIcon from "@mui/icons-material/Add";
import CheckCircleOutlineIcon from "@mui/icons-material/CheckCircleOutlined";
import FolderOpenOutlinedIcon from "@mui/icons-material/FolderOpenOutlined";
import ScheduleOutlinedIcon from "@mui/icons-material/ScheduleOutlined";
import {
Alert,
Box,
CircularProgress,
Paper,
Stack,
Table,
TableBody,
TableCell,
TableContainer,
TableHead,
TableRow,
Typography,
} from "@mui/material";
import { useDashboardStats } from "@/domain/dashboard/use-cases/use-dashboard-stats";
import DashboardPage from "@/app/(protected)/dashboard";
const INVOICE_STATUSES = ["Draft", "Challenged", "Pending Approval", "Approved", "Paid"] as const;
const PRIORITY_LEVELS = [5, 4, 3, 2, 1] as const;
interface KpiCardProps {
title: string;
description?: string;
value?: string | number;
icon: ReactNode;
color: "success" | "primary" | "info" | "warning";
onClick: () => void;
loading?: boolean;
}
function KpiCard({ title, description, value, icon, color, onClick, loading }: KpiCardProps) {
const colorMap = {
success: "success.main",
primary: "primary.main",
info: "info.main",
warning: "warning.main",
} as const;
return (
<Paper
variant="outlined"
onClick={onClick}
className="flex min-h-[140px] flex-1 cursor-pointer transition-shadow hover:shadow-md"
sx={{
borderLeftWidth: 4,
borderLeftStyle: "solid",
borderLeftColor: colorMap[color],
}}
>
<Box className="flex w-full gap-4 p-4">
<Box
className="flex h-12 w-12 shrink-0 items-center justify-center rounded-full"
sx={{ bgcolor: `${colorMap[color]}22`, color: colorMap[color] }}
>
{icon}
</Box>
<Box className="flex min-w-0 flex-col justify-center gap-1">
<Typography variant="subtitle1" className="font-semibold">
{title}
</Typography>
{value !== undefined && (
<Typography variant="h4" component="p" className="font-bold leading-tight">
{loading ? "..." : typeof value === "number" ? value.toLocaleString() : value}
</Typography>
)}
{Boolean(description) && (
<Typography
variant="body2"
sx={{
color: "text.secondary",
}}
>
{description}
</Typography>
)}
</Box>
</Box>
</Paper>
);
}
export default function DashboardPage() {
const navigate = useNavigate();
const { data: stats, isLoading, isFetching, error } = useDashboardStats();
const formatStat = (value: number | undefined) => (isLoading ? undefined : (value ?? 0));
return (
<Box className="flex flex-col gap-4 p-4">
<Stack
direction="row"
spacing={2}
sx={{
alignItems: "baseline",
}}
>
<Typography variant="h5" component="h1">
Dashboard
</Typography>
{isFetching && !isLoading && <CircularProgress size={16} />}
</Stack>
{Boolean(error) && (
<Alert severity="error">
{error instanceof Error ? error.message : "Failed to load dashboard stats"}
</Alert>
)}
<Stack
direction={{ xs: "column", lg: "row" }}
spacing={2}
useFlexGap
sx={{
flexWrap: "wrap",
}}
>
<KpiCard
title="Create a Work Order"
description="Report a problem you need fixed"
icon={<AddIcon />}
color="success"
onClick={() => navigate("/workorders/new")}
/>
<KpiCard
title="Open Work Orders"
value={formatStat(stats?.open)}
icon={<FolderOpenOutlinedIcon />}
color="primary"
loading={isLoading}
onClick={() => navigate("/workorders")}
/>
<KpiCard
title="Not Dispatched"
value={formatStat(stats?.notDispatched)}
icon={<ScheduleOutlinedIcon />}
color="info"
loading={isLoading}
onClick={() => navigate("/workorders")}
/>
<KpiCard
title="Completed Orders"
value={formatStat(stats?.completed)}
icon={<CheckCircleOutlineIcon />}
color="warning"
loading={isLoading}
onClick={() => navigate("/workorders")}
/>
</Stack>
<Paper variant="outlined" className="overflow-hidden">
<Box className="border-b border-border px-4 py-3">
<Typography variant="h6" component="h2">
Priority Analysis
</Typography>
<Typography
variant="body2"
sx={{
color: "text.secondary",
}}
>
Age of open Work Orders by Priority
</Typography>
</Box>
<TableContainer>
<Table size="small">
<TableHead>
<TableRow>
<TableCell className="font-semibold">Priority</TableCell>
<TableCell align="right" className="font-semibold">
Total
</TableCell>
<TableCell align="right" className="font-semibold">
0-14 Days
</TableCell>
<TableCell align="right" className="font-semibold">
15-29 Days
</TableCell>
<TableCell align="right" className="font-semibold">
30-59 Days
</TableCell>
<TableCell align="right" className="font-semibold">
60+ Days
</TableCell>
</TableRow>
</TableHead>
<TableBody>
{PRIORITY_LEVELS.map((priority) => (
<TableRow key={priority}>
<TableCell>{priority}</TableCell>
<TableCell align="right">—</TableCell>
<TableCell align="right">—</TableCell>
<TableCell align="right">—</TableCell>
<TableCell align="right">—</TableCell>
<TableCell align="right">—</TableCell>
</TableRow>
))}
</TableBody>
</Table>
</TableContainer>
</Paper>
<Paper variant="outlined" className="overflow-hidden">
<Box className="border-b border-border px-4 py-3">
<Typography variant="h6" component="h2">
Invoice Analysis
</Typography>
</Box>
<TableContainer>
<Table size="small">
<TableHead>
<TableRow>
<TableCell className="font-semibold">Status</TableCell>
<TableCell align="right" className="font-semibold">
Count
</TableCell>
<TableCell align="right" className="font-semibold">
Amount
</TableCell>
</TableRow>
</TableHead>
<TableBody>
{INVOICE_STATUSES.map((status) => (
<TableRow key={status}>
<TableCell>{status}</TableCell>
<TableCell align="right">0</TableCell>
<TableCell align="right">$0.00</TableCell>
</TableRow>
))}
</TableBody>
</Table>
</TableContainer>
</Paper>
</Box>
);
export default function HomePage() {
return <DashboardPage />;
}

37
src/app/(protected)/workorders/_hooks/use-dashboard-drilldown-filters.ts Normal file
View file

@ -0,0 +1,37 @@
import { useEffect, useRef, useState } from "react";
import { useSearchParams } from "react-router";
import type { WorkOrderAdvancedFilters } from "@/domain/work-orders/types/work-order-advanced-filters";
import { parseDashboardDrilldownParams } from "@/domain/work-orders/utils/dashboard-drilldown-params";
export function useDashboardDrilldownFilters(
onApply: (filters: WorkOrderAdvancedFilters) => void,
): boolean {
const [searchParams, setSearchParams] = useSearchParams();
const appliedRef = useRef(false);
// Hold onApply in a ref so a caller passing a fresh closure each render does not
// re-run the apply effect; it should fire only when the URL search params change.
const onApplyRef = useRef(onApply);
const [fromDashboard, setFromDashboard] = useState(false);
useEffect(() => {
onApplyRef.current = onApply;
}, [onApply]);
useEffect(() => {
if (appliedRef.current) {
return;
}
const drilldown = parseDashboardDrilldownParams(searchParams);
if (!drilldown) {
return;
}
appliedRef.current = true;
setFromDashboard(true);
onApplyRef.current(drilldown);
setSearchParams({}, { replace: true });
}, [searchParams, setSearchParams]);
return fromDashboard;
}

11
src/app/(protected)/workorders/index.tsx
View file

@ -1,4 +1,5 @@
import { Box } from "@mui/material";
import { Box, Link as MuiLink } from "@mui/material";
import { Link as RouterLink } from "react-router";
import { PageHeader } from "@/components/ui/page-header";
import { QueryErrorPanel } from "@/components/ui/query-error-panel";
import { WorkOrdersAdvancedFiltersBanner } from "@/app/(protected)/workorders/_components/list/work-orders-advanced-filters-banner";
@ -8,6 +9,7 @@ import { WorkOrdersListHeader } from "@/app/(protected)/workorders/_components/l
import { WorkOrdersListPagePanels } from "@/app/(protected)/workorders/_components/list/work-orders-list-page-panels";
import { WoTable } from "@/app/(protected)/workorders/_components/list/table/wo-table";
import { useWorkOrdersListPage } from "@/app/(protected)/workorders/_hooks/use-work-orders-list-page";
import { useDashboardDrilldownFilters } from "@/app/(protected)/workorders/_hooks/use-dashboard-drilldown-filters";
import type { WorkOrderTableRow } from "@/domain/work-orders/types/work-order-table-row";
import { hasCompletionDocService } from "@/domain/work-orders/utils/completion-doc-service-gate";
import { useAuthContext } from "@/providers/auth-context";
@ -24,6 +26,7 @@ export default function WorkOrdersListPage() {
const { user } = useAuthContext();
const page = useWorkOrdersListPage();
const { filters, tableData } = page;
const fromDashboard = useDashboardDrilldownFilters(filters.applyAdvancedFilters);
return (
<Box className="flex h-full flex-col overflow-hidden p-2.5">
@ -54,6 +57,12 @@ export default function WorkOrdersListPage() {
}
/>
{fromDashboard && (
<MuiLink component={RouterLink} to="/" underline="hover" className="mb-2 self-start">
Back to Dashboard
</MuiLink>
)}
<WorkOrdersFilterBar
weekMonday={filters.weekMonday}
onWeekChange={filters.setWeekMonday}

404
src/domain/dashboard/api/dashboard-api.ts
View file

@ -1,7 +1,30 @@
import { API_PATHS } from "@/api/api-paths";
import { apiGet } from "@/api/api";
import { handleApiResponse } from "@/api/handle-api-response";
import type { DashboardStats } from "@/domain/dashboard/types/dashboard-stats";
import type { Options } from "ky";
import type { DashboardRangeParams } from "@/domain/dashboard/types/dashboard-range";
import type {
DashboardBreakdownRow,
DashboardStats,
DashboardStatusBucketRow,
} from "@/domain/dashboard/types/dashboard-stats";
import type { DispatcherPerformanceRow } from "@/domain/dashboard/types/dashboard-performance";
import {
DISPATCHER_PAGE_SIZE,
type DispatcherPage,
} from "@/domain/dashboard/types/dashboard-dispatcher-page";
import type { DashboardTrendParams } from "@/domain/dashboard/types/dashboard-trend";
import type {
DashboardTrend,
DashboardTrendGranularity,
} from "@/domain/dashboard/types/dashboard-trend";
import {
UNMAPPED_REGION_LABEL,
type RegionWorkOrdersRow,
} from "@/domain/dashboard/types/dashboard-regions";
import type { DispatcherWorkloadRow } from "@/domain/dashboard/types/dashboard-workload";
import type { VendorInsightRow } from "@/domain/dashboard/types/dashboard-vendor-insights";
import { WO_TYPES } from "@/domain/work-orders/types/work-order-wizard";
function toNumber(value: unknown): number {
if (typeof value === "number" && Number.isFinite(value)) {
@ -16,20 +39,383 @@ function toNumber(value: unknown): number {
return 0;
}
function mapDashboardStats(raw: unknown): DashboardStats {
const data = (typeof raw === "object" && raw !== null ? raw : {}) as Record<string, unknown>;
function asString(value: unknown): string {
if (typeof value === "string") {
return value.trim();
}
if (typeof value === "number" && Number.isFinite(value)) {
return String(value);
}
return "";
}
function asRecords(value: unknown): Record<string, unknown>[] {
if (!Array.isArray(value)) {
return [];
}
return value.filter(
(item): item is Record<string, unknown> =>
typeof item === "object" && item !== null && !Array.isArray(item),
);
}
function readField(data: Record<string, unknown>, key: string): unknown {
const capitalized = key.charAt(0).toUpperCase() + key.slice(1);
const value = data[key] ?? data[capitalized];
return value === null ? undefined : value;
}
function toRecord(value: unknown): Record<string, unknown> {
return typeof value === "object" && value !== null && !Array.isArray(value)
? (value as Record<string, unknown>)
: {};
}
function readCollection(value: unknown, key: string): Record<string, unknown>[] {
const data = toRecord(value);
const collection = key ? (readField(data, key) ?? value) : value;
return asRecords(collection);
}
/**
* Stats, Regions, Workload, and Performance share `DashboardStatsQueryDTO`
* (backend#145): the range dates ride along when present, and `dispatcherId`
* scopes the read to a single dispatcher (SH-336's picker — All sends nothing,
* My WOs / an individual sends that id). Vendor Insights and Trend take no such
* param and stay company-wide (SH-349).
*/
function scopedSearchParams(
range?: DashboardRangeParams,
dispatcherId?: string,
): Options | undefined {
const searchParams: Record<string, string> = {};
if (range?.dateFrom && range?.dateTo) {
searchParams.dateFrom = range.dateFrom;
searchParams.dateTo = range.dateTo;
}
if (dispatcherId) {
searchParams.dispatcherId = dispatcherId;
}
return Object.keys(searchParams).length > 0 ? { searchParams } : undefined;
}
/**
* Workload and Performance are paged server-side (backend#126/#127): `page` is
* 1-based and always sent, the range dates ride along when present, and
* `dispatcherId` scopes to a single dispatcher (SH-336).
*/
function dispatcherPageSearchParams(
range: DashboardRangeParams | undefined,
page: number,
dispatcherId?: string,
): Options {
const searchParams: Record<string, string | number> = { page };
if (range?.dateFrom && range?.dateTo) {
searchParams.dateFrom = range.dateFrom;
searchParams.dateTo = range.dateTo;
}
if (dispatcherId) {
searchParams.dispatcherId = dispatcherId;
}
return { searchParams };
}
/**
* Reads the paging envelope the dispatcher endpoints return (`Page`, `PageSize`,
* `TotalDispatchers`). Falls back to the requested page, the default page size,
* and the item count for the legacy bare-array shape so older responses still
* render (with the pager hidden).
*/
function readDispatcherPageMeta(
raw: unknown,
requestedPage: number,
itemCount: number,
): { page: number; pageSize: number; totalDispatchers: number } {
const data = toRecord(raw);
const pageValue = readField(data, "page");
const pageSizeValue = readField(data, "pageSize");
const totalValue = readField(data, "totalDispatchers");
return {
open: toNumber(data.open ?? data.Open),
notDispatched: toNumber(data.notDispatched ?? data.NotDispatched),
completed: toNumber(data.completed ?? data.Completed),
page: pageValue == null ? requestedPage : toNumber(pageValue),
pageSize: pageSizeValue == null ? DISPATCHER_PAGE_SIZE : toNumber(pageSizeValue),
totalDispatchers: totalValue == null ? itemCount : toNumber(totalValue),
};
}
function trendSearchParams(params?: DashboardTrendParams): Options | undefined {
if (
!params ||
(!params.dateFrom && !params.dateTo && !params.granularity && !params.range && !params.year)
) {
return undefined;
}
const searchParams: Record<string, string | number> = {};
if (params.dateFrom) searchParams.dateFrom = params.dateFrom;
if (params.dateTo) searchParams.dateTo = params.dateTo;
if (params.granularity) searchParams.granularity = params.granularity;
if (params.range) searchParams.range = params.range;
if (params.year) searchParams.year = params.year;
return { searchParams };
}
const BREAKDOWN_TYPE_BY_LOWER = new Map<string, string>(
WO_TYPES.map((type) => [type.toLowerCase(), type]),
);
/**
* The backend breakdown object (backend#138) serializes its keys with no
* JsonPropertyName, so `PM`/`Emergency`/`Reactive`/`Overdue`/`Other` arrive
* lowercase. The card uses the row label as both display text and the
* `types` drill-down id, and `workOrderTypeDrilldownSearch` only accepts
* canonical `WOType` values — so map lowercase type keys back to their
* canonical labels. `other` is not a WOType: keep it as a labelled,
* non-drillable "Other" row. Unknown values (e.g. lifecycle labels from the
* legacy array shape) pass through unchanged.
*/
function normalizeBreakdownStatus(raw: string): string {
const trimmed = raw.trim();
const canonical = BREAKDOWN_TYPE_BY_LOWER.get(trimmed.toLowerCase());
if (canonical) return canonical;
if (trimmed.toLowerCase() === "other") return "Other";
return trimmed;
}
function mapBreakdownRow(raw: Record<string, unknown>): DashboardBreakdownRow {
const status = asString(
readField(raw, "status") ?? readField(raw, "name") ?? readField(raw, "label"),
);
return {
status: status ? normalizeBreakdownStatus(status) : UNMAPPED_REGION_LABEL,
count: toNumber(readField(raw, "count") ?? readField(raw, "value")),
};
}
function mapBreakdown(value: unknown): DashboardBreakdownRow[] {
if (Array.isArray(value)) {
return asRecords(value).map(mapBreakdownRow);
}
if (typeof value === "object" && value !== null) {
return Object.entries(value as Record<string, unknown>)
.map(([status, count]) => ({
status: normalizeBreakdownStatus(status),
count: toNumber(count),
}))
.filter((row) => row.status !== "");
}
return [];
}
function mapDispatcherIdentity(raw: Record<string, unknown>): {
dispatcherId: string;
dispatcherName: string;
} {
return {
dispatcherId: asString(
readField(raw, "dispatcherId") ?? readField(raw, "id") ?? readField(raw, "userId"),
),
dispatcherName: asString(readField(raw, "dispatcherName") ?? readField(raw, "name")),
};
}
function mapStatusDistribution(value: unknown): DashboardStatusBucketRow[] {
return asRecords(value)
.map((row) => ({
status: asString(
readField(row, "status") ?? readField(row, "name") ?? readField(row, "label"),
),
count: toNumber(readField(row, "count") ?? readField(row, "value")),
}))
.filter((row) => row.status !== "");
}
function mapDashboardStats(raw: unknown): DashboardStats {
const data = toRecord(raw);
const average = readField(data, "averageResolutionDays");
return {
total: toNumber(readField(data, "total")),
open: toNumber(readField(data, "open")),
notDispatched: toNumber(readField(data, "notDispatched")),
completed: toNumber(readField(data, "completed")),
dueCount: toNumber(readField(data, "dueCount")),
completedDueCount: toNumber(readField(data, "completedDueCount")),
completionRate: toNumber(readField(data, "completionRate")),
averageResolutionDays: average == null ? null : toNumber(average),
scheduledTomorrow: toNumber(readField(data, "scheduledTomorrow")),
pendingUplifts: toNumber(readField(data, "pendingUplifts")),
avetaPending: toNumber(readField(data, "avetaPending")),
breakdown: mapBreakdown(readField(data, "breakdown") ?? readField(data, "workOrderBreakdown")),
statusDistribution: mapStatusDistribution(readField(data, "statusDistribution")),
};
}
function mapDispatcherWorkload(raw: unknown): DispatcherWorkloadRow[] {
return readCollection(raw, "items").map((rawRow) => {
const identity = mapDispatcherIdentity(rawRow);
return {
...identity,
openWorkOrders: toNumber(
readField(rawRow, "openWorkOrders") ??
readField(rawRow, "openCount") ??
readField(rawRow, "open"),
),
totalWorkOrders: toNumber(
readField(rawRow, "totalWorkOrders") ??
readField(rawRow, "totalCount") ??
readField(rawRow, "scheduledWorkOrders") ??
readField(rawRow, "scheduled"),
),
};
});
}
function mapDispatcherPerformance(raw: unknown): DispatcherPerformanceRow[] {
return readCollection(raw, "items").map((rawRow) => {
const identity = mapDispatcherIdentity(rawRow);
return {
...identity,
completionRate: toNumber(
readField(rawRow, "completionRate") ?? readField(rawRow, "onTimeRate"),
),
averageResolutionDays:
readField(rawRow, "averageResolutionDays") == null
? null
: toNumber(readField(rawRow, "averageResolutionDays")),
assignedCount: toNumber(readField(rawRow, "assignedCount") ?? readField(rawRow, "assigned")),
completedCount: toNumber(
readField(rawRow, "completedCount") ?? readField(rawRow, "completed"),
),
};
});
}
function mapRegions(raw: unknown): RegionWorkOrdersRow[] {
return readCollection(raw, "items").map((rawRow) => {
const region =
asString(readField(rawRow, "region") ?? readField(rawRow, "name")) || UNMAPPED_REGION_LABEL;
return {
region,
workOrderCount: toNumber(
readField(rawRow, "workOrderCount") ??
readField(rawRow, "count") ??
readField(rawRow, "total"),
),
};
});
}
function mapVendorInsights(raw: unknown): VendorInsightRow[] {
return readCollection(raw, "items").map((rawRow) => ({
vendorId: asString(
readField(rawRow, "vendorId") ??
readField(rawRow, "vendorCompanyId") ??
readField(rawRow, "id"),
),
vendorName: asString(
readField(rawRow, "vendorName") ??
readField(rawRow, "vendorCompanyName") ??
readField(rawRow, "companyName") ??
readField(rawRow, "name"),
),
completionRate: toNumber(readField(rawRow, "completionRate")),
rescheduleRate: toNumber(readField(rawRow, "rescheduleRate")),
averageResolutionDays:
readField(rawRow, "averageResolutionDays") == null
? null
: toNumber(readField(rawRow, "averageResolutionDays")),
totalJobs: toNumber(readField(rawRow, "totalJobs")),
}));
}
function mapTrendGranularity(value: unknown): DashboardTrendGranularity | null {
const granularity = asString(value).toLowerCase();
return granularity === "day" || granularity === "week" || granularity === "month"
? granularity
: null;
}
function mapDashboardTrend(raw: unknown): DashboardTrend {
const data = toRecord(raw);
const buckets = readCollection(data, "buckets");
const legacyPoints = readCollection(data, "points");
const points = (buckets.length > 0 ? buckets : legacyPoints).map((rawPoint) => ({
date: asString(readField(rawPoint, "date")),
label: asString(
readField(rawPoint, "label") ?? readField(rawPoint, "period") ?? readField(rawPoint, "date"),
),
total: toNumber(
readField(rawPoint, "total") ?? readField(rawPoint, "count") ?? readField(rawPoint, "value"),
),
open: toNumber(readField(rawPoint, "open")),
completed: toNumber(readField(rawPoint, "completed")),
canceled: toNumber(readField(rawPoint, "canceled")),
overdue: toNumber(readField(rawPoint, "overdue")),
isCurrent: readField(rawPoint, "isCurrent") === true,
}));
return { granularity: mapTrendGranularity(readField(data, "granularity")), points };
}
export const dashboardApi = {
getStats: async (): Promise<DashboardStats> => {
const data = await apiGet<unknown>(API_PATHS.dashboard.stats);
getStats: async (
range?: DashboardRangeParams,
dispatcherId?: string,
): Promise<DashboardStats> => {
const data = await apiGet<unknown>(
API_PATHS.dashboard.stats,
scopedSearchParams(range, dispatcherId),
);
return mapDashboardStats(handleApiResponse<unknown>(data));
},
getWorkload: async (
range?: DashboardRangeParams,
page = 1,
dispatcherId?: string,
): Promise<DispatcherPage<DispatcherWorkloadRow>> => {
const data = await apiGet<unknown>(
API_PATHS.dashboard.workload,
dispatcherPageSearchParams(range, page, dispatcherId),
);
const response = handleApiResponse<unknown>(data);
return mapDashboardStats(response);
const items = mapDispatcherWorkload(response);
return { items, ...readDispatcherPageMeta(response, page, items.length) };
},
getPerformance: async (
range?: DashboardRangeParams,
page = 1,
dispatcherId?: string,
): Promise<DispatcherPage<DispatcherPerformanceRow>> => {
const data = await apiGet<unknown>(
API_PATHS.dashboard.performance,
dispatcherPageSearchParams(range, page, dispatcherId),
);
const response = handleApiResponse<unknown>(data);
const items = mapDispatcherPerformance(response);
return { items, ...readDispatcherPageMeta(response, page, items.length) };
},
getRegions: async (
range?: DashboardRangeParams,
dispatcherId?: string,
): Promise<RegionWorkOrdersRow[]> => {
const data = await apiGet<unknown>(
API_PATHS.dashboard.regions,
scopedSearchParams(range, dispatcherId),
);
return mapRegions(handleApiResponse<unknown>(data));
},
getVendorInsights: async (): Promise<VendorInsightRow[]> => {
const data = await apiGet<unknown>(API_PATHS.dashboard.vendorInsights);
return mapVendorInsights(handleApiResponse<unknown>(data));
},
getTrend: async (params?: DashboardTrendParams): Promise<DashboardTrend> => {
const data = await apiGet<unknown>(API_PATHS.dashboard.trend, trendSearchParams(params));
return mapDashboardTrend(handleApiResponse<unknown>(data));
},
};

10
src/domain/dashboard/types/dashboard-dispatcher-page.ts Normal file
View file

@ -0,0 +1,10 @@
/** Backend pages both dispatcher tables at 10 rows (backend#126/#127). */
export const DISPATCHER_PAGE_SIZE = 10;
/** A single page of dispatcher rows plus the paging metadata the tables need. */
export interface DispatcherPage<TRow> {
items: TRow[];
page: number;
pageSize: number;
totalDispatchers: number;
}

8
src/domain/dashboard/types/dashboard-performance.ts Normal file
View file

@ -0,0 +1,8 @@
export interface DispatcherPerformanceRow {
dispatcherId: string;
dispatcherName: string;
completionRate: number;
averageResolutionDays: number | null;
assignedCount: number;
completedCount: number;
}

10
src/domain/dashboard/types/dashboard-range.ts Normal file
View file

@ -0,0 +1,10 @@
export const DASHBOARD_RANGES = ["this-week", "last-3-months", "today", "all-time"] as const;
export type DashboardRangeKey = (typeof DASHBOARD_RANGES)[number];
export const DEFAULT_DASHBOARD_RANGE: DashboardRangeKey = "this-week";
export interface DashboardRangeParams {
dateFrom?: string;
dateTo?: string;
}

6
src/domain/dashboard/types/dashboard-regions.ts Normal file
View file

@ -0,0 +1,6 @@
export const UNMAPPED_REGION_LABEL = "Unmapped/Other";
export interface RegionWorkOrdersRow {
region: string;
workOrderCount: number;
}

20
src/domain/dashboard/types/dashboard-stats.ts
View file

@ -1,5 +1,25 @@
export interface DashboardBreakdownRow {
status: string;
count: number;
}
export interface DashboardStatusBucketRow {
status: string;
count: number;
}
export interface DashboardStats {
total: number;
open: number;
notDispatched: number;
completed: number;
dueCount: number;
completedDueCount: number;
completionRate: number;
averageResolutionDays: number | null;
scheduledTomorrow: number;
pendingUplifts: number;
avetaPending: number;
breakdown: DashboardBreakdownRow[];
statusDistribution: DashboardStatusBucketRow[];
}

25
src/domain/dashboard/types/dashboard-trend.ts Normal file
View file

@ -0,0 +1,25 @@
export type DashboardTrendGranularity = "day" | "week" | "month";
export interface DashboardTrendParams {
dateFrom?: string;
dateTo?: string;
granularity?: DashboardTrendGranularity;
range?: "3m";
year?: number;
}
export interface DashboardTrendPoint {
date: string;
label: string;
total: number;
open: number;
completed: number;
canceled: number;
overdue: number;
isCurrent: boolean;
}
export interface DashboardTrend {
granularity: DashboardTrendGranularity | null;
points: DashboardTrendPoint[];
}

8
src/domain/dashboard/types/dashboard-vendor-insights.ts Normal file
View file

@ -0,0 +1,8 @@
export interface VendorInsightRow {
vendorId: string;
vendorName: string;
completionRate: number;
rescheduleRate: number;
averageResolutionDays: number | null;
totalJobs: number;
}

6
src/domain/dashboard/types/dashboard-workload.ts Normal file
View file

@ -0,0 +1,6 @@
export interface DispatcherWorkloadRow {
dispatcherId: string;
dispatcherName: string;
openWorkOrders: number;
totalWorkOrders: number;
}

22
src/domain/dashboard/use-cases/use-dashboard-performance.ts Normal file
View file

@ -0,0 +1,22 @@
import { useQuery, type UseQueryResult } from "@tanstack/react-query";
import { dashboardApi } from "@/domain/dashboard/api/dashboard-api";
import type { DispatcherPage } from "@/domain/dashboard/types/dashboard-dispatcher-page";
import type { DispatcherPerformanceRow } from "@/domain/dashboard/types/dashboard-performance";
import type { DashboardRangeKey } from "@/domain/dashboard/types/dashboard-range";
import { dashboardRangeParams } from "@/domain/dashboard/utils/dashboard-range-utils";
import { queryKeys } from "@/infra/query-key/query-key";
export function useDashboardPerformance(
range: DashboardRangeKey,
page = 1,
dispatcherId: string | null = null,
enabled = true,
): UseQueryResult<DispatcherPage<DispatcherPerformanceRow>, Error> {
return useQuery({
queryKey: queryKeys.dashboard.performance(range, page, dispatcherId),
queryFn: () =>
dashboardApi.getPerformance(dashboardRangeParams(range), page, dispatcherId ?? undefined),
staleTime: 60 * 1000,
enabled,
});
}

17
src/domain/dashboard/use-cases/use-dashboard-regions.ts Normal file
View file

@ -0,0 +1,17 @@
import { useQuery, type UseQueryResult } from "@tanstack/react-query";
import { dashboardApi } from "@/domain/dashboard/api/dashboard-api";
import type { RegionWorkOrdersRow } from "@/domain/dashboard/types/dashboard-regions";
import type { DashboardRangeKey } from "@/domain/dashboard/types/dashboard-range";
import { dashboardRangeParams } from "@/domain/dashboard/utils/dashboard-range-utils";
import { queryKeys } from "@/infra/query-key/query-key";
export function useDashboardRegions(
range: DashboardRangeKey,
dispatcherId: string | null = null,
): UseQueryResult<RegionWorkOrdersRow[], Error> {
return useQuery({
queryKey: queryKeys.dashboard.regions(range, dispatcherId),
queryFn: () => dashboardApi.getRegions(dashboardRangeParams(range), dispatcherId ?? undefined),
staleTime: 60 * 1000,
});
}

11
src/domain/dashboard/use-cases/use-dashboard-stats.ts
View file

@ -1,12 +1,17 @@
import { useQuery, type UseQueryResult } from "@tanstack/react-query";
import { dashboardApi } from "@/domain/dashboard/api/dashboard-api";
import type { DashboardRangeKey } from "@/domain/dashboard/types/dashboard-range";
import type { DashboardStats } from "@/domain/dashboard/types/dashboard-stats";
import { dashboardRangeParams } from "@/domain/dashboard/utils/dashboard-range-utils";
import { queryKeys } from "@/infra/query-key/query-key";
export function useDashboardStats(): UseQueryResult<DashboardStats, Error> {
export function useDashboardStats(
range: DashboardRangeKey,
dispatcherId: string | null = null,
): UseQueryResult<DashboardStats, Error> {
return useQuery({
queryKey: queryKeys.dashboard.stats(),
queryFn: () => dashboardApi.getStats(),
queryKey: queryKeys.dashboard.stats(range, dispatcherId),
queryFn: () => dashboardApi.getStats(dashboardRangeParams(range), dispatcherId ?? undefined),
staleTime: 60 * 1000,
});
}

17
src/domain/dashboard/use-cases/use-dashboard-trend.ts Normal file
View file

@ -0,0 +1,17 @@
import { useQuery, type UseQueryResult } from "@tanstack/react-query";
import { dashboardApi } from "@/domain/dashboard/api/dashboard-api";
import type {
DashboardTrend,
DashboardTrendParams,
} from "@/domain/dashboard/types/dashboard-trend";
import { queryKeys } from "@/infra/query-key/query-key";
export function useDashboardTrend(
params?: DashboardTrendParams,
): UseQueryResult<DashboardTrend, Error> {
return useQuery({
queryKey: queryKeys.dashboard.trend(params),
queryFn: () => dashboardApi.getTrend(params),
staleTime: 60 * 1000,
});
}

12
src/domain/dashboard/use-cases/use-dashboard-vendor-insights.ts Normal file
View file

@ -0,0 +1,12 @@
import { useQuery, type UseQueryResult } from "@tanstack/react-query";
import { dashboardApi } from "@/domain/dashboard/api/dashboard-api";
import type { VendorInsightRow } from "@/domain/dashboard/types/dashboard-vendor-insights";
import { queryKeys } from "@/infra/query-key/query-key";
export function useDashboardVendorInsights(): UseQueryResult<VendorInsightRow[], Error> {
return useQuery({
queryKey: queryKeys.dashboard.vendorInsights(),
queryFn: () => dashboardApi.getVendorInsights(),
staleTime: 60 * 1000,
});
}

22
src/domain/dashboard/use-cases/use-dashboard-workload.ts Normal file
View file

@ -0,0 +1,22 @@
import { useQuery, type UseQueryResult } from "@tanstack/react-query";
import { dashboardApi } from "@/domain/dashboard/api/dashboard-api";
import type { DispatcherPage } from "@/domain/dashboard/types/dashboard-dispatcher-page";
import type { DispatcherWorkloadRow } from "@/domain/dashboard/types/dashboard-workload";
import type { DashboardRangeKey } from "@/domain/dashboard/types/dashboard-range";
import { dashboardRangeParams } from "@/domain/dashboard/utils/dashboard-range-utils";
import { queryKeys } from "@/infra/query-key/query-key";
export function useDashboardWorkload(
range: DashboardRangeKey,
page = 1,
dispatcherId: string | null = null,
enabled = true,
): UseQueryResult<DispatcherPage<DispatcherWorkloadRow>, Error> {
return useQuery({
queryKey: queryKeys.dashboard.workload(range, page, dispatcherId),
queryFn: () =>
dashboardApi.getWorkload(dashboardRangeParams(range), page, dispatcherId ?? undefined),
staleTime: 60 * 1000,
enabled,
});
}

73
src/domain/dashboard/utils/dashboard-range-utils.ts Normal file
View file

@ -0,0 +1,73 @@
import { DEFAULT_DASHBOARD_RANGE } from "@/domain/dashboard/types/dashboard-range";
import type {
DashboardRangeKey,
DashboardRangeParams,
} from "@/domain/dashboard/types/dashboard-range";
export const BUSINESS_TIME_ZONE = "America/New_York";
const ISO_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
export function businessTodayIso(now: Date = new Date()): string {
return new Intl.DateTimeFormat("en-CA", {
timeZone: BUSINESS_TIME_ZONE,
year: "numeric",
month: "2-digit",
day: "2-digit",
}).format(now);
}
export function isIsoDate(value: string): boolean {
return ISO_DATE_PATTERN.test(value);
}
export function addDaysIso(isoDate: string, days: number): string {
const [year, month, day] = isoDate.split("-").map(Number);
const shifted = new Date(Date.UTC(year, month - 1, day + days));
return shifted.toISOString().slice(0, 10);
}
export function mondayOf(isoDate: string): string {
const [year, month, day] = isoDate.split("-").map(Number);
const weekday = new Date(Date.UTC(year, month - 1, day)).getUTCDay();
return addDaysIso(isoDate, -((weekday + 6) % 7));
}
export function monthStartIso(isoDate: string): string {
return `${isoDate.slice(0, 7)}-01`;
}
export function monthEndIso(isoDate: string): string {
const year = Number(isoDate.slice(0, 4));
const month = Number(isoDate.slice(5, 7));
const lastDay = new Date(Date.UTC(year, month, 0)).getUTCDate();
return `${isoDate.slice(0, 7)}-${String(lastDay).padStart(2, "0")}`;
}
function shiftMonthsIso(isoDate: string, months: number): string {
const year = Number(isoDate.slice(0, 4));
const month = Number(isoDate.slice(5, 7));
const shifted = new Date(Date.UTC(year, month - 1 + months, 1));
return `${shifted.getUTCFullYear()}-${String(shifted.getUTCMonth() + 1).padStart(2, "0")}-01`;
}
export function dashboardRangeParams(
range: DashboardRangeKey = DEFAULT_DASHBOARD_RANGE,
today: string = businessTodayIso(),
): DashboardRangeParams {
switch (range) {
case "today":
return { dateFrom: today, dateTo: today };
case "this-week": {
const monday = mondayOf(today);
return { dateFrom: monday, dateTo: addDaysIso(monday, 4) };
}
case "last-3-months":
return {
dateFrom: monthStartIso(shiftMonthsIso(today, -2)),
dateTo: monthEndIso(today),
};
case "all-time":
return {};
}
}

96
src/domain/dashboard/utils/work-order-drilldown-links.ts Normal file
View file

@ -0,0 +1,96 @@
import { ALL_WIZARD_STATUSES } from "@/domain/work-orders/types/work-order-wizard";
import { WO_TYPES, type WOType } from "@/domain/work-orders/types/work-order-wizard";
import type { DashboardRangeKey } from "@/domain/dashboard/types/dashboard-range";
import {
addDaysIso,
businessTodayIso,
dashboardRangeParams,
} from "@/domain/dashboard/utils/dashboard-range-utils";
export const WORK_ORDERS_ROUTE = "/workorders";
export const UPLIFTS_ROUTE = "/uplifts";
export const OPEN_WIZARD_STATUSES: readonly string[] = ALL_WIZARD_STATUSES.filter(
(status) => status !== "Completed",
);
export function workOrderDrilldownUrl(search: URLSearchParams): string {
const query = search.toString();
return query ? `${WORK_ORDERS_ROUTE}?${query}` : WORK_ORDERS_ROUTE;
}
function setDateRange(search: URLSearchParams, range: DashboardRangeKey): void {
const params = dashboardRangeParams(range);
if (params.dateFrom && params.dateTo) {
search.set("dateFrom", params.dateFrom);
search.set("dateTo", params.dateTo);
}
}
export function workOrderRangeDrilldownSearch(range: DashboardRangeKey): URLSearchParams {
const search = new URLSearchParams();
setDateRange(search, range);
return search;
}
export function workOrderStatusDrilldownSearch(
status: string,
range: DashboardRangeKey,
): URLSearchParams {
const search = workOrderRangeDrilldownSearch(range);
search.set("statuses", status);
return search;
}
export function workOrderTypeDrilldownSearch(
type: string,
range: DashboardRangeKey,
): URLSearchParams | null {
if (!WO_TYPES.includes(type as WOType)) return null;
const search = workOrderRangeDrilldownSearch(range);
search.set("types", type);
return search;
}
export function workOrderDispatcherDrilldownSearch(
dispatcherId: string,
range: DashboardRangeKey,
): URLSearchParams {
const search = workOrderRangeDrilldownSearch(range);
search.set("dispatchers", dispatcherId);
return search;
}
export function workOrderRegionDrilldownSearch(
region: string,
range: DashboardRangeKey,
): URLSearchParams {
const search = workOrderRangeDrilldownSearch(range);
search.set("regions", region);
return search;
}
export function scheduledTomorrowDrilldownSearch(
today: string = businessTodayIso(),
): URLSearchParams {
const tomorrow = addDaysIso(today, 1);
const search = new URLSearchParams();
search.set("dateFrom", tomorrow);
search.set("dateTo", tomorrow);
return search;
}
export function avetaPendingDrilldownSearch(today: string = businessTodayIso()): URLSearchParams {
// The Aveta Pending count (backend#138 / SH-294) is: AvetaRequired, scheduled
// today or tomorrow, open, and missing its Aveta-category document. The board
// has no missing-Aveta-document filter, so the closest reachable set is the
// Aveta-required work in the two-day open window. `docs=No` is deliberately
// NOT sent: it filters on completion-document status, a different document
// from the Aveta clearance one, so it would narrow to the wrong rows.
const search = new URLSearchParams();
search.set("dateFrom", today);
search.set("dateTo", addDaysIso(today, 1));
search.set("aveta", "1");
search.set("statuses", OPEN_WIZARD_STATUSES.join(","));
return search;
}

3
src/domain/work-orders/types/work-order-advanced-filters.ts
View file

@ -32,6 +32,7 @@ export interface WorkOrderAdvancedFilters {
types: Set<WOType>;
severities: Set<WorkOrderSeverity>;
dispatchers: Set<string>;
regions: Set<string>;
statuses: Set<WizardWOStatus>;
rescheduled: boolean;
carriedOver: boolean;
@ -55,6 +56,7 @@ export const EMPTY_ADVANCED_FILTERS: WorkOrderAdvancedFilters = {
types: new Set(),
severities: new Set(),
dispatchers: new Set(),
regions: new Set(),
statuses: new Set(),
rescheduled: false,
carriedOver: false,
@ -97,6 +99,7 @@ export type AdvancedFilterSetKey =
| "sites"
| "types"
| "dispatchers"
| "regions"
| "statuses"
| "pmTypes"
| "vendorTechs"

2
src/domain/work-orders/types/work-order-board.ts
View file

@ -290,6 +290,8 @@ export interface WorkOrderBoardSearchQueryParams {
/** Past-due filter; independent of WorkOrderType (Other remains types=99). */
overdue?: boolean;
dispatchers?: string[];
/** SH-348: region names (East/Central/West/California/Unmapped/Other). */
regions?: string[];
statuses?: number[];
pmTypes?: string[];
vendorIds?: number[];

9
src/domain/work-orders/utils/advanced-filter-chip-builders.ts
View file

@ -108,6 +108,15 @@ export function appendSetChips(
nameOf: (v) => v,
clear: (current) => ({ ...current, types: new Set() }),
});
pushSetChip({
chips,
key: "regions",
group: "Region",
set: filters.regions,
nameOf: (v) => v,
clear: (current) => ({ ...current, regions: new Set() }),
});
}
export function appendSeverityChip(chips: AdvancedFilterChip[], filters: WorkOrderAdvancedFilters) {

2
src/domain/work-orders/utils/advanced-filters-utils.ts
View file

@ -26,6 +26,7 @@ function cloneFilters(filters: WorkOrderAdvancedFilters): WorkOrderAdvancedFilte
types: new Set(filters.types),
severities: new Set(filters.severities ?? []),
dispatchers: new Set(filters.dispatchers),
regions: new Set(filters.regions ?? []),
statuses: new Set(filters.statuses),
pmTypes: new Set(filters.pmTypes),
vendorTechs: new Set(filters.vendorTechs),
@ -42,6 +43,7 @@ const ADVANCED_FILTER_ACTIVE_SIGNALS = (filters: WorkOrderAdvancedFilters): bool
Boolean(filters.types?.size),
Boolean(filters.severities?.size),
Boolean(filters.dispatchers?.size),
Boolean(filters.regions?.size),
Boolean(filters.statuses?.size),
filters.rescheduled,
filters.carriedOver,

1
src/domain/work-orders/utils/board-query-params.ts
View file

@ -217,6 +217,7 @@ export function toBoardSearchQueryParams(input: {
types: typeFilters.types,
overdue: typeFilters.overdue,
dispatchers: mapDispatchers(filters.dispatchers),
regions: filters.regions.size > 0 ? [...filters.regions] : undefined,
statuses: mapStatuses(filters.statuses),
pmTypes: filters.pmTypes.size > 0 ? [...filters.pmTypes] : undefined,
vendorIds: resolveVendorIds(filters.vendorTechs, input.vendorIdsByCompanyName),

123
src/domain/work-orders/utils/dashboard-drilldown-params.ts Normal file
View file

@ -0,0 +1,123 @@
import type { CompletionDocFilter } from "@/domain/work-orders/types/work-order-advanced-filters";
import type { WorkOrderAdvancedFilters } from "@/domain/work-orders/types/work-order-advanced-filters";
import { EMPTY_ADVANCED_FILTERS } from "@/domain/work-orders/types/work-order-advanced-filters";
import { ALL_WIZARD_STATUSES, WO_TYPES } from "@/domain/work-orders/types/work-order-wizard";
import type { WizardWOStatus, WOType } from "@/domain/work-orders/types/work-order-wizard";
import type { UpliftFilterStatus } from "@/domain/work-orders/types/work-order-uplift-filter";
import { cloneAdvancedFilters } from "@/domain/work-orders/utils/advanced-filters-utils";
const ISO_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
const COMPLETION_DOC_FILTERS: CompletionDocFilter[] = ["No", "Yes", "NN"];
// SH-348: the board region filter (backend#146) accepts these region names.
const BOARD_REGION_NAMES = ["East", "Central", "West", "California", "Unmapped/Other"];
const UPLIFT_FILTER_VALUES: UpliftFilterStatus[] = [
"pending",
"approved",
"auto_approved",
"rejected",
];
function parseList(raw: string | null): string[] {
if (!raw) {
return [];
}
return raw
.split(",")
.map((item) => item.trim())
.filter((item) => item !== "");
}
function parseStatuses(raw: string | null): WizardWOStatus[] {
const valid = new Set<string>(ALL_WIZARD_STATUSES);
return [...new Set(parseList(raw))].filter((status): status is WizardWOStatus =>
valid.has(status),
);
}
function parseTypes(raw: string | null): WOType[] {
const valid = new Set<string>(WO_TYPES);
return [...new Set(parseList(raw))].filter((type): type is WOType => valid.has(type));
}
function parseCompletionDocs(raw: string | null): CompletionDocFilter[] {
const valid = new Set<string>(COMPLETION_DOC_FILTERS);
return [...new Set(parseList(raw))].filter((doc): doc is CompletionDocFilter => valid.has(doc));
}
function parseRegions(raw: string | null): string[] {
const valid = new Set<string>(BOARD_REGION_NAMES);
return [...new Set(parseList(raw))].filter((region) => valid.has(region));
}
function parseUpliftStatuses(raw: string | null): UpliftFilterStatus[] {
const valid = new Set<string>(UPLIFT_FILTER_VALUES);
return [...new Set(parseList(raw))].filter((value): value is UpliftFilterStatus =>
valid.has(value),
);
}
export function parseDashboardDrilldownParams(
params: URLSearchParams,
): WorkOrderAdvancedFilters | null {
const dateFrom = (params.get("dateFrom") ?? "").trim();
const dateTo = (params.get("dateTo") ?? "").trim();
const hasDateRange = ISO_DATE_PATTERN.test(dateFrom) && ISO_DATE_PATTERN.test(dateTo);
const avetaOnly = params.get("aveta") === "1";
const docs = parseCompletionDocs(params.get("docs"));
const statuses = parseStatuses(params.get("statuses"));
const types = parseTypes(params.get("types"));
const dispatchers = parseList(params.get("dispatchers"));
const regions = parseRegions(params.get("regions"));
const upliftStatuses = parseUpliftStatuses(params.get("upliftStatuses"));
const hasUplift = params.get("hasUplift") === "1";
const hasAny = [
hasDateRange,
avetaOnly,
docs.length,
statuses.length,
types.length,
dispatchers.length,
regions.length,
upliftStatuses.length,
hasUplift,
].some(Boolean);
if (!hasAny) {
return null;
}
const filters = cloneAdvancedFilters(EMPTY_ADVANCED_FILTERS);
if (hasDateRange) {
filters.dateRange = "custom";
filters.customFrom = dateFrom;
filters.customTo = dateTo;
}
filters.avetaOnly = avetaOnly;
filters.hasUplift = hasUplift || upliftStatuses.length > 0;
if (docs.length > 0) {
filters.docs = new Set(docs);
}
if (statuses.length > 0) {
filters.statuses = new Set(statuses);
}
if (types.length > 0) {
filters.types = new Set(types);
}
if (dispatchers.length > 0) {
filters.dispatchers = new Set(dispatchers);
}
if (regions.length > 0) {
filters.regions = new Set(regions);
}
if (upliftStatuses.length > 0) {
filters.upliftStatuses = new Set(upliftStatuses);
}
return filters;
}

14
src/infra/query-key/query-key.ts
View file

@ -1,3 +1,5 @@
import type { DashboardRangeKey } from "@/domain/dashboard/types/dashboard-range";
import type { DashboardTrendParams } from "@/domain/dashboard/types/dashboard-trend";
import type { WorkOrdersListParams } from "@/domain/work-orders/types/work-order-list";
import type {
WorkOrderBoardQueryParams,
@ -54,7 +56,17 @@ export const queryKeys = {
},
dashboard: {
all: ["dashboard"] as const,
stats: () => [...queryKeys.dashboard.all, "stats"] as const,
stats: (range: DashboardRangeKey, dispatcherId: string | null = null) =>
[...queryKeys.dashboard.all, "stats", range, dispatcherId] as const,
workload: (range: DashboardRangeKey, page = 1, dispatcherId: string | null = null) =>
[...queryKeys.dashboard.all, "workload", range, page, dispatcherId] as const,
performance: (range: DashboardRangeKey, page = 1, dispatcherId: string | null = null) =>
[...queryKeys.dashboard.all, "performance", range, page, dispatcherId] as const,
regions: (range: DashboardRangeKey, dispatcherId: string | null = null) =>
[...queryKeys.dashboard.all, "regions", range, dispatcherId] as const,
vendorInsights: () => [...queryKeys.dashboard.all, "vendorInsights"] as const,
trend: (params?: DashboardTrendParams) =>
[...queryKeys.dashboard.all, "trend", params ?? {}] as const,
},
dropdownOptions: {
all: ["dropdownOptions"] as const,

15
src/lib/auth/user-utils.ts
View file

@ -14,3 +14,18 @@ export function isAdminUser(userRoles: string | null | undefined): boolean {
.map((role) => role.trim().toLowerCase())
.includes("admin");
}
/**
* SH-336's `viewAllDispatchersOnDashboard` permission. The codebase has no
* permission model, so it is derived from role: Admin and Scheduler may pick any
* dispatcher (or the whole company) on the Dashboard; a Dispatcher may not and
* is locked to their own work orders. Unknown roles default to the restrictive
* (Dispatcher) behaviour so no one accidentally gains a company-wide view.
*/
export function canViewAllDispatchersOnDashboard(userRoles: string | null | undefined): boolean {
if (!userRoles) {
return false;
}
const roles = userRoles.split(",").map((role) => role.trim().toLowerCase());
return roles.includes("admin") || roles.includes("scheduler");
}

265
src/test/app/(protected)/dashboard/dashboard-page.test.tsx Normal file
View file

@ -0,0 +1,265 @@
import { fireEvent, screen } from "@testing-library/react";
import { beforeEach, describe, expect, it, vi } from "vitest";
import type { DashboardRangeKey } from "@/domain/dashboard/types/dashboard-range";
import { renderWithProviders } from "@/test/test-utils";
const navigate = vi.fn();
const statsRange = vi.fn<(range: DashboardRangeKey) => void>();
const { workloadMock, performanceMock, authUser } = vi.hoisted(() => ({
workloadMock: vi.fn(),
performanceMock: vi.fn(),
authUser: { current: { id: "99", userRoles: "Admin" } as { id: string; userRoles: string } },
}));
const EMPTY_DISPATCHER_PAGE = { items: [], page: 1, pageSize: 10, totalDispatchers: 0 };
vi.mock("react-router", async (importOriginal) => ({
...(await importOriginal<typeof import("react-router")>()),
useNavigate: () => navigate,
}));
// An Admin has `viewAllDispatchersOnDashboard`, so the scope picker and the
// dispatcher tables render (SH-336).
vi.mock("@/providers/auth-context", async (importOriginal) => ({
...(await importOriginal<typeof import("@/providers/auth-context")>()),
useAuthContext: () => ({ user: authUser.current }),
}));
vi.mock("@/domain/work-orders/use-cases/use-work-orders-list", () => ({
useWorkOrderUsers: () => ({ data: [], isLoading: false, isFetching: false, error: null }),
}));
vi.mock("@/domain/dashboard/use-cases/use-dashboard-workload", () => ({
useDashboardWorkload: workloadMock,
}));
vi.mock("@/domain/dashboard/use-cases/use-dashboard-performance", () => ({
useDashboardPerformance: performanceMock,
}));
vi.mock("@/domain/dashboard/use-cases/use-dashboard-regions", () => ({
useDashboardRegions: () => ({ data: [], isLoading: false, isFetching: false, error: null }),
}));
vi.mock("@/domain/dashboard/use-cases/use-dashboard-vendor-insights", () => ({
useDashboardVendorInsights: () => ({
data: [],
isLoading: false,
isFetching: false,
error: null,
}),
}));
vi.mock("@/domain/dashboard/use-cases/use-dashboard-trend", () => ({
useDashboardTrend: () => ({
data: { granularity: null, points: [] },
isLoading: false,
isFetching: false,
error: null,
}),
}));
const statsData = {
scheduledTomorrow: 3,
pendingUplifts: 5,
avetaPending: 0,
breakdown: [
{ status: "PM", count: 7 },
{ status: "Completed", count: 0 },
],
};
vi.mock("@/domain/dashboard/use-cases/use-dashboard-stats", () => ({
useDashboardStats: (range: DashboardRangeKey) => {
statsRange(range);
return { data: statsData, isLoading: false, isFetching: false, error: null };
},
}));
import DashboardPage from "@/app/(protected)/dashboard";
import {
avetaPendingDrilldownSearch,
scheduledTomorrowDrilldownSearch,
} from "@/domain/dashboard/utils/work-order-drilldown-links";
import { addDaysIso, businessTodayIso } from "@/domain/dashboard/utils/dashboard-range-utils";
function renderDashboard() {
return renderWithProviders(<DashboardPage />);
}
describe("DashboardPage", () => {
beforeEach(() => {
authUser.current = { id: "99", userRoles: "Admin" };
navigate.mockReset();
statsRange.mockReset();
workloadMock.mockReset();
performanceMock.mockReset();
workloadMock.mockReturnValue({
data: EMPTY_DISPATCHER_PAGE,
isLoading: false,
isFetching: false,
error: null,
});
performanceMock.mockReturnValue({
data: EMPTY_DISPATCHER_PAGE,
isLoading: false,
isFetching: false,
error: null,
});
});
it("renders the prototype title, range options, and card titles", () => {
renderDashboard();
expect(screen.getByRole("heading", { name: "Dashboard" })).toBeInTheDocument();
for (const label of ["This week", "Last 3 months", "Today", "All time"]) {
expect(screen.getByRole("button", { name: label })).toBeInTheDocument();
}
for (const title of [
"Scheduled Tomorrow",
"Pending Uplifts",
"Aveta Pending",
"Work Order Breakdown",
"Status Distribution",
"Dispatcher Workload",
"Dispatcher Performance",
"Work Orders by Region",
"Vendor Insights",
]) {
expect(screen.getByText(title)).toBeInTheDocument();
}
expect(statsRange).toHaveBeenCalledWith("this-week");
});
it("shows a Dispatcher the static My WOs scope and hides the dispatcher tables", () => {
authUser.current = { id: "7", userRoles: "Dispatcher" };
renderDashboard();
expect(screen.getByText("My WOs")).toBeInTheDocument();
expect(screen.queryByRole("button", { name: "All dispatchers" })).toBeNull();
expect(screen.queryByText("Dispatcher Workload")).toBeNull();
expect(screen.queryByText("Dispatcher Performance")).toBeNull();
// Their scope is server-scoped, so the tables are never even queried.
expect(workloadMock).toHaveBeenCalledWith("this-week", 1, null, false);
});
it("lets an Admin open the dispatcher-scope picker", () => {
renderDashboard();
expect(screen.getByRole("button", { name: /All dispatchers/ })).toBeInTheDocument();
expect(screen.getByText("Dispatcher Workload")).toBeInTheDocument();
expect(workloadMock).toHaveBeenCalledWith("this-week", 1, null, true);
});
it("exposes positive KPI cards as keyboard-accessible drill-downs", () => {
renderDashboard();
const tomorrowCard = screen.getByRole("button", { name: /Scheduled Tomorrow/ });
expect(tomorrowCard).toBeInTheDocument();
fireEvent.click(tomorrowCard);
const today = businessTodayIso();
expect(navigate).toHaveBeenCalledWith(
`/workorders?${scheduledTomorrowDrilldownSearch(today).toString()}`,
);
fireEvent.click(screen.getByRole("button", { name: /Pending Uplifts/ }));
expect(navigate).toHaveBeenCalledWith("/uplifts");
});
it("keeps zero counts inert", () => {
renderDashboard();
expect(screen.queryByRole("button", { name: /Aveta Pending/ })).toBeNull();
fireEvent.click(screen.getByText("Aveta Pending"));
expect(navigate).not.toHaveBeenCalled();
const inertRow = screen.getByText("Completed");
fireEvent.click(inertRow);
expect(navigate).not.toHaveBeenCalled();
});
it("drills the breakdown status into filtered work orders", () => {
renderDashboard();
fireEvent.click(screen.getByText("PM"));
const calls = navigate.mock.calls;
const [url] = calls[calls.length - 1] ?? [];
expect(String(url)).toContain("/workorders?");
expect(String(url)).toContain("types=PM");
});
it("switches the stats range from the toggle", () => {
renderDashboard();
fireEvent.click(screen.getByRole("button", { name: "Today" }));
expect(statsRange).toHaveBeenCalledWith("today");
});
it("shows the documented empty states when datasets are empty", () => {
renderDashboard();
// Region, Status Distribution, and Trend share this empty copy.
expect(screen.getAllByText("No work orders match the current filters.")).toHaveLength(3);
expect(screen.getAllByText("No dispatchers are set up yet.")).toHaveLength(2);
expect(screen.getByText("No active vendor has any work orders yet.")).toBeInTheDocument();
});
it("pages the dispatcher tables at 10 rows and re-queries on page change", () => {
const rows = Array.from({ length: 10 }, (_, index) => ({
dispatcherId: String(index + 1),
dispatcherName: `Dispatcher ${index + 1}`,
openWorkOrders: 1,
totalWorkOrders: 2,
}));
workloadMock.mockReturnValue({
data: { items: rows, page: 1, pageSize: 10, totalDispatchers: 23 },
isLoading: false,
isFetching: false,
error: null,
});
renderDashboard();
// 23 dispatchers at 10/page = 3 pages; selecting page 2 re-queries with page 2.
fireEvent.click(screen.getByRole("button", { name: "Go to page 2" }));
const requestedPages = workloadMock.mock.calls.map((call) => call[1]);
expect(requestedPages).toContain(2);
});
it("resets the dispatcher page when the range changes", () => {
const rows = Array.from({ length: 10 }, (_, index) => ({
dispatcherId: String(index + 1),
dispatcherName: `Dispatcher ${index + 1}`,
openWorkOrders: 1,
totalWorkOrders: 2,
}));
workloadMock.mockReturnValue({
data: { items: rows, page: 2, pageSize: 10, totalDispatchers: 23 },
isLoading: false,
isFetching: false,
error: null,
});
renderDashboard();
fireEvent.click(screen.getByRole("button", { name: "Go to page 2" }));
fireEvent.click(screen.getByRole("button", { name: "Today" }));
const calls = workloadMock.mock.calls;
const lastRequestedPage = calls[calls.length - 1]?.[1];
expect(lastRequestedPage).toBe(1);
});
it("keeps drilldown dates deterministic on the business clock", () => {
const today = businessTodayIso();
expect(scheduledTomorrowDrilldownSearch(today).get("dateFrom")).toBe(addDaysIso(today, 1));
expect(avetaPendingDrilldownSearch(today).get("aveta")).toBe("1");
});
});

39
src/test/app/(protected)/dashboard/dispatcher-table-pager.test.tsx Normal file
View file

@ -0,0 +1,39 @@
import { fireEvent, render, screen } from "@testing-library/react";
import { describe, expect, it, vi } from "vitest";
import { DispatcherTablePager } from "@/app/(protected)/dashboard/_components/dispatcher-table-pager";
describe("DispatcherTablePager", () => {
it("renders nothing when everything fits on one page", () => {
const { container } = render(
<DispatcherTablePager
page={1}
pageSize={10}
totalDispatchers={10}
onPageChange={vi.fn()}
label="pager"
/>,
);
expect(container).toBeEmptyDOMElement();
});
it("renders a page per 10 rows and reports the selected page", () => {
const onPageChange = vi.fn();
render(
<DispatcherTablePager
page={1}
pageSize={10}
totalDispatchers={23}
onPageChange={onPageChange}
label="pager"
/>,
);
// 23 rows at 10/page = 3 pages.
expect(screen.getByRole("button", { name: "Go to page 3" })).toBeInTheDocument();
expect(screen.queryByRole("button", { name: "Go to page 4" })).toBeNull();
fireEvent.click(screen.getByRole("button", { name: "Go to page 2" }));
expect(onPageChange).toHaveBeenCalledWith(2);
});
});

248
src/test/domain/dashboard/dashboard-api.test.ts Normal file
View file

@ -0,0 +1,248 @@
import { beforeEach, describe, expect, it, vi } from "vitest";
const apiGet = vi.fn();
vi.mock("@/api/api", () => ({
apiGet: (...args: unknown[]) => apiGet(...args),
}));
import { dashboardApi } from "@/domain/dashboard/api/dashboard-api";
describe("dashboardApi", () => {
beforeEach(() => {
apiGet.mockReset();
});
it("maps stats tolerantly and sends the range params", async () => {
apiGet.mockResolvedValue({
Data: {
Total: 12,
Open: 8,
NotDispatched: 2,
Completed: 4,
DueCount: 5,
CompletedDueCount: 3,
CompletionRate: 60,
AverageResolutionDays: 4.5,
ScheduledTomorrow: "3",
PendingUplifts: 2,
AvetaPending: "1",
Breakdown: [
{ Status: "Scheduled", Count: "7" },
{ Status: "Completed", Count: 4 },
],
StatusDistribution: [
{ Status: "Scheduled", Count: "7" },
{ Status: "Unknown", Count: 1 },
],
},
});
const stats = await dashboardApi.getStats({ dateFrom: "2026-09-14", dateTo: "2026-09-18" });
expect(stats).toEqual({
total: 12,
open: 8,
notDispatched: 2,
completed: 4,
dueCount: 5,
completedDueCount: 3,
completionRate: 60,
averageResolutionDays: 4.5,
scheduledTomorrow: 3,
pendingUplifts: 2,
avetaPending: 1,
breakdown: [
{ status: "Scheduled", count: 7 },
{ status: "Completed", count: 4 },
],
statusDistribution: [
{ status: "Scheduled", count: 7 },
{ status: "Unknown", count: 1 },
],
});
expect(apiGet).toHaveBeenCalledWith("Dashboard/Stats", {
searchParams: { dateFrom: "2026-09-14", dateTo: "2026-09-18" },
});
});
it("maps the object breakdown shape to canonical WOType labels", async () => {
apiGet.mockResolvedValue({
Data: {
Breakdown: { pm: 3, emergency: 1, reactive: "2", overdue: 4, other: 5 },
},
});
const stats = await dashboardApi.getStats();
expect(stats.breakdown).toEqual([
{ status: "PM", count: 3 },
{ status: "Emergency", count: 1 },
{ status: "Reactive", count: 2 },
{ status: "Overdue", count: 4 },
{ status: "Other", count: 5 },
]);
});
it("omits search params for the all-time range", async () => {
apiGet.mockResolvedValue({ scheduledTomorrow: 0, pendingUplifts: 0, avetaPending: 0 });
await dashboardApi.getStats({});
expect(apiGet).toHaveBeenCalledWith("Dashboard/Stats", undefined);
});
it("maps workload rows and returns the paging envelope", async () => {
apiGet.mockResolvedValue({
Items: [{ DispatcherId: 12, DispatcherName: "Dana Reyes", OpenCount: "4", TotalCount: 6 }],
Page: 1,
PageSize: 10,
TotalDispatchers: 23,
});
await expect(dashboardApi.getWorkload()).resolves.toEqual({
items: [
{
dispatcherId: "12",
dispatcherName: "Dana Reyes",
openWorkOrders: 4,
totalWorkOrders: 6,
},
],
page: 1,
pageSize: 10,
totalDispatchers: 23,
});
expect(apiGet).toHaveBeenCalledWith("Dashboard/Workload", { searchParams: { page: 1 } });
});
it("sends the requested page and range and maps performance rows", async () => {
apiGet.mockResolvedValue({
Items: [
{
DispatcherId: 12,
DispatcherName: "Dana Reyes",
CompletionRate: 96.5,
AverageResolutionDays: 3.25,
AssignedCount: 40,
CompletedCount: "38",
},
],
Page: 2,
PageSize: 10,
TotalDispatchers: 14,
});
await expect(
dashboardApi.getPerformance({ dateFrom: "2026-09-14", dateTo: "2026-09-18" }, 2),
).resolves.toEqual({
items: [
{
dispatcherId: "12",
dispatcherName: "Dana Reyes",
completionRate: 96.5,
averageResolutionDays: 3.25,
assignedCount: 40,
completedCount: 38,
},
],
page: 2,
pageSize: 10,
totalDispatchers: 14,
});
expect(apiGet).toHaveBeenCalledWith("Dashboard/Performance", {
searchParams: { dateFrom: "2026-09-14", dateTo: "2026-09-18", page: 2 },
});
});
it("falls back to the requested page for the legacy bare-array shape", async () => {
apiGet.mockResolvedValue([
{ DispatcherId: 7, DispatcherName: "Lee Ash", OpenCount: 1, TotalCount: 2 },
]);
await expect(dashboardApi.getWorkload({}, 1)).resolves.toEqual({
items: [
{ dispatcherId: "7", dispatcherName: "Lee Ash", openWorkOrders: 1, totalWorkOrders: 2 },
],
page: 1,
pageSize: 10,
totalDispatchers: 1,
});
});
it("maps unknown regions to Unmapped", async () => {
apiGet.mockResolvedValue({
Items: [{ Region: "North", Count: 5 }, { Name: " ", WorkOrderCount: 2 }, {}],
});
await expect(dashboardApi.getRegions()).resolves.toEqual([
{ region: "North", workOrderCount: 5 },
{ region: "Unmapped/Other", workOrderCount: 2 },
{ region: "Unmapped/Other", workOrderCount: 0 },
]);
});
it("maps vendor insights with company-name fallback", async () => {
apiGet.mockResolvedValue({
Items: [
{
VendorCompanyId: 3,
VendorCompanyName: "Gateway Plumbing",
CompletionRate: 82,
RescheduleRate: 4,
AverageResolutionDays: 3,
TotalJobs: 11,
},
],
});
await expect(dashboardApi.getVendorInsights()).resolves.toEqual([
{
vendorId: "3",
vendorName: "Gateway Plumbing",
completionRate: 82,
rescheduleRate: 4,
averageResolutionDays: 3,
totalJobs: 11,
},
]);
});
it("maps the trend contract and sends date, granularity, and year params", async () => {
apiGet.mockResolvedValue({
Granularity: "Week",
Buckets: [{ Date: "2026-09-07", Label: "2026-W37", Total: "9", IsCurrent: true }],
});
await expect(
dashboardApi.getTrend({
dateFrom: "2026-09-01",
dateTo: "2026-09-30",
granularity: "month",
year: 2026,
}),
).resolves.toEqual({
granularity: "week",
points: [
{
date: "2026-09-07",
label: "2026-W37",
total: 9,
open: 0,
completed: 0,
canceled: 0,
overdue: 0,
isCurrent: true,
},
],
});
expect(apiGet).toHaveBeenCalledWith("Dashboard/Trend", {
searchParams: {
dateFrom: "2026-09-01",
dateTo: "2026-09-30",
granularity: "month",
year: 2026,
},
});
});
});

68
src/test/domain/dashboard/dashboard-range-utils.test.ts Normal file
View file

@ -0,0 +1,68 @@
import { describe, expect, it } from "vitest";
import {
addDaysIso,
businessTodayIso,
dashboardRangeParams,
mondayOf,
monthEndIso,
monthStartIso,
} from "@/domain/dashboard/utils/dashboard-range-utils";
describe("businessTodayIso", () => {
it("formats the America/New_York calendar date regardless of UTC time", () => {
expect(businessTodayIso(new Date("2026-09-16T23:30:00Z"))).toBe("2026-09-16");
expect(businessTodayIso(new Date("2026-09-17T02:30:00Z"))).toBe("2026-09-16");
expect(businessTodayIso(new Date("2026-01-01T04:30:00Z"))).toBe("2025-12-31");
});
});
describe("addDaysIso", () => {
it("rolls over month and year boundaries", () => {
expect(addDaysIso("2026-01-31", 1)).toBe("2026-02-01");
expect(addDaysIso("2026-12-31", 1)).toBe("2027-01-01");
expect(addDaysIso("2026-09-14", -7)).toBe("2026-09-07");
});
});
describe("mondayOf", () => {
it("returns the Monday of the ISO week", () => {
expect(mondayOf("2026-09-16")).toBe("2026-09-14");
expect(mondayOf("2026-09-14")).toBe("2026-09-14");
expect(mondayOf("2026-09-13")).toBe("2026-09-07");
});
});
describe("monthStartIso / monthEndIso", () => {
it("returns month bounds", () => {
expect(monthStartIso("2026-09-16")).toBe("2026-09-01");
expect(monthEndIso("2026-09-16")).toBe("2026-09-30");
expect(monthEndIso("2026-02-16")).toBe("2026-02-28");
});
});
describe("dashboardRangeParams", () => {
it("maps today to the business date", () => {
expect(dashboardRangeParams("today", "2026-09-16")).toEqual({
dateFrom: "2026-09-16",
dateTo: "2026-09-16",
});
});
it("maps this week to the Monday-Friday business week", () => {
expect(dashboardRangeParams("this-week", "2026-09-16")).toEqual({
dateFrom: "2026-09-14",
dateTo: "2026-09-18",
});
});
it("maps last 3 months to the trailing month span", () => {
expect(dashboardRangeParams("last-3-months", "2026-09-16")).toEqual({
dateFrom: "2026-07-01",
dateTo: "2026-09-30",
});
});
it("maps all time to unbounded params", () => {
expect(dashboardRangeParams("all-time", "2026-09-16")).toEqual({});
});
});

59
src/test/domain/dashboard/work-order-drilldown-links.test.ts Normal file
View file

@ -0,0 +1,59 @@
import { afterEach, describe, expect, it, vi } from "vitest";
import {
avetaPendingDrilldownSearch,
scheduledTomorrowDrilldownSearch,
workOrderDrilldownUrl,
workOrderRangeDrilldownSearch,
workOrderStatusDrilldownSearch,
} from "@/domain/dashboard/utils/work-order-drilldown-links";
describe("work-order drilldown links", () => {
afterEach(() => {
vi.useRealTimers();
});
it("schedules the tomorrow drilldown on the business clock", () => {
const search = scheduledTomorrowDrilldownSearch("2026-09-16");
expect(search.get("dateFrom")).toBe("2026-09-17");
expect(search.get("dateTo")).toBe("2026-09-17");
});
it("builds the Aveta Pending drilldown per SH-294", () => {
const search = avetaPendingDrilldownSearch("2026-09-16");
const statuses = (search.get("statuses") ?? "").split(",");
expect(search.get("dateFrom")).toBe("2026-09-16");
expect(search.get("dateTo")).toBe("2026-09-17");
expect(search.get("aveta")).toBe("1");
// `docs=No` is the completion-document status, not the Aveta document, so it
// must not be part of the Aveta Pending drilldown (SH-294 / backend#138).
expect(search.get("docs")).toBeNull();
expect(statuses).toContain("Scheduled");
expect(statuses).not.toContain("Completed");
});
it("carries the range into status drilldowns", () => {
// "today" resolves against the business clock, so pin it (midday EDT on
// 2026-09-16 → 2026-09-16 in America/New_York) to keep the test deterministic.
vi.useFakeTimers();
vi.setSystemTime(new Date("2026-09-16T16:00:00Z"));
const search = workOrderStatusDrilldownSearch("Scheduled", "today");
expect(search.get("dateFrom")).toBe("2026-09-16");
expect(search.get("dateTo")).toBe("2026-09-16");
expect(search.get("statuses")).toBe("Scheduled");
});
it("omits dates for the all-time range", () => {
expect(workOrderRangeDrilldownSearch("all-time").toString()).toBe("");
});
it("renders plain or query-bearing work order URLs", () => {
expect(workOrderDrilldownUrl(new URLSearchParams())).toBe("/workorders");
expect(workOrderDrilldownUrl(new URLSearchParams({ statuses: "Scheduled" }))).toBe(
"/workorders?statuses=Scheduled",
);
});
});

70
src/test/domain/work-orders/dashboard-drilldown-params.test.ts Normal file
View file

@ -0,0 +1,70 @@
import { describe, expect, it } from "vitest";
import { parseDashboardDrilldownParams } from "@/domain/work-orders/utils/dashboard-drilldown-params";
import { avetaPendingDrilldownSearch } from "@/domain/dashboard/utils/work-order-drilldown-links";
describe("parseDashboardDrilldownParams", () => {
it("returns null when no recognized param is present", () => {
expect(parseDashboardDrilldownParams(new URLSearchParams())).toBeNull();
expect(
parseDashboardDrilldownParams(new URLSearchParams({ dateFrom: "2026-09-16" })),
).toBeNull();
expect(parseDashboardDrilldownParams(new URLSearchParams({ aveta: "0" }))).toBeNull();
});
it("maps dates to a custom advanced-filter range", () => {
const filters = parseDashboardDrilldownParams(
new URLSearchParams({ dateFrom: "2026-09-14", dateTo: "2026-09-18" }),
);
expect(filters).not.toBeNull();
expect(filters?.dateRange).toBe("custom");
expect(filters?.customFrom).toBe("2026-09-14");
expect(filters?.customTo).toBe("2026-09-18");
});
it("parses the Aveta Pending drilldown and drops unknown statuses", () => {
const params = avetaPendingDrilldownSearch("2026-09-16");
params.append("statuses", "NotAStatus");
const filters = parseDashboardDrilldownParams(params);
expect(filters).not.toBeNull();
expect(filters?.avetaOnly).toBe(true);
// The Aveta drilldown no longer sends `docs=No` (completion-doc status), so
// no completion-document filter is applied.
expect(filters?.docs.size).toBe(0);
expect(filters?.statuses).not.toBeNull();
expect([...(filters?.statuses ?? [])]).not.toContain("Completed");
expect([...(filters?.statuses ?? [])]).not.toContain("NotAStatus");
expect(filters?.statuses.has("Scheduled")).toBe(true);
expect(filters?.statuses.has("Pending Quote")).toBe(true);
});
it("parses dispatcher and uplift params", () => {
const filters = parseDashboardDrilldownParams(
new URLSearchParams({
dispatchers: " 12 , 13",
upliftStatuses: "pending,bogus",
}),
);
expect(filters?.dispatchers).toEqual(new Set(["12", "13"]));
expect(filters?.hasUplift).toBe(true);
expect(filters?.upliftStatuses).toEqual(new Set(["pending"]));
});
it("parses the region drilldown and drops unknown region names", () => {
const filters = parseDashboardDrilldownParams(
new URLSearchParams({ regions: "California, Atlantis" }),
);
expect(filters?.regions).toEqual(new Set(["California"]));
});
it("rejects partial or malformed date ranges", () => {
expect(
parseDashboardDrilldownParams(
new URLSearchParams({ dateFrom: "2026-9-16", dateTo: "2026-09-18" }),
),
).toBeNull();
});
});

16
src/test/lib/auth/user-utils.test.ts
View file

@ -1,5 +1,5 @@
import { describe, expect, it } from "vitest";
import { isAdminUser } from "@/lib/auth/user-utils";
import { canViewAllDispatchersOnDashboard, isAdminUser } from "@/lib/auth/user-utils";
describe("isAdminUser", () => {
it("returns true when Admin appears in roles", () => {
@ -13,3 +13,17 @@ describe("isAdminUser", () => {
expect(isAdminUser(undefined)).toBe(false);
});
});
describe("canViewAllDispatchersOnDashboard", () => {
it("grants the dashboard picker to Admin and Scheduler", () => {
expect(canViewAllDispatchersOnDashboard("Admin")).toBe(true);
expect(canViewAllDispatchersOnDashboard("Scheduler")).toBe(true);
expect(canViewAllDispatchersOnDashboard("Dispatcher, Scheduler")).toBe(true);
});
it("locks a Dispatcher (and unknown roles) to their own work orders", () => {
expect(canViewAllDispatchersOnDashboard("Dispatcher")).toBe(false);
expect(canViewAllDispatchersOnDashboard("Technician")).toBe(false);
expect(canViewAllDispatchersOnDashboard(undefined)).toBe(false);
});
});