feat(timeline): add the Job Stages Timeline — per-job stage history that drives job status, with interviewers and prep lists

__tests__/AddPrepQuestionsDialog.spec.tsx

@@ -0,0 +1,86 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { AddPrepQuestionsDialog } from "@/components/myjobs/job-details/timeline/AddPrepQuestionsDialog";
+import { addStagePrepQuestions } from "@/actions/jobStage.actions";
+import { getQuestionsList } from "@/actions/question.actions";
+
+vi.mock("@/actions/jobStage.actions", () => ({
+  addStagePrepQuestions: vi.fn().mockResolvedValue({ success: true, data: [] }),
+}));
+vi.mock("@/actions/question.actions", () => ({
+  getQuestionsList: vi.fn(),
+  createQuestion: vi.fn().mockResolvedValue({
+    success: true,
+    data: { id: "q9", question: "New one", tags: [] },
+  }),
+}));
+vi.mock("@/actions/tag.actions", () => ({ getAllTags: vi.fn().mockResolvedValue([]) }));
+vi.mock("@/lib/toast", () => ({
+  toastActionResult: vi.fn((res, opts) => res.success && opts.onSuccess?.()),
+  toastSuccess: vi.fn(),
+  toastError: vi.fn(),
+}));
+
+const stage = {
+  id: "st1",
+  occurredAt: new Date(2026, 8, 24, 10, 0),
+  StageType: { label: "Final / Onsite Interview", Status: { value: "interview" } },
+  prepQuestions: [{ id: "p1", questionId: "q1" }],
+} as any;
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  (getQuestionsList as any).mockResolvedValue({
+    success: true,
+    total: 2,
+    data: [
+      { id: "q1", question: "Walk through your caching strategy", tags: [{ id: "tg1", label: "System Design", value: "system design", createdBy: "u1" }] },
+      { id: "q2", question: "Tell me about a conflict with a teammate", tags: [] },
+    ],
+  });
+});
+
+describe("AddPrepQuestionsDialog", () => {
+  it("heads the dialog with the stage and explains the asked workflow", async () => {
+    render(<AddPrepQuestionsDialog open stage={stage} onOpenChange={() => {}} onAdded={() => {}} />);
+
+    expect(await screen.findByText("Final / Onsite Interview · Sep 24, 2026")).toBeInTheDocument();
+    expect(
+      screen.getByText(/check them off as "asked" from the Timeline tab/),
+    ).toBeInTheDocument();
+  });
+
+  // The same question cannot be added twice to one stage.
+  it("shows a question already on the prep list as such and does not allow selecting it", async () => {
+    render(<AddPrepQuestionsDialog open stage={stage} onOpenChange={() => {}} onAdded={() => {}} />);
+
+    const already = await screen.findByRole("checkbox", {
+      name: /Walk through your caching strategy/,
+    });
+    expect(already).toBeDisabled();
+    expect(already).toBeChecked();
+  });
+
+  it("shows a selection as a removable chip and submits it", async () => {
+    render(<AddPrepQuestionsDialog open stage={stage} onOpenChange={() => {}} onAdded={() => {}} />);
+
+    await userEvent.click(
+      await screen.findByRole("checkbox", { name: /Tell me about a conflict/ }),
+    );
+    expect(
+      screen.getByRole("button", { name: /Remove Tell me about a conflict/ }),
+    ).toBeInTheDocument();
+
+    await userEvent.click(
+      screen.getByRole("button", { name: "Done — 1 question added to prep list" }),
+    );
+
+    expect(addStagePrepQuestions).toHaveBeenCalledWith("st1", ["q2"]);
+  });
+
+  it("renders the question's tags as category badges", async () => {
+    render(<AddPrepQuestionsDialog open stage={stage} onOpenChange={() => {}} onAdded={() => {}} />);
+
+    expect(await screen.findByText("System Design")).toBeInTheDocument();
+  });
+});

__tests__/AddStageDialog.spec.tsx

