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:
Marc-André BombeckandMarc-André Bombeck authored and GitHub committed 2026-05-08 12:42:48 +02:00
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" });
});
});
+172
View File
@@ -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 };
}