Tour·component·@astryxdesign/labExperimental

Tour

A guided product tour (NUX / onboarding). Tour is a controller that steps a user through a sequence of spotlight callouts anchored to elements on the page. It renders no chrome itself; it owns the active-step state and shares it with declaratively-nested TourStep children (step order follows the children). Experimental: lands in lab first (facebook/astryx#4239).

@astryxdesign/lab

Usage

Use a Tour to introduce a feature or onboard a user through a few key parts of the UI. Compose it from TourStep children, each pointing at an element via targetRef; the Tour advances through them with Next/Back and ends on Done. It is controlled: keep isActive in your own state and persist "has seen this tour" yourself (the component only reports dismissal via onDismiss). Built on the existing Popover/Layer anchoring and overlay tokens rather than a bespoke positioning engine.

Keep tours short: a few high-value steps. Long tours get skipped.
Persist completion yourself (from onDismiss) so a user does not see the same tour on every visit.
Point each step at a stable, visible element; ensure the target is on-screen before its step becomes active.
Gate essential, must-see information behind a tour step; users can dismiss it; put critical info inline.
Use a tour as a substitute for clear UI; fix confusing interfaces rather than narrating them.

Typed props

Tour

Prop	Type and behavior
`isActive`	`boolean` · required Whether the tour is running. When false nothing renders and the tour resets to the first step, so it restarts cleanly next time it becomes active.
`children`	`ReactNode` The tour steps: TourStep elements. Step order follows their order here; only the active step renders its callout. Slot: TourStep
`onDismiss`	`(source: TourDismissSource) => void` · required Called on every exit, with the reason ('backdrop' \| 'escape' \| 'close' \| 'skip' \| 'complete'). The consumer flips isActive to false in response, and can branch on the source to distinguish a successful finish from an early exit.
`hasBackdrop`	`boolean` · default false Dim the page around the active step as a spotlight cutout: the target stays lit while everything else darkens. Use for modal-style steps that demand focus; leave off for a lightweight coachmark that only rings the target.
`isStepCountShown`	`boolean` · default false Show the step count ("2 of 5") in each step.

TourStep

Prop	Type and behavior
`targetRef`	`RefObject<HTMLElement>` · required Ref to the element this step points at. The callout anchors to it like a Popover trigger; it must be a <button> or [role="button"] element (Popover's anchorRef contract).
`heading`	`ReactNode` · required Step heading.
`children`	`ReactNode` Step body content.
`placement`	`'above' \| 'below' \| 'start' \| 'end'` · default 'below' Which side of the target the callout sits on.
`alignment`	`'start' \| 'center' \| 'end'` · default 'start' How the callout aligns along the placement side (e.g. with placement="below": start left-aligns under the target, center centers, end right-aligns).