Skip to main content

CnWalkthrough

Abstract, manifest-driven product walkthrough (ADR-043). Renders a manifest.walkthrough tour as a gray dimmer with a spotlight cutout around one real, interactive element, plus an auto-positioned coachmark card. The element stays clickable in place — the dimmer is four strips framing the target rect, so it works inside overflow:hidden / transformed ancestors where a z-index bump would fail.

Step advancement is declarative: the component sources signals (route change via $router, a cn-walkthrough:object-created window event, an appearing element via MutationObserver, a click on the target, or a delay) and feeds them to useWalkthrough, which captures route params / object ids into a context bag interpolated into later steps via {{var}}.

CnAppRoot auto-mounts it over the live shell (non-gating) when the manifest declares an enabled walkthrough; you can also mount it standalone.

When CnAppRoot starts the tour​

A first-time user can qualify for several first-open surfaces at once. CnAppRoot shows them one at a time and holds the tour back while any of these is true:

  • the per-user completion preference is still loading (see below);
  • the support note is on screen;
  • the setup status is still loading, or the non-gating CnSetupWizard is open. While a required setup step is unmet the wizard replaces the whole shell, tour included.

Held back means not mounted, so nothing is recorded as seen in the meantime. In particular an ESC that closes the setup wizard no longer also dismisses the tour. When the last surface closes (the wizard is cancelled or finished, the note is dismissed) the tour mounts and a qualifying tour starts, or resumes where it was.

Usage​

<CnWalkthrough
:app-id="'pipelinq'"
:manifest="manifest"
:seen-version="seenVersion"
:translate="t"
@complete="onComplete"
@dismiss="onDismiss" />

Manifest​

"walkthrough": {
"enabled": true, "version": 1, "completionConfigKey": "walkthrough_seen_version",
"tours": [{
"id": "getting-started", "trigger": "first-visit",
"steps": [
{ "id": "welcome", "placement": "center", "sinceVersion": "1.0.0",
"title": "...", "body": "...",
"target": { "kind": "page", "ref": "Products" },
"advanceOn": { "type": "manual" } },
{ "id": "create-product", "sinceVersion": "1.0.0",
"body": "...", "task": "Click New product",
"target": { "kind": "element", "ref": "products-add" },
"advanceOn": { "type": "object-created", "register": "pipelinq", "schema": "product",
"capture": { "productId": ":id" } } }
]
}]
}

Where a tour starts​

An auto-start tour whose first step spotlights a page or nav item opens only on that route. A tour whose first step is centered spotlights nothing, so it opens wherever the user lands.

startOn names the routes a tour may auto-start on, whatever its first step looks like:

{ "id": "getting-started", "trigger": "first-visit", "startOn": ["Dashboard"], "steps": [ ... ] }

A user whose first visit is a link to a detail page does not get the tour there. It waits until they reach a named route. A tour started by hand (tourId, or the restart menu) ignores startOn.

Completion persistence​

walkthrough.completionConfigKey names a per-user preference holding the last app version whose tour the user has seen. CnAppRoot owns the round trip:

  • on mount it GETs /apps/{appId}/api/preferences/{completionConfigKey} and holds the overlay back until the answer arrives, so a returning user never sees the tour flash open;
  • on completion (✕ / Skip, or Finish on the last step) it PUTs { "value": "<manifest.version>" } to that same URL, and mirrors it into localStorage (cn-walkthrough-seen:{appId}) so the next boot resolves synchronously.

ESC and a click on the dim pause the tour: it hides and keeps its step. ESC while an app dialog is open belongs to that dialog and leaves the tour alone. While an app dialog is open the overlay drops its dim and docks the coachmark in a corner, so the dialog can be filled in, and an object-created step advances when it is saved.

Progress is remembered too. On every step change CnAppRoot writes { tourId, stepId, index, version } to the preference <completionConfigKey>-progress (and localStorage cn-walkthrough-progress:{appId}). The next visit resumes at that step, and the user settings offer "Continue where you left off" and "Start over". Finishing or skipping the tour clears it.

A step whose target is an element (index-add, say) belongs to the page it was first found on. On another page the same element is not spotlighted.

Only null / missing / "" count as "never seen" — a recorded value that happens to be JS-falsy (0, false, "0") still means the user has seen the tour.

Omit completionConfigKey and persistence stays per-browser (localStorage only): the tour then reopens in a fresh browser profile, which is exactly what breaks e2e runs. Declare the key.

The helpers are exported for hosts that mount CnWalkthrough standalone: loadWalkthroughSeenVersion and persistWalkthroughSeenVersion.

Props​

PropTypeDefaultDescription
appIdstring— (required)The Nextcloud app id (walkthrough machine cache key).
manifestobjectnullThe app manifest; manifest.walkthrough + manifest.version are read.
seenVersionstring''The user's last-seen app version (drives "what's new" composition).
tourIdstring''Force a specific tour id; when empty the auto-start tour is used.
resumeobjectnullResume token { tourId, stepId } (refresh / cross-app hand-off).
zIndexnumber10000Stacking order of the overlay.
nextLabel / backLabel / skipLabel / finishLabelstringlocalizedControl labels.
closeLabelstring"Close tour"Accessible label for the corner ✕ button that ends the tour for good (marks it complete).
translatefunctionnullOptional translator applied to step title/body/task i18n keys.

Events​

EventPayloadDescription
complete—The last step was passed.
dismiss—The user skipped (ended) the tour. Always followed by complete.
pause—The user hid the tour (backdrop / ESC). It can continue later.
progress{ tourId, stepId, index }The active step changed; the host remembers it.
step-change{ stepId, index }The active step changed.
advance{ stepId }The user advanced the tour.
handoff{ app, url }A cross-app hand-off step (handoff.url) navigated to another app with a cn_resume_tour/cn_resume_step token.

Slots​

SlotScopeDescription
coachmark{ step, index, total, next, back, skip }Override the whole coachmark body.

Accessibility​

Moves focus to the coachmark controls (never out of an open app dialog), pauses on ESC, and announces each step via an aria-live region. Targets are scrolled into view before spotlighting.

Target kinds​

nav-item / page (route name), widget (widgetKey), action (action id), element (data-walkthrough-id, falling back to data-testid), selector (raw CSS). The resolver prefers stable manifest identities over CSS.