feat(admin): guided editor tour + onboarding checklist rework - #406
Open
Snoe0 wants to merge 21 commits into
Open
feat(admin): guided editor tour + onboarding checklist rework#406Snoe0 wants to merge 21 commits into
Snoe0 wants to merge 21 commits into
Conversation
…kspace-scoped commands workspaceFromPathname() only recognized content/data/media/plugins/ users/account and defaulted everything else — including /admin/dashboard and /admin/ai — to 'site'. That let site-only commands (layers, panels, framework, preview, ...) leak into workspaces with no open editor, and made cross-workspace commands like "Take the editor tour" think they were already on the Site workspace instead of queuing their navigate.
capabilities.e2e.ts and ai.e2e.ts create their own throwaway personas and drive them into the Site editor via a local openReadableSiteEditor helper. Those personas never touch the central seeding in account-persona.setup.ts, so they were genuine first-run users — the tour's fixed inset-0 backdrop would intercept their subsequent clicks. Seed 'completed' at the top of each file's openReadableSiteEditor, before the first /admin/site visit.
Moves workspaceFromPathname out of SpotlightRoot.tsx into its own module (same reason spotlightContext.ts is split out: react-refresh/only-export- components wants .tsx files to only export components) so it's a plain, directly testable export. Adds one case per AdminWorkspace plus the dashboard catch-all, covering the branches the prior fix commit touched.
The coach-mark bubble was remounted via key={stepIndex} on every step,
so it always popped in fresh at (0, 0) before its position was
computed instead of moving from the previous step's position to the
next. TourOverlayInner now owns a single persistent bubble + backdrop
for the whole tour run; the per-step key={stepIndex} logic becomes a
non-visual TourStepResolver that reports {step, anchorEl} upward once
resolved, so the bubble keeps showing the previous step's content in
place while the next one resolves and transitions smoothly via CSS
once it lands. Centered steps now compute a pixel position too instead
of a CSS top:50% override, so they animate the same way.
User feedback: the framework step showed the panel but never told people to click the rail icon to get there. Anchor the step on panel-rail-framework (the left-rail icon) instead of framework-panel, keep prepare() opening the panel so it's visible next to the spotlit icon, and lead the copy with "click this icon" instead of describing the panel as already open. The icon's deterministic rail accent resolves to 'violet' (var(--accent-9)), which renders as magenta/ fuchsia rather than purple, so the copy names that color instead.
…pletes the team step on viewing roles The dashboard checklist's "Create your first page" CTA now queues a site.revealNewPage pending action: the editor opens the Explorer's Site tab and plays a short achromatic attention pulse on the New page button, showing the user where pages are created instead of bare-navigating. The "Invite your team" step becomes "View your team & roles": its CTA queues users.viewRoles so UsersPage lands on the Roles tab, and visiting that tab writes a new set-once team-roles-viewed user preference, which is what completes the step (headcount no longer matters — viewing the team is the step, inviting is optional).
Snoe0
marked this pull request as ready for review
August 18, 2026 20:50
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What changed
walkthrough (welcome → Explorer → new page → modules → Properties panel →
Framework panel → publish), built on a new generic, reusable tour engine
(
src/admin/shared/tour/— step definitions, a small Zustand store, and anSVG-spotlight overlay renderer) with the Site-specific steps layered on top
(
src/admin/pages/site/tour/).editor, and persists its outcome (
completed/dismissed) as aserver-backed
editor-touruser preference so it never reappearsuninvited.
from two entry points: the command palette ("Take the editor tour", ⌘K)
and the dashboard onboarding checklist.
plugin" step (a dead end — the plugin registry doesn't exist yet) and
replaced it with "Tour the editor" at position 3, wired to the new tour.
pages are created: it lands in the editor with the Explorer's Site tab
open and a short attention pulse on the New page button (a new
site.revealNewPagepending action), instead of a bare navigation.roles": its CTA opens the Users page pre-selected on the Roles tab (new
users.viewRolespending action), and visiting that tab is whatcompletes the step — persisted as a new set-once
team-roles-vieweduser preference. Viewing the team is the step; inviting members is
optional, so headcount deliberately no longer matters.
(
workspaceFromPathname) so Dashboard, AI, and plugin-page routes reporttheir real workspace instead of falling through to Site — needed for
cross-workspace commands like "Take the editor tour" to correctly detect
whether they're already on the Site editor.
flows, and updated the docs that describe the feature (
docs/editor.md,new
docs/features/editor-tour.md,docs/features/dashboard.md,docs/features/spotlight.md,docs/reference/persistence-keys.md,docs/reference/design-tokens.md,docs/e2e/feature-matrix.md).Why
Part of #223 (the step-copy fix itself is in #286; this PR is the broader
onboarding work from that thread). The reporter and @DavidBabinec (maintainer) flagged that the
dashboard onboarding checklist gives new users mixed signals and includes a
step (installing a plugin) that doesn't belong before a plugin registry
exists. @DavidBabinec invited me to take on the broader onboarding work in
that thread ("it's time to work on it ... would be great you could help
out"). Reading through the editor cold, the checklist's biggest gap wasn't
wording — it's that a brand-new user has no guided path through the editor
itself (pages, modules, properties, framework variables, publish) before
being asked to do any of those five setup steps. This PR adds that guided
path and folds the plugin-step removal into the same checklist rework, since
both land in the same file and the same review pass.
The plugin-step removal itself was already agreed in #223 between
@AidanAJoyce and @Varshavia, who'd offered to make that specific change
separately. It's included here as a courtesy — @Varshavia, if you'd already
started on it locally, sorry for the overlap; happy to rebase around
whichever lands first.
User impact
dropped into an empty canvas with no orientation.
reappears once skipped or finished — it doesn't nag.
the first time — from the command palette or the dashboard checklist.
don't exist yet.
page" points at the actual New page button, and "View roles" opens the
Roles tab it's asking them to explore.
Verification
E2E (not run as part of this gate — Playwright suite is exercised
separately):
tests/e2e/editor-tour.e2e.tscovers auto-start-to-completion,skip-and-persist, and command-palette replay (TOUR-001–TOUR-003 in
docs/e2e/feature-matrix.md);dashboard.e2e.tscovers the reworkedchecklist (DASH-003).