Skip to content

feat: add a guided tour to the Analytics page - #1708

Merged
1nonlypiece merged 2 commits into
Commitlabs-Org:masterfrom
mikewheeleer:issue-924-page-tours
Jul 30, 2026
Merged

feat: add a guided tour to the Analytics page#1708
1nonlypiece merged 2 commits into
Commitlabs-Org:masterfrom
mikewheeleer:issue-924-page-tours

Conversation

@mikewheeleer

Copy link
Copy Markdown
Contributor

Summary

Context: while working this issue I found this repo has a large amount of previously-deleted UI infrastructure (a single upstream commit removed ~2,500 files / 170K lines, including the app shell, command palette, and several modals -- none have been rebuilt since). Per maintainer guidance I received, I'm building small, fresh, self-contained pieces rather than trying to resurrect the old deleted implementations wholesale.

The create wizard (src/app/create/page.tsx) has a guided tour via useGuidedTour, but no other page does. That hook can't be reused as-is: it's tightly coupled to the wizard's 3-step model (TOUR_STEPS is hardcoded to wizardStep: 1|2|3, and stepping through the tour actively drives setWizardStep).

What this adds

  • usePageTour (src/hooks/usePageTour.ts) -- a small, page-agnostic tour hook. Tracks a step index over a flat PageTourStep[] list and persists "seen" state to localStorage under a caller-supplied key, so any page can have its own independent tour.
  • GuidedTour (src/components/onboarding/GuidedTour.tsx) -- the tour dialog UI, which didn't exist at all before this PR (it's imported by create/page.tsx but was one of the files deleted in the incident above). Built on the existing Dialog primitive (focus trap, Escape-to-close, background inert, portal) instead of a viewport-anchored tooltip -- reuses already-tested accessibility scaffolding rather than adding new custom positioning/z-index logic. A "Show me on the page" link scrolls the step's target element into view instead.
  • Wires a 3-step tour into the Analytics page (view toggle → KPI cards → trend charts) behind a "Take a tour" button in the header.

Testing

  • usePageTour.test.ts -- 8 tests (start/end, next/prev with clamping, empty-steps no-op, per-key localStorage persistence).
  • GuidedTour.test.tsx -- 9 tests (renders nothing when inactive/no step, progress text, Back button hidden on step 1, Next→Finish label on last step, Skip/Next/Back callbacks, scroll-into-view).
  • All 17 new tests pass.

Note on verification: this page -- and most of the repo -- currently doesn't build (pnpm build fails on a pre-existing, unrelated missing module, @/components/KPICard, part of the same deletion incident). I confirmed via git stash A/B comparison that this diff adds zero new build errors and zero new test failures (baseline: 22 failed test files / 37 failed tests / 488 passed, unchanged except my +17 passing). Also removed one unused local (isAnyLoading) in the same file -- the pre-commit lint hook flagged this pre-existing dead code on a file I was already touching; one-line removal, no behavior change.

Closes #924

The create wizard has a guided tour (useGuidedTour), but no other page
does, and that hook is tightly coupled to the wizard's 3-step model
(TOUR_STEPS is hardcoded, step transitions drive setWizardStep), so it
can't be reused directly elsewhere.

Adds usePageTour, a small page-agnostic tour hook (step index over a
flat PageTourStep[] list, localStorage-persisted "seen" state keyed
per page) and GuidedTour, an accessible tour dialog built on the
existing Dialog primitive (focus trap, Escape-to-close, background
inert) rather than a viewport-anchored tooltip -- this trades visual
polish for reusing already-tested a11y scaffolding instead of adding
new custom positioning logic.

Wires a 3-step tour into the Analytics page (view toggle, KPI cards,
trend charts) behind a "Take a tour" button.

Also removes an unused `isAnyLoading` local in the same file (pre-
existing dead code the pre-commit lint hook flagged on this touched
file; trivial one-line removal, not a behavior change).

Note: this page (and much of this repo) currently doesn't build --
`pnpm build` fails on a pre-existing, unrelated missing module
(`@/components/KPICard`). Confirmed via git stash A/B comparison that
this diff introduces no new build or test failures; my 17 new tests
all pass in isolation.

Closes Commitlabs-Org#924
@vercel

vercel Bot commented Jul 30, 2026

Copy link
Copy Markdown

@mikewheeleer is attempting to deploy a commit to the 1nonly's projects Team on Vercel.

A member of the Team first needs to authorize it.

@1nonlypiece
1nonlypiece merged commit f2063de into Commitlabs-Org:master Jul 30, 2026
9 of 11 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add per-page guided tours beyond the create wizard using useGuidedTour

2 participants