Skip to content

Job application tracker and AI-powered job search assistant. Helps job seekers manage their search journey with AI resume review, job matching, task logging, and application analytics, all while keeping your data private.

feat(timeline): add stage display helpers and the shared job-stages hook

Khuram Niazdb49b0983410
diff --git a/__tests__/stageDisplay.spec.ts b/__tests__/stageDisplay.spec.ts
new file mode 100644
index 0000000..e79c106
--- /dev/null
+++ b/__tests__/stageDisplay.spec.ts
@@ -0,0 +1,113 @@
+import {
+ formatStageDate,
+ formatStageDateTime,
+ stageInitials,
+ isInterviewStage,
+ terminalStagesFor,
+ askedTally,
+} from "@/components/myjobs/job-details/timeline/stageDisplay";
+
+const stage = (over: any = {}) => ({
+ id: "s1",
+ occurredAt: null,
+ durationMins: null,
+ prepQuestions: [],
+ StageType: { id: "t1", value: "offer", sortOrder: 7, Status: { value: "offer" } },
+ ...over,
+});
+
+describe("formatStageDate", () => {
+ it("renders an em dash for an undated stage rather than a blank", () => {
+ expect(formatStageDate(null)).toBe("—");
+ });
+
+ it("renders a short month and day", () => {
+ expect(formatStageDate(new Date(2026, 8, 24, 10, 0))).toBe("Sep 24");
+ });
+});
+
+describe("formatStageDateTime", () => {
+ it("says so plainly when there is no date", () => {
+ expect(formatStageDateTime(null, null)).toBe("No date set");
+ });
+
+ it("includes the duration only when there is one", () => {
+ const past = new Date(2020, 8, 24, 10, 0);
+ expect(formatStageDateTime(past, 90)).toBe("Sep 24, 2020 · 10:00 AM · 90 min");
+ expect(formatStageDateTime(past, null)).toBe("Sep 24, 2020 · 10:00 AM");
+ });
+
+ // The artboard's wording, kept only where it is true. A past stage that
+ // reads "Scheduled for" a date already gone is simply wrong, and the
+ // prefix doubles as the at-a-glance upcoming/done signal.
+ it('prefixes "Scheduled for" only when the stage is still ahead', () => {
+ const future = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000);
+ expect(formatStageDateTime(future, 90)).toMatch(/^Scheduled for /);
+
+ const past = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
+ expect(formatStageDateTime(past, 90)).not.toMatch(/^Scheduled for /);
+ });
+});
+
+describe("stageInitials", () => {
+ it("takes the first letter of the first two words", () => {
+ expect(stageInitials("Priya Nair")).toBe("PN");
+ expect(stageInitials("Cher")).toBe("C");
+ expect(stageInitials(" ")).toBe("?");
+ });
+});
+
+describe("isInterviewStage", () => {
+ it("discriminates on the parent status, never on the stage's timing", () => {
+ expect(isInterviewStage(stage({ StageType: { Status: { value: "interview" } } }) as any)).toBe(true);
+ expect(isInterviewStage(stage() as any)).toBe(false);
+ });
+});
+
+describe("terminalStagesFor", () => {
+ const types = [
+ { id: "t-off", value: "offer", sortOrder: 7, statusId: "s-off", label: "Offer", Status: { value: "offer" } },
+ { id: "t-rej", value: "rejected", sortOrder: 10, statusId: "s-rej", label: "Rejected", Status: { value: "rejected" } },
+ { id: "t-int", value: "interview", sortOrder: 3, statusId: "s-int", label: "Interview", Status: { value: "interview" } },
+ ] as any;
+
+ // D6: Offer alone. Rejected and Withdrawn are alternative endings, not
+ // next steps, and the mockup shows a single greyed tail step.
+ it("returns only the unreached Offer step", () => {
+ const result = terminalStagesFor([], types);
+ expect(result.map((t: any) => t.value)).toEqual(["offer"]);
+ });
+
+ it("drops the terminal type the job has already reached", () => {
+ const result = terminalStagesFor(
+ [stage({ stageTypeId: "t-off" })] as any,
+ types,
+ );
+ expect(result).toEqual([]);
+ });
+
+ // A custom "Verbal Offer" type under the same parent status must not put a
+ // second greyed Offer step on the rail.
+ it("returns at most one type per parent status", () => {
+ const withCustom = [
+ ...types,
+ { id: "t-verbal", value: "verbal offer", sortOrder: 14, statusId: "s-off", label: "Verbal Offer", Status: { value: "offer" } },
+ ] as any;
+
+ const result = terminalStagesFor([], withCustom);
+ expect(result).toHaveLength(1);
+ expect(result[0].value).toBe("offer");
+ });
+});
+
+describe("askedTally", () => {
+ it("counts asked out of total", () => {
+ expect(
+ askedTally(
+ stage({
+ prepQuestions: [{ asked: true }, { asked: true }, { asked: false }, { asked: false }],
+ }) as any,
+ ),
+ ).toEqual({ asked: 2, total: 4 });
+ });
+});
diff --git a/src/components/myjobs/job-details/timeline/stageDisplay.ts b/src/components/myjobs/job-details/timeline/stageDisplay.ts
new file mode 100644
index 0000000..7aee4f2
--- /dev/null
+++ b/src/components/myjobs/job-details/timeline/stageDisplay.ts
@@ -0,0 +1,65 @@
+import { format } from "date-fns";
+import { TERMINAL_STAGE_STATUSES } from "@/lib/constants";
+import type { JobStage, JobStageTypeRef } from "@/models/jobStage.model";
+
+// An undated stage renders an em dash, never a fabricated date or a blank.
+export function formatStageDate(occurredAt: Date | null): string {
+ return occurredAt ? format(occurredAt, "MMM d") : "—";
+}
+
+// "Scheduled for" only while the stage is still ahead (the artboard's wording,
+// kept where it is true): a past stage that reads "Scheduled for" a date
+// already gone is wrong, and the prefix doubles as the upcoming/done signal.
+export function formatStageDateTime(
+ occurredAt: Date | null,
+ durationMins: number | null,
+): string {
+ if (!occurredAt) return "No date set";
+ const base = format(occurredAt, "MMM d, yyyy · h:mm a");
+ const withDuration = durationMins ? `${base} · ${durationMins} min` : base;
+ return occurredAt.getTime() > Date.now()
+ ? `Scheduled for ${withDuration}`
+ : withDuration;
+}
+
+export function stageInitials(name: string): string {
+ const parts = name.trim().split(/\s+/).filter(Boolean);
+ if (parts.length === 0) return "?";
+ return parts
+ .slice(0, 2)
+ .map((p) => p[0]!.toUpperCase())
+ .join("");
+}
+
+// The gate is stage KIND, never stage timing: an interview a week away is
+// still an interview stage.
+export function isInterviewStage(stage: JobStage): boolean {
+ return stage.StageType?.Status?.value === "interview";
+}
+
+// One greyed step per unreached terminal STATUS, not per type (D6): a user
+// whose Library holds a custom "Verbal Offer" under the offer status would
+// otherwise get two greyed Offer steps side by side.
+export function terminalStagesFor(
+ stages: JobStage[],
+ stageTypes: JobStageTypeRef[],
+): JobStageTypeRef[] {
+ const reachedStatuses = new Set(
+ stages.map((s) => s.StageType?.Status?.value).filter(Boolean),
+ );
+ const terminal = new Set<string>(TERMINAL_STAGE_STATUSES);
+
+ const byStatus = new Map<string, JobStageTypeRef>();
+ for (const type of [...stageTypes].sort((a, b) => a.sortOrder - b.sortOrder)) {
+ const status = type.Status?.value ?? "";
+ if (!terminal.has(status)) continue;
+ if (reachedStatuses.has(status)) continue;
+ if (!byStatus.has(status)) byStatus.set(status, type);
+ }
+ return [...byStatus.values()];
+}
+
+export function askedTally(stage: JobStage): { asked: number; total: number } {
+ const rows = stage.prepQuestions ?? [];
+ return { asked: rows.filter((r) => r.asked).length, total: rows.length };
+}
diff --git a/src/components/myjobs/job-details/timeline/useJobStages.ts b/src/components/myjobs/job-details/timeline/useJobStages.ts
new file mode 100644
index 0000000..d6d5cdd
--- /dev/null
+++ b/src/components/myjobs/job-details/timeline/useJobStages.ts
@@ -0,0 +1,48 @@
+"use client";
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { getJobStages } from "@/actions/jobStage.actions";
+import { sortStages } from "@/lib/jobs/sortStages";
+import type { JobStage } from "@/models/jobStage.model";
+
+// Lives in JobDetails' scope, not the tab's: the header's Update Status menu
+// is visible on every tab and targets the same selected stage.
+export function useJobStages(jobId: string, initial: JobStage[]) {
+ // The server prop comes from JOB_DETAILS_INCLUDE, which carries no orderBy
+ // and could not usefully have one (D2) — without this every job opens with
+ // a scrambled stepper until the first write triggers a refetch.
+ const [stages, setStages] = useState<JobStage[]>(() => sortStages(initial));
+ const [selectedStageId, setSelectedStageId] = useState<string | null>(null);
+
+ const currentStage = useMemo(
+ () => stages.find((s) => s.isCurrent) ?? null,
+ [stages],
+ );
+
+ // Selection defaults to the current stage, and re-homes when the selected
+ // stage is deleted rather than leaving the panel pointed at nothing.
+ useEffect(() => {
+ if (selectedStageId && stages.some((s) => s.id === selectedStageId)) return;
+ setSelectedStageId(currentStage?.id ?? stages[0]?.id ?? null);
+ }, [stages, selectedStageId, currentStage]);
+
+ const selectedStage = useMemo(
+ () => stages.find((s) => s.id === selectedStageId) ?? null,
+ [stages, selectedStageId],
+ );
+
+ // getJobStages already sorts, but sorting again is free and keeps the one
+ // rule ("this list is always sorted") true of every path into setStages.
+ const reload = useCallback(async () => {
+ const fresh = await getJobStages(jobId);
+ if (Array.isArray(fresh)) setStages(sortStages(fresh));
+ }, [jobId]);
+
+ return {
+ stages,
+ currentStage,
+ selectedStage,
+ selectedStageId,
+ selectStage: setSelectedStageId,
+ reload,
+ };
+}