mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-15 23:12:04 +00:00
feat(v1.4): onboarding redesign — dashboard-first checklist, 3 focused steps, inline trend hints (#131)
Redesigns the first-run experience around three patterns we see in
Linear, Vercel and Notion: a short focused wizard, a persistent
getting-started checklist on the dashboard, and contextual hints
inside still-empty charts.
- Onboarding shrinks from 4 steps (one was marketing-only) to 3:
About you (display name + locale + height + DOB + gender) → log
your first measurement (real action via the existing form) → pick
one notification channel (or skip).
- Every step except the first now has a Back button and exactly one
Skip link with the honest "you can finish setup later from
Settings" tail. The legacy duplicate Skip is removed.
- A new dashboard "Getting started" card lists the five quick wins
(profile, first measurement, medication, Withings, notifications).
Each row links to the right place. Items can be hidden one-by-one
or the whole card can be dismissed; both states persist in
localStorage. The card auto-hides once you finish onboarding and
log your fifth measurement.
- Charts that have ≥1 but <5 readings now show a subtle inline hint
("First trend after 5 readings — N more to go") so the user knows
the line will appear soon.
- Display name is captured during onboarding and saved to the
profile.
All new strings are translated to English and German via the
existing i18n pipeline.
Co-authored-by: Marc-André Bombeck <noreply@anthropic.com>
This commit is contained in:
1 parent
14cbc69a2d
commit
f4a2e13985
11 files changed
+1438
-252
No files matched your search
@@ -0,0 +1,217 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import {
|
||||
buildChecklist,
|
||||
checklistProgress,
|
||||
isProfileComplete,
|
||||
shouldShowChecklist,
|
||||
trendHintFor,
|
||||
visibleChecklist,
|
||||
type ChecklistItemId,
|
||||
} from "../checklist";
|
||||
|
||||
const completeProfile = {
|
||||
heightCm: 175,
|
||||
dateOfBirth: "1990-01-01",
|
||||
gender: "MALE",
|
||||
};
|
||||
|
||||
function inputs(overrides: Partial<Parameters<typeof buildChecklist>[0]> = {}) {
|
||||
return {
|
||||
profile: completeProfile,
|
||||
measurementCount: 0,
|
||||
medicationCount: 0,
|
||||
withingsConnected: false,
|
||||
notificationsConfigured: false,
|
||||
dismissedIds: new Set<ChecklistItemId>(),
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
describe("isProfileComplete", () => {
|
||||
it("requires height, dob and gender all set", () => {
|
||||
expect(isProfileComplete(completeProfile)).toBe(true);
|
||||
expect(isProfileComplete({ ...completeProfile, heightCm: null })).toBe(
|
||||
false,
|
||||
);
|
||||
expect(isProfileComplete({ ...completeProfile, dateOfBirth: null })).toBe(
|
||||
false,
|
||||
);
|
||||
expect(isProfileComplete({ ...completeProfile, gender: "" })).toBe(false);
|
||||
expect(isProfileComplete({ ...completeProfile, heightCm: 0 })).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe("buildChecklist", () => {
|
||||
it("emits the five canonical items in stable order", () => {
|
||||
const items = buildChecklist(inputs());
|
||||
expect(items.map((i) => i.id)).toEqual([
|
||||
"profile",
|
||||
"measurement",
|
||||
"medication",
|
||||
"withings",
|
||||
"notifications",
|
||||
]);
|
||||
});
|
||||
|
||||
it("marks profile done when all three fields set", () => {
|
||||
const items = buildChecklist(inputs());
|
||||
expect(items.find((i) => i.id === "profile")?.done).toBe(true);
|
||||
});
|
||||
|
||||
it("flags measurement done at first reading", () => {
|
||||
const items = buildChecklist(inputs({ measurementCount: 1 }));
|
||||
expect(items.find((i) => i.id === "measurement")?.done).toBe(true);
|
||||
});
|
||||
|
||||
it("flags medication and withings independently", () => {
|
||||
const items = buildChecklist(
|
||||
inputs({ medicationCount: 2, withingsConnected: true }),
|
||||
);
|
||||
expect(items.find((i) => i.id === "medication")?.done).toBe(true);
|
||||
expect(items.find((i) => i.id === "withings")?.done).toBe(true);
|
||||
});
|
||||
|
||||
it("propagates per-item dismissal", () => {
|
||||
const items = buildChecklist(
|
||||
inputs({ dismissedIds: new Set<ChecklistItemId>(["medication"]) }),
|
||||
);
|
||||
expect(items.find((i) => i.id === "medication")?.dismissed).toBe(true);
|
||||
expect(items.find((i) => i.id === "profile")?.dismissed).toBe(false);
|
||||
});
|
||||
|
||||
it("attaches deep-link hrefs", () => {
|
||||
const items = buildChecklist(inputs());
|
||||
const hrefs = Object.fromEntries(items.map((i) => [i.id, i.href]));
|
||||
expect(hrefs.profile).toBe("/settings#profile");
|
||||
expect(hrefs.measurement).toBe("/measurements");
|
||||
expect(hrefs.medication).toBe("/medications");
|
||||
expect(hrefs.withings).toBe("/settings#withings");
|
||||
expect(hrefs.notifications).toBe("/settings#notifications");
|
||||
});
|
||||
});
|
||||
|
||||
describe("visibleChecklist + checklistProgress", () => {
|
||||
it("hides per-item dismissed rows from the visible list", () => {
|
||||
const items = buildChecklist(
|
||||
inputs({ dismissedIds: new Set<ChecklistItemId>(["withings"]) }),
|
||||
);
|
||||
const visible = visibleChecklist(items);
|
||||
expect(visible.map((i) => i.id)).not.toContain("withings");
|
||||
});
|
||||
|
||||
it("counts done items inside the visible subset", () => {
|
||||
const items = buildChecklist(
|
||||
inputs({
|
||||
measurementCount: 3,
|
||||
medicationCount: 1,
|
||||
// dismiss the only one not done so percent jumps to 100
|
||||
dismissedIds: new Set<ChecklistItemId>(["withings", "notifications"]),
|
||||
}),
|
||||
);
|
||||
const progress = checklistProgress(items);
|
||||
expect(progress.total).toBe(3);
|
||||
expect(progress.done).toBe(3);
|
||||
expect(progress.percent).toBe(100);
|
||||
expect(progress.allDone).toBe(true);
|
||||
});
|
||||
|
||||
it("returns 0% when nothing done", () => {
|
||||
const items = buildChecklist({
|
||||
profile: { heightCm: null, dateOfBirth: null, gender: null },
|
||||
measurementCount: 0,
|
||||
medicationCount: 0,
|
||||
withingsConnected: false,
|
||||
notificationsConfigured: false,
|
||||
dismissedIds: new Set(),
|
||||
});
|
||||
const progress = checklistProgress(items);
|
||||
expect(progress.percent).toBe(0);
|
||||
expect(progress.allDone).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe("shouldShowChecklist", () => {
|
||||
it("hides when user fully dismissed the checklist", () => {
|
||||
const items = buildChecklist(inputs());
|
||||
expect(
|
||||
shouldShowChecklist({
|
||||
onboardingCompletedAt: null,
|
||||
measurementCount: 0,
|
||||
dismissedAll: true,
|
||||
items,
|
||||
}),
|
||||
).toBe(false);
|
||||
});
|
||||
|
||||
it("hides once user has finished onboarding AND has 5+ measurements", () => {
|
||||
const items = buildChecklist(inputs({ measurementCount: 10 }));
|
||||
expect(
|
||||
shouldShowChecklist({
|
||||
onboardingCompletedAt: "2026-01-01T00:00:00Z",
|
||||
measurementCount: 10,
|
||||
dismissedAll: false,
|
||||
items,
|
||||
}),
|
||||
).toBe(false);
|
||||
});
|
||||
|
||||
it("stays visible while onboarding is incomplete", () => {
|
||||
const items = buildChecklist(inputs({ measurementCount: 7 }));
|
||||
expect(
|
||||
shouldShowChecklist({
|
||||
onboardingCompletedAt: null,
|
||||
measurementCount: 7,
|
||||
dismissedAll: false,
|
||||
items,
|
||||
}),
|
||||
).toBe(true);
|
||||
});
|
||||
|
||||
it("stays visible while measurement count under 5 even after onboarding ack", () => {
|
||||
const items = buildChecklist(inputs({ measurementCount: 2 }));
|
||||
expect(
|
||||
shouldShowChecklist({
|
||||
onboardingCompletedAt: "2026-01-01T00:00:00Z",
|
||||
measurementCount: 2,
|
||||
dismissedAll: false,
|
||||
items,
|
||||
}),
|
||||
).toBe(true);
|
||||
});
|
||||
|
||||
it("hides when every visible item is done", () => {
|
||||
const items = buildChecklist(
|
||||
inputs({
|
||||
measurementCount: 3,
|
||||
medicationCount: 1,
|
||||
withingsConnected: true,
|
||||
notificationsConfigured: true,
|
||||
}),
|
||||
);
|
||||
expect(
|
||||
shouldShowChecklist({
|
||||
onboardingCompletedAt: null,
|
||||
measurementCount: 3,
|
||||
dismissedAll: false,
|
||||
items,
|
||||
}),
|
||||
).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe("trendHintFor", () => {
|
||||
it("hides at 0 readings (chart empty-state owns this)", () => {
|
||||
expect(trendHintFor(0)).toEqual({ kind: "hidden" });
|
||||
});
|
||||
|
||||
it("shows the right remainder between 1 and 4", () => {
|
||||
expect(trendHintFor(1)).toEqual({ kind: "show", remaining: 4 });
|
||||
expect(trendHintFor(4)).toEqual({ kind: "show", remaining: 1 });
|
||||
});
|
||||
|
||||
it("hides once 5 readings reached", () => {
|
||||
expect(trendHintFor(5)).toEqual({ kind: "hidden" });
|
||||
expect(trendHintFor(99)).toEqual({ kind: "hidden" });
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,172 @@
|
||||
/**
|
||||
* Pure progression logic for the v1.4 dashboard "Getting started"
|
||||
* checklist. Decoupled from React so it can be unit-tested without a
|
||||
* DOM. The component layer (`<GettingStartedChecklist>`) reads inputs
|
||||
* (auth user + analytics summaries + medications count + Withings
|
||||
* status + dismissed-ids set) and renders against the result.
|
||||
*/
|
||||
|
||||
export const CHECKLIST_ITEM_IDS = [
|
||||
"profile",
|
||||
"measurement",
|
||||
"medication",
|
||||
"withings",
|
||||
"notifications",
|
||||
] as const;
|
||||
|
||||
export type ChecklistItemId = (typeof CHECKLIST_ITEM_IDS)[number];
|
||||
|
||||
export interface ChecklistItem {
|
||||
id: ChecklistItemId;
|
||||
done: boolean;
|
||||
/** Pre-built href the CTA should jump to. Hash anchors target settings sections. */
|
||||
href: string;
|
||||
/** True if the user explicitly hid this row. */
|
||||
dismissed: boolean;
|
||||
}
|
||||
|
||||
export interface ChecklistInputs {
|
||||
/** Profile completeness — height + dateOfBirth + gender all set. */
|
||||
profile: {
|
||||
heightCm: number | null;
|
||||
dateOfBirth: string | null;
|
||||
gender: string | null;
|
||||
};
|
||||
/** Total measurements logged across all types. */
|
||||
measurementCount: number;
|
||||
/** Number of medications the user has created. */
|
||||
medicationCount: number;
|
||||
/** True iff Withings OAuth is connected (status.connected). */
|
||||
withingsConnected: boolean;
|
||||
/**
|
||||
* True iff the user has set up at least one notification channel
|
||||
* (Telegram, ntfy, or Web Push).
|
||||
*/
|
||||
notificationsConfigured: boolean;
|
||||
/** Dismissed item ids (per-item localStorage state). */
|
||||
dismissedIds: ReadonlySet<ChecklistItemId>;
|
||||
}
|
||||
|
||||
/**
|
||||
* Compute the ordered checklist for the dashboard hero. Stable order:
|
||||
* profile → measurement → medication → withings → notifications. Each
|
||||
* item carries the deep-link the row's CTA should navigate to.
|
||||
*/
|
||||
export function buildChecklist(inputs: ChecklistInputs): ChecklistItem[] {
|
||||
const profileDone = isProfileComplete(inputs.profile);
|
||||
const items: ChecklistItem[] = [
|
||||
{
|
||||
id: "profile",
|
||||
done: profileDone,
|
||||
href: "/settings#profile",
|
||||
dismissed: inputs.dismissedIds.has("profile"),
|
||||
},
|
||||
{
|
||||
id: "measurement",
|
||||
done: inputs.measurementCount >= 1,
|
||||
href: "/measurements",
|
||||
dismissed: inputs.dismissedIds.has("measurement"),
|
||||
},
|
||||
{
|
||||
id: "medication",
|
||||
done: inputs.medicationCount >= 1,
|
||||
href: "/medications",
|
||||
dismissed: inputs.dismissedIds.has("medication"),
|
||||
},
|
||||
{
|
||||
id: "withings",
|
||||
done: inputs.withingsConnected,
|
||||
href: "/settings#withings",
|
||||
dismissed: inputs.dismissedIds.has("withings"),
|
||||
},
|
||||
{
|
||||
id: "notifications",
|
||||
done: inputs.notificationsConfigured,
|
||||
href: "/settings#notifications",
|
||||
dismissed: inputs.dismissedIds.has("notifications"),
|
||||
},
|
||||
];
|
||||
return items;
|
||||
}
|
||||
|
||||
/**
|
||||
* The checklist visible to the user — drops dismissed items and items
|
||||
* already done **and** hidden by completion. We keep done items
|
||||
* visible until the user completes the whole list, so they get the
|
||||
* satisfaction of ticking the last box.
|
||||
*/
|
||||
export function visibleChecklist(items: ChecklistItem[]): ChecklistItem[] {
|
||||
return items.filter((item) => !item.dismissed);
|
||||
}
|
||||
|
||||
export interface ChecklistProgress {
|
||||
total: number;
|
||||
done: number;
|
||||
/** Integer percentage 0-100. */
|
||||
percent: number;
|
||||
/** True iff every non-dismissed item is done. */
|
||||
allDone: boolean;
|
||||
}
|
||||
|
||||
export function checklistProgress(items: ChecklistItem[]): ChecklistProgress {
|
||||
const visible = visibleChecklist(items);
|
||||
const total = visible.length;
|
||||
const done = visible.filter((item) => item.done).length;
|
||||
const percent = total === 0 ? 100 : Math.round((done / total) * 100);
|
||||
return { total, done, percent, allDone: total > 0 && done === total };
|
||||
}
|
||||
|
||||
/**
|
||||
* Should the dashboard render the checklist at all?
|
||||
*
|
||||
* Visible while the user is still in the setup phase:
|
||||
* - `onboardingCompletedAt` is null OR
|
||||
* - they have fewer than 5 measurements
|
||||
*
|
||||
* AND the user has not dismissed the entire checklist
|
||||
* AND there is at least one undone, non-dismissed item.
|
||||
*/
|
||||
export function shouldShowChecklist(args: {
|
||||
onboardingCompletedAt: string | null;
|
||||
measurementCount: number;
|
||||
dismissedAll: boolean;
|
||||
items: ChecklistItem[];
|
||||
}): boolean {
|
||||
if (args.dismissedAll) return false;
|
||||
const stillInSetup =
|
||||
args.onboardingCompletedAt == null || args.measurementCount < 5;
|
||||
if (!stillInSetup) return false;
|
||||
const visible = visibleChecklist(args.items);
|
||||
if (visible.length === 0) return false;
|
||||
return visible.some((item) => !item.done);
|
||||
}
|
||||
|
||||
/**
|
||||
* Profile is "complete" once height, date of birth and gender are all
|
||||
* set. Display name is captured automatically at signup, so it doesn't
|
||||
* gate this item.
|
||||
*/
|
||||
export function isProfileComplete(
|
||||
profile: ChecklistInputs["profile"],
|
||||
): boolean {
|
||||
return (
|
||||
profile.heightCm != null &&
|
||||
profile.heightCm > 0 &&
|
||||
profile.dateOfBirth != null &&
|
||||
profile.gender != null &&
|
||||
profile.gender !== ""
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Trend hint: when the user has between 1 and 4 readings of a metric we
|
||||
* surface "First trend after 5 readings — N more to go". 0 readings is
|
||||
* handled by the existing chart empty-state. ≥5 readings hides the
|
||||
* hint entirely.
|
||||
*/
|
||||
export function trendHintFor(
|
||||
count: number,
|
||||
): { kind: "hidden" } | { kind: "show"; remaining: number } {
|
||||
if (count < 1 || count >= 5) return { kind: "hidden" };
|
||||
return { kind: "show", remaining: 5 - count };
|
||||
}
|
||||
Reference in new issue
Block a user