@@ -0,0 +1,118 @@
+import { render, screen, within } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { AddStageDialog } from "@/components/myjobs/job-details/timeline/AddStageDialog";
+import { addJobStage } from "@/actions/jobStage.actions";
+
+vi.mock("@/actions/jobStage.actions", () => ({
+  addJobStage: vi.fn().mockResolvedValue({ success: true, data: { id: "st1" } }),
+  updateJobStage: vi.fn().mockResolvedValue({ success: true, data: { id: "st1" } }),
+}));
+vi.mock("@/lib/toast", () => ({
+  toastActionResult: vi.fn((res, opts) => res.success && opts.onSuccess?.()),
+  toastSuccess: vi.fn(),
+  toastError: vi.fn(),
+}));
+
+// jsdom lacks scrollIntoView, which cmdk calls when selecting an item
+Element.prototype.scrollIntoView = vi.fn();
+
+const stageTypes = [
+  { id: "t-off", label: "Offer", value: "offer", statusId: "s-off", sortOrder: 7, Status: { id: "s-off", label: "Offer", value: "offer" } },
+  { id: "t-int", label: "Final / Onsite Interview", value: "final / onsite interview", statusId: "s-int", sortOrder: 6, Status: { id: "s-int", label: "Interview", value: "interview" } },
+] as any;
+
+const jobStatuses = [
+  { id: "s-off", label: "Offer", value: "offer" },
+  { id: "s-int", label: "Interview", value: "interview" },
+] as any;
+
+const props = {
+  open: true,
+  jobId: "j1",
+  jobLabel: "Senior Frontend Engineer · Acme Corp",
+  stage: null,
+  stageTypes,
+  jobStatuses,
+  onOpenChange: () => {},
+  onSaved: vi.fn(),
+};
+
+// The shared Combobox takes no data-testid, so the picker is wrapped in one
+// and the trigger reached through it (Playwright's centre click lands on the
+// button; a jsdom click on the wrapper would not).
+const openStageTypePicker = async () =>
+  userEvent.click(
+    within(screen.getByTestId("stage-type-select")).getByRole("combobox"),
+  );
+
+describe("AddStageDialog", () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it("heads the dialog with the job it belongs to", () => {
+    render(<AddStageDialog {...props} />);
+    expect(screen.getByText("Senior Frontend Engineer · Acme Corp")).toBeInTheDocument();
+  });
+
+  it("ticks Set as current stage by default", () => {
+    render(<AddStageDialog {...props} />);
+    expect(screen.getByRole("checkbox", { name: /Set as current stage/ })).toBeChecked();
+  });
+
+  // Nothing demotes a stage, so a live checkbox here would silently do nothing.
+  it("locks the checkbox when editing the stage that is already current", () => {
+    render(
+      <AddStageDialog
+        {...props}
+        stage={{ id: "st1", isCurrent: true, stageTypeId: "t-int", occurredAt: null, notes: null, outcome: null, durationMins: null, format: null, location: null, StageType: stageTypes[1] } as any}
+      />,
+    );
+
+    const box = screen.getByRole("checkbox", { name: /Set as current stage/ });
+    expect(box).toBeChecked();
+    expect(box).toBeDisabled();
+    expect(screen.getByText(/tick the box on another stage to move it/)).toBeInTheDocument();
+  });
+
+  it("hides the parent-status picker until a custom name is typed", async () => {
+    render(<AddStageDialog {...props} />);
+    expect(screen.queryByText(/PARENT STATUS/i)).toBeNull();
+
+    await userEvent.type(
+      screen.getByPlaceholderText("e.g. Panel Interview, Reference Check…"),
+      "Panel Interview",
+    );
+
+    expect(screen.getByText(/PARENT STATUS/i)).toBeInTheDocument();
+  });
+
+  // Adding a stage records something that just happened, so the date and time
+  // open on now rather than empty.
+  it("saves with the picked type, today's date and time, and set-as-current", async () => {
+    render(<AddStageDialog {...props} />);
+
+    await openStageTypePicker();
+    await userEvent.click(screen.getByRole("option", { name: "Offer" }));
+    await userEvent.click(screen.getByRole("button", { name: "Add Stage" }));
+
+    expect(addJobStage).toHaveBeenCalledWith(
+      expect.objectContaining({
+        jobId: "j1",
+        stageTypeId: "t-off",
+        setAsCurrent: true,
+        date: expect.any(Date),
+        time: expect.stringMatching(/^(0[1-9]|1[0-2]):[0-5][0-9] (AM|PM)$/),
+      }),
+    );
+  });
+
+  it("refuses to save with neither a type nor a custom name", async () => {
+    render(<AddStageDialog {...props} />);
+
+    await userEvent.click(screen.getByRole("button", { name: "Add Stage" }));
+
+    expect(addJobStage).not.toHaveBeenCalled();
+    expect(
+      await screen.findByText(/Pick a stage or enter a custom stage name/),
+    ).toBeInTheDocument();
+  });
+});

__tests__/AdminTabsContainer.spec.tsx

@@ -46,6 +46,13 @@ vi.mock("@/actions/contactRole.actions", () => ({
   deleteContactRoleById: vi.fn(),
 }));
 
+vi.mock("@/actions/jobStageType.actions", () => ({
+  getJobStageTypeList: vi.fn().mockResolvedValue({ data: [], total: 0 }),
+  createJobStageType: vi.fn(),
+  updateJobStageType: vi.fn(),
+  deleteJobStageTypeById: vi.fn(),
+}));
+
 describe("AdminTabsContainer", () => {
   const user = userEvent.setup({ skipHover: true });
 
@@ -70,6 +77,12 @@ describe("AdminTabsContainer", () => {
     expect(screen.getByRole("tab", { name: "Roles" })).toBeInTheDocument();
   });
 
+  it("offers a Stages tab", () => {
+    render(<AdminTabsContainer />);
+
+    expect(screen.getByRole("tab", { name: "Stages" })).toBeInTheDocument();
+  });
+
   it("should default to companies tab", () => {
     render(<AdminTabsContainer />);
 

__tests__/ComboBox.spec.tsx

@@ -37,6 +37,10 @@ vi.mock("@/actions/contactRole.actions", () => ({
   createContactRole: vi.fn(),
 }));
 
+vi.mock("@/actions/tag.actions", () => ({
+  createTag: vi.fn(),
+}));
+
 vi.mock("@/lib/toast", () => ({
   toastError: vi.fn(),
 }));