@astryxdesign/lab 0.3.0-canary.6f9bc84 → 0.3.0-canary.b68ee61

package/dist/Tour/Tour.d.ts

@@ -0,0 +1,85 @@
+/**
+ * @file Tour.tsx
+ * @input Uses React state/refs, TourContext
+ * @output Exports Tour controller component and TourProps
+ * @position Lab experiment (facebook/astryx#4239); controller consumed by index.ts
+ *
+ * Tour is the controller for a product-tour / NUX walkthrough. It renders no
+ * visible chrome of its own — it owns the tour state (active step, advance /
+ * retreat / complete / dismiss) and shares it with declaratively-nested
+ * `<TourStep>` children through context. Steps register on mount, so the step
+ * ORDER is taken from the children in document order (no step array to keep in
+ * sync with the markup).
+ *
+ * The behavior (a controller plus spotlight feature steps, an `isActive`
+ * switch, dismiss-with-reason, and step progress) is composed from Astryx
+ * primitives. Each step anchors its callout via Popover and draws its own
+ * highlight/backdrop (see TourStep) — the controller owns no chrome.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/lab/src/Tour/TourStep.tsx
+ * - /packages/lab/src/Tour/TourContext.ts
+ * - /packages/lab/src/Tour/useTour.ts
+ * - /packages/lab/src/Tour/Tour.doc.mjs (props table, features)
+ * - /packages/lab/src/Tour/Tour.test.tsx (tests for new/changed behavior)
+ * - /packages/lab/src/Tour/index.ts (exports if types change)
+ */
+import { type ReactNode } from 'react';
+import { type TourDismissSource } from './TourContext';
+export interface TourProps {
+    /**
+     * Whether the tour is running. When false, nothing renders and step state
+     * resets — the tour restarts from the first step next time it becomes active.
+     * (Controlled: the consumer owns "has this user seen the tour?".)
+     */
+    isActive: boolean;
+    /**
+     * The tour's steps — `<TourStep>` elements. Step order is taken from their
+     * order here; only the active step renders its callout.
+     */
+    children?: ReactNode;
+    /**
+     * Called when the tour is dismissed, with the reason. Fires for every exit,
+     * including completing the last step (`source === 'complete'`). The consumer
+     * flips `isActive` to false in response, and can branch on the source to tell
+     * a successful finish apart from an early skip/backdrop/escape.
+     */
+    onDismiss: (source: TourDismissSource) => void;
+    /**
+     * Dim the page around the active step's target (a spotlight cutout — the
+     * target stays lit, everything else darkens). Use for modal-style steps that
+     * demand focus; leave off for a lightweight coachmark that only rings the
+     * target.
+     * @default false
+     */
+    hasBackdrop?: boolean;
+    /**
+     * Show the step count ("2 of 5") in each step.
+     * @default false
+     */
+    isStepCountShown?: boolean;
+}
+/**
+ * Controller for a guided product tour. Renders no chrome; coordinates the
+ * active step among its `<TourStep>` children.
+ *
+ * @example
+ * ```
+ * const [isActive, setIsActive] = useState(true);
+ * const saveRef = useRef(null);
+ * const shareRef = useRef(null);
+ * <Tour isActive={isActive} hasBackdrop isStepCountShown onDismiss={() => setIsActive(false)}>
+ *   <TourStep targetRef={saveRef} heading="Save your work">
+ *     Changes save automatically to the cloud.
+ *   </TourStep>
+ *   <TourStep targetRef={shareRef} heading="Share it">
+ *     Invite teammates from here.
+ *   </TourStep>
+ * </Tour>
+ * ```
+ */
+export declare function Tour({ isActive, children, onDismiss, hasBackdrop, isStepCountShown, }: TourProps): import("react").JSX.Element;
+export declare namespace Tour {
+    var displayName: string;
+}
+//# sourceMappingURL=Tour.d.ts.map

package/dist/Tour/Tour.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Tour.d.ts","sourceRoot":"","sources":["../../src/Tour/Tour.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAA4C,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAChF,OAAO,EAEL,KAAK,iBAAiB,EAEvB,MAAM,eAAe,CAAC;AAEvB,MAAM,WAAW,SAAS;IACxB;;;;OAIG;IACH,QAAQ,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB;;;;;OAKG;IACH,SAAS,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAC/C;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,IAAI,CAAC,EACnB,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,WAAmB,EACnB,gBAAwB,GACzB,EAAE,SAAS,+BAuEX;yBA7Ee,IAAI"}

package/dist/Tour/Tour.js

@@ -0,0 +1,112 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file Tour.tsx
+ * @input Uses React state/refs, TourContext
+ * @output Exports Tour controller component and TourProps
+ * @position Lab experiment (facebook/astryx#4239); controller consumed by index.ts
+ *
+ * Tour is the controller for a product-tour / NUX walkthrough. It renders no
+ * visible chrome of its own — it owns the tour state (active step, advance /
+ * retreat / complete / dismiss) and shares it with declaratively-nested
+ * `<TourStep>` children through context. Steps register on mount, so the step
+ * ORDER is taken from the children in document order (no step array to keep in
+ * sync with the markup).
+ *
+ * The behavior (a controller plus spotlight feature steps, an `isActive`
+ * switch, dismiss-with-reason, and step progress) is composed from Astryx
+ * primitives. Each step anchors its callout via Popover and draws its own
+ * highlight/backdrop (see TourStep) — the controller owns no chrome.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/lab/src/Tour/TourStep.tsx
+ * - /packages/lab/src/Tour/TourContext.ts
+ * - /packages/lab/src/Tour/useTour.ts
+ * - /packages/lab/src/Tour/Tour.doc.mjs (props table, features)
+ * - /packages/lab/src/Tour/Tour.test.tsx (tests for new/changed behavior)
+ * - /packages/lab/src/Tour/index.ts (exports if types change)
+ */
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { TourContext } from "./TourContext.js";
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Controller for a guided product tour. Renders no chrome; coordinates the
+ * active step among its `<TourStep>` children.
+ *
+ * @example
+ * ```
+ * const [isActive, setIsActive] = useState(true);
+ * const saveRef = useRef(null);
+ * const shareRef = useRef(null);
+ * <Tour isActive={isActive} hasBackdrop isStepCountShown onDismiss={() => setIsActive(false)}>
+ *   <TourStep targetRef={saveRef} heading="Save your work">
+ *     Changes save automatically to the cloud.
+ *   </TourStep>
+ *   <TourStep targetRef={shareRef} heading="Share it">
+ *     Invite teammates from here.
+ *   </TourStep>
+ * </Tour>
+ * ```
+ */
+export function Tour({
+  isActive,
+  children,
+  onDismiss,
+  hasBackdrop = false,
+  isStepCountShown = false
+}) {
+  // Steps register on mount; insertion order (document order) defines the
+  // sequence. A plain array keeps registration order deterministic.
+  const [stepIds, setStepIds] = useState([]);
+  const [activeStepIndex, setActiveStepIndex] = useState(0);
+  const registerStep = useCallback(id => {
+    setStepIds(prev => prev.includes(id) ? prev : [...prev, id]);
+    return () => {
+      setStepIds(prev => prev.filter(stepId => stepId !== id));
+    };
+  }, []);
+
+  // Reset to the first step whenever the tour is (re)started, so a dismissed
+  // tour begins from the top next time isActive flips back on.
+  useEffect(() => {
+    if (!isActive) {
+      setActiveStepIndex(0);
+    }
+  }, [isActive]);
+  const stepCount = stepIds.length;
+  const onNext = useCallback(() => {
+    // Runs from a click/imperative call (never during render), so branch on the
+    // current index directly rather than inside a state updater — calling
+    // onDismiss from within setState triggers a "setState while rendering"
+    // warning.
+    if (activeStepIndex < stepCount - 1) {
+      setActiveStepIndex(activeStepIndex + 1);
+      return;
+    }
+    // Past the last step → complete. onDismiss carries the reason so a
+    // consumer can branch on 'complete' vs an early exit.
+    onDismiss('complete');
+  }, [activeStepIndex, stepCount, onDismiss]);
+  const onPrevious = useCallback(() => {
+    setActiveStepIndex(prev => prev > 0 ? prev - 1 : prev);
+  }, []);
+  const activeStepId = isActive ? stepIds[activeStepIndex] ?? null : null;
+  const contextValue = useMemo(() => ({
+    registerStep,
+    activeStepId,
+    activeStepIndex,
+    stepCount,
+    isStepCountShown,
+    hasBackdrop,
+    onNext,
+    onPrevious,
+    onDismiss
+  }), [registerStep, activeStepId, activeStepIndex, stepCount, isStepCountShown, hasBackdrop, onNext, onPrevious, onDismiss]);
+  return /*#__PURE__*/_jsx(TourContext.Provider, {
+    value: contextValue,
+    children: children
+  });
+}
+Tour.displayName = 'Tour';

package/dist/Tour/TourContext.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Why a tour was dismissed. Lets a consumer distinguish "finished the whole
+ * tour" from the various early exits, so it can persist "has seen this tour"
+ * appropriately.
+ * - `backdrop`: clicked the dimmed background
+ * - `escape`: pressed Escape at any step
+ * - `close`: pressed the step's close (X) control
+ * - `skip`: chose "skip"/"maybe later" on the first step
+ * - `complete`: advanced past the final step
+ */
+export type TourDismissSource = 'backdrop' | 'escape' | 'close' | 'skip' | 'complete';
+/**
+ * Value shared from the Tour controller to its steps. Steps register
+ * themselves on mount (so the controller learns the step order from the
+ * children, in document order) and read whether they are the active step.
+ */
+export interface TourContextValue {
+    /** Register a step by its stable id; returns an unregister cleanup. */
+    registerStep: (id: string) => () => void;
+    /** The id of the step that is currently active, or null when none. */
+    activeStepId: string | null;
+    /** Zero-based index of the active step among registered steps. */
+    activeStepIndex: number;
+    /** Total number of registered steps. */
+    stepCount: number;
+    /** Whether the tour's step count should be shown in each step. */
+    isStepCountShown: boolean;
+    /** Whether a dimmed background is shown behind the active step. */
+    hasBackdrop: boolean;
+    /** Advance to the next step (or complete on the last step). */
+    onNext: () => void;
+    /** Return to the previous step (no-op on the first step). */
+    onPrevious: () => void;
+    /** Dismiss the tour with a reason. */
+    onDismiss: (source: TourDismissSource) => void;
+}
+export declare const TourContext: import("react").Context<TourContextValue | null>;
+//# sourceMappingURL=TourContext.d.ts.map

package/dist/Tour/TourContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TourContext.d.ts","sourceRoot":"","sources":["../../src/Tour/TourContext.ts"],"names":[],"mappings":"AAmBA;;;;;;;;;GASG;AACH,MAAM,MAAM,iBAAiB,GAC3B,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,UAAU,CAAC;AAExD;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,uEAAuE;IACvE,YAAY,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,IAAI,CAAC;IACzC,sEAAsE;IACtE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,kEAAkE;IAClE,eAAe,EAAE,MAAM,CAAC;IACxB,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,gBAAgB,EAAE,OAAO,CAAC;IAC1B,mEAAmE;IACnE,WAAW,EAAE,OAAO,CAAC;IACrB,+DAA+D;IAC/D,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,6DAA6D;IAC7D,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,sCAAsC;IACtC,SAAS,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,IAAI,CAAC;CAChD;AAED,eAAO,MAAM,WAAW,kDAA+C,CAAC"}

package/dist/Tour/TourContext.js

@@ -0,0 +1,36 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file TourContext.ts
+ * @input Uses React createContext
+ * @output Exports TourContext, TourContextValue, TourDismissSource
+ * @position Internal context; provided by Tour, consumed by TourStep + useTour
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/lab/src/Tour/Tour.tsx
+ * - /packages/lab/src/Tour/TourStep.tsx
+ * - /packages/lab/src/Tour/useTour.ts
+ * - /packages/lab/src/Tour/Tour.doc.mjs
+ */
+import { createContext } from 'react';
+
+/**
+ * Why a tour was dismissed. Lets a consumer distinguish "finished the whole
+ * tour" from the various early exits, so it can persist "has seen this tour"
+ * appropriately.
+ * - `backdrop`: clicked the dimmed background
+ * - `escape`: pressed Escape at any step
+ * - `close`: pressed the step's close (X) control
+ * - `skip`: chose "skip"/"maybe later" on the first step
+ * - `complete`: advanced past the final step
+ */
+
+/**
+ * Value shared from the Tour controller to its steps. Steps register
+ * themselves on mount (so the controller learns the step order from the
+ * children, in document order) and read whether they are the active step.
+ */
+
+export const TourContext = /*#__PURE__*/createContext(null);

package/dist/Tour/TourStep.d.ts

@@ -0,0 +1,77 @@
+/**
+ * @file TourStep.tsx
+ * @input Uses React, Popover/Button/Text/Heading/Stack from @astryxdesign/core, TourContext
+ * @output Exports TourStep component and TourStepProps
+ * @position Lab experiment (facebook/astryx#4239); a single spotlight step in a Tour
+ *
+ * A TourStep highlights a target element and renders a callout anchored to it,
+ * with a heading, body, optional step progress ("2 of 5"), and back / next /
+ * close controls. It registers with the parent `<Tour>` on mount (so step
+ * order follows the children) and only renders its callout while it is the
+ * active step. Anchoring + the callout surface reuse the core `Popover`
+ * (`anchorRef` → the step's target), so positioning, top-layer rendering, and
+ * dismiss semantics come from the existing layer system rather than a bespoke
+ * implementation.
+ *
+ * The highlight is drawn as a separate overlay tracking the target's box — the
+ * consumer's element is never restyled, so there is no cascade fight with the
+ * target's own styles. That overlay is promoted into the browser TOP LAYER
+ * (via the popover API, like the rest of the layer system) so it sits above
+ * page content without any hardcoded z-index; the callout is promoted after
+ * it, so the callout stays above the highlight. Because it is promoted in
+ * place (not portaled out of the tree), it stays inside the consumer's Theme
+ * subtree and inherits theme tokens — including a scoped/nested theme's accent
+ * for the ring. Dimming is an opt-in spotlight cutout (dims around the target,
+ * not over it) rather than a flat scrim.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/lab/src/Tour/Tour.tsx
+ * - /packages/lab/src/Tour/TourContext.ts
+ * - /packages/lab/src/Tour/Tour.doc.mjs (props table, features)
+ * - /packages/lab/src/Tour/Tour.test.tsx (tests for new/changed behavior)
+ * - /packages/lab/src/Tour/index.ts (exports if types change)
+ */
+import { type ReactNode } from 'react';
+import type { LayerAlignment, LayerPlacement } from '@astryxdesign/core/Layer';
+export interface TourStepProps {
+    /**
+     * 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,
+     * matching Popover's `anchorRef` contract. Accepts a ref to any HTMLElement
+     * subtype (e.g. `useRef<HTMLButtonElement>(null)`).
+     */
+    targetRef: React.RefObject<HTMLElement | null>;
+    /** Step heading. */
+    heading: ReactNode;
+    /** Step body content. */
+    children?: ReactNode;
+    /**
+     * Which side of the target the callout sits on.
+     * @default 'below'
+     */
+    placement?: LayerPlacement;
+    /**
+     * How the callout aligns along the placement side — e.g. with `placement="below"`,
+     * `start` left-aligns it under the target, `center` centers it, `end` right-aligns it.
+     * @default 'start'
+     */
+    alignment?: LayerAlignment;
+    /** Test id applied to the callout content. */
+    'data-testid'?: string;
+}
+/**
+ * A single spotlight step within a `<Tour>`. Renders its callout only while
+ * active.
+ *
+ * @example
+ * ```
+ * <TourStep targetRef={saveRef} heading="Save your work">
+ *   Changes save automatically.
+ * </TourStep>
+ * ```
+ */
+export declare function TourStep({ targetRef, heading, children, placement, alignment, 'data-testid': testId, }: TourStepProps): import("react").JSX.Element | null;
+export declare namespace TourStep {
+    var displayName: string;
+}
+//# sourceMappingURL=TourStep.d.ts.map

package/dist/Tour/TourStep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TourStep.d.ts","sourceRoot":"","sources":["../../src/Tour/TourStep.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAOL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAGf,OAAO,KAAK,EAAC,cAAc,EAAE,cAAc,EAAC,MAAM,0BAA0B,CAAC;AAmK7E,MAAM,WAAW,aAAa;IAC5B;;;;;OAKG;IACH,SAAS,EAAE,KAAK,CAAC,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAC/C,oBAAoB;IACpB,OAAO,EAAE,SAAS,CAAC;IACnB,yBAAyB;IACzB,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB;;;OAGG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B;;;;OAIG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,8CAA8C;IAC9C,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,EACvB,SAAS,EACT,OAAO,EACP,QAAQ,EACR,SAAmB,EACnB,SAAmB,EACnB,aAAa,EAAE,MAAM,GACtB,EAAE,aAAa,sCA0If;yBAjJe,QAAQ"}

package/dist/Tour/TourStep.js

@@ -0,0 +1,307 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file TourStep.tsx
+ * @input Uses React, Popover/Button/Text/Heading/Stack from @astryxdesign/core, TourContext
+ * @output Exports TourStep component and TourStepProps
+ * @position Lab experiment (facebook/astryx#4239); a single spotlight step in a Tour
+ *
+ * A TourStep highlights a target element and renders a callout anchored to it,
+ * with a heading, body, optional step progress ("2 of 5"), and back / next /
+ * close controls. It registers with the parent `<Tour>` on mount (so step
+ * order follows the children) and only renders its callout while it is the
+ * active step. Anchoring + the callout surface reuse the core `Popover`
+ * (`anchorRef` → the step's target), so positioning, top-layer rendering, and
+ * dismiss semantics come from the existing layer system rather than a bespoke
+ * implementation.
+ *
+ * The highlight is drawn as a separate overlay tracking the target's box — the
+ * consumer's element is never restyled, so there is no cascade fight with the
+ * target's own styles. That overlay is promoted into the browser TOP LAYER
+ * (via the popover API, like the rest of the layer system) so it sits above
+ * page content without any hardcoded z-index; the callout is promoted after
+ * it, so the callout stays above the highlight. Because it is promoted in
+ * place (not portaled out of the tree), it stays inside the consumer's Theme
+ * subtree and inherits theme tokens — including a scoped/nested theme's accent
+ * for the ring. Dimming is an opt-in spotlight cutout (dims around the target,
+ * not over it) rather than a flat scrim.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/lab/src/Tour/Tour.tsx
+ * - /packages/lab/src/Tour/TourContext.ts
+ * - /packages/lab/src/Tour/Tour.doc.mjs (props table, features)
+ * - /packages/lab/src/Tour/Tour.test.tsx (tests for new/changed behavior)
+ * - /packages/lab/src/Tour/index.ts (exports if types change)
+ */
+import { useContext, useEffect, useId, useLayoutEffect, useRef, useState } from 'react';
+import * as stylex from '@stylexjs/stylex';
+import { Popover } from '@astryxdesign/core/Popover';
+import { Button } from '@astryxdesign/core/Button';
+import { Text } from '@astryxdesign/core/Text';
+import { Heading } from '@astryxdesign/core/Heading';
+import { VStack, HStack } from '@astryxdesign/core/Layout';
+import '@astryxdesign/core/theme/tokens.stylex';
+import { colorVars, spacingVars, durationVars, easeVars } from '@astryxdesign/core/theme/tokens.stylex';
+import { TourContext } from "./TourContext.js";
+
+// Client-only layout effect (SSR renders no overlay, so this only runs on the
+// client). Kept local since core does not export its isomorphic variant.
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+const useClientLayoutEffect = typeof window !== 'undefined' ? useLayoutEffect : useEffect;
+
+// Gap between the target's edge and the highlight ring, in px.
+const HIGHLIGHT_PADDING = 4;
+const styles = {
+  footer: {
+    kGNEyG: "x6s0dn4",
+    kjj79g: "x1qughib",
+    $$css: true
+  },
+  calloutGapBelow: {
+    keoZOQ: "xtbrsbv",
+    $$css: true
+  },
+  calloutGapAbove: {
+    k1K539: "x1p37lm5",
+    $$css: true
+  },
+  calloutGapStart: {
+    k71WvV: "x1pezmd8",
+    $$css: true
+  },
+  calloutGapEnd: {
+    keTefX: "x1cmpsy9",
+    $$css: true
+  }
+};
+const calloutGapStyles = {
+  below: styles.calloutGapBelow,
+  above: styles.calloutGapAbove,
+  start: styles.calloutGapStart,
+  end: styles.calloutGapEnd
+};
+
+/**
+ * The highlight overlay: a top-layer box sized to the target, plus an optional
+ * spotlight-cutout dim. Rendered inline (not portaled) so it stays inside the
+ * consumer's Theme subtree and inherits theme tokens — the popover API promotes
+ * it into the top layer in place. Rendered before the callout so the callout
+ * promotes on top of it; promoted once (never re-promoted) so that ordering
+ * holds across re-measures.
+ */
+function TourHighlight({
+  rect,
+  hasBackdrop,
+  onBackdropClick
+}) {
+  const ref = useRef(null);
+  useClientLayoutEffect(() => {
+    const el = ref.current;
+    if (el == null || typeof el.showPopover !== 'function') {
+      return;
+    }
+    el.showPopover();
+    return () => {
+      if (el.isConnected && typeof el.hidePopover === 'function') {
+        el.hidePopover();
+      }
+    };
+  }, []);
+  return /*#__PURE__*/_jsx("div", {
+    ref: ref,
+    popover: "manual",
+    "data-testid": hasBackdrop ? 'tour-backdrop' : undefined,
+    "aria-hidden": "true",
+    onClick: hasBackdrop ? onBackdropClick : undefined,
+    ...{
+      0: {
+        className: "xixxii4 x10a8y8t x1ghz6dp x1717udv xc342km xng3xce xjbqb8w x1rea2x4 x47corl"
+      },
+      1: {
+        className: "xixxii4 x10a8y8t x1ghz6dp x1717udv xc342km xng3xce xjbqb8w x1rea2x4 x67bb7w"
+      }
+    }[!!hasBackdrop << 0],
+    children: /*#__PURE__*/_jsx("div", {
+      "data-testid": "tour-highlight",
+      ...{
+        0: {
+          className: "x10l6tqk x47corl xr5mita x1gfj591 xuedmi6 xlr8y92"
+        },
+        2: {
+          className: "x10l6tqk x47corl x1gfj591 xuedmi6 xlr8y92 xefcaua"
+        },
+        1: {
+          className: "x10l6tqk x47corl xr5mita x1gfj591 xuedmi6 xlr8y92 xg01cxk"
+        },
+        3: {
+          className: "x10l6tqk x47corl x1gfj591 xuedmi6 xlr8y92 xefcaua xg01cxk"
+        }
+      }[!!hasBackdrop << 1 | !!(rect == null) << 0],
+      style: rect != null ? {
+        top: rect.top - HIGHLIGHT_PADDING,
+        left: rect.left - HIGHLIGHT_PADDING,
+        width: rect.width + HIGHLIGHT_PADDING * 2,
+        height: rect.height + HIGHLIGHT_PADDING * 2,
+        borderRadius: rect.radius
+      } : undefined
+    })
+  });
+}
+/**
+ * A single spotlight step within a `<Tour>`. Renders its callout only while
+ * active.
+ *
+ * @example
+ * ```
+ * <TourStep targetRef={saveRef} heading="Save your work">
+ *   Changes save automatically.
+ * </TourStep>
+ * ```
+ */
+export function TourStep({
+  targetRef,
+  heading,
+  children,
+  placement = 'below',
+  alignment = 'start',
+  'data-testid': testId
+}) {
+  const tour = useContext(TourContext);
+  const id = useId();
+  const isActiveStep = tour != null && tour.activeStepId === id;
+
+  // The active target's viewport box, tracked so the highlight overlay can sit
+  // exactly over it. null until measured (or when inactive).
+  const [rect, setRect] = useState(null);
+
+  // Register with the controller on mount so the tour learns this step (and
+  // its position among siblings). Unregister on unmount.
+  useEffect(() => {
+    if (tour == null) {
+      return;
+    }
+    return tour.registerStep(id);
+  }, [tour, id]);
+
+  // Track the target's box while this step is active. Re-measure on
+  // scroll/resize so the highlight stays glued to the target.
+  useEffect(() => {
+    const el = targetRef.current;
+    if (el == null || !isActiveStep) {
+      setRect(null);
+      return;
+    }
+    const measure = () => {
+      const box = el.getBoundingClientRect();
+      setRect({
+        top: box.top,
+        left: box.left,
+        width: box.width,
+        height: box.height,
+        radius: getComputedStyle(el).borderRadius || '0px'
+      });
+    };
+    measure();
+    window.addEventListener('scroll', measure, true);
+    window.addEventListener('resize', measure);
+    return () => {
+      window.removeEventListener('scroll', measure, true);
+      window.removeEventListener('resize', measure);
+      setRect(null);
+    };
+  }, [targetRef, isActiveStep]);
+
+  // Outside a <Tour>, or when this isn't the active step, render nothing.
+  if (tour == null || !isActiveStep) {
+    return null;
+  }
+  const {
+    activeStepIndex,
+    stepCount,
+    isStepCountShown,
+    hasBackdrop,
+    onNext,
+    onPrevious,
+    onDismiss
+  } = tour;
+  const isFirstStep = activeStepIndex <= 0;
+  const isLastStep = stepCount > 0 && activeStepIndex === stepCount - 1;
+  const content = /*#__PURE__*/_jsxs("div", {
+    ...{
+      className: "x78zum5 xdt5ytf xjcht0a x1va8c73"
+    },
+    "data-testid": testId,
+    children: [/*#__PURE__*/_jsxs(VStack, {
+      gap: 1,
+      children: [/*#__PURE__*/_jsx(Heading, {
+        level: 4,
+        children: heading
+      }), children != null && /*#__PURE__*/_jsx(Text, {
+        type: "body",
+        children: children
+      })]
+    }), /*#__PURE__*/_jsxs(HStack, {
+      gap: 2,
+      xstyle: styles.footer,
+      children: [isStepCountShown && stepCount > 0 ? /*#__PURE__*/_jsx(Text, {
+        type: "supporting",
+        color: "secondary",
+        children: `${activeStepIndex + 1} of ${stepCount}`
+      }) : /*#__PURE__*/_jsx("span", {}), /*#__PURE__*/_jsxs(HStack, {
+        gap: 2,
+        children: [!isFirstStep && /*#__PURE__*/_jsx(Button, {
+          variant: "ghost",
+          size: "sm",
+          label: "Back",
+          onClick: onPrevious
+        }), /*#__PURE__*/_jsx(Button, {
+          variant: "primary",
+          size: "sm",
+          label: isLastStep ? 'Done' : 'Next',
+          onClick: onNext
+        })]
+      })]
+    })]
+  });
+  return /*#__PURE__*/_jsxs(_Fragment, {
+    children: [/*#__PURE__*/_jsx(TourHighlight, {
+      rect: rect,
+      hasBackdrop: hasBackdrop,
+      onBackdropClick: () => onDismiss('backdrop')
+    }), /*#__PURE__*/_jsx(Popover
+    // Popover types anchorRef as RefObject<HTMLElement>; TourStep accepts a
+    // nullable ref for ergonomics (useRef<HTMLButtonElement>(null)). Popover
+    // guards a null `.current` internally, so this widening is safe.
+    , {
+      anchorRef: targetRef,
+      isOpen: true,
+      onOpenChange: open => {
+        // Popover reports close from light-dismiss (backdrop) or Escape.
+        // Route it to the tour as a dismissal so the whole tour ends, not
+        // just this step's popover. Escape and outside-click both surface
+        // here.
+        if (!open) {
+          onDismiss('close');
+        }
+      },
+      placement: placement,
+      alignment: alignment
+      // Size the callout to its content instead of matching the target's
+      // width (Popover's default minWidth: anchor-size(width) makes it span a
+      // wide target); the content's own maxWidth caps it.
+      ,
+      width: "fit-content"
+      // Push the callout clear of the highlight ring so the ring is never
+      // covered (placement-aware; adds to Popover's own anchor gap).
+      ,
+      xstyle: calloutGapStyles[placement],
+      label: typeof heading === 'string' ? heading : 'Tour step',
+      hasCloseButton: true,
+      closeButtonLabel: "Close tour",
+      content: content
+    })]
+  });
+}
+TourStep.displayName = 'TourStep